Skip to content

Channel

A Channel is the mailbox between ConfigHub and one bot. The bot's process claims the Channel and polls it. Callers run the commands the Channel declares on it, each as a CommandRun. The Channel carries subscriptions to events in the event log and a bookmark of how far delivery has reached. Everything addressed to the bot that is waiting, in progress, or recorded lives on the Channel, so it is there whether or not a process is connected.

A Channel lives in a Space. It has no identity of its own: its reader is a ServiceAccount with Claim on it, and what the bot may do with a command is what that account is granted.

Commands

Commands is the map of commands the bot handles, by name, each with a signature: a description, the options it takes, and optionally the schema of what it returns. A command name is dot-separated lowercase segments, by convention a thing and a verb, preview.deploy, optionally under a DNS domain that says who owns the name, acme.com/preview.deploy.

Each option is named and typed: string, int, bool, json with its own schema, or an entity, UnitID, SpaceID, TargetID or ChannelID, which cub resolves from a slug. Options are flat so that any generic surface, the CLI today and a UI later, can render a form for a command it has never seen.

{
  "preview.deploy": {
    "Description": "Deploy or update the preview of a pull request.",
    "Options": [
      {"Name": "pr", "DataType": "int", "Required": true},
      {"Name": "sha", "DataType": "string", "Description": "the commit to deploy"}
    ]
  },
  "preview.delete": {
    "Options": [{"Name": "pr", "DataType": "int", "Required": true}]
  }
}

The commands are set by whoever manages the Channel, with cub channel create --commands or cub channel update --commands, not by the bot. When the bot connects it verifies that the Channel declares what it handles and refuses the Channel otherwise, so the declaration is a contract between the operator and the process, visible before any process runs. cub command list shows every command the Channels of an Organization or a Space declare.

Subscriptions and the bookmark

Subscriptions is a list of filters over the event log. Each names the event types to deliver, such as release.published, and optionally one Space or one Target to narrow to; an event matching any of them is delivered. An empty list subscribes to nothing.

EventPosition is the Channel's bookmark: the position of the last event delivered. There is one per Channel, however many subscriptions it has, so a bot watching several things reads one ordered stream. A new Channel's bookmark starts at the tail of the log, so it reacts to what happens from then on and never replays history by accident. Moving it is a deliberate edit, cub channel update --event-position, to replay or to skip.

Delivery is best effort. The bookmark is advanced as events are handed over, and a reader can miss an event; see delivery for what that means and what is required of a bot in return.

The lease

One process reads a Channel at a time. It acquires a lease and holds it by polling; ClaimTTLSeconds, 60 by default, is how long the lease survives without a poll. Condition is Claimed while a lease is held and Unclaimed otherwise, and LastSeenAt and IPAddress are when and from where the holder last polled, so whether the bot is up can be read from the entity.

When the lease is released or expires, any run that was delivered and never answered goes back to Pending, and the next holder receives it. A second process that connects while the lease is held waits for it, which is how a rolling restart hands over.

Permissions

A Channel has Permissions like other entities, and one category exists for it alone:

  • Claim: acquire the lease, poll, report results, and advance the bookmark. This is the grant for the bot's ServiceAccount. It includes View and is not included in Manage, so administering a Channel does not by itself make anyone its reader; only a holder can grant it.
  • Use: run the Channel's commands. A caller also needs CreateChildren on the Space, since a run is created there, and ViewChildren to read the run back.
  • Edit: change the commands, the subscriptions and the bookmark. Manage: change Permissions and delete.

Subscriptions narrow what is delivered, and the reader's permissions bound it: an event reaches the bot only if its ServiceAccount may view the Space the event is about, or holds ViewChildren on the Target it is about. What the account may not see is left out, and the bookmark passes it.

See Command bots for building and running a bot on a Channel, and Authorization for the categories.