-
Notifications
You must be signed in to change notification settings - Fork 27
Membership
Currently the membership code is grouped into six module pairs. By module pairs we mean a module for interface and a module for implementation. These modules are:
- Group policy - Provides look ups of group policy files for holding identities after they have been parsed from the CPI.
- Membership client - Client component for calling membership functionality across workers (such as starting registration from the RPC worker)
- Membership service - The server side component for the member processor responding to calls from the membership client.
- Membership group reader - Client component for maintaining a local cache of group data (e.g. member lists) and performing lookups.
- HTTP RPC - Membership related HTTP API endpoints (e.g. for starting registration in a group)
- Registration - Components for performing group registration. Could contain multiple components for different registration types.
External to the membership processor, the registration and membership service components will never be used. Otherwise, all components are available for use outside of the membership processor (e.g. the http rpc component and membership client component will be deployed as part of the rpc processor and the membership group reader and group policy components will be deployed as part of the p2p processor).
Specific components in these modules are described further below.
The group policy provider supplies a holding identity's GroupPolicy object. It comes as a GroupPolicy.json file in a .cpi. CPI installation should include parsing this json as a string and publishing it to the message bus for this component to pick up.
The GroupPolicyProvider component has only one implementation, which depends on the virtual node read component, and the .cpi information read component.
- The virtual node read component retrieves virtual node information for the holding identity.
- The
.cpiinformation component retrieves the node's.cpimetadata, which includes the group policy files as a string. - This
GroupPolicyProvidercomponent implementation parses the string into aGroupPolicyobject.
GroupPolicy objects are cached, so multiple reads return the same object. The cache clears when the component stops or if it goes down due to down dependencies.
The single default implementation of the GroupPolicyProvider component responds to incoming events with these behaviors.
Start event:
- Create registration handle for dependencies (if it hasn't already been created).
Registration changed to status UP event:
- Creates cache map (if it hasn't already been created or it has been closed).
- Creates callback with virtual node service so that the cache is updated when virtual node info changes.
- Sets lifecycle status to UP.
Registration changed to status DOWN event:
- Sets lifecycle status to DOWN.
- Closes the handle on virtual node component callback.
- Closes (nullifies) the cache map.
Stop event:
- Sets lifecycle status to DOWN.
- Closes the handle on virtual node component callback.
- Closes the handle on registration for dependency components.
- Closes (nullifies) the cache map.
The GroupPolicyProvider is used to expose the GroupPolicy objects internally to any interested services. This component can be included with any worker requiring group policy lookups (e.g. the member or p2p worker).
For static networks, GroupPolicy.json defines the static member list. This component is used in the static registration implementation of the MemberRegistrationService to parse static group configurations. Also during registration, the group policy lookup is used to decide which registration implementation to use for a member.
This component provides a group reader for a holding identity. A network member can call it to access the group data it has permission to see, such as group parameters, and to access functionality such as member lookups.
There is only one implementation of this component, which creates group reader instances on request and caches them for faster lookups later. It also creates subscriptions to receive group data, which it caches and uses later to create the group readers as needed. These caches are cleared when this component stops or goes down and they are recreated when the component starts or comes back up.
The single default implementation of the MembershipGroupReaderProvider component responds to incoming events with these behaviors.
Start event:
- Initiates caches for group data and group readers (if they haven't already been created).
- Creates registration handle for dependency components (if one hasn't already been created).
Registration changed to status UP event:
- Registers configuration change callback handler.
Registration changed to status DOWN event:
- Sets lifecycle status to DOWN.
- Closes the handle on registered configuration callback.
Configuration received event
- Sets lifecycle status to DOWN.
- Stops subscriptions.
- Closes caches.
- Recreates caches.
- Recreates subscriptions with updated configuration.
- Sets lifecycle status to UP.
Currently, only the MESSAGING configuration is handled.
Stop event:
- Sets lifecycle status to DOWN.
- Stops subscriptions.
- Closes caches.
- Closes registered callback handler for configuration and dependency services status changes.
Any internal component can use the MembershipGroupReaderProvider if it requires member lookups or a member's view of group data, such as group parameters or the .cpi whitelist.
For example, P2P components can use it to look up member information.
The RegistrationProvider is called to start registration or check on the status of a registration request. This service retrieves the group policy file from the GroupPolicyProvider, check the name of the registration protocol to use, loads that service and calls the appropriate registration function call on that service.
Note: We plan to remove this service in favour of a proxy service in the future.
There is only one implementation of this component interface; RegistrationProviderImpl. This service depends on the group policy provider and retrieves a list of all member registration services.
- The group policy provider is used to find the configured registration protocol.
- The configured registration protocol is used to select the correct registration service from the list of injected services.
A new registration protocol can be made available by just adding a new component implementing
MemberRegistrationService. Then the class name of that component can be set in the group policy and is available for use once deployed.
Start event:
- Starts all member registration components that were injected into this service.
- Creates registration handle for dependency components (if one hasn't already been created).
Registration changed to status UP event:
- Sets lifecycle status to UP.
Registration changed to status DOWN event:
- Sets lifecycle status to DOWN.
Stop event:
- Sets lifecycle status to DOWN.
- Closes registered callback handler for dependency services status changes.
This component is intended only for use by internal membership processor services. Specifically, clients wishing to start registration can use the membership client service to send and RPC request picked up by the membership service on the member processor which will call the registration provider.
Implementations of member registration service are responsible for registering a specific member in a group and checking on the registration status for that member.
The static registration service implementation of the registration service performs registration for a member in the context of a static group. This means that no registration request is sent to an MGM. Instead, all member data is loaded from the group policy file. Members can be set in this file which will be parsed and published to kafka for the registering member (including it's own member info).
// TO DO.
This is not yet implemented but in the future we will have a service responsible for registering with a real MGM. Further documentation will follow when that exists.
Implementations of MemberRegistrationService should never be used directly. The MemberRegistrationProvider is responsible for selecting the correct registration service and calling it. The starting point for registration should always be the membership client component.
// TO DO
// TO DO
// TO DO.
// TO DO.
// TO DO
// TO DO
// TO DO.
// TO DO.
// TO DO
// TO DO
// TO DO.
// TO DO.
The MembershipGroupReader is closely connected to the MembershipGroupReaderProvider component. This class should only be initialised by the MembershipGroupReaderProvider and should always be accessed via that component i.e. references to instances of MembershipGroupReader should not be held long term. Instead use the provider component to get the group reader each time you are trying to read group data.
MembershipGroupReader is created in the context of a holding ID. It is used to retrieve a specific members view on the group. It will primarily be used for member lookups, but can also provide access to the group parameters and CPI whitelist.
Instances of MembershipGroupReader do not implement Lifecycle. Instead, the MembershipGroupReaderProvider described previously has lifecycle and the reader services provide member views on the member group cache. The MembershipGroupReaderProvider may modify/clear cached data in response to lifecycle events and updated data which is why references to the MembershipGroupReader instances should not be held.
The group policy file is a definition of group protocols and protocol configurations. The group policy file is always packaged within the CPI file (the CPI is a combination of a CPB and a GroupPolicy.json file).
There are two scenarios in which a group policy file will be generated; when we need the initial group definition to bootstrap a group, and when we need to export the configuration of a running group to allow new members to join.
In the first scenario, bootstrapping a group, corda-cli is used to create a GroupPolicy file locally. This can be used as part of a CPI for an MGM, or to set up a static group. At the time of writing, the latter is more fleshed out while the former still requires some design work.
In the second scenario, export group policy for joining members, a running MGM is required. A HTTP API endpoint is exposed on the MGM virtual node which returns a group policy when called which can then be packaged into the CPI distributed to members. The corda-cli will expose functionality which calls that endpoint so that the group policy for an active group can be retrieved via the corda-cli also.
Internally we will expose this file to components as a parsed object from the component GroupPolicyProvider.