Skip to content

Membership

Jump to bottom
Charlie Crean edited this page Feb 15, 2022 · 28 revisions

Components

GroupPolicyProvider

Description

The group policy provider supplies a holding identity's GroupPolicy Java object. It comes as a GroupPolicy.json file in a .cpi.

Implementation

The GroupPolicyProvider component has only one implementation, which depends on the virtual node read component, and the .cpi information read component.

  1. The virtual node read component retrieves virtual node information for the holding identity.
  2. The .cpi information component retrieves the node's .cpi metadata, which includes the group policy files as a string.
  3. This GroupPolicyProvider component implementation parses the string into a GroupPolicy object.

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.

Usage

The MembershipGroupReaderProvider uses GroupPolicyProvider to expose the GroupPolicy object internally to any interested parties, through the group reader objects. For static networks, GroupPolicy.json defines the static member list. It is used in the static registration implementation of the MemberRegistrationService.

Lifecycle handling

The single default implementation of the GroupPolicyProvider component responds to incoming events with these behaviors.

Start event:

  1. Creates cache map (if it hasn't already been created or it has been closed).
  2. Create registration handle for dependencies (if it hasn't already been created).

Registration changed to status UP event:

  1. Creates cache map (if it hasn't already been created or it has been closed).
  2. Creates callback with virtual node service so that the cache is updated when virtual node info changes.
  3. Sets lifecycle status to UP.

Registration changed to status DOWN event:

  1. Sets lifecycle status to DOWN.
  2. Closes the handle on virtual node component callback.
  3. Closes (nullifies) the cache map.

Stop event:

  1. Sets lifecycle status to DOWN.
  2. Closes the handle on virtual node component callback.
  3. Closes the handle on registration for dependency components.
  4. Closes (nullifies) the cache map.

MembershipGroupReaderProvider

Description

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.

Implementations

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.

Usage

Any internal component can use the MembershipGroupReaderProvider if it requires member lookups or a member's view of group data, such as group parameters. It can also be used to access the member's group policy file or .cpi whitelist. For example, P2P components can use it to look up member information.

Lifecycle handling

The single default implementation of the MembershipGroupReaderProvider component responds to incoming events with these behaviors.

Start event:

  1. Initiates caches for group data and group readers (if they haven't already been created).
  2. Creates registration handle for dependency components (if one hasn't already been created).

Registration changed to status UP event:

  1. Registers configuration change callback handler.
  2. Sets lifecycle status to UP.

Registration changed to status DOWN event:

  1. Sets lifecycle status to DOWN.
  2. Closes the handle on registered configuration callback.

Configuration received event

  1. Sets lifecycle status to DOWN.
  2. Stops subscriptions.
  3. Closes caches.
  4. Recreates caches.
  5. Recreates subscriptions with updated configuration.
  6. Sets lifecycle status to UP.

Currently, only the MESSAGING configuration is handled.

Stop event:

  1. Sets lifecycle status to DOWN.
  2. Stops subscriptions.
  3. Closes caches.
  4. Closes registered callback handler for configuration and dependency services status changes.

RegistrationProvider

// TO DO

StaticMemberRegistrationService

// TO DO.

Services

MembershipGroupReader

Description

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.

Group Policy

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.

Clone this wiki locally