This site has been deprecated. Do not edit pages here. Please visit the new Pico Labs documentation.


Skip to end of metadata
Go to start of metadata
Draft Specification

This specification is currently a draft under development.

The CloudOS Subscription Event Protocol provides an event based model for managing subscriptions between Personal Clouds. The current implementation of the protocol will create a symmetric relationship between both Personal Clouds. Cloud subscriptions are done in such a way that both the originating and target clouds end up with a unique event channel to the other that is specific to the purpose for the subscription. 

Rulesets do not manage subscriptions directly, but rather rely on the CloudOS service to do it for them. Consequently, to use the Subscription Event Protocol, the CloudOS service ruleset must be installed in the Personal Cloud for both the originator and target. The CloudOS service listens for certain events, manages subscriptions, and provides functions for getting information about subscriptions. Developers need not be concerned with the details of how subscriptions are created between clouds, just the service interface documented here. 

Events

Subscribe

The system:subscribe event is used to create a channel between two Personal Clouds.

Domaincloudos
Typesubscribe
AttributeschannelName, namespace, relationship, targetChannel, subAttrs

The attributes have the following semantics:

  • The channelName attribute is a label associated with the subscription that should convey meaning to developer. The channelName is only used as a component in the creation of the event channel identifier. If no channelName is specified the value of "orphan" will be used.
  • The namespace attribute is provided as a means for the developer to group subscriptions within a single, or group, or applications. The namespace is used to filter the list of subscriptions returned by the subscriptionList() function. If no namespace is specified the value of "shared" will be used.
  • The relationship attribute allows the developer to characterize the relationship between the originator and target clouds. The relationship attribute should be specified as a pair of values separated by a dash (e.g. parent-child, peer-peer, master-slave). The first value of the relationship attribute will be stored with the originating Personal Cloud subscription, the second value will be stored with the target Personal Cloud subscription. The relationship attribute values are used to filter the list of subscriptions returned by the subscriptionList() function. If no relationship is specified the value of "peer-peer" will be used.
  • The targetChannel attribute is the event channel identifier (ECI) for the target cloud to which the subscription is to be made. Usually, this is the well-known ECI (doorbell) for the target cloud. The well-known ECI provides a means for bootstrapping subscriptions between clouds.
  • The subAttrs is an optional attribute that you can use to pass a JSON hash for key/value pairs to the target personal cloud.

Any ruleset wishing to create the subscription signals the CloudOS to do so by raising the system:subscribe event. This is most often done in a rule postlude as shown in the following example:

The CloudOS service raises the cloudos:subscriptionRequestAdded to the originating cloud:

Domaincloudos
Type
subscriptionRequestAdded
Attributes
targetChannel, backChannel, namespace, relationship, channelName

The backChannel attribute contains an ECI for the originating cloud that the CloudOS service has created and will pass to the target cloud. 

The following rule would be selected upon seeing the cloudos:subscriptionRequestAdded event with appropriate values for the event attributes:

Upon see the subscription, the CloudOS service in the target cloud raises the cloudos:subscriptionRequestPending to signal the receipt of a pending subscription request:

Domaincloudos
Type
subscriptionRequestPending
Attributes
eventChannel, namespace, relationship, channelName, subAttrs

Note: The subAttrs attribute is encoded, you will want to decode() it prior to use.

The following rule would be selected upon seeing the cloudos:subscriptionRequestAdded event with appropriate values for the event attributes:

Subscription Event Flow

  1. The cloudos:subscribe event is raised by the originating personal cloud.
  2. CloudOS will create a new channel and raise the cloudos:subscriptionRequestAdded event within the originating personal cloud. The main purpose for raising this event is to provide the application developer the opportunity to capture the newly created channel, backChannel.
  3. CloudOS then raises an event to the target personal cloud over the targentChannel (typically the doorbell ECI) requesting the subscription.
  4. CloudOS in the target personal cloud will raise the cloudos:subscriptionRequestPending giving rulesets the opportunity to respond with either an approval or rejection (see below).

Subscription Approval or Rejection

With the subscription request pending approval, the target cloud can either approve or reject the request.

Approval

To approve the subscription request a ruleset in the the target cloud raises the cloudos:subscriptionRequestApproved event to signal the CloudOS service that the subscription is approved:

Domaincloudos
Type
subscriptionRequestApproved
Attributes
eventChannel, approveAttrs

The approveAttrs attribute is an optional parameter that can be used to pass a JSON hash of key/value pairs to the originating personal cloud.

For example, the following postlude would raise the cloudos:subscriptionRequestApproved event:

For example, this postlude might be in a rule that has received input from the user indicating the user has approved the request. For some requests in some clouds, you may want to create a rule that rule that automatically approves the request. 

Once the subscription request is approved, the CloudOS service in both the orginating and target clouds will raise the cloudos:subscriptionAdded event so that a ruleset can take additional actions once the subscription has been created:

Domaincloudos
Type
subscriptionAdded
Attributes
eventChannel, backChannel, namespace, relationship, channelName, approveAttrs

Note: The approvalAttrs attribute is encoded, you will want to decode() it prior to use.

The following shows a rule that is selected when the cloudos:subscriptionAdded event is raised:

Subscription Approval Event Flow

  1. The cloudos:subscriptionRequestApproved event is raised into the target personal cloud after creating a new channel.
  2. CloudOS raises the cloudos:subscriptionAdded event within the target personal cloud.
  3. CloudOS raises a event over the eventChannel to the originating personal cloud to indicate that the subscription request has been approved.
  4. Within the originating personal cloud CloudOS raises the cloudos:subscriptionAdded event.

Rejection

To reject the subscription request a ruleset in the the target cloud raises the cloudos:subscriptionRequestRejected event to signal the CloudOS service that the subscription is rejected:

Domaincloudos
Type
subscriptionRequestRejected
Attributes
eventChannel

For example, the following postlude would raise the cloudos:subscriptionRequestRejected event:

When the subscription request is rejected the CloudOS service will raise the cloudos:subscriptionRejected event within the target cloud (i.e. the cloud rejecting the subscription):

Domaincloudos
Type
subscriptionRejected
Attributes
eventChannel, namespace, relationship, channelName

The following rule is selected when the cloudos:subscriptionRejected event is seen:

In addition, the CloudOS service raises the cloudos:subscriptionRejected event in the originating cloud:

Domaincloudos
Type
subscriptionRejected
Attributes
backChannel, namespace, relationship, channelName

The only difference is that the attribute backChannel is contains the value of the ECI to the target cloud. 

The following rule is selected when the cloudos:subscriptionRejected event is raised:

Subscription Rejection Event Flow

  1. The cloudos:subscriptionRequestRejected event is raised into the target personal cloud.
  2. CloudOS raises the cloudos:subscriptionRejected event within the target personal cloud.
  3. CloudOS raises an event over the eventChannel to the originating personal cloud to indicate that the subscription request was rejected.
  4. Within the originating personal cloud CloudOS raises the cloudos:subscriptionRejected event.

Unsubscribe

A ruleset that wishes to remove the channels between two clouds raises the cloudos:unsubscribe event:

Domaincloudos
Type
unsubscribe
Attributes
targetChannel

The targetChannel attribute uniquely identifies the channel to be unsubscribed. The backChannel is one of the results provided by the subscriptionList() function.

The following postlude shows this event being raised:

The CloudOS service in both the originating and target clouds raises the cloudos:subscriptionRemoved event so that rulesets within the respective clouds can take any appropriate action:

Domaincloudos
Type
subscriptionRemoved
Attributes
eventChannel, backChannel, namespace, relationship, channelName, approveAttrs

Note: The approvalAttrs attribute is encoded, you will want to decode() it prior to use.

The following rule is selected when the cloudos:CloudOS_subscriptionRemoved event is raised:

Unsubscribe Event Flow

  1. The cloudos:unsubscribe event is raised into the originating personal cloud. Note that it is also possible to raised the cloudos:unsubscribe event in the target personal cloud as well. "Originating" and "target" are relative to where the cloudos:unsubscribe event is raised. 
  2. CloudOS raises the cloudos:subscriptionRemoved event within the originating personal cloud.
  3. CloudOS raises an event over the eventChannel to the target personal cloud to indicate that the subscription has been removed.
  4. CloudOS raises the cloudos:subscriptionRemoved event within the target personal cloud.

Functions

The CloudOS service provides the following functions. In order to use these functions, a ruleset must include the CloudOS service ruleset as a module:

subscriptionList(namespace, relationship)

The subscriptionList() function will return a map of the subscriptions within the specified namespace and relationship. 

getAllSubscriptions()

The getAllSubscriptions() function will return a map of all active subscriptions within the current Personal Cloud. The subscription sample application provides an example of using this function.

getAllPendingApproval()

The getAllPendingApproval() function returns a map of all subscription request that are pending your approval. The subscription sample application provides an example of using this function.

getAllPendingSubscriptions

The getAllPendingSubscriptions() function returns a map of all subscription request that have been generated within this Personal Cloud. The subscription sample application provides an example of using this function.

Labels: