Table of Contents

maxLevel	3

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.

...

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. only outbound eci should Events should be used to raise events toosent 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. attributesattrs - 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.
Pico A sends a wrangler:pending_subscription event to Pico B, using the channel given by the subscriber_eci in 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 (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.
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 event. Pico A raises wranglerraises the wrangler:outbound_pending_subscription_event_added internal event event.
The state of each Picos subscription is static at this point. Pico A has on out going pending an outgoing pending subscription and Pico B has an in coming pending an incoming pending subscription.
If Pico B wants to approve the subscription request, it raises the wrangler:pending_subscription_approval event (internally) with an attribute named channelsubscription_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 Picos Pico B's outbound_eci value stored in its subscription.
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. event.
1. Pico A then raises the wrangler:sending_key event to faclitate a key exchange with the pico it is subscribing to.
If Pico B wants to reject the subscription, it raises the wrangler:inbound_subscription_rejectioncancellation event (internally) with an attribute named channelsubscription_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

...

Image Added

Subscription Approval Flow

Image Removed

Image Added

Subscription Rejection Flow

Image RemovedImage Added

Subscription Events

Subscriptions Functions

...

Function

...

Use

...

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

Info
This section mentions getSubscriptions(), which is documented in the last section, Subscription Functions.

Overview

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

Events Users Might Raise

wrangler:subscription
wrangler:outbound_subscription_cancellation
wrangler:inbound_subscription_rejection
wrangler:subscription_cancellation
wrangler:pending_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> = <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>,

_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)

Name	Default	Use
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
name	string including a random English word	If 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"
subscriber_eci	the subscription won't be created	the subscription process needs one of pico B's existing eci's
subscriber_host	none	the 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

Name	Default	Use
subscription_name	no subscription cancelled	the full name of the subscription to cancel - both picos will receive wrangler:subscription_removed

wrangler:pending_subscription_approval (pico B)

Name	Default	Use
subscription_name	no subscription approved	the full name of the pending subscription to approve - both picos will receive wrangler:subscription_added

wrangler:outbound_pending_subscription_added (pico A)

Name	Value
attributes	attrs in wrangler:subscription
channel_name	full subscription name(e.g. "namespace:name")
channel_type	defined in wrangler:subscription
inbound_eci	pico A's new eci created for the subscription
my_role	defined in wrangler:subscription
name	defined in wrangler:subscription
name_space	defined in wrangler:subscription
relationship	string of the form `my_role+"<->"+subscriber_role`
status	"outbound"
subscriber_eci	defined in wrangler:subscription
subscriber_host (only included if the picos are hosted on different engines)	defined in wrangler:subscription
subscriber_role	defined in wrangler:subscription

example value of getSubscriptions(){channel_name}:

Code Block

   { "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)

Name	Value
attributes	attrs in wrangler:subscription
channel_name	full subscription name(e.g. "namespace:name")
channel_type	defined in wrangler:subscription
my_role	subscriber_role in wrangler:subscription
name	defined in wrangler:subscription
name_space	defined in wrangler:subscription
outbound_eci	pico A's new eci created for the subscription
relationship	string 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_role	my_role in wrangler:subscription

example value of getSubscriptions(){channel_name}:

Code Block
{ "

...

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

...

},..{}n

]

uses example

Code Block

language	javascript
theme	Confluence

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

...

"http://localhost:8080"} }

wrangler:subscription_removed

Name	Value
removed_subscription	the value of getSubscriptions(){full subscription name} before it was removed

wrangler:subscription_added

Name	Value
channel_name	full subscription name(e.g. "namespace:name")
verify_key	public cryptographic key used to verify digital signatures
other_verify_key	the public crytpographic key from the pico that this pico is subscribed to. Used to verify digitally signed messages
encryption_public_key	the public key that can can be used by another channel to create a shared secret, in conjuction with that channl's private key, to allow encryption and decryption.
other_encryption_public_key	the public cryptographic key form the pico that this pico is subscribed to. It is used to allow encryption of channel messages.

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

Code Block

   { "eci": "cj3lyamf30003pi0n6u39rsqs", // pico A's new eci
     "name": "namespace:name",
     "type": "subscription",
     "verify_key": "F9S4uC6bZ9pDBZMPeKUHCHrhdMkrTq9GExj8HHtGDTKq",
	 "other_verify_key": "GjmSgqkBpAcCkt9H179pqgrQ27zPn336aaNHHHtFspAz",
     "encryption_public_key": "3cyFiAMRpq1Q4ciEzSoQNzAQHr9voTCu9P46Kyx6qCUz",
     "other_encryption_public_key": "7y9dqgw7KucvYToAguuBP4Shf1cqtnhUF93waBR799e3",
     "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",
        "outbound_eci": "cj3n6fe0w0003v8id271a0rlz" } } // now available to pico A

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

Code Block

   { "eci": "cj3n6fe0w0003v8id271a0rlz", // pico B's new eci
     "name": "namespace:name",
     "type": "subscription",
     "verify_key": "GjmSgqkBpAcCkt9H179pqgrQ27zPn336aaNHHHtFspAz",
	 "other_verify_key": "F9S4uC6bZ9pDBZMPeKUHCHrhdMkrTq9GExj8HHtGDTKq",
     "encryption_public_key": "7y9dqgw7KucvYToAguuBP4Shf1cqtnhUF93waBR799e3",
     "other_encryption_public_key": "3cyFiAMRpq1Q4ciEzSoQNzAQHr9voTCu9P46Kyx6qCUz",
     "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" } }

Subscription Functions

getSubscriptions

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

Parameter	Datatype	Required
<collectBy>	<hash path>	no
<filterValue>	<string>	no, and don't use if <collectBy> is omitted

getSubscriptions() with no arguments returns the entire map, e.g.

Code Block

{
  "namespace:name1": {
    "name": "namespace:name1",
    "attributes": {
      "status": "subscribed",
      ...
    },
    ...
  },
  "namespace:name2": {
    "name": "namespace:name2",
    "attributes": {
      "status": "inbound",
      ...
    },
    ...
  }
}

getSubscriptions(["attributes", "status"]) collects by the value at that hash path, returning a map from subscription statuses (in this example) to arrays of subscription objects with those values, e.g.

Code Block

{
  "inbound": [
    {
      "namespace:name2": {
        "name": "namespace:name2",
        "attributes": {
          "status": "inbound",
          ...
        },
        ...
      }
    }
  ],
  "subscribed": [
    {
      "namespace:name1": {
        "name": "namespace:name1",
        "attributes": {
          "status": "subscribed",
          ...
        },
        ...
      }
    }
  ]
}

getSubscriptions(["attributes", "status"], "inbound") uses "inbound" as the filter value, returning only the first array above.

Versions Compared

Old Version 10

New Version Current

Key

Introduction to Subscriptions

Initial Subscription Flow

Subscription Approval Flow

Subscription Rejection Flow

Subscription Events

Subscriptions Functions

Subscriptions Actions

Overview

Events Users Might Raise

subscriptions

Events Users Might React To

Event Attributes

Subscription Functions

getSubscriptions

Page Comparison

Versions Compared

Old Version 10

New Version Current

Key

Introduction to Subscriptions

Initial Subscription Flow

Subscription Approval Flow

Subscription Rejection Flow

Subscription Events

Subscriptions Functions

Subscriptions Actions

Overview

Events Users Might Raise

subscriptions

Events Users Might React To

Event Attributes

Subscription Functions

getSubscriptions