Draft Specification
This specification is currently a draft under development.
Subscription Event Protocol
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. In order to used the Subscription Event Protocol the CloudOS ruleset must be installed in the Personal Cloud for both the originating and target.
Subscribe
The system:subscribe event is used to create a Personal Channel between two Personal Clouds.
- domain: cloudos
- type: subscribe
- attributes:
- channelName
- namespace
- relationship
- targetChannel
- 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 channel token. 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 not namespace is specified the value of "shared" will be used.
- The relationship attribute is provided as a means for the developer to characterize the relationship between the originating and target Personal Cloud. 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 not relationship is specified the value of "peer-peer" will be used.
- The targetChannel attribute is the Personal Channel token for the target Personal Cloud to which the subscription is to be made.
- domain: cloudos
- type: subscriptionRequestAdded
- attributes: targetChannel, backChannel, namespace, relationship, channelName
- domain: cloudos
- type: subscriptionRequestPending
- attributes: eventChannel, namespace, relationship, channelName
Subscription Approval or Rejection
- domain: cloudos
- type: subscriptionRequestApproved
- attributes: eventChannel
- domain: cloudos
- type: CloudOS_subscriptionAdded
- attributes: eventChannel, backChannel, namespace, relationship, channelName
- domain: cloudos
- type: subscriptionRequestRejected
- attributes: eventChannel
- domain: cloudos
- type: subscriptionRejected
- attributes: eventChannel, namespace, relationship, channelName
- domain: cloudos
- type: subscriptionRejected
- attributes: backChannel, namespace, relationship, channelName
fired { raise cloudos event subscribe with channelName = "Coworkers Bob+Ted" and namespace = "DocSample" and relationship = "friend-friend" and targetChannel = "3f15b820-af7f-012f-4c6e-00163ebczzzz" and _api = "sky"; }
Unsubscribe
The system:unsubscribe event is used to remove the Personal Channels between two Personal Clouds.
- domain: cloudos
- type: unsubscribe
- attribute: backChannel
- domain: cloudos
- type: CloudOS_subscriptionRemoved
- attributes: eventChannel, backChannel, namespace, relationship, channelName
always { raise system event unsubscribe with backChannel = "3f15b820-af7f-012f-4c6e-00163ebcfddfd" and _api = "sky"; }
Functions
subscriptionList(namespace, relationship)
The subscriptionList() function will return a map of the subscriptions within the specified namespace and relationship. In order to use the function you must include the CloudOS module as a pragma in the meta section of your ruleset:
use module a169x625 alias CloudOS