Table of Contents | ||
---|---|---|
|
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.
...
Info |
---|
At the time of writing this, single use configuration is a planned feature. |
Subscription Event Flow
To establish a basic subscription between pico A and pico B:
...
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
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 | subscription_cancellation | inbound_rejection | outbound_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 | established_removal | inbound_removal | outbound_removal | deletes channel used for subscription and updates subscription ruleset persistance | Internally for removing channel used for subscription |
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)
...
Name | Value |
---|---|
name | channel 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 channel'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. |
Subscription Functions
wellKnown_Rx()
wellKnown_Rx() returns the well known channel, e.g.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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.
Code Block | ||
---|---|---|
| ||
[ { "Rx": "5sk3bNLv1aZC1w4Gz9tg7i", "Tx": "BQMnQkRhpwRBspcnz4LdX8", "Tx_verify_key": "6frM5S1t6i2SJh1Rp4AXDpsmwQsCqMjLagsyEKrv6HEN", "Tx_public_key": "DCVx2iExZb6gnumBoHz5GA2rdrt3BbsU41YUJjcF7Peq" } ] |
outbound()
outbound() returns all outbound subscriptions in an array, e.g.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
[ { "wellKnown_Tx": "B5JMLRzZnz7NQcDJuBAPSr", "Rx": "Q4aosn4DiPdEEpqwZZGEbh" } ] |
inbound()
inbound() returns all inbound subscriptions in an array, e.g.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
[ { "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.
...