hwm.network.security.permissions.PermissionManager Class Reference

Stores and provides access to user permission settings. More...

Public Member Functions
def	__init__
	Sets up the permission manager. More...
def	get_user_permissions
	Returns the permissions structure for the indicated user. More...
def	purge_user_permissions
	Removes all old permission settings. More...

Public Attributes
	permissions
	use_remote_permissions
	permissions_location
	config
	update_frequency

Private Member Functions
def	_update_user_permissions
	Updates the permissions for the indicated user. More...
def	_download_remote_permissions
	Loads the user's permissions from a remote location. More...
def	_load_local_permissions
	Load the user's permissions from a local file. More...
def	_background_update_error
	This callback responds to errors when updating the permissions in the background. More...
def	_save_permissions
	Saves the user command execution permission settings in the PermissionManager. More...
def	_validate_permissions
	Validates the provided permission settings. More...

Detailed Description

Stores and provides access to user permission settings.

This class stores user command permission settings for use by the command parser and related classes. All permission settings are stored with an associated timestamp. This is used to invalidate permissions after a set amount of time, forcing a redownload.

Constructor & Destructor Documentation

def hwm.network.security.permissions.PermissionManager.__init__	(		self,
			permissions_endpoint,
			update_frequency
	)

Sets up the permission manager.

Parameters

permissions_endpoint	The location that can be queried to find user command permissions. This can either be the mercury2 user interface API or a file. If this points to the mercury2 API, it must start with http or https.
update_frequency	How often the user's permissions should be updated (i.e. if a user's permissions are requested and the cached version is older than this value, update them). Specified in seconds.

Member Function Documentation

def hwm.network.security.permissions.PermissionManager._background_update_error (   self,   update_error  )

private

This callback responds to errors when updating the permissions in the background.

Parameters

update_error

A Failure object containing the error.

Returns

Simply returns True to keep the error from getting collected.

def hwm.network.security.permissions.PermissionManager._download_remote_permissions (   self,   user_id  )

private

Loads the user's permissions from a remote location.

 This method loads the specified user's command execution permissions from a remote location (e.g. the mercury2 
 user interface) and returns them.

Exceptions

PermissionsError	if an error occurs while downloading or parsing the schedule.
May	throw PermissionsInvalidSchema if the permission settings do not conform to the defined schema.

Note

This method is intended to be called with threads.deferToThread. The returned permissions will be passed to the resulting deferred's callback chain.

Parameters

user_id

The ID of the user we want to download permissions for.

Returns

Returns an array of JSON objects representing the permissions for each queried user. Note that in this case the array will only have a single element.

def hwm.network.security.permissions.PermissionManager._load_local_permissions (   self,   user_id  )

private

Load the user's permissions from a local file.

 This method loads the specified user's command execution permissions from a local master permissions file (generated
 by the mercury2 user interface). 

Exceptions

PermissionsError	if the file can't be loaded for some reason.
May	throw PermissionsInvalidSchema if the permission settings file does not conform to the defined schema.

Note

This method is intended to be called with threads.deferToThread. The returned permissions will be passed to the resulting deferred's callback chain.

Parameters

user_id

The ID of the user to load permissions for.

Returns

Returns an array of JSON objects representing the permissions for each queried user. Note that in this case the array will only have a single element.

def hwm.network.security.permissions.PermissionManager._save_permissions (   self,   permission_settings,   user_id  )

private

Saves the user command execution permission settings in the PermissionManager.

 This callback saves the permissions for every user with permissions defined in permission settings.

Note

Depending on how the permissions are loaded (i.e. either from a remote API location or a local offline file), permission_settings can contain the permissions for multiple users. Regardless of how many users are represented in permission_settings, the permissions will be saved for all of them. This prevents frequent file loads when operating in offline mode.

If a user already has non-expired permissions in the manager, they will be overwritten by the new values.

Exceptions

PermissionsUserNotFound

if the user originally indicated couldn't be located in the loaded permissions resource.

Parameters

permission_settings	An array containing the JSON permission objects for users it includes.
user_id	The ID of the user that was initially queried for.

Returns

Returns the permission settings for the user that was originally queried for.

def hwm.network.security.permissions.PermissionManager._update_user_permissions (   self,   user_id  )

private

Updates the permissions for the indicated user.

 This method downloads (or loads), validates, and saves the specified user's permission settings.

Note

If a non-remote permissions endpoint is specified, the permissions will be loaded from the offline local file.

If the indicated user already has permission settings recorded, they will be overridden with the new settings.

Exceptions

Throws	PermissionsInvalidSchema if the dictionary defined in permission_settings does not conform to the permission settings schema, as checked by _validate_permissions().
PermissionsUserNotFound	if the indicated user couldn't be located in the loaded permissions resource.

Parameters

user_id

The ID of the user that the command permissions are for.

Returns

Returns a deferred that will be fired with the results of the permission settings load/download. That is, an error or the permissions object for the indicated user.

def hwm.network.security.permissions.PermissionManager._validate_permissions (   self,   raw_permissions,   user_id  )

private

Validates the provided permission settings.

 This method makes sure that the provided permission structure conforms to the defined JSON schema.

Exceptions

Throws	PermissionsInvalidSchema if the dictionary defined in permission_settings does not conform to the permission settings schema.
Throws	PermissionsError if the raw permissions resource can't be parsed.

Parameters

raw_permissions	A raw, unparsed, permissions resource file (either from net or local machine).
user_id	The ID of the user who's permissions are being queried for.

Returns

Returns a dictionary containing the parsed permissions.

def hwm.network.security.permissions.PermissionManager.get_user_permissions	(		self,
			user_id
	)

Returns the permissions structure for the indicated user.

 If the user does not have any permissions loaded, they will be downloaded/loaded in a thread and returned via a 
 deferred. If the user does have cached permissions, they will be fired immediately into the returned deferred (and 
 will get updated in the background if they are too old).

Note

The permissions returned from this function are a copy. That is, they don't reference the permission manager's main permission dictionary.

Exceptions

Throws

PermissionsUserNotFound if the specified user doesn't have any permission settings saved.

Parameters

user_id

The ID of the user to fetch permissions for. This refers to the UUID that was generated for the user, not their username.

Returns

Returns a deferred that will be fired with the user's permissions (or an error, if one occurs).

def hwm.network.security.permissions.PermissionManager.purge_user_permissions	(		self,
			age
	)

Removes all old permission settings.

 This method removes all permission settings entries older than the specified value. Once the permissions have been 
 removed, applicable calls to get_user_permissions will fail and the permissions will be re-downloaded.

Note

The preferred way to update user permissions is to simply let get_user_permissions do it automatically if needed and return the old cached user permissions while they're being updated. If this method is used instead, the deferred returned from get_user_permissions will take longer more often as the permissions are being updated.

Parameters

age	Any permission entries older than age will be purged. The age is specified in seconds.

---

The documentation for this class was generated from the following file:

• hwm/network/security/permissions.py