acme.plugins.services.RemoteCSEManager.RemoteCSEManager

class documentation

class RemoteCSEManager(object):

Constructor: RemoteCSEManager()

This class defines functionalities to handle remote CSE/CSR registrations.

Method	`__init__`	Class constructor.
Method	`checkConnectionsNow`	Force the connection monitor to check the connections now.
Method	`configUpdate`	Callback for the `configUpdate` event.
Method	`configure`	Read the configuration for the registrar and populate the configuration object.
Method	`connectionMonitorWorker`	The background worker that checks periodically whether the connection to the registrar and registree CSEs is still valid.
Method	`getAllLocalCSRs`	Return all local <CSR> resources. This includes the <CSR> of the registrar CSE. This function builds the list from a temporary internal list, but not from the database.
Method	`getCSRFromPath`	Try to get a CSR even from a longer path (only the first 2 path elements are relevant).
Method	`getRemoteCSEBaseAddress`	Get the SP-relative /csi/ri resource ID of a remote CSE from its CSI. The searched for remote CSE must be registered either directly, or be a descendant CSE.
Method	`handleCSRUpdateEvent`	Event handler for an updates of a registree or registrar CSR.
Method	`handleRegistrarDeregistrationEvent`	Event handler for removing the registrar CSE/CSR CSI from the list of registered csi.
Method	`handleRegistrarRegistrationEvent`	Event handler for adding a registrar CSE/CSR CSI to the list of registered csi.
Method	`handleRegistreeCSEDeregistrationEvent`	Event handler for removals of registree's CSE/CSR CSI from the list of registered descendant CSE.
Method	`handleRegistreeCSERegistrationEvent`	Event handler for adding a registree's CSE's <CSR> to the list of registered descendant CSE.
Method	`isRegisteredToRegistrarCSE`	Check whether this CSE is registered to its registrar CSE.
Method	`restart`	Restart the remote service monitor.
Method	`retrieveRemoteResource`	Retrieve a remote resource from one of the interconnected CSEs.
Method	`start`	Start the RemoteCSEManager.
Method	`startConnectionMonitor`	Start the remote monitor as a background worker.
Method	`stop`	Stop the RemoteCSEManager.
Method	`stopConnectionMonitor`	Stop the connection monitor. Also delete the CSR resources on both sides, if possible.
Method	`updateRemoteDescendantCSR`	Update all the remote CSR of the descendant CSEs.
Method	`validate`	Validate the configuration for the registrar and perform some additional initialization.
Class Variable	`__slots__`	Slots for RemoteCSEManager class.
Class Variable	`dispatcher`	Injected Dispatcher instance.
Class Variable	`factory`	Injected Factory instance.
Class Variable	`registration`	Injected Registration manager instance.
Class Variable	`request`	Injected RequestManager instance.
Class Variable	`security`	Injected SecurityManager instance.
Instance Variable	`connectionMonitor`	The background worker that periodically checks the connections to the registrar and registree CSEs. It is started when the CSE starts and stopped when the CSE stops.
Instance Variable	`descendantCSR`	csi -> (CSR, registeredATcsi).
Instance Variable	`registrarConfig`	The local registrar configuration entry. This is stored internally for simplicity.
Instance Variable	`spRegistrarConfigs`	A dictionary of all SP registrar configurations except the own one.
Method	`_assignConfig`	Store relevant configuration values in the manager.
Method	`_checkConnectionToRegistrarCSE`	Check the connection for this CSE to the registrar CSE.
Method	`_checkRegistreeLiveliness`	Check the liveliness of all registree CSEss that are connected to this CSE. This is done by trying to retrieve the own remote <CSR> from the remote CSE. If it cannot be retrieved then the related local CSR is removed.
Method	`_copyCSE2CSR`	Copy the relevant attributes from a <CSEBase> to a <CSR> resource.
Method	`_createCSRonRegistrarCSE`	Create the own <CSR> resource on the registrar CSE.
Method	`_createLocalCSR`	Create a local <CSR> resource for the given registrar configuration.
Method	`_deleteOwnCSRonRegistrarCSE`	Delete the own <CSR> resource from the registrar CSE.
Method	`_deleteRegistreeCSR`	Delete a local registree <CSR> resource. Unregister it first.
Method	`_retrieveLocalCSRResources`	Retrieve the local <CSR> resources.
Method	`_retrieveOwnCSRfromRegistrarCSE`	Retrieve the own <CSR> resource from the registrar CSE.
Method	`_retrieveRegistrarCB`	Retrieve the remote registrar CSEBase resource.
Method	`_updateOwnCSEBaseWithRegistrarCSEInfo`	Update the local CSEBase resource with information from the registrar CSE's CSR.
Method	`_updateOwnCSRonRegistrarCSE`	Update the own <CSR> resource on the registrar CSE.

def __init__(self): ¶

Class constructor.

def checkConnectionsNow(self): ¶

Force the connection monitor to check the connections now.

This is useful for testing purposes or when the CSE is started and the connection monitor should be run immediately.

@onEvent(eventManager.configUpdate)

def configUpdate(self, eventData: EventData): ¶

Callback for the configUpdate event.

Parameters
eventData:`EventData`	The event data, containing the name of the updated configuration setting and its new value.

@configure

def configure(self, config: Configuration): ¶

Read the configuration for the registrar and populate the configuration object.

Parameters
config:`Configuration`	The configuration object to populate.

def connectionMonitorWorker(self) -> bool: ¶

The background worker that checks periodically whether the connection to the registrar and registree CSEs is still valid.

Returns
`bool`	Always True to keep the worker running.

def getAllLocalCSRs(self) -> list[Resource]: ¶

Return all local <CSR> resources. This includes the <CSR> of the registrar CSE. This function builds the list from a temporary internal list, but not from the database.

Returns
`list[Resource]`	List of <CSR> resources.

def getCSRFromPath(self, id: str) -> tuple[Resource, list[str]] | None: ¶

Try to get a CSR even from a longer path (only the first 2 path elements are relevant).

If no direct CSR could be found then that CSR is returned where the addressed csi is a descendant.

Parameters
id:`str`	CSE-ID to search for

Returns
`tuple[Resource, list[str]] \| None`	A tuple (csr resource, list of path elements), or (None, None) in case of an error).

def getRemoteCSEBaseAddress(self, csi: str) -> str | None: ¶

Get the SP-relative /csi/ri resource ID of a remote CSE from its CSI. The searched for remote CSE must be registered either directly, or be a descendant CSE.

Parameters
csi:`str`	The CSI of the remote CSE.

Returns
`str \| None`	The SP-relative /csi/ri resource ID of the remote CSE, or None if not found.

@onEvent(eventManager.csrUpdated)

def handleCSRUpdateEvent(self, eventData: EventData): ¶

Event handler for an updates of a registree or registrar CSR.

Only the local registrar configuration is involved here.

Parameters
eventData:`EventData`	The event data containing the updated CSR and the update dictionary.

@onEvent(eventManager.deregisteredFromRegistrarCSE)

def handleRegistrarDeregistrationEvent(self, eventData: EventData): ¶

Event handler for removing the registrar CSE/CSR CSI from the list of registered csi.

Parameters
eventData:`EventData`	The event data containing the registrar configuration and the registrar CSE resource that is de-registered.

@onEvent(eventManager.registeredToRegistrarCSE)

def handleRegistrarRegistrationEvent(self, eventData: EventData): ¶

Event handler for adding a registrar CSE/CSR CSI to the list of registered csi.

Parameters
eventData:`EventData`	The event data containing the registrar configuration, the registrar CSE resource, the own CSR on the registrar CSE and the local CSR representing the registrar CSE.

@onEvent(eventManager.registreeCSEHasDeregistered)

def handleRegistreeCSEDeregistrationEvent(self, eventData: EventData): ¶

Event handler for removals of registree's CSE/CSR CSI from the list of registered descendant CSE.

Only the local registrar configuration is involved here.

Parameters
eventData:`EventData`	The event data containing the registree CSR resource that is de-registered. The CSR resource must contain the csi of the deregistering CSE.

@onEvent(eventManager.registreeCSEHasRegistered)

def handleRegistreeCSERegistrationEvent(self, eventData: EventData): ¶

Event handler for adding a registree's CSE's <CSR> to the list of registered descendant CSE.

Only the local registrar configuration is involved here.

Parameters
eventData:`EventData`	The event data containing the registree CSR resource that is registered.

def isRegisteredToRegistrarCSE(self) -> bool: ¶

Check whether this CSE is registered to its registrar CSE.

Returns
`bool`	True if registered, False otherwise.

@restart

def restart(self): ¶

Restart the remote service monitor.

def retrieveRemoteResource(self, id: str, originator: str | None = None) -> Resource: ¶

Retrieve a remote resource from one of the interconnected CSEs.

Parameters
id:`str`	The resource ID. It must be at least in SP-relative format.
originator:`str \| None`	Optional request originator. If None is given then the CSE's CSE-ID is used.

Returns
`Resource`	Result object with the status and, if successful, the resource object in the resource attribute.

@start

def start(self): ¶

Start the RemoteCSEManager.

@onEvent(eventManager.cseStartup)

def startConnectionMonitor(self, eventData: EventData): ¶

Start the remote monitor as a background worker.

Parameters
eventData:`EventData`	The event data. Not used in this handler.

@stop

def stop(self) -> bool: ¶

Stop the RemoteCSEManager.

Returns
`bool`	Always return True.

def stopConnectionMonitor(self): ¶

Stop the connection monitor. Also delete the CSR resources on both sides, if possible.

def updateRemoteDescendantCSR(self, data: JSON, target: list[str] | str | None = None): ¶

Update all the remote CSR of the descendant CSEs.

This happens in the background.

Parameters
data:`JSON`	The content to update the descendant CSR with. This should be a dictionary with the attributes to update and their new values.
target:`list[str] \| str \| None`	Optional list of CSR IDs to update. If None then all descendant CSRs are updated.

@validate

def validate(self, config: Configuration): ¶

Validate the configuration for the registrar and perform some additional initialization.

Parameters
config:`Configuration`	The configuration object to validate and initialize.

__slots__: tuple[str, ...] = ¶

Slots for RemoteCSEManager class.

dispatcher: Dispatcher = ¶

Injected Dispatcher instance.

factory: Factory = ¶

Injected Factory instance.

registration: RegistrationManager = ¶

Injected Registration manager instance.

request: RequestManager = ¶

Injected RequestManager instance.

security: SecurityManager = ¶

Injected SecurityManager instance.

connectionMonitor: BackgroundWorker = ¶

The background worker that periodically checks the connections to the registrar and registree CSEs. It is started when the CSE starts and stopped when the CSE stops.

descendantCSR: dict[str, tuple[Resource, str]] = ¶

csi -> (CSR, registeredATcsi).

registrarConfig: CSERegistrar = ¶

The local registrar configuration entry. This is stored internally for simplicity.

spRegistrarConfigs: dict[str, CSERegistrar] = ¶

A dictionary of all SP registrar configurations except the own one.

def _assignConfig(self): ¶

Store relevant configuration values in the manager.

def _checkConnectionToRegistrarCSE(self, registrarConfig: CSERegistrar): ¶

Check the connection for this CSE to the registrar CSE.

def _checkRegistreeLiveliness(self, registrarConfig: CSERegistrar): ¶

Check the liveliness of all registree CSEss that are connected to this CSE. This is done by trying to retrieve the own remote <CSR> from the remote CSE. If it cannot be retrieved then the related local CSR is removed.

Parameters
registrarConfig:`CSERegistrar`	The registrar configuration to use for the search.

def _copyCSE2CSR(self, registrarConfig: CSERegistrar, target: Resource, source: Resource, isUpdate: bool | None = False, targetCsi: str = None, forOwnCSR: bool | None = False): ¶

Copy the relevant attributes from a <CSEBase> to a <CSR> resource.

Parameters
registrarConfig:`CSERegistrar`	The registrar configuration to use for the copy operation.
target:`Resource`	The target <CSEBase> resource.
source:`Resource`	The source <CSR> resource.
isUpdate:`bool \| None`	Indicator that the copy operation is for an UPDATE request.
targetCsi:`str`	Optional target CSE-ID to use for the copy operation.
forOwnCSR:`bool \| None`	If True then the copy is for the own CSR, otherwise it is for a remote CSR.

def _createCSRonRegistrarCSE(self, registrarConfig: CSERegistrar) -> Resource: ¶

Create the own <CSR> resource on the registrar CSE.

Parameters
registrarConfig:`CSERegistrar`	The registrar configuration to use for the creation.

Returns
`Resource`	Remote <CSR> resource

def _createLocalCSR(self, registrarConfig: CSERegistrar) -> Resource: ¶

Create a local <CSR> resource for the given registrar configuration.

The CSR is created based on the local CSEBase and the remote CSEBase of the registrar.

Parameters
registrarConfig:`CSERegistrar`	The registrar configuration to use for the creation.

Returns
`Resource`	Local <CSR> resource

def _deleteOwnCSRonRegistrarCSE(self, registrarConfig: CSERegistrar): ¶

Delete the own <CSR> resource from the registrar CSE.

Parameters
registrarConfig:`CSERegistrar`	The registrar configuration to use for the deletion.

def _deleteRegistreeCSR(self, registreeCSR: Resource): ¶

Delete a local registree <CSR> resource. Unregister it first.

Parameters
registreeCSR:`Resource`	The <CSR> resource to de-register and delete.

def _retrieveLocalCSRResources(self, registrarConfig: CSERegistrar, includeRegistrarCSR: bool | None = False, includeRegistreeCSR: bool | None = False) -> list[Resource]: ¶

Retrieve the local <CSR> resources.

Parameters
registrarConfig:`CSERegistrar`	The registrar configuration to use for the search.
includeRegistrarCSR:`bool \| None`	If True then include the CSR to the registrar CSE in the result.
includeRegistreeCSR:`bool \| None`	if True then include the CSR(s) to the registree CSE(s) in the result.

Returns
`list[Resource]`	A list of found CSR resources.

def _retrieveOwnCSRfromRegistrarCSE(self, registrarConfig: CSERegistrar) -> Resource: ¶

Retrieve the own <CSR> resource from the registrar CSE.

Returns
`Resource`	Resource object

def _retrieveRegistrarCB(self, registrarConfig: CSERegistrar) -> Resource: ¶

Retrieve the remote registrar CSEBase resource.

The actual request uses a direct URL as a fallback because the RETRIEVE request happens when the actual registration may not yet have happened, and the registrars <CSR> resource with the actual POA is not available at that time.

Returns
`Resource`	The registrar's <CSE> resource.

def _updateOwnCSEBaseWithRegistrarCSEInfo(self, localRegistrarCSR: Resource) -> JSON: ¶

Update the local CSEBase resource with information from the registrar CSE's CSR.

Parameters
localRegistrarCSR:`Resource`	The local <CSR> resource for the registrar CSE. This resource is provided during a registration or update event.

Returns
`JSON`	Dictionary with the updated attributes. If no attributes have been updated then an empty dictionary is returned.

def _updateOwnCSRonRegistrarCSE(self, registrarConfig: CSERegistrar, hostingCSE: Resource | None = None) -> Resource: ¶

Update the own <CSR> resource on the registrar CSE.

Parameters
registrarConfig:`CSERegistrar`	The registrar configuration to use for the update.
hostingCSE:`Resource \| None`	Optional CSE resource to use for the update. If None, the hosting <CSEBase> resource will be used.

Returns
`Resource`	Resource