Introduction to Subscriptions

Subscriptions allow two picos to communicate with each other on a secure channel. Subscriptions have several advantages and uses:

...

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. 

...

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 subscription_name giving the name of the channel/subscription 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. 
   1. Pico A then raises the wrangler:sending_key event to faclitate a key exchange with the pico it is subscribing to.
6. If Pico B wants to reject the subscription, it raises the wrangler:subscription_cancellation event (internally) with an attribute named subscription_name - the name of the channel/subscription 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

Overview

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)

...

   { "eci": "cj3n6fe0w0003v8id271a0rlz", // pico B's new eci
     "name": "namespace:name",
     "type": "subssubscription",
    
     "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

...

...

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

   { "eci": "cj3lyamf30003pi0n6u39rsqs", // pico A's new eci
     "name": "namespace:name",
     "type": "subscription",
     "verify_key": "F9S4uC6bZ9pDBZMPeKUHCHrhdMkrTq9GExj8HHtGDTKq",
	 "other_verify_key": "GjmSgqkBpAcCkt9H179pqgrQ27zPn336aaNHHHtFspAz",
     "encryption_public_key": "3cyFiAMRpq1Q4ciEzSoQNzAQHr9voTCu9P46Kyx6qCUz",
     "typeother_encryption_public_key": "subs7y9dqgw7KucvYToAguuBP4Shf1cqtnhUF93waBR799e3",
     "attributes": 
      { "subscription_name": "name",
        "name_space": "namespace",
        "relationship": "peer 1<->peer 2",
        "my_role": "peer 1",
        "subscriber_role": "peer 2",
        "subscriber_eci": "cj3ly7c9m0002pl0nk2zklk4g",
        "status": "status"subscribed", // changed
        "attributes": "status",
        "subscriber_host": "subscribedhttp://localhost:8081", // changed
        "attributesoutbound_eci": "statuscj3n6fe0w0003v8id271a0rlz", } } // now available to pico  "subscriber_hostA

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

   { "eci": "http://localhost:8081cj3n6fe0w0003v8id271a0rlz", // pico B's new eci
     "sidname": "namespace:name",
  
     "outbound_ecitype": "cj3n6fe0w0003v8id271a0rlzsubscription",
} } // now available to pico A

...

   { "eci "verify_key": "GjmSgqkBpAcCkt9H179pqgrQ27zPn336aaNHHHtFspAz",
	 "other_verify_key": "cj3n6fe0w0003v8id271a0rlzF9S4uC6bZ9pDBZMPeKUHCHrhdMkrTq9GExj8HHtGDTKq", // pico B's new eci
     "nameencryption_public_key": "namespace:name7y9dqgw7KucvYToAguuBP4Shf1cqtnhUF93waBR799e3",
     "typeother_encryption_public_key": "subs3cyFiAMRpq1Q4ciEzSoQNzAQHr9voTCu9P46Kyx6qCUz",
     "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

getSubscriptions

Returns a map from subscription names to subscription objects, or various forms of this map.

...