Subscriptions allow two picos to communicate with each other on a secure channel. Subscriptions have several advantages and uses:
- Subscriptions can occur between any two picos, augmenting the parent-child hierarchy to create peer-to-peer structures.
- Subscriptions allow picos to establish communication channels with relationships.
Subscriptions are formed from two channels from two different Picos. Each channel has a corresponding Eci stored for the other Picos channel.
From each pico's perspective there is an incoming channel and an outgoing channel. The pico receives events and queries from the other pico in the subscriptions over the incoming channel and makes queries and sends events to the other pico using the outgoing channel.
Subscriptions can exist between any two picos. They do not have to have the same parent. In the Forever application, for example, the picos belonged to different people and represented their personal contact information.
There are several important steps in establishing a subscription:
- Pico A receives a
wrangler:subscription
event that includes the following attributes:name
- name of subscription (if none is supplied, a random subscription name will be generated)name_space
- name space for subscription (if none is suppliedshared
will be used as the name space)my_role
- Pico A's role in the subscription (if none is supplied,peer
will be used for the role)subscriber_role
- Pico B's role in the subscription (also defaults topeer
).subscriber_eci
- Pico B's well known ECI. Pico A must receive an ECI to contact Pico B. (This eci will be stored after subscription has been accepted. only outbound eci should be used to raise events too.)channel_type
- the channel type for Pico A's yet to be created inbound ECI (if none is supplied,subs
will be used).attributes
- the attributes for this subscription. These are used for Pico A's incoming channel's attributes.
- Pico A sends a
wrangler:pending_subscription
event to Pico B, using the channel given by thesubscriber_eci in step one with the following attributes:
name
- name of subscription.name_space
- name space for subscription.my_role
- Pico B's role in the subscription.subscriber_role
- Pico A's role in the subscription.- outbound_eci - Pico A's newly created inbound ECI. Pico B must receive an ECI to contact Pico A.
channel_type
- the channel type for Pico B's yet to be created inbound ECI.attributes
- the attributes for this subscription. These are used for Pico B's incoming channel's attributes.
Pico A also raises an internalwrangler:pending_subscription
event with the corresponding attributes above. - Upon receiving the
wrangler:pending_subscription
event, Pico B, creates a pending subscription(channel mentioned above) and raises thewrangler:inbound_pending_subscription_event_added
internal event. Pico A raises wrangler:outbound_pending_subscription_event_added internal event.
The state of each Picos subscription is static at this point. Pico A has on out going pending subscription and Pico B has an in coming pending subscription. - If Pico B wants to approve the subscription request, it raises the
wrangler:pending_subscription_approval
event (internally) with an attribute namedchannel_name
giving the name of the channel to approve. Upon successfully creating the subscription. Pico B:- sends the
wrangler:pending_subscription_approved
event to Pico A on Picos B outbound_eci. - raises the
wrangler:subscription_added
event
- sends the
- Upon receiving the
wrangler:pending_subscription_approved
event, Pico A adds an outbound_eci to the subscription on its side and raises thewrangler:subscription_added
internal event. - If Pico B wants to reject the subscription, it raises the
wrangler:inbound_subscription_rejection
event (internally) with an attribute namedchannel_name
- the name of the channel to reject. Pico B:- sends the
wrangler:subscription_removal
event to Pico A on Picos B outbound_eci. - raises the
wrangler:subscription_removal
event.
- sends the
Upon receiving a wrangler:subscription_removal
event, the pico deletes the named subscription from the inbound or outbound subscriptions list as appropriate.
Initial Subscription Flow
Subscription Approval Flow