Skip to end of metadata
Go to start of metadata

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:

  1. 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 the subscription has been accepted. Events should be sent to the outbound eci, not the original subscriber eci.)
    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. attrs - the attributes for this subscription. These are used for Pico A's incoming channel's attributes. If none are supplied, the default is "status".
    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.
  2. 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.
    6. channel_type - the channel type for Pico B's yet to be created inbound ECI (the same as Pico A's).  
    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. 
  3. Upon receiving the wrangler:pending_subscription event, Pico B, creates a pending subscription (channel mentioned above) and raises the wrangler:inbound_pending_subscription_added event. Pico A raises the wrangler:outbound_pending_subscription_added event.
    The state of each Picos subscription is static at this point. Pico A has an outgoing pending subscription and Pico B has an incoming pending subscription.
  4. If Pico B wants to approve the subscription request, it raises the wrangler:pending_subscription_approval event 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 Pico B's outbound_eci value stored in its subscription.
    2. raises the wrangler:subscription_added event
  5. 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 event. 
  6. 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, which then raises the wrangler:subscription_removed event to itself.
    2. raises the wrangler:subscription_removal event, which raises the wrangler:subscription_removed 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

Subscription Events

This section mentions getSubscriptions(), which is provided by the Subscriptions ruleset and returns a map from all subscription names to subscription objects.

Overview

Event Domain

Event Type

Actions

Use

wranglersubscription

creates outbound pending subscription and sends pending_subscription event to external pico

Creates a new outbound pending subscription
wranglerpending_subscriptioncreates inbound pending subscriptionCreates a new inbound pending subscription
wranglerpending_subscription_approvalsends pending_subscription_approved event with inbound_eci and outbound status to external pico and raises pending_subscription_approved with inbound statusAprove inbound pending subscription
wranglerpending_subscription_approvedupdates subscription status and outbound_eci if neededInternally 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 selfalert external pico to remove subscriptions and alert self to remove subscription
wranglersubscription_removaldeletes channel used for subscriptioninternally for removing channel used for subscription

Events Users Might Raise

  • wrangler:subscription
  • wrangler:outbound_subscription_cancellation
  • wrangler:inbound_subscription_rejection
  • wrangler:subscription_cancellation
  • wrangler:pending_subscription_approval

Events Users Might React To

  • wrangler:outbound_pending_subscription_added
  • wrangler:inbound_pending_subscription_added
  • wrangler:subscription_removed
  • wrangler:subscription_added

Event Attributes

wrangler:subscription (pico A)

NameDefaultUse
attrs"status"additional data to store for the new subscription - can be any type
channel_type"subs"describes each pico's new channel created for the subscription
my_role"peer"describes pico A (self) in the context of the subscription
namestring including a random English wordIf a subscription with the same combination of name and namespace exists in the engine hosting pico A, the subscription won't be created. Otherwise, pico A will receive wrangler:outbound_pending_subscription_added and pico B will receive wrangler:inbound_pending_subscription_added.

If pico B is hosted on a different engine and a subscription with this full name already exists there (e.g. "namespace:name"), the new subscription will be cancelled and both picos will receive wrangler:subscription_removed after the '_added' events.
name_space"shared" (doesn't work in 0.11.x)
subscriber_ecithe subscription won't be createdthe subscription process needs one of pico B's existing eci's
subscriber_hostnonethe public DNS name of the engine hosting pico B (only needed if different from pico A's) - e.g. "https://localhost:8080"
subscriber_role"peer"describes pico B in the context of the subscription


wrangler:outbound_subscription_cancellation
,
wrangler:inbound_subscription_rejection,
wrangler:subscription_cancellation

NameDefaultUse
subscription_nameno subscription cancelledthe full name of the subscription to cancel - both picos will receive wrangler:subscription_removed


wrangler:pending_subscription_approval
(pico B)

NameDefaultUse
subscription_nameno subscription approvedthe full name of the pending subscription to approve - both picos will receive wrangler:subscription_added


wrangler:outbound_pending_subscription_added
(pico A)

NameValue
attributesattrs in wrangler:subscription
channel_namefull subscription name (e.g. "namespace:name")
channel_typedefined in wrangler:subscription
inbound_ecipico A's new eci created for the subscription
my_roledefined in wrangler:subscription
namedefined in wrangler:subscription
name_spacedefined in wrangler:subscription
relationshipstring of the form my_role+"<->"+subscriber_role
status"outbound"
subscriber_ecidefined in wrangler:subscription
subscriber_host (only included if the
picos are hosted on different engines)
defined in wrangler:subscription
subscriber_roledefined in wrangler:subscription


example value of getSubscriptions(){channel_name}:

   { "eci": "cj3lyamf30003pi0n6u39rsqs", // pico A's new eci
     "name": "name_space:name",
     "type": "subs",
     "attributes": 
      { "subscription_name": "name",
        "name_space": "namespace",
        "relationship: "peer 1<->peer 2",
        "my_role": "peer 1",
        "subscriber_role": "peer 2",
        "subscriber_eci": "cj3ly7c9m0002pl0nk2zklk4g",
        "status": "outbound",
        "attributes": "status",
        "subscriber_host": "http://localhost:8081",
        "sid": "namespace:name" } }


wrangler:inbound_pending_subscription_added
(pico B)

NameValue

attributes

attrs in wrangler:subscription
channel_namefull subscription name (e.g. "namespace:name")
channel_typedefined in wrangler:subscription
my_rolesubscriber_role in wrangler:subscription
namedefined in wrangler:subscription
name_spacedefined in wrangler:subscription
outbound_ecipico A's new eci created for the subscription
relationshipstring of the form my_role+"<->"+subscriber_role
status"inbound"
subscriber_host (only included if the
picos are hosted on different engines)
public DNS name of the engine hosting pico A
subscriber_rolemy_role in wrangler:subscription


example value of getSubscriptions(){channel_name}:

   { "eci": "cj3n6fe0w0003v8id271a0rlz", // pico B's new eci
     "name": "namespace:name",
     "type": "subs",
     "attributes": 
      { "subscription_name": "name",
        "name_space": "namespace",
        "relationship": "peer 2<->peer 1",
        "my_role": "peer 2",
        "subscriber_role": "peer 1",
        "outbound_eci": "cj3lyamf30003pi0n6u39rsqs",
        "status": "inbound",
        "attributes": "status",
        "subscriber_host": "http://localhost:8080",
        "sid": "namespace:name" } }


wrangler:subscription_removed

NameValue
removed_subscriptionthe value of getSubscriptions(){full subscription name} before it was removed


wrangler:subscription_added

NameValue
channel_namefull subscription name (e.g. "namespace:name")


example value of getSubscriptions(){channel_name}: (pico A)

   { "eci": "cj3lyamf30003pi0n6u39rsqs", // pico A's new eci
     "name": "namespace:name",
     "type": "subs",
     "attributes": 
      { "subscription_name": "name",
        "name_space": "namespace",
        "relationship": "peer 1<->peer 2",
        "my_role": "peer 1",
        "subscriber_role": "peer 2",
        "subscriber_eci": "cj3ly7c9m0002pl0nk2zklk4g",
        "status": "subscribed", // changed
        "attributes": "status",
        "subscriber_host": "http://localhost:8081",
        "sid": "namespace:name",
        "outbound_eci": "cj3n6fe0w0003v8id271a0rlz" } } // now available to pico A


example value of getSubscriptions(){channel_name}: (pico B)

   { "eci": "cj3n6fe0w0003v8id271a0rlz", // pico B's new eci
     "name": "namespace:name",
     "type": "subs",
     "attributes": 
      { "subscription_name": "name",
        "name_space": "namespace",
        "relationship": "peer 2<->peer 1",
        "my_role": "peer 2",
        "subscriber_role": "peer 1",
        "outbound_eci": "cj3lyamf30003pi0n6u39rsqs",
        "status": "subscribed", // changed
        "attributes: "status",
        "subscriber_host": "http://localhost:8080",
        "sid": "namespace:name" } }

Subscription Functions

The following subscription functions are not yet implemented.

Function
Use
subscriptionsList a set of subscriptions depending on what parameters are given.
subscriptionAttributesLists a subscription's attributes
checkSubscriptionNameChecks if a subscription's name exists

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

subscriptions

returns an array of subscription collections keyed to subscriptions. Each subscription object is owned by the pico that 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>
       }
,...

}

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



  • No labels