Introduction to Subscriptions

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:
1. name - name of subscription (if none is supplied, a random subscription name will be generated)
2. name_space - name space for subscription (if none is supplied shared will be used as the name space)
3. my_role - Pico A's role in the subscription (if none is supplied, peer will be used for the role)
4. subscriber_role - Pico B's role in the subscription (also defaults to peer).
5. 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.)
6. channel_type - the channel type for Pico A's yet to be created inbound ECI (if none is supplied, subs will be used).
7. attributes - the attributes for this subscription. These are used for Pico A's incoming channel's attributes.
Pico A creates a channel for the subscription which stores subscription information in the new channel and provides a new inbound eci for this particular subscription.
Pico A sends a wrangler:pending_subscription event to Pico B, using the channel given by the subscriber_eci in step one with the following attributes:
1. name - name of subscription.
2. name_space - name space for subscription.
3. my_role - Pico B's role in the subscription.
4. subscriber_role - Pico A's role in the subscription.
5. outbound_eci - Pico A's newly created inbound ECI. Pico B must receive an ECI to contact Pico A.
6. channel_type - the channel type for Pico B's yet to be created inbound ECI.
7. attributes - the attributes for this subscription. These are used for Pico B's incoming channel's attributes.
Pico B creates a channel for the subscription which stores subscription information in the new channel and provides a new inbound eci for this particular subscription.
Pico A also raises an internal wrangler: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 the wrangler: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 named channel_name giving the name of the channel to approve. Upon successfully creating the subscription. Pico B:
1. sends the wrangler:pending_subscription_approved event to Pico A on Picos B outbound_eci.
2. raises the wrangler:subscription_added event
Upon receiving the wrangler:pending_subscription_approved event, Pico A adds an outbound_eci to the subscription on its side and raises the wrangler:subscription_added internal event.
If Pico B wants to reject the subscription, it raises the wrangler:inbound_subscription_rejection event (internally) with an attribute named channel_name - the name of the channel to reject. Pico B:
1. sends the wrangler:subscription_removal event to Pico A on Picos B outbound_eci.
2. raises the wrangler:subscription_removal event.

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

Subscription Rejection Flow

Subscriptions Functions

Function	Use
subscriptions	List a set of subscriptions depending on what parameters are past.
subscriptionAttributes	Lists a subscriptions attributes
checkSubscriptionName	Checks if a subscriptions name exists

All subscriptions functions return an object with a status and an return object except for checkSubscriptionName. Documentation will reference the return object only.

Subscriptions Actions

Event Domain	Event Type	Actions	Use
wrangler	subscription	creates outbound pending subscription and sends pending_subscription event to external pico	Creates a new outbound pending subscription
wrangler	pending_subscription	creates inbound pending subscription	Creates a new inbound pending subscription
wrangler	pending_subscription_approval	sends pending_subscription_approved event with inbound_eci and outbound status to external pico and raises pending_subscription_approved with inbound status	Aprove inbound pending subscription
wrangler	pending_subscription_approved	updates subscription status and outbound_eci if needed	Internally for adding aproved subscriptions
wrangler	subscription_cancellation \| inbound_subscription_rejection \| outbound_subscription_cancellation	sends subscription_removal event with eci and status and raise the same event to self	alert external pico to remove subscriptions and alert self to remove subscription
wrangler	subscription_removal	deletes channel used for subscription	internally for removing channel used for subscription

subscriptions

returns an array of subscriptions collections keyed to subscriptions. Each subscriptions is owned by the pico which calls this function.

Parameter	Datatype	Required
<id>	<string>
<collection>	<string>
<filtered>	<string>

<id> = <subscription channel_name> | <subscriptions channel_eci> | <subscriptions_name>
<collection> = <name_space> | <relationship> | <status> | <channel_name> | <inbound_eci> | <outbound_eci> | <subscriber_role> | <my_role> | <subscriber_eci>(might break things) |<attributes>
<filtered> = <desired value of collection>

On success

key

value

subscriptions

[{

<name_space:channel_name>:

      {"name_space":<string>,

       "relationship":<string>,

       "status":<string>,

       "channel_name":<string>,

       "inbound_eci":<string>,

       "subscriber_role":<string>,

       "my_role":<string>,

       "subscriber_eci":<string>,

       "attributes":<string>,

       "subscription_name":<string>

},

},..{}n

]

uses example

response = v1_wrangler:subscriptions(null,null,null){"subscriptions"}; // all subscriptions
response = v1_wrangler:subscriptions("flipper",null,null){"subscriptions"}; // single "flipper" subscriptions
response = v1_wrangler:subscriptions(null,"status",null){"subscriptions"}; // collection of subscriptions by status
response = v1_wrangler:subscriptions(null,"status","inbound"){"subscriptions"}; // collection of subscriptions with "inbound" as status

Managing Subscriptions