Draft Specification
This specification is currently a draft under development.
Issues:
- We need a picture
- Unclear where or who raises approval and rejection events
- Some examples show postlude event raise where PJW thinks an event:send() is correct
- Not sure why cloudos:CloudOS_subscriptionRemoved and cloudos:CloudOS_subscriptionAdded have CloudOS_ prepended when the event domain gives that information. Also, the provided examples don't have the prepend.
- An example of
subscriptionList()
would be nice
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.
Events
Subscribe
The system:subscribe
event is used to create a channel between two Personal Clouds.
cloudos:subscribe(channelName, namespace, relationship, targetChannel)
The attributes have the following semantics:
- The
channelName
attribute is a label associated with the subscription that should convey meaning to developer. ThechannelName
is only used as a component in the creation of the event channel identifier. If nochannelName
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. Thenamespace
is used to filter the list of subscriptions returned by thesubscriptionList()
function. If nonamespace
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. Therelationship
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. Therelationship
attribute values are used to filter the list of subscriptions returned by thesubscriptionList()
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.
system:subscribe
event. This is most often done in a rule postlude as shown in the following example:fired { raise cloudos event subscribe with channelName = "Coworkers Bob+Ted" and namespace = "MyFriends" and relationship = "friend-friend" and targetChannel = "3f15b820-fa7f-012f-4c6e-00163ebccdcd" and _api = "sky"; }
The CloudOS service raises the cloudos:subscriptionRequestAdded
to the target cloud:
cloudos:subscriptionRequestAdded(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:
rule process_subscriptionRequestAdded { select when cloudos subscriptionRequestAdded namespace re/MyFriends/" channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ ... }
The CloudOS services in the target cloud raises the cloudos:subscriptionRequestPending
to signal the receipt of a pending subscription request:
cloudos:subscriptionRequestPending(eventChannel, namespace, relationship, channelName)
Subscription Approval or Rejection
Approval
cloudos:subscriptionRequestApproved
event to signal the CloudOS service that the subscription is approved:
cloudos:subscriptionRequestApproved(eventChannel)
For example, the following postlude would raise the cloudos:subscriptionRequestApproved
event:
fired { raise cloudos event subscriptionRequestApproved with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa" and _api = "sky"; }
Once the subscription request is approved, the CloudOS service in both the orginating and target clouds will raise the cloudos:CloudOS_subscriptionAdded
event so that a ruleset can take additional actions once the subscription has been created
cloudos:CloudOS_subscriptionAdded(eventChannel, backChannel, namespace, relationship, channelName)
cloudos:CloudOS_subscriptionAdded event
is raised:
rule process_subscriptionRequestAdded { select when cloudos subscriptionRequestAdded namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ ... }
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:
cloudos:subscriptionRequestRejected(eventChannel)
For example, the following postlude would raise the cloudos:subscriptionRequestRejected
event:
fired { raise cloudos event subscriptionRequestRejected with eventChannel = "3f15b820-af7f-012f-4c6e-00163ebcaaaa" and _api = "sky"; }
cloudos:subscriptionRejected
event within the target cloud (i.e. the cloud rejecting the subscription):
cloudos:subscriptionRejected(eventChannel, namespace, relationship, channelName)
The following rule is selected when the cloudos:subscriptionRejected
event is seen:
rule receive_subscriptionRejected { select when cloudos subscriptionRejected namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ ... }
In addition, the CloudOS service raises the cloudos:subscriptionRejected event in the originating cloud:
cloudos:subscriptionRejected(backChannel, namespace, relationship, channelName)
The following rule is selected when the cloudos:subscriptionRejected event is raised:
rule receive_subscriptionRejected { select when cloudos subscriptionRejected namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ ... }
Unsubscribe
A ruleset that wishes to remove the channels between two clouds raises the cloudos:unsubscribe event:
cloudos:unsubscribe(backChannel)
The backChannel
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 raises:
fired { raise cloudos event unsubscribe with eventChannel = "3f15b820-7aff-012f-4c6e-00163ebcfddfd" and _api = "sky"; }
The CloudOS service in both the originating and target clouds raises the cloudos:CloudOS_subscriptionRemoved
event so that rulesets within the respective clouds can take any appropriate action:
cloudos:CloudOS_subscriptionRemoved(eventChannel, backChannel, namespace, relationship, channelName)
The following rule is selected when the cloudos:CloudOS_subscriptionRemoved
event is raised:
rule receive_CloudOS_subscriptionRemoved { select when cloudos CloudOS_subscriptionRemoved namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ ... }
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:
use module a169x625 alias CloudOS
subscriptionList(namespace, relationship)
The subscriptionList()
function will return a map of the subscriptions within the specified namespace and relationship.