Subscriptions in the CloudOS


The CloudOS service provides a means for one cloud to subscribe to another. This blog post describes the subscription protocol and how it is used.

Crystal Clouds

My recent screencast on The Personal Cloud Desktop in Action featured an interaction that showed one personal cloud subscribing to another. The screencast is about the desktop, so it showed the user experience, not what's happening under the covers. I said:

The subscriptions are decentralized and based on HTTP using the Evented API specification and event channels. Nothing magic or proprietary. Everything is pretty straightforward underneath the covers.

The purpose of this blog post is to describe in detail what's happening when two personal clouds form a peer-to-peer relationship through subscription.

Event Channels

The first step in understanding how two clouds can form a relationship is to understand event channels. Events in KRL are raised using the Sky version of the Event Exchange Protocol, an implementation of the Evented API specification which is based on HTTP and URLs. Sky makes use of an event channel identifier, or ECI, to name event channels. Each ECI names a channel that is associated with a single personal cloud. A personal cloud can create as many channels as it needs and remove them at will.

So, if you give me a channel identifier, I can use it to raise events into your personal cloud. You control it since you can remove it, and this keep me from contacting you. Removing the channel between my cloud and yours doesn't affect any other channels you've set up. In the future, we expect that you will be able to have more fine-grained control of a channel, specifying what events can be raised on it.

Cloud Interactions

Creating a link between personal clouds requires that the clouds exchange ECIs so that each has a channel to contact the other. We call this "subscribing" to the events from the cloud. Just as you would give a magazine publisher your mailing address to subscribe to a magazine, when you subscribe to events from my cloud, you give me an ECI, the address to a specific channel to your personal cloud.

Subscriptions between clouds are created and managed by the CloudOS service. The CloudOS service is one of the primary services I identified in the service layer of the CloudOS. The CloudOS service provides cloud management services including channel and subscription management. Ed Orcutt is the primary author of the CloudOS service.

cloudos layers

To understand how the CloudOS service handles subscriptions using channels, suppose two people, Alice and Bob, each have a personal cloud. Alice wants to create a symmetric, peer-to-peer relationship with Bob (i.e. she want to "connect with" or "friend" him). The obvious problem for a developer implementing this is "how does Alice's cloud make contact with Bob's cloud when they don't already have a connection?" There's a bootstrap problem.

Each personal cloud has a well-known event channel, that we euphemistically call the personal cloud's "doorbell." The well-known event channel is published and discoverable, so any other cloud can raise events on it. The doorbell is how Alice contacts Bob.

The following diagram describes the method that the CloudOS subscription module implements for creating a peer-to-peer, symmetric relationship:

Subscriptions between personal clouds

A note on the diagram: personal clouds own their inbound channels. Thus in the diagram above, Alice's PC controls the orange (1) and blue (3) channels, while Bob's personal cloud controls the red (2) and green (4) channels. Specifically, Alice's PC creates the blue channel and then gives the ECI to Bob' PC to create a channel from Bob to Alice.

Here's the explanation of the protocol for establishing the channels.

  1. The subscription dance is set off by Alice's PC (APC) receiving a system:subscribe event on an existing channel. The event has attributes that specify the relationship type (peer-to-peer in this case), a name and namespace for the relationship, and the well-known ECI of the PC to link to. For example, in my recent screencast, clicking on the Steve's avatar in the White Pages app eventually leads to a system:subscribe event being raised in Phil's cloud with Steve's well-known ECI.
  2. Alice's PC raises a system:requestSubscription event to Bob's PC (BPC) using BPC's well-known ECI (the red arrow). This event has attributes that specify the relationship type (peer-to-peer in this case), a name and namespace for the relationship, and an ECI for the "back channel," the blue link in the diagram. APC has created the back channel in anticipation of connecting. APC stores the back channel ECI and other related information in a "pending subscriptions" map.
  3. BPC responds to the system:requestSubscription event by creating a new channel for the connection, the green channel in the diagram. BPC raises the system:confirmSubscription event on the back channel ECI that APC created in (2) with attributes that include the new channel's ECI. By using the back channel to contact APC, BPC ensures that APC will know who is making contact, preventing spoofing since at this point the back channel ECI represents a shared secret of sorts. BPC stores the new ECI in association with the APC's ECI and the ECI for the new channel it just created in a "subscriptions" map.
  4. APC responds to the system:confirmSubscription event by updating the pending subscription it stored in (2) with the ECI that BPC sent (the green arrow). APC and BPC are now linked.

Alice's PC and Bob's PC now have a symmetric, peer-to-peer relationship that they can use to interact in the future. For example, in the personal cloud desktop screencast, one PC used the channel to send updated profile information so that the contacts database could be kept up to date. There's nothing to say that APC and BPC can only have one relationship. They could create as many different relationships as needed.

Subscriptions are Easy

The good news is that KRL programmers building apps that need intercloud subscription need not really be concerned with most of the details I describe above, although knowing what's going on will help a lot if you have to debug any of this. The CloudOS service contains that rules that make this work.

The hard part, for now, is knowing the well-known ECI of the cloud you want to subscribe to. If you know that, raising a system:subscribe event on the ECI will set the proper chain of events in motion. For example, the following rule would subscribe to the cloud identified by the well-known ECI given in the event attribute well_known_eci.

rule test_subscribe {
  select when test newSubscription
  pre {
    wk_eci = event:attr("well_known_eci");
  always {
    raise system subscribe with
       channelName   = "userProfile";
       namespace     = "myConnections";
       relationship  = "peer-peer";
       targetChannel = wk_eci

The CloudOS service, assuming it's installed in the personal cloud where this rule runs, would take care of the details of establishing the connection. The new channel would be a peer-to-peer relationship in the namespace "myConnections" with the name "userProfile."


There are several things that remain to be done for this service to be ready for general use:

  • The current service doesn't allow Bob to approve the subscription. There ought to be both programatic and manual ways to approve a subscription request. Bob certainly doesn't want to connect to everyone who asks.
  • Event channels need a way of attenuating the kinds of events that are raised on them. For example, Bob may want to allow Alice to only send profile updates.
  • The system needs a means of discovery for well-known ECIs. For now, we just put them all in a white pages, but that doesn't scale. The whole idea of a well-known anything is to not have a list. We could provide discovery by several different mechanisms. We have ideas, but I'm not ready to commit to any of them yet since they're not baked. The simplest scheme involves using a host-meta file at a URL the owner of the personal cloud controls along with the WebFinger protocol. We anticipate XDI helping with this problem eventually.

None of these are minor, but they are reasonable to layer onto the current implementation. The current service provides everything we need for prototype investigations and application development.