Subscriptions API

Notes

  • For all functions, enter the parameters in the order listed.
  • Italicized parameters are optional.
  • Received Events are events of the "wrangler" domain that Wrangler will respond to
  • Raised Events are events that can be selected on within any ruleset in the pico when they occur
  • Sent Events are events that the pico will send elsewhere as a result of triggering a Wrangler event.

"io.picolabs.subscription" must be installed on your pico for these to work

See Managing Subscriptions for an in-depth explanation on the subscription process.

Functions


established

Returns all of the established subscriptions for this pico in an array

Returns

NO ARGS: An array of subscription maps

key and value passed: The array will be filtered according to if the value at the key subscription attribute matches the value parameter

Parameters

ParameterDatatypeDescription
key

String

The subscription attribute that you want to filter for
valueStringThe value of the subscription attribute you want to filter for

Returns 

An array of established subscriptions. Possibly filtered.

Example
establishedArray = subscription:established()
/*
[
  {
    "Tx_host": "http://10.37.68.7:8080", // The host of the other pico
    "Id": "cjrcuow1a001q04rqu6h7ihit", // The ID of the subscription
    "Tx": "5V8ks8hmirW8MfE96aNaHn", // The transmitting channel to send events to on the other pico
    "Rx": "5N8EnBfeCA3ajsniKDZdkQ", // The receiving channel to receive events on this pico
	"Tx_role": "sensor", // The role of the pico on the other end of the subscription
	"Rx_role": "manager", // This pico's role from its own perspective
    "Tx_verify_key": "3SnLikfRD8Cm5JtHaWe26byvcn4f7bQAVVZM2zWEEgUm", // The key used for verifying signed messages sent through the subscription
    "Tx_public_key": "FzkwstPeu7jQamcsY4HycW6f4RmNNPynqCveTiGbsVHy" // The public key used for encrypting messages to send to the other pico
  },
  {
    "Id": "cjrcv4dwt003004rqdonu3ulx",
    "Rx": "E8Ei7TFbUNs4VSqsYHBWhb",
    "Tx": "T7wRhAvKNJocFezx2QCUpY",
    "Tx_verify_key": "FEhBwJFRy9WGx3QQPaKWXSvxB9YRQDNk6QVmX1GW9e6y",
    "Tx_public_key": "5UENb6pXGw5W9Vmz9uKmkzoMWifxWfeDLHsnFhMvkCYK"
  }
]
*/

outbound

Returns the pending outbound subscription requests in an array

Returns

NO ARGS: An array of pending outbound subscription maps

key and value passed: The array will be filtered according to if the value at the key map attribute matches the value parameter

Parameters

ParameterDatatypeDescription
key

String

The outbound subscription attribute that you want to filter for
valueStringThe value of the outbound subscription attribute you want to filter for

Returns 

An array of outbound subscriptions. Possibly filtered.

Example
pendingOutboundSubs = subscription:outbound()
/*
[
  {
    "Id": "cjrcv6tzl003g04rqlri0vqqw",
    "wellKnown_Tx": "HLy15B5xmws3avFpbS6beZ",
    "Rx": "AgZKbAHa47RYytKBAK31DF"
  }
]
*/

inbound

Returns the pending inbound subscription requests in an array

Returns

NO ARGS: An array of pending inbound subscription maps

key and value passed: The array will be filtered according to if the value at the key map attribute matches the value parameter

Parameters

ParameterDatatypeDescription
key

String

The inbound subscription attribute that you want to filter for
valueStringThe value of the inbound subscription attribute you want to filter for

Returns 

An array of inbound subscriptions. Possibly filtered.

Example
pendingInboundSubs = subscription:inbound()
/*
[
  {
    "Id": "cjrcv6tzl003g04rqlri0vqqw", // The ID of the subscription
    "Tx": "AgZKbAHa47RYytKBAK31DF", // The channel to transmit events to on the other pico
    "Rx": "GTh2ZdE6tpWqQQQ3jHL1Dv", // The channel to receive events on for this pico
    "Tx_verify_key": "6H4w3JV3VktkV1hAkYXFbba1d1dYSTQfZ7PgdcBtrnGs", // signing key for sending signed messages
    "Tx_public_key": "GaTt4ChY1Fre39szbRGLVE4waVGJ3qqo1NQWg1nutugN" // public key for encrypting messages
  },
  {
    "Id": "cjrcvvq0e004104rq8obn20e0",
    "Tx": "X9o6b6dhGevQGNZCyg3AEx",
    "Rx": "Rj6ACgfzVhU6PNgbjHhNTz",
    "Tx_verify_key": "HS9rJbPdQjsgY4q18eVxv7QPQkJcTdN14aiorDHeEEhu",
    "Tx_public_key": "DxbYXzoj9ozkHUz2NtWm7aXgGUSuRR8BbQTZeT1aKAni"
  }
]
*/

wellKnown_Rx

Returns the channel map of the WellKnown_Rx for this pico

Returns

A map in the channel map structure, describing the channel for the WellKnown_Rx on this pico.

Example
wellKnownChannel = subscription:wellKnown_Rx()
/*
{
  "id": "Cv1x3ufMEemxoYwFZ41WKb",
  "pico_id": "cjrb850we001cnkrq4in3pd37",
  "name": "wellKnown_Rx",
  "type": "Tx_Rx",
  "policy_id": "cjrcuog6b001l04rqfxz9lnei",
  "sovrin": {
    "did": "Cv1x3ufMEdmxoYwFZ41WKb",
    "verifyKey": "7VddbRHoDdxGBvqL6iYMi83T3QoKxxCLjNijMFawXbcV",
    "encryptionPublicKey": "BX1eddj7carru3KEd4CrAwmxG6S7A16hbpDCSoUXaGdw"
  }
}
*/

autoAcceptConfig

Returns the current autoAccept configuration for subscriptions. This map represents a configuration that you can set for auto accepting subscription requests with the added attribute value.

Returns

A map with the auto accept configuration of the pico's subscriptions ruleset.

Example
subscriptionConfig = subscription:autoAcceptConfig()
/*
{
  "password": [
    "1234"
  ]
}
*/


Received Events


subscription

wrangler:subscription

When a pico receives or raises this event, it initiates the subscription protocol. Through the protocol, a wrangler:inbound_pending_subscription_added event will be raised within the other pico. A wrangler:outbound_pending_subscription_added event will be raised in the pico which received the initial wrangler:subscription event.

Attributes

AttributeDatatypeDescription
wellKnown_TxStringThe wellKnown_Rx channel from the other pico that you want to establish a subscription with.

name

StringThe name of the Rx to be created on each pico. Defaults to a random English word if not given.
channel_typeStringThe channel type that you want both pico's Rx to be
Rx_roleStringDescribes this pico's role in the subscription
Tx_roleStringDescribes the other pico's role in the subscription
IdStringOptionally provide a custom Id for the subscription, defaults to a UUID. Be very careful when providing your own Id.
Tx_hostStringThe network address of the engine hosting the other pico to subscribe to. Defaults to the same engine.
passwordStringNot implemented

Directives Returned

Will return empty directives. 

Corresponding Raised Events:


pending_subscription_approval

wrangler:pending_subscription_approval

Should be raised by the developer as a response to wrangler:inbound_pending_subscription_added. The pico which received a wrangler:inbound_pending_subscription_added event should review the attributes and raise the wrangler:pending_subscription_approval event if the pico accepts the incoming subscription. See the example code for how this can be easily signaled using the "attributes" keyword.

Attributes

Must provide any one of the attributes.

AttributeDatatypeDescription
RxStringThe receiving channel created for this subscription. This is already created and given as an attribute of wrangler:inbound_pending_subscription_added.
TxStringThe channel on the pico that sent the subscription request that was created to receive events from this pico.
IdStringThe subscription Id of the subscription you want to accept. Also given in wrangler:inbound_pending_subscription_added.

Directives Returned

Will return empty directives. 

An example of a rule that raises wrangler:pending_subscription_approval to accept an inbound subscription request.

Example
/*
  rule auto_accept {
    select when wrangler inbound_pending_subscription_added
    pre {
      attributes = event:attrs.klog("inbound subscription attributes: ")
    }
    always {
      raise wrangler event "pending_subscription_approval"
        attributes attributes);
    }
*/

Corresponding Raised Events:


send_event_on_subs

wrangler:send_event_on_subs

This event can be used to send an arbitrary event to one or many subscriptions. Given a subscription ID, it will send the event on that subscription. Given a Tx_role or Rx_role it will send an event to all subscriptions that have that Tx_role or Rx_role recorded.

Attributes

Must provide any one of the attributes.

AttributeDatatypeDescription
domainStringThe domain of the event to send
typeStringThe type of the event you want to send
attrsMapA map of the attributes you want to be associated with the sent event
subIDStringThe subscription ID of the subscription you want to send the event on
Rx_roleStringThe Rx_role of the subscriptions you want to send the event on
Tx_roleStringThe Tx_role of the subscription you want to send the event on

Directives Returned

Will return empty directives. 

outbound_cancellation

wrangler:outbound_cancellation

Raise this within the pico that initiated the subscription creation exchange to cancel an outbound subscription request.

Attributes

Must provide any one of the attributes.

AttributeDatatypeDescription
RxStringThe receiving channel created for this subscription. This is already created and given as an attribute of wrangler:outbound_pending_subscription_added.
IdStringThe subscription Id of the outbound subscription request you want to cancel.

Directives Returned

Will return empty directives. 

Corresponding Raised Events:


inbound_rejection

wrangler:inbound_rejection

Raise this within the pico that has received an inbound_pending_subscription_added event to cancel an an inbound subscription request.

Attributes

Must provide any one of the attributes.

AttributeDatatypeDescription
RxStringThe receiving channel created for this subscription. This is already created and given as an attribute of wrangler:inbound_pending_subscription_added.
IdStringThe subscription Id of the inbound subscription request you want to cancel. Also given in wrangler:inbound_pending_subscription_added.

Directives Returned

Will return empty directives. 

Example
/*
  rule auto_deny {
    select when wrangler inbound_pending_subscription_added
    pre {
      attributes = event:attrs.klog("inbound subscription attributes: ")
    }
    always {
      raise wrangler event "inbound_rejection" 
        attributes event:attrs);
    }
*/

Corresponding Raised Events:


subscription_cancellation

wrangler:subscription_cancellation

Raise this within a pico to cancel its subscription to another pico. 

Attributes

Provide any one of the attributes. 

If none of these attributes are given it will try to cancel the subscription associated with the channel the event was received on.

AttributeDatatypeDescription
RxStringThe receiving channel created for the subscription you want to cancel.
TxStringThe transmitting channel for the subscription you want to cancel.
IdStringThe Id of the subscription you want to cancel.

Directives Returned

Will return empty directives. 

Example
/*
{
  "directives": []
}
*/

Corresponding Raised Events:

Raised Events



subscription_added

wrangler:subscription:added

Fired within a pico whenever a new subscription has been added.

Attributes Added

AttributeDatatypeDescription
IdString

The subscription ID of the added subscription

TxStringThe transmitting channel for the added subscription
Rx_roleStringThe role this pico has in this subscription
Tx_roleString or NULLThe role the other pico has in the subscription
Tx_public_keyString or NULLThe key used for decryption of encrypted messages sent through the subscription
Tx_verify_keyStringThe key used for verifying signed messages to send through the subscription
busMapHolds the above information but contains the receiving channel under key "Rx" and if the other pico is on a different host, its host under key "Tx_host"

The event attributes look like the following structure:

Example
{
  "Id": "cjrl7rbbh005kksrqle152lji",
  "Tx": "DWkbD6URr3JuQWtq9FjzQH",
  "Tx_public_key": "DWbUgvRLhtrp6Zv4CbuMLCZnV9qShsB2bXfW4E5EbEYh",
  "Tx_verify_key": "7pZSMfshJjPhjDbspNgko2KkmfET3pgW733UAZkbKxSX",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "content-type": "application/json",
    "host": "10.37.155.96:8080",
    "content-length": "585",
    "connection": "close"
  },
  "bus": {
    "Tx_host": "http://localhost:8080",
    "Id": "cjrl7rbbh005kksrqle152lji",
    "Rx": "UGRZHTfz5P9AXFb4WXkJF8",
    "Tx": "DWkbD6URr3JuQWtq9FjzQH",
    "Tx_verify_key": "7pZSMfshJjPhjDbspNgko2KkmfET3pgW733UAZkbKxSX",
    "Tx_public_key": "DWbUgvRLhtrp6Zv4CbuMLCZnV9qShsB2bXfW4E5EbEYh"
  }
}

An example of a rule selecting on a new subscription creation.

Example
rule get_peer_ids {
  select when wrangler subscription_added
  foreach subscription:established() setting (subscription)
  pre {
  }
  if (subscription{"Rx_role"}.klog("RX_ROLE: ") == "node") then
    event:send({
      "eci":subscription{"Tx"},
      "eid":"getting_info",
      "domain":"gossip",
      "type":"get_peer_id",
      "attrs":{
        "channel":subscription{"Tx"}
    }
  }, subscription{"Tx_host"}.defaultsTo(meta:host))
  fired {
    ent:subscription_result := event:attrs
  }
}

subscription_removed

wrangler:subscription_removed

Raised within the pico when a subscription has been removed.

Attributes Added

AttributeDatatypeDescription
IdString

The subscription ID of the added subscription

busMapContains more information on the removed subscription

The event attributes look like the following structure:

Example
{
  "Id": "cjrmo1pox002fvkrq36wbu7tk",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "host": "localhost:8080",
    "connection": "keep-alive",
    "accept": "application/json, text/javascript, */*; q=0.01",
    "x-requested-with": "XMLHttpRequest",
    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.81 Safari/537.36",
    "referer": "http://localhost:8080/",
    "accept-encoding": "gzip, deflate, br",
    "accept-language": "en-US,en;q=0.9"
  },
  "bus": {
    "Rx_role": "10",
    "Tx_role": "2",
    "Tx_host": "http://10.37.184.244:8080",
    "Id": "cjrmo1pox002fvkrq36wbu7tk",
    "Tx": "BcAgD4DVKfmhsxKPhi55dz",
    "Rx": "QWEuQaqCP7pdeLR4riPfEs",
    "Tx_verify_key": "6nHdu1Ygf8GZaS2DnFHqjjv5psVvJsPnQfeBV8A6Tqxk",
    "Tx_public_key": "CmLjRfsPrxARqQCUWshDxLosQudvfDBV4iSReHU8qQyr"
  }
}

An example of a rule selecting on a subscription removal.

Example
rule remove_node_entry_after_sub_removal {
  select when wrangler subscription_removed
  pre {
	sub_id = event:attr("Id")
  }
  if (subscription{"Rx_role"}.klog("RX_ROLE: ") == "node") then
  noop()
  fired {
    ent:node_list := ent:node_list.delete([sub_id]);
  }
}

inbound_pending_subscription_added

wrangler:inbound_pending_subscription_added

This event is raised within the pico when a new inbound subscription request has been sent to the pico, and the developer needs to approve it. Typical use is to use the event attributes to determine whether the subscription is one you are expecting, and then raising wrangler:pending_subscription_approval if they are. 

Attributes Added

AttributeDatatypeDescription
IdString

The subscription ID of the added subscription

RxStringThe receiving channel that this pico will receive subscription events on
Rx_roleStringThe role that this pico will take in the subscription
TxStringThe channel to transmit events to on the other pico
Tx_hostStringThe network address of the pico engine hosting the other pico in the subscription
Tx_public_keyString
Tx_roleStringThe role of the other pico in the subscription relationship
Tx_verify_keyString
channel_nameStringThe name of the channel created for the subscription
channel_typeStringThe type of the channel created for the subscription
nameStringAlso the name of the channel created for the subscription
public_keyString
verify_keyString
wellKnown_TxStringThe wellKnown of this pico

The event attributes look like the following structure, depending on the arguments given to wrangler:subscription on the other pico:

Example
{
  "Id": "cjrmog0gd0030vkrqu0eeqax5",
  "Rx": "AQM7aFvb2Yp33pjypNcBhM",
  "Rx_role": "10",
  "Tx": "3naK2ZUH6a4vaWzLvU5cfn",
  "Tx_host": "http://10.37.184.244:8080",
  "Tx_public_key": "6G1fmv3KQd7hXpokesKFKrHE8dJJYpiew4eEAZwWbEKa",
  "Tx_role": "2",
  "Tx_verify_key": "2X4gcL8FGA4qrCniyBmYnfdKN5fitDu843mJtFFR5kBi",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "content-type": "application/json",
    "host": "localhost:8080",
    "content-length": "981",
    "connection": "close"
  },
  "channel_name": "cool",
  "channel_type": "cool sub channel",
  "name": "cool",
  "password": "",
  "public_key": "6G1fmv3KQd7hXpokesKFKrHE8dJJYpiew4eEAZwWbEKa",
  "verify_key": "2X4gcL8FGA4qrCniyBmYnfdKN5fitDu843mJtFFR5kBi",
  "wellKnown_Tx": "5qMBoPpNh2fBnfG7JNk5yD"
}

An example of a rule accepting new subscription requests by selecting on wrangler:inbound_pending_subscription_added:

Example
rule auto_accept {
  select when wrangler inbound_pending_subscription_added
  pre {
  }
  always {
    raise wrangler event "pending_subscription_approval"
      attributes event:attrs
  }
}

outbound_pending_subscription_added

wrangler:outbound_pending_subscription_added

This is raised within the pico that has just initiated a subscription request using wrangler:subscription. This allows manipulation of the outgoing request, including cancelling it if necessary.

Attributes Added

These are currently identical to the attributes passed to wrangler:subscription.

AttributeDatatypeDescription
Rx_roleStringThe role that this pico will take in the subscription
Tx_hostStringThe network address of the pico engine hosting the other pico in the subscription
Tx_roleStringThe role of the other pico in the subscription relationship
channel_typeStringThe type of the channel created for the subscription
nameStringThe name of the channel created for the subscription
wellKnown_TxStringThe wellKnown of the pico the request is being sent to

The event attributes look like the following structure, depending on the arguments given to wrangler:subscription:

Example
{
  "Rx_role": "2",
  "Tx_host": "http://localhost:8080",
  "Tx_role": "10",
  "_headers": { // These were appended from the HTTP communication between the two picos
    "host": "localhost:8080",
    "connection": "keep-alive",
    "accept": "application/json, text/javascript, */*; q=0.01",
    "x-requested-with": "XMLHttpRequest",
    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.81 Safari/537.36",
    "referer": "http://localhost:8080/",
    "accept-encoding": "gzip, deflate, br",
    "accept-language": "en-US,en;q=0.9",
    "if-none-match": "W/\"11-cFrA0CClfKTQMohnyK0tNW5C4dU\""
  },
  "channel_type": "cool sub channel",
  "name": "cool",
  "password": "",
  "wellKnown_Tx": "5qMBoPpNh2fBnfG7JNk5yD"
}

An example of a rule selecting on wrangler:oubound_pending_subscription_added to prepare for the subscription.

Example
rule auto_accept {
  select when wrangler outbound_pending_subscription_added
  pre {
	other_pico_host = event:attr{"Tx_host"}
  }
  if other_pico_host then
    noop()
  fired {
    ent:attempted_hosts := ent:attempted_hosts.append(other_pico_host);
  }
}

outbound_subscription_cancelled

wrangler:outbound_subscription_cancelled

Raised when an outbound subscription has been cancelled through the use of wrangler:outbound_cancellation or the inbound request rejected on the other pico using wrangler:inbound_rejection.

Attributes Added

AttributeDatatypeDescription
IdStringThe Id that had been created for the possible subscription
Rx/TxStringUse the bus attribute to get information. This attribute will change depending on how the subscription was cancelled. It will give a channel that was originally created for the subscription from either pico.
busMap

The internals of the cancelled outbound request. See attached example for its values.

An example of a rule selecting on wrangler:outbound_subscription_cancelled:

Example
rule sub_request_cancelled_or_rejected {
  select when wrangler outbound_subscription_cancelled
  always {
    ent:sub := event:attrs
  }
}

The structure of the bus when the oubound subscription has been cancelled:

Example
{
  "bus": {
    "Id": "cjs51fu2a006kksrq7av62ttd", // the ID of the cancelled subscription request
    "wellKnown_Tx": "5qMBoPpNh2fBnfG7JNk5yD", // The well known of the other pico
    "Rx": "AiPhhS6Tkz7QqmqbRZujEM" // The receiving channel that no longer exists that was created for this pico for the subscription
  }
}

inbound_subscription_cancelled

wrangler:inbound_subscription_cancelled

Raised when an inbound subscription has been cancelled through the use of wrangler:inbound_rejection or the outbound request was rejected on the other pico using wrangler:outbound_cancellation.

Attributes Added

AttributeDatatypeDescription
IdStringThe Id that had been created for the possible subscription
Rx/TxStringUse the bus attribute to get information. This attribute will change depending on how the subscription was cancelled. It will give a channel that was originally created for the subscription from either pico.
busMapThe internals of the cancelled inbound request. The internals of the cancelled outbound request. See attached example for its values.

An example of a rule selecting on wrangler:inbound_subscription_cancelled:

Example
rule inbound_sub_req_cancelled {
  select when wrangler inbound_subscription_cancelled
  always {
    ent:sub := event:attrs
  }
}

The structure of the bus when the inbound subscription has been cancelled:

Example
{
  "bus": {
    "Id": "cjs51fu2a006kksrq7av62ttd", // the ID of the cancelled subscription request
    "Tx": "AiPhhS6Tkz7QqmqbRZujEM", // The transmitting channel that no longer exists that was created for the other pico for the subscription
    "Rx": "8UVQvmstjx7C35D3sKHRy6", // The receiving channel that no longer exists that was created for this pico for the subscription
    "Tx_verify_key": "6J4uxarQkQGc43KZkUhmHwowPAc3Hb5oezLnyoJgvM5k", // The signing key that had been created to allow signing of future subscription events
    "Tx_public_key": "9xvw5iYsPjGirBofxAniXU8w1bZ4CfT6pfmcigZpzGkQ" // The encryption key that had been created to allow encrypted communication of future subscription events
  }
}​_



Copyright Picolabs | Licensed under Creative Commons.