Date: Fri, 29 Mar 2024 10:17:35 +0000 (UTC) Message-ID: <84404985.1325.1711707455273@62fb1278b993> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_1324_1473714045.1711707455273" ------=_Part_1324_1473714045.1711707455273 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Draft Specification
This specification is currently a draft under development.
The CloudOS Subscription Event Protocol provides an event based model fo= r managing subscriptions between Personal Clouds. The current implementatio= n of the protocol will create a symmetric relationship between both Persona= l Clouds. Cloud subscriptions are done in such a way that both the originat= ing 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 Cl= oudOS service to do it for them. Consequently, to use the Subscription Even= t Protocol, the CloudOS service ruleset must be installed in the Personal C= loud for both the originator and target. The CloudOS service listens for ce= rtain events, manages subscriptions, and provides functions for getting inf= ormation about subscriptions. Developers need not be concerned with the det= ails of how subscriptions are created between clouds, just the service inte= rface documented here.
The system:subscribe
event is used to create a channel betw=
een two Personal Clouds.
Domain | cloudos
|
---|---|
Type | subscribe |
Attributes | channelName, namespace, relationship=
, targetChannel, subAttrs |
The attributes have the following semantics:
channelName
attribute is a label associated with the s=
ubscription that should convey meaning to developer. The channelName<=
/code> is only used as a component in the creation of the ev=
ent channel identifier. If no channelName
is specified the=
value of "orphan" will be used.
namespace
attribute is provided as a means for the dev=
eloper to group subscriptions within a single, or group, or applications. T=
he namespace
is used to filter the list of subscriptions retur=
ned by the subscriptionList()
function. If no namespace<=
/code> is specified the value of "shared" will be used.
relationship
attribute allows the developer to charact=
erize the relationship between the originator and target clouds. The =
relationship
attribute should be specified as a pair of values separ=
ated by a dash (e.g. parent-child
, peer-peer
, re=
lationship
attribute values are used to filter the list of subscript=
ions returned by the subscriptionList()
function. If no relati=
onship is specified the value of "peer-peer" will be used.targetChannel
attribute is the event channel identifie=
r (ECI) for the target cloud to which the subscription is to be made. Usual=
ly, this is the well-known ECI (doorbell) for the target cloud. The well-kn=
own ECI provides a means for bootstrapping subscriptions between clouds.
Any ruleset wishing to create the subscription signals the CloudOS to do=
so by raising the system:subscribe
event. This is m=
ost often done in a rule postlude as shown in the following example:
f= ired { raise cloudos event subscribe with channelName =3D "Coworkers Bob+Ted" and namespace =3D "MyFriends" and relationship =3D "friend-friend" and targetChannel =3D "3f15b820-fa7f-012f-4c6e-00163ebccdcd" and subAttr =3D {"name": "Ed Orcutt", "age": "43"} and _api =3D "sky"; }
The CloudOS service raises the cloudos:subscriptionRequestAdded to the originating cloud:
Domain | cloudos |
---|---|
Type |
subscriptionRequestAdded |
Attributes |
targetChannel, backChannel, namespace, relationship,&nb= sp;channelName |
The backChannel
attribute contains an ECI for the originati=
ng cloud that the CloudOS service has created and will pass to the target c=
loud.
The following rule would be selected upon seeing the cloudos:subsc=
riptionRequestAdded
event with appropriate values for the event=
attributes:
r= ule process_subscriptionRequestAdded { select when cloudos subscriptionRequestAdded namespace re/MyFriends/" channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ ... }
Upon see the subscription, the CloudOS service in the target cloud raise=
s the cloudos:subscriptionRequestPending
to signal the receipt=
of a pending subscription request:
Domain | cl=
oudos |
---|---|
Type |
subscriptionRequestPending |
Attributes= |
eventChannel, namespace, relationship, channelName, sub= Attrs |
Note: The subAttrs attribute is encoded, you will want to decode() it pr= ior to use.
The following rule would be selected upon seeing the cloudos:=
subscriptionRequestAdded
event with appropriate values for the =
event attributes:
r= ule process_subscriptionRequestPending { select when cloudos subscriptionRequestPending namespace re/MyFriends/" channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ pre { subAttrs =3D event:attr("subAttrs").decode(); } ... }
cloudos:subscribe
event is raised by the originat=
ing personal cloud.cloudos:subscript=
ionRequestAdded
event within the originating personal cloud. The mai=
n purpose for raising this event is to provide the application developer th=
e opportunity to capture the newly created channel, backChannel.cloudos:subsc=
riptionRequestPending
giving rulesets the opportunity to respond wit=
h either an approval or rejection (see below).To approve the subscription request a ruleset in the the target cloud ra=
ises the cloudos:subscriptionRequestApproved
event t=
o signal the CloudOS service that the subscription is approved:
Domain= | cloudos |
---|---|
Type |
subscriptionRequestApproved |
Attributes |
eventChannel, approveAttrs |
The approveAttrs attribute is an optional parameter that can be use= d to pass a JSON hash of key/value pairs to the originating personal cloud.=
For example, the following postlude would raise the cloudos:s=
ubscriptionRequestApproved
event:
f= ired { raise cloudos event subscriptionRequestApproved with eventChannel =3D "3f15b820-af7f-012f-4c6e-00163ebcaaaa" and approveAttrs =3D {"name": "Fred Wilson" , "age": "22" } and _api =3D "sky"; }
For example, this postlude might be in a rule that has received input fr= om 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 t=
he orginating and target clouds will raise the cloudos:subscriptionAd=
ded
event so that a ruleset can take additional actions once th=
e subscription has been created:
Domain | cloudos |
---|---|
Type |
subscriptionAdded |
Attributes |
eventChannel, backChannel, namespace, relationship, channelN= ame, 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:
r= ule process_subscriptionAdded { select when cloudos subscriptionAdded namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ pre { approveAttrs =3D event:attr("approveAttrs").decode(); } ... }
cloudos:subscriptionRequestApproved
event is rais=
ed into the target personal cloud after creating a new channel.cloudos:subscriptionAdded
eve=
nt within the target personal cloud.cloudos:=
subscriptionAdded
event.To reject the subscription request a ruleset in the the target cloud rai=
ses the cloudos:subscriptionRequestRejected
event to=
signal the CloudOS service that the subscription is rejected:
Domain | cloudos |
---|---|
Type |
subscriptionRequestRejected |
Attributes |
eventChannel |
For example, the following postlude would raise the cloudos:s=
ubscriptionRequestRejected
event:
f= ired { raise cloudos event subscriptionRequestRejected with eventChannel =3D "3f15b820-af7f-012f-4c6e-00163ebcaaaa" and _api =3D "sky"; }
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):
Domain | cloudos |
---|---|
Type |
subscriptionRejected |
Attributes |
eventChannel, namespace, relationship, channelName |
The following rule is selected when the cloudos:subscriptionR=
ejected
event is seen:
r= ule 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:subscriptionRe=
jected
event in the originating cloud:
Domain= | cloudos |
---|---|
Type |
subscriptionRejected |
Attributes |
backChannel, namespace, relationship, channelName |
The only difference is that the attribute backChannel is contains the va= lue of the ECI to the target cloud.
The following rule is selected when the cloudos:subscriptionR=
ejected
event is raised:
r= ule receive_subscriptionRejected { select when cloudos subscriptionRejected namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ ... }
cloudos:subscriptionRequestRejected
event is raised in=
to the target personal cloud.cloudos:subscriptionRejected
event with=
in the target personal cloud.cloudos:=
subscriptionRejected
event.A ruleset that wishes to remove the channels between two clouds raises t= he cloudos:unsubscribe event:
Domain | cl=
oudos |
---|---|
Type |
unsubscribe |
Attributes= |
targetChannel |
The targetChannel
attribute uniquely identifies the ch=
annel to be unsubscribed. The backChannel
is one of the result=
s provided by the subscriptionList()
function.
The following postlude shows this event being raised:
f= ired { raise cloudos event unsubscribe with targetChannel =3D "3f15b820-7aff-012f-4c6e-00163ebcfddfd" and _api =3D "sky"; }
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:
Domain= | cloudos |
---|---|
Type |
subscriptionRemoved |
Attributes |
eventChannel, backChannel, namespace, relationship, channelName, appro= veAttrs |
Note: The approvalAttrs attribute is encoded, you will want to decode() = it prior to use.
The following rule is selected when the cloudos:CloudOS_subsc=
riptionRemoved
event is raised:
r= ule receive_subscriptionRemoved { select when cloudos subscriptionRemoved namespace re/MyFriends/ channelName re/Coworkers Bob+Ted/ relationship re/friend-friend/ pre { approveAttrs =3D event:attr("approveAttrs"); } ... }
cloudos:unsubscribe
event is raised into the originati=
ng personal cloud. Note that it is also possible to raised the cloudo=
s:unsubscribe
event in the target personal cloud as well. "Originati=
ng" and "target" are relative to where the cloudos:unsubscribe
=
event is raised. cloudos:subscriptionRemoved
event withi=
n the originating personal cloud.cloudos:subscriptionRemoved
e=
vent within the target personal cloud.The CloudOS service provides the following functions. In order to use th= ese functions, a ruleset must include the CloudOS service ruleset as a module:
u= se module a169x625 alias CloudOS
The subscriptionList()
function will return a map=
of the subscriptions within the specified namespace and relationship. =
;
p= re { friendsList =3D CloudOS:subscriptionList("myConnections", "friend"); }
The getAllSubscriptions()
function will return a map of all=
active subscriptions within the current Personal Cloud. The subscription sample app=
lication provides an example of using this function.
p= re { allSubscriptions =3D CloudOS:getAllSubscriptions(); }
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.
p= re { allSubscriptionsPendingApproval =3D CloudOS:getAllPendingApproval(); }
The getAllPendingSubscriptions()
function returns a ma=
p of all subscription request that have been generated within this Personal=
Cloud. The subscription sample application provides an example of usin=
g this function.
p= re { allSubscriptionRequest =3D CloudOS:getAllPendingSubscriptions(); }