Note |
---|
"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
establishedReturns all of the established subscriptions for this pico in an array ReturnsNO 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 ParametersParameter | Datatype | Description |
---|
key | String | The subscription attribute that you want to filter for | value | String | The value of the subscription attribute you want to filter for |
Returns An array of established subscriptions. Possibly filtered. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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"
}
]
*/ |
outboundReturns the pending outbound subscription requests in an array ReturnsNO 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 ParametersParameter | Datatype | Description |
---|
key | String | The outbound subscription attribute that you want to filter for | value | String | The value of the outbound subscription attribute you want to filter for |
Returns An array of outbound subscriptions. Possibly filtered. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | Example |
---|
| pendingOutboundSubs = subscription:outbound()
/*
[
{
"Id": "cjrcv6tzl003g04rqlri0vqqw",
"wellKnown_Tx": "HLy15B5xmws3avFpbS6beZ",
"Rx": "AgZKbAHa47RYytKBAK31DF"
}
]
*/ |
inboundReturns the pending inbound subscription requests in an array ReturnsNO 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 ParametersParameter | Datatype | Description |
---|
key | String | The inbound subscription attribute that you want to filter for | value | String | The value of the inbound subscription attribute you want to filter for |
Returns An array of inbound subscriptions. Possibly filtered. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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_RxReturns the channel map of the WellKnown_Rx for this pico ReturnsA map in the channel map structure, describing the channel for the WellKnown_Rx on this pico. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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"
}
}
*/ |
autoAcceptConfigReturns 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. ReturnsA map with the auto accept configuration of the pico's subscriptions ruleset. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | Example |
---|
| subscriptionConfig = subscription:autoAcceptConfig()
/*
{
"password": [
"1234"
]
}
*/ |
Received Events
subscriptionwrangler:subscriptionWhen 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. AttributesAttribute | Datatype | Description |
---|
wellKnown_Tx | String | The wellKnown_Rx channel from the other pico that you want to establish a subscription with. | name | 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 ReturnedWill return empty directives. Corresponding Raised Events:
pending_subscription_approvalwrangler:pending_subscription_approvalShould 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. AttributesMust provide any one of the 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 ReturnedWill return empty directives. An example of a rule that raises wrangler:pending_subscription_approval to accept an inbound subscription request. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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_subswrangler:send_event_on_subsThis 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. AttributesMust provide any one of the 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 ReturnedWill return empty directives. outbound_cancellationwrangler:outbound_cancellationRaise this within the pico that initiated the subscription creation exchange to cancel an outbound subscription request. AttributesMust provide any one of the 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 ReturnedWill return empty directives. Corresponding Raised Events:
inbound_rejectionwrangler:inbound_rejectionRaise this within the pico that has received an inbound_pending_subscription_added event to cancel an an inbound subscription request. AttributesMust provide any one of the 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 ReturnedWill return empty directives. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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_cancellationwrangler:subscription_cancellationRaise this within a pico to cancel its subscription to another pico. AttributesProvide 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. 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 ReturnedWill return empty directives. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | Example |
---|
| /*
{
"directives": []
}
*/ |
Corresponding Raised Events: - 687767607 in both picos in the subscription relationship
Raised Events
Anchor |
---|
| subscription_added |
---|
| subscription_added |
---|
|
subscription_addedwrangler:subscription:addedFired within a pico whenever a new subscription has been added. Attributes AddedAttribute | Datatype | Description |
---|
Id | String | The subscription ID of the added subscription | 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" |
The event attributes look like the following structure: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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
}
} |
Anchor |
---|
| subscription_removed |
---|
| subscription_removed |
---|
|
subscription_removedwrangler:subscription_removedRaised within the pico when a subscription has been removed. Attributes AddedAttribute | Datatype | Description |
---|
Id | String | The subscription ID of the added subscription | bus | Map | Contains more information on the removed subscription |
The event attributes look like the following structure: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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]);
}
} |
Anchor |
---|
| inbound_pending_subscription_added |
---|
| inbound_pending_subscription_added |
---|
|
inbound_pending_subscription_addedwrangler:inbound_pending_subscription_addedThis 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 AddedAttribute | Datatype | Description |
---|
Id | String | The subscription ID of the added subscription | 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 |
The event attributes look like the following structure, depending on the arguments given to wrangler:subscription on the other pico: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | Example |
---|
| rule auto_accept {
select when wrangler inbound_pending_subscription_added
pre {
}
always {
raise wrangler event "pending_subscription_approval"
attributes event:attrs
}
} |
Anchor |
---|
| outbound_pending_subscription_added |
---|
| outbound_pending_subscription_added |
---|
|
outbound_pending_subscription_addedwrangler:outbound_pending_subscription_addedThis 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 AddedThese are currently identical to the attributes passed to wrangler:subscription. 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 |
The event attributes look like the following structure, depending on the arguments given to wrangler:subscription: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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. Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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);
}
} |
Anchor |
---|
| outbound_subscription_cancelled |
---|
| outbound_subscription_cancelled |
---|
|
outbound_subscription_cancelledwrangler:outbound_subscription_cancelledRaised 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 AddedAttribute | 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 outbound request. See attached example for its values. |
An example of a rule selecting on wrangler:outbound_subscription_cancelled: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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
}
} |
Anchor |
---|
| inbound_subscription_cancelled |
---|
| inbound_subscription_cancelled |
---|
|
inbound_subscription_cancelledwrangler:inbound_subscription_cancelledRaised 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 AddedAttribute | 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. |
An example of a rule selecting on wrangler:inbound_subscription_cancelled: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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: Code Block |
---|
language | js |
---|
theme | Confluence |
---|
title | 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
}
}_ |
|