Table of Contents | ||
---|---|---|
|
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:name
- name of subscription (if none is supplied, a random subscription name will be generated)name_space
- name space for subscription (if none is suppliedshared
will be used as the name space)my_role
- Pico A's role in the subscription (if none is supplied,peer
will be used for the role)subscriber_role
- Pico B's role in the subscription (also defaults topeer
).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.)channel_type
- the channel type for Pico A's yet to be created inbound ECI (if none is supplied,subs
will be used).attributes
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 sends a
wrangler:pending_subscription
event to Pico B, using the channel given by thesubscriber_eci in
in step one with the following attributes:name
- name of subscription.name_space
- name space for subscription.my_role
- Pico B's role in the subscription.subscriber_role
- Pico A's role in the subscription.outbound_eci
- Pico A's newly created inbound ECI. Pico B must receive an ECI to contact Pico A.channel_type
- the channel type for Pico B's yet to be created inbound ECI (the same as Pico A's).attributes
- the attributes for this subscription. These are used for Pico B's incoming channel's attributes.
Pico A also raises an internalwrangler: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 thewrangler:inbound_pending_subscription_event_added
internal event event. Pico A raises wranglerraises thewrangler: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 namedchannelsubscription_name
giving the name of the channel/subscription to approve. Upon successfully creating the subscription. Pico B:- sends the
wrangler:pending_subscription_approved
event to Pico A on Picos Pico B'soutbound_eci
value stored in its subscription. - raises the
wrangler:subscription_added
event
- sends the
- Upon receiving the
wrangler:pending_subscription_approved
event, Pico A adds an outbound_eci to the subscription on its side and raises thewrangler:subscription_added
internal event. event.- 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 namedchannelsubscription_name
- the name of the channel/subscription to reject. Pico B:- sends the
wrangler:subscription_removal
event to Pico A on Picos B outbound_eci, which then raises thewrangler:subscription_removed
event to itself. - raises the
wrangler:subscription_removal
event, which raises thewrangler:subscription_removed
event.
- sends the
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
Subscriptions Functions
...
...
...
All subscriptions functions return an object with a status and an return object except for checkSubscriptionName. Documentation will reference the return object only.
...
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_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": "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.