Managing Channels

Owned by Phil Windley
Last updated: Mar 07, 2022 by Bruce ConradVersion comment

What are pico channels?

A pico receives events and respond to queries on its channels (Event-Query API). A channel on a pico can be viewed as a unique stream of communication with that pico. A pico can have any number of channels. Through the use of policies, type of communication through the channel can be controlled (e.g. only allows events of a certain type/domain to be received on a channel). Pico channels are a type of Event Channels.

A pico channel is represented by an ECI (Event Channel Identifier). It is a unique token, a string, such as "ckiz680qq000a7u2r8myeezof". To use a channel, a programmer only needs the ECI itself and the location of the engine the pico is located. Then, following the Sky Event API or Sky Cloud API queries and events can be sent. Mechanisms within KRL have this built in, such as the event library and Wrangler's picoQuery() function. 

Wrangler's Subscriptions use channels to create unique relationships between picos.

Purpose of channels

As a quick illustration of the purpose of channels, a pico representing a real-life lamp may wish to make the ability to query whether it is "lit" or "off" to some entities, but reserve the ability to actually change its state to "lit" or "off" to other actors:

For each actor that the lamp pico will give control to, the lamp pico may create a channel that is able to receive "lamp:on" and "lamp:off" events, and then share the created channel with the desired actor. Conversely, for actors that are only allowed to query for the state of the lamp pico, the lamp pico will create channels that only allow an "IsLampOn" query and share that.

Finally, because the lamp pico created a channel for each actor, if any actor misbehaves (e.g. the lamp pico is programmed to stop actors from rapidly flashing the light), the lamp pico can revoke or restrict just that channel, without affecting its communication with any other actor.

Channels in the developer UI

A pico's channels as shown in the developer UI, for a pico named "Alpha" which has both a parent pico and one child pico:

Types of channels

There are channels for use inside the pico-engine, and those which can be used by outside systems (such as browsers) to communicate a query or event to a pico.

Besides have a unique identifier (the ECI), each channel also has one or more tags and a policy. The tags can be used to search for a channel, and the policy determines how the channel can be used. For detailed discussion about the attributes of a channel, see below.

Family channels

Family channels are usable only within a pico-engine. They have a "system" tag.

Family channels do not have policies. Any event or query is allowed on a family channel, but has to come from the right pico.

Self channel

Each pico has such a channel, with a "self" tag. Since a pico cannot send itself a query or an event, this channel serves only to identify it. And in fact its ECI is the same as the pico's identifier.

Child channel

Each pico except the root pico has one such channel, with a "child" tag. This channel can be used by code running in its parent to send this pico events and queries.

Parent channels

Each pico which has children has one such channel for each child, with a "parent" tag. This channel can be used by code running in the child to send this pico events and queries.

External channels

All other channels to a pico can be used either by other picos in the same pico-engine, other picos hosted in external pico-engines, or by systems anywhere on the Internet. Each external channel you give to a pico defines an API for the pico. That API is determined by the rulesets which you install in the pico and shaped by the policies you bake into these channels.

Policies, discussed in more detail below, allow or deny certain specified events and queries. It is through these policies that the lamp pico discussed above implements the restrictions spoken of.

Creating a Channel

Manual creation of a channel using the developer UI

The "Channels" tab of the developer UI, besides listing the channels currently in the pico, has a form that you can use to create a new channel for the pico.

Here is a screenshot showing the creation of channel giving full access to the lamp pico, just before the developer clicks on the "Add" button:

Here is the same tab after the developer has created both a full-access channel and a read-only channel for the Lamp pico:

The channel identifiers (ECIs) are assigned by the pico-engine and are globally unique.

Notice that checking the box beside a channel's ECI shows the policies of the channel.

The ECI "ckj080ny8008ffi2r1n1b2kr0" can be given to trustworthy actors, giving them the ability to use the full capabilities of the lamp_ruleset to control the lamp.

On the other hand the ECI "ckj081v5a0093fi2r9es49i77" could be more widely published so that less-trusted actors can check the lamp's state. Such actors would not be able to send any events to the Lamp pico.

If any actor misbehaves, you can simply delete the channel and recreate it, with a different ECI. Even though the read-only ECI gives access only to a single query, an actor might misbehave by mounted a distributed denial of service attack on the pico-engine. Again, you can eliminate the attack simply by deleting that channel. After recreating it, you can give the new ECI to good actors, and they can resume their legitimate work.

Programmatic creation of a channel

Synchronous creation

Channels can be created synchronously by your KRL code using the wrangler:createChannel defined action which is provided to any ruleset that uses Wrangler as a module. See the Pico-Based Systems lesson for more examples. This code shows how to use the Wrangler ruleset as a module:

meta {
  use module io.picolabs.wrangler alias wrangler
  shares IsLampOn
}

Line 2 makes the ruleset available within this ruleset using the internal name wrangler. Line 3 shares the IsLampOn function so that it can be used by external systems over an appropriate channel.

This is code to create one of the lamp channel within KRL code:

rule create_limited_use_channel {
  select when lamp read_only_channel_needed
  pre {
    tags = ["lamp","read-only"]
    eventPolicy = {"allow": [], "deny": [{"domain": "*", "name": "*"}]}
    queryPolicy = {"allow":[{"rid": meta:rid, "name": "IsLampOn"}], "deny": []}
  }
  every {
    wrangler:createChannel(tags,eventPolicy,queryPolicy) setting(channel)
    send_directive("new channel",{"eci": channel{"id"}})
  }
}

Lines 3-7 bind local names to the tags, the eventPolicy and the queryPolicy for the new channel. The rule will unconditionally fire executing both of the actions specified (in order).

In line 9 the io.picolabs.wrangler module will run the createChannel defaction, creating the new channel and returning it, where it will be bound to the internal name channel by the setting clause.

Finally, line 10 will return a directive to the event generator, giving it the channel's ECI.

The event generator might be a trusted web page (given an ECI with a policy allowing the event lamp:read_only_channel_needed) which could send the event to the Lamp pico and use the response to set up a URL that could be given to the user to check on the lamp's state.

Asynchronous creation

Channels can be created asynchronously by raising the wrangler:new_channel_request event. Wrangler enforces that all channels with the same type must have a unique name. On a successful channel creation, a wrangler:channel_created event will be raised by Wrangler.

Creation Example

Channels can be created asynchronously by raising thewrangler:new_channel_requestevent. Wrangler enforces that all channels with the same type must have a unique name. On a successful channel creation, a wrangler:channel_created event will be raised by Wrangler.

raise wrangler event "new_channel_request" attributes {
  "tags":["lamp","read-only"],
  "eventPolicy":{"allow": [], "deny": [{"domain": "*", "name": "*"}]},
  "queryPolicy":{"allow":[{"rid": meta:rid, "name": "IsLampOn"}], "deny": []},
  "co_id":meta:rid // Added attributes get passed through
}

Responding to Creation

  rule onNewTestChannel {
    select when wrangler channel_created where event:attr("co_id") == meta:rid
    pre {
      newChannel = event:attr("channel").klog("New channel")
      channelID = newChannel{"id"}
    }
  }
/*
[KLOG] New channel
    {
      "id": "ckj081v5a0093fi2r9es49i77",
      "tags": [
        "lamp",
        "read-only"
      ],
      "eventPolicy": {
        "allow": [],
        "deny": [
          {
            "domain": "*",
            "name": "*"
          }
        ]
      },
      "queryPolicy": {
        "allow": [
          {
            "rid": "lamp_ruleset",
            "name": "IsLampOn"
          }
        ],
        "deny": []
      },
      "familyChannelPicoID": null
    }
*/

Deleting a Channel

Deleting a channel occurs in much the same way that creating one does. The client raises a wrangler:channel_deletion_request event with attributes that are either the tags, or the ECI of the channel they wish to delete. If invalid attributes are provided a wrangler:channel_deletion_failed event will be raised by Wrangler.

Deletion Example

raise wrangler event "channel_deletion_request" attributes {
  "tags":["lamp","read-only"],
  "co_id":meta:rid
}

Responding to Deletion

rule onChannelDeleted {
  select when wrangler channel_deleted where event:attr("co_id") == meta:rid
  pre {
    deletedChannel = event:attr("channel").klog("Deleted channel")
    channelID = deletedChannel{"id"}.klog("Channel ID")
  }
}

Channel Attributes

A pico channel has certain attributes that each serve a unique purpose in identifying and using that channel. A map containing these attributes is often given to the client by Wrangler, such as when creating and deleting channels.

ID

The channel ID is the globally unique identifier for a channel. It is also known by the initialism "ECI" (Event Channel Identifier). Anyone who knows the ECI and has network access to the engine that the pico with the channel lives on can send events and queries to the channel.

Tags

The channel has one or more tags as a way to identify the channel without knowing its ECI. This allows easier manipulation of the channels that the KRL programmer cares about.

Event Policy

This is a map that encodes the "policy" that the channel uses for events . The policy determines what events are allowed on that channel.

Query Policy

This is a map that encodes the "policy" that the channel uses for queries. The policy determines what queries are allowed on that channel.

Policies

Every channel has a policy attached to it. Policies limit which events or queries a channel will accept. They are defined using JSON maps. For events you define which domains and names are allowed and which are denied. Queries use "rid" and "name" instead of "domain" and "name".

For example, a policy that allows all events with domain `foo` and name `bar`. An event `foo:hello` will be rejected.

"eventPolicy": {
    "allow": [
        // This is a list of rules.
        // If the event matches one of these rules, the event will be allowed
        {"domain": "foo", "name": "bar"}
    ],
    "deny": []
}

Now let's try a policy that will allow all events with domain `foo`, but reject `foo/bar`.

    "eventPolicy": {
        "allow": [
            {"domain": "foo", "name": "*"},// "*" means match all
            {"domain": "aaa", "name": "bbb"},
        ],
        "deny": [
            // deny creates a black list of events
            {"domain": "foo", "name": "bar"}
        ],
    }

// foo:foo - allowed
// foo:wat - allowed
// foo:bar - denied b/c it matches a rule in the `deny` list
// zzz:wat - denied b/c domain zzz is not allowed
// aaa:bbb - allowed b/c it matched an `allow` rule
// aaa:ccc - denied b/c it didn't match an `allow` rule

Now let's allow all events except `system:*` and `danger:nuke`

    "event": {
        "allow": [
            {"domain": "*", "name": "*"}// using "*" for `domain` and `type` means match all events
        ],
        "deny": [
            {"domain": "system"},
            {"domain": "danger", "name": "nuke"},
        ],
    }

// foo:bar - allowed
// hello:system - allowed
// system:secret - denied
// system:foobar - denied
// danger:gun - allowed
// danger:nuke - denied

Queries work the same. But use `rid`+`name` instead of `domain`+`name`

The allow all policy looks like this

{
  "id": "ckj0a2o12009efi2r576qhe5q",
  "tags": [
    "allow_all"
  ],
  "eventPolicy": {
    "allow": [
      {
        "domain": "*",
        "name": "*"
      }
    ],
    "deny": []
  },
  "queryPolicy": {
    "allow": [
      {
        "rid": "*",
        "name": "*"
      }
    ],
    "deny": []
  },
  "familyChannelPicoID": null
}

Using Channels

List of ways to interact with channels:

Channels API

A list of the functions, actions, received events (that Wrangler responds to) and raised events (that Wrangler raises) and in-depth descriptions of when to use them can be found in the Wrangler page.




Copyright Picolabs | Licensed under Creative Commons.