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. Returns all of the established subscriptions for this pico in an array 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 String Returns An array of established subscriptions. Possibly filtered. Returns the pending outbound subscription requests in an array 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 String Returns An array of outbound subscriptions. Possibly filtered. Returns the pending inbound subscription requests in an array 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 String Returns An array of inbound subscriptions. Possibly filtered. Returns the channel map of the WellKnown_Rx for this pico A map in the channel map structure, describing the channel for the WellKnown_Rx on this pico. 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. A map with the auto accept configuration of the pico's subscriptions ruleset. 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. name Will return empty directives. Corresponding Raised Events: 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. Must provide any one of the attributes. Will return empty directives. An example of a rule that raises wrangler:pending_subscription_approval to accept an inbound subscription request. Corresponding Raised Events: 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. Must provide any one of the attributes. Will return empty directives. Raise this within the pico that initiated the subscription creation exchange to cancel an outbound subscription request. Must provide any one of the attributes. Will return empty directives. Corresponding Raised Events: Raise this within the pico that has received an inbound_pending_subscription_added event to cancel an an inbound subscription request. Must provide any one of the attributes. Will return empty directives. Corresponding Raised Events: Raise this within a pico to cancel its subscription to another pico. 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. Will return empty directives. Corresponding Raised Events: Fired within a pico whenever a new subscription has been added. The subscription ID of the added subscription The event attributes look like the following structure: An example of a rule selecting on a new subscription creation. Raised within the pico when a subscription has been removed. The subscription ID of the added subscription The event attributes look like the following structure: An example of a rule selecting on a subscription removal. 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. The subscription ID of the added subscription The event attributes look like the following structure, depending on the arguments given to wrangler:subscription on the other pico: An example of a rule accepting new subscription requests by selecting on wrangler:inbound_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. These are currently identical to the attributes passed to wrangler:subscription. The event attributes look like the following structure, depending on the arguments given to wrangler:subscription: An example of a rule selecting on wrangler:oubound_pending_subscription_added to prepare for the subscription. 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. The internals of the cancelled outbound request. See attached example for its values. An example of a rule selecting on wrangler:outbound_subscription_cancelled: The structure of the bus when the oubound subscription has been 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. An example of a rule selecting on wrangler:inbound_subscription_cancelled: The structure of the bus when the inbound subscription has been cancelled:Functions
established
Returns
Parameters
Parameter Datatype Description key The subscription attribute that you want to filter for value String The value of the subscription attribute you want to filter for 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
Parameters
Parameter Datatype Description key The outbound subscription attribute that you want to filter for value String The value of the outbound subscription attribute you want to filter for pendingOutboundSubs = subscription:outbound()
/*
[
{
"Id": "cjrcv6tzl003g04rqlri0vqqw",
"wellKnown_Tx": "HLy15B5xmws3avFpbS6beZ",
"Rx": "AgZKbAHa47RYytKBAK31DF"
}
]
*/
inbound
Returns
Parameters
Parameter Datatype Description key The inbound subscription attribute that you want to filter for value String The value of the inbound subscription attribute you want to filter for 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
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
subscriptionConfig = subscription:autoAcceptConfig()
/*
{
"password": [
"1234"
]
}
*/
Received Events
subscription
wrangler:subscription
Attributes
Attribute Datatype Description wellKnown_Tx String The wellKnown_Rx channel from the other pico that you want to establish a subscription with. String The name of the Rx to be created on each pico. Defaults to a random English word if not given. channel_type String The channel type that you want both pico's Rx to be Rx_role String Describes this pico's role in the subscription Tx_role String Describes the other pico's role in the subscription Id String Optionally provide a custom Id for the subscription, defaults to a UUID. Be very careful when providing your own Id. Tx_host String The network address of the engine hosting the other pico to subscribe to. Defaults to the same engine. password String Not implemented Directives Returned
pending_subscription_approval
wrangler:pending_subscription_approval
Attributes
Attribute Datatype Description Rx String The receiving channel created for this subscription. This is already created and given as an attribute of wrangler:inbound_pending_subscription_added. Tx String The channel on the pico that sent the subscription request that was created to receive events from this pico. Id String The subscription Id of the subscription you want to accept. Also given in wrangler:inbound_pending_subscription_added. Directives Returned
/*
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);
}
*/
send_event_on_subs
wrangler:send_event_on_subs
Attributes
Attribute Datatype Description domain String The domain of the event to send type String The type of the event you want to send attrs Map A map of the attributes you want to be associated with the sent event subID String The subscription ID of the subscription you want to send the event on Rx_role String The Rx_role of the subscriptions you want to send the event on Tx_role String The Tx_role of the subscription you want to send the event on Directives Returned
outbound_cancellation
wrangler:outbound_cancellation
Attributes
Attribute Datatype Description Rx String The receiving channel created for this subscription. This is already created and given as an attribute of wrangler:outbound_pending_subscription_added. Id String The subscription Id of the outbound subscription request you want to cancel. Directives Returned
inbound_rejection
wrangler:inbound_rejection
Attributes
Attribute Datatype Description Rx String The receiving channel created for this subscription. This is already created and given as an attribute of wrangler:inbound_pending_subscription_added. Id String The subscription Id of the inbound subscription request you want to cancel. Also given in wrangler:inbound_pending_subscription_added. Directives Returned
/*
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);
}
*/
subscription_cancellation
wrangler:subscription_cancellation
Attributes
Attribute Datatype Description Rx String The receiving channel created for the subscription you want to cancel. Tx String The transmitting channel for the subscription you want to cancel. Id String The Id of the subscription you want to cancel. Directives Returned
/*
{
"directives": []
}
*/
Raised Events
subscription_added
wrangler:subscription:added
Attributes Added
Attribute Datatype Description Id String Tx String The transmitting channel for the added subscription Rx_role String The role this pico has in this subscription Tx_role String or NULL The role the other pico has in the subscription Tx_public_key String or NULL The key used for decryption of encrypted messages sent through the subscription Tx_verify_key String The key used for verifying signed messages to send through the subscription bus Map Holds 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" {
"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"
}
}
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
Attributes Added
Attribute Datatype Description Id String bus Map Contains more information on the removed subscription {
"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"
}
}
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
Attributes Added
Attribute Datatype Description Id String Rx String The receiving channel that this pico will receive subscription events on Rx_role String The role that this pico will take in the subscription Tx String The channel to transmit events to on the other pico Tx_host String The network address of the pico engine hosting the other pico in the subscription Tx_public_key String Tx_role String The role of the other pico in the subscription relationship Tx_verify_key String channel_name String The name of the channel created for the subscription channel_type String The type of the channel created for the subscription name String Also the name of the channel created for the subscription public_key String verify_key String wellKnown_Tx String The wellKnown of this pico {
"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"
}
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
Attributes Added
Attribute Datatype Description Rx_role String The role that this pico will take in the subscription Tx_host String The network address of the pico engine hosting the other pico in the subscription Tx_role String The role of the other pico in the subscription relationship channel_type String The type of the channel created for the subscription name String The name of the channel created for the subscription wellKnown_Tx String The wellKnown of the pico the request is being sent to {
"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"
}
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
Attributes Added
Attribute Datatype Description Id String The Id that had been created for the possible subscription Rx/Tx String Use 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. bus Map rule sub_request_cancelled_or_rejected {
select when wrangler outbound_subscription_cancelled
always {
ent:sub := event:attrs
}
}
{
"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
Attributes Added
Attribute Datatype Description Id String The Id that had been created for the possible subscription Rx/Tx String Use 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. bus Map The internals of the cancelled inbound request. The internals of the cancelled outbound request. See attached example for its values. rule inbound_sub_req_cancelled {
select when wrangler inbound_subscription_cancelled
always {
ent:sub := event:attrs
}
}
{
"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.