Introduction to Subscriptions

Subscriptions allow two picos to communicate with each other on a secure channel, augmenting the parent-child hierarchy to create peer-to-peer structures.  From each pico's perspective there is a receiving channel, Rx, and a transmitting channel, Tx. The pico receives events and queries from the other pico in the subscriptions over the Rx channel and makes queries and sends events to the other pico using the Tx channel. 

Subscriptions do not have to have the same parent. For example, in the Forever application, the picos belonged to different people and represented their personal contact information. 
Subscriptions are established by a pico accepting a request from another pico. Subscriptions' details are listed below.

Well Known Rx

When the subscription ruleset is installed, a well known Rx channel is created. As a reminder, a channel contains three pieces of information: the long identifier (eci), a name, and a descriptive type. The well known channel name is wellKnown_Rx with Tx_Rx as its channel type. This channel is used to establish new subscriptions between picos, and is meant to be publicly shared with potential subscribers. In the future this channel will use policies to restrict events to only subscription requests, making your engine more secure.

A wellKnown_Rx can be accessed by querying subscriptions wellKnown_Rx() function.

Simple Subscription

A simple subscription only contains what is needed for secure communication.

To create a simple subscription request from pico A to pico B. Raise a wrangler subscription event to pico A containing an attribute named "wellKnown_Tx" , and the value set to pico B's wellKnown_Rx.

Directional Subscription

A directional subscription is a subscription that stores roles, providing an easier way to identify master slave relationships in a subscription.

To create a directional subscription request from pico A to pico B. Raise a wrangler subscription event to pico A with additional attributes, Rx_role, Tx_role.  Rx_role is pico A's role in the subscription, leaving Tx_role to be pico B's role in the subscription relationship.

Cross Engine Subscription

It is easy to imagine a situation where you want to create a subscritption between picos hosted on different engines. Cross engine subscriptions allow us to do so by storing the host of the other pico in a subscription relationship.

To create a cross engine subscription between pico A and pico B, raise a wrangler subscription event to pico A with event attribute Tx_host.  Tx_host is pico B's engine host url including protocol, for example, "http://localhost:8282".

Accepting Subscription Request

After you raise the initiating event wrangler subscription to pico A, the inner workings of the subscription ruleset will automatically make a subscription request to pico B. This subscription request must be accepted by pico B before the subscription can be established. 

To accept an inbound subscription request from pico A to pico B, raise a wrangler pending_subscription_approval event to pico B with a Rx event attribute. The value of that event attribute will be the "Rx" attribute stored in the incoming request. You can find this value by looking at pico B's subscription ruleset entity variables on the UI, or by querying pico B's subscription ruleset inbound() function.

Auto Accepting Subscription Request

The Subscription ruleset is configurable to auto accept subscription requests if given certain attributes.  A Subscription request with attributes that matches any configured attribute and corresponding value will be auto accepted.

To configure an attribute for auto accepting subscriptions, Raise a wrangler autoAcceptConfigUpdate event with attributes, regex_str and variable.  The variable is the added attribute name.  The regex_str is the value of the added attribute that will trigger autoacceptance.

Subscription Event Flow

To establish a basic subscription between pico A and pico B:

1. Pico A receives a wrangler:subscription event which includes a wellKnown_Tx attribute. wellKnown_Tx is Pico B's wellKnown_Rx .  Pico A then creates a channel for the subscription which is stored as Rx.
2. Pico A sends pico B wrangler:pending_subscription with attribute status set to inbound. Pico A sends all attributes it received with the following key attributes updated.
   
   1. Tx - Pico A Rx.
   2. Tx_verify_key - Pico A's Rx channel verifyKey.
   3. Tx_public_key - Pico A's Rx channel encryptionPublicKey.
   4. name - name used for channel.
   5. channel_type - string used for channel type
3. Pico B creates a Rx channel for the subscription which is stored as Rx along with Tx , Tx_verify_key, Tx_public_key in inbound subscription entity variable.
   Pico A also raises an internal  wrangler:pending_subscription event with status set to outbound, with the corresponding attributes above which is stored in outbound subscription entity variable. 
4. After storing pending subscriptions, Pico B and Pico A raises corresponding wrangler:inbound_pending_subscription_added event and 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.
5. If Pico B wants to approve the subscription request, it raises the wrangler:pending_subscription_approval event with an attribute Rx containing the Rx channel identifier of the subscription to approve.  Upon successfully storing the subscription in established entity variable. Pico B: 
   1. sends the wrangler:pending_subscription_approved event with attribute status set to outbound to Pico A on Pico B's subscriptions Tx. 
   2. raises an API internal event wrangler:subscription_added.
6. Upon receiving the wrangler:pending_subscription_approved event, Pico A adds an Tx eci to the subscription and stores the subscription in established entity variable.  And raises the wrangler:subscription_added event.
7. If Pico B wants to reject the subscription, it raises the wrangler:subscription_cancellation event (internally) with an attribute named Rx - which is the Rx of the subscription to reject. Pico B:
   1. sends the wrangler:established_removal event to Pico A on Picos B Tx eci, which then raises an internal API wrangler:subscription_removed event to itself.
   2. raises the wrangler:established_removal event, which then raises an internal API wrangler:subscription_removed event.

Upon receiving a wrangler:established_removal event, the pico deletes the specified subscription from the established entity variable.

Initial Subscription Flow

Subscription Approval Flow

Subscription Rejection Flow

Subscription Events

Overview

Events Users Could Raise

• wrangler:subscription
• wrangler:pending_subscription_approval
• wrangler:outbound_cancellation
• wrangler:inbound_rejection
• wrangler:subscription_cancellation

Events Users Could React To

• wrangler:subscription_added
• wrangler:subscription_removed

Event Attributes

wrangler:subscription (pico A)

wrangler:outbound_cancellation,
wrangler:inbound_rejection,
wrangler:subscription_cancellation

wrangler:pending_subscription_approval (pico B)

wrangler:outbound_pending_subscription_added (pico A)

wrangler:inbound_pending_subscription_added (pico B)

wrangler:subscription_removed

wrangler:subscription_added

Subscription Functions

wellKnown_Rx()

wellKnown_Rx() returns the well known channel, e.g.

{
  "id": "4H2tXa1NkexgyfEbzCFsPE",
  "pico_id": "cjc78fh4s000b9iry4u2j2len",
  "name": "wellKnown_Rx",
  "type": "Tx_Rx",
  "sovrin": {
    "did": "4H2tXa1NkexgyfEbzCFsPE",
    "verifyKey": "2naJczreMuFRiDJcc3SWpP4CkXVSuViKMNq4gRmh3Tzq",
    "encryptionPublicKey": "G3Xq6daaUndzwjiP8H1WFt9fKKb2NCbZtEVwGqXLuGMC"
  }
}

established()

established() returns all established subscription in an array, e.g.

[
  {
    "Rx": "5sk3bNLv1aZC1w4Gz9tg7i",
    "Tx": "BQMnQkRhpwRBspcnz4LdX8",
    "Tx_verify_key": "6frM5S1t6i2SJh1Rp4AXDpsmwQsCqMjLagsyEKrv6HEN",
    "Tx_public_key": "DCVx2iExZb6gnumBoHz5GA2rdrt3BbsU41YUJjcF7Peq"
  }
]

outbound()

outbound() returns all outbound subscriptions in an array, e.g.

[
  {
    "wellKnown_Tx": "B5JMLRzZnz7NQcDJuBAPSr",
    "Rx": "Q4aosn4DiPdEEpqwZZGEbh"
  }
]

inbound()

inbound() returns all inbound subscriptions in an array, e.g.

[
  {
    "Tx": "Q4aosn4DiPdEEpqwZZGEbh",
    "Rx": "MvgUk1pHSFHqtzpUKkJErC",
    "Tx_verify_key": "Da2dgGAEFPLJV4bTP6kYTdphUXcJaQ5Zrnq5rnMXS5UZ",
    "Tx_public_key": "39V93tWrxWBK2Anez4Mz6J6ec8eX3v7ZcTEdsEMSL42a"
  }
  {
    "Rx_role": "teacher",
    "Tx_role": "student",
    "Tx_host": "http://localhost:8040",
    "Tx": "WeEHHsfEVoS2to7LSpyrC8",
    "Rx": "SCmhMnquJrwxoM5SLmofjv",
    "Tx_verify_key": "HA3Dc9K5H4g2njJ6yFGsoi6d3tchs7RN91d9sbpJupi4",
    "Tx_public_key": "BVr8EBML6cbRtUvaxDV44TXjN1dHRiwFS7XpNiAfrGqC"
  }
]

autoAcceptConfig()

autoAcceptConfig() returns all auto accepted attributes keyed to array of possible values. In the future this may be remove for security.

{
  "password": [
    "toor"
  ]
}