Protocol vocabulary
Every glowcap session uses a small vocabulary from the OCapN specifications. Concepts explains how the parts work together, and the protocol diagrams draw the flows.
The operation and descriptor names below are checked against the Syrup codec. In the tables, 1.0 means CapTP 1.0, the version Goblins speaks, and Next means glowcap-next, the profile tracking newer draft operations.
Operations
An operation (op:...) opens or ends a session, makes a call, settles a promise, or releases references.
| Message | What it does |
|---|---|
op:start-session | Opens a session. Each side announces its location and session public key, with a signature over the location. |
op:deliver | Calls a method on a reference. Next has separate resolver and listen-mode operands. The optional answer position enables pipelining. On 1.0, omitting both answer and resolver makes a one-way send. |
op:deliver-only | Next sends a message without requesting a result. |
op:resolve | Settles an answer to its value or a break. glowcap never sends it to a live peer: CapTP 1.0 settles through the resolver below, and glowcap-next through its inline subscription or op:listen. The codec reads and writes it for the reference fixtures. |
op:listen | Requests a notification when a promise resolves. |
op:abort | Ends the session with a typed reason. A refused handshake is answered the same way, before the session ever opens. |
op:get | On 1.0, reads a named field of an answer without waiting for the whole result. |
op:index | On 1.0, reads one item of an answer by position. |
op:untag | Unwraps a tagged value read from an answer. glowcap accepts it on every 1.0 session and sends it only when the partner advertises the untag feature, so a silent Goblins peer never sees one. |
op:gc-exports | Tells the peer that some exported references have been released, so it can drop them. |
op:gc-answers | Tells the peer that some answers can be discarded, so it can release them. |
How a promise settles
On a CapTP 1.0 session, a caller that wants an answer passes a resolver with its op:deliver: a reference the callee calls back. The answer returns as another op:deliver to that resolver, carrying ['fulfill <value>] or ['break <error>]. Goblins and glowcap both settle promises this way.
glowcap-next tracks the draft’s operation contracts while keeping the shared Goblins-compatible hello and crypto formats. A call carries its resolver and a listen mode inline: mode 1 requests shortening (later messages to the promise go straight to what it resolves to), and mode 3 requests shortening or settlement. A separate op:listen can add a mode-2 settling subscription after mode 1. Notifications use op:deliver-only. Next refuses op:get, op:index, and op:untag, which exist only on 1.0.
What a CapTP 1.0 peer sees from glowcap
A Goblins peer, or any other CapTP 1.0 implementation, sees plain CapTP 1.0 over Syrup. glowcap’s preferences travel as three hints on the location its op:start-session signs: glowcap/captp-version, glowcap/codec, and glowcap/features. A peer that doesn’t know them ignores them, and the session uses the 1.0 baseline. The version and codec hints for glowcap’s own tracks also name the exact wire a build writes, so two glowcap builds that write it differently use the 1.0 baseline. Goblins refuses a hinted onion address, so over Tor glowcap sends hints only to a partner it already knows is glowcap. With anyone else, an onion session runs the baseline.
glowcap sends op:untag only to a partner that lists the untag feature. Application code uses the same call API under either version. session.listen accepts a live far object on 1.0 but only a far promise on glowcap-next.
Reference descriptors
A descriptor (desc:...) names a reference or a handoff inside a message: what a slot points at.
| Descriptor | What it names |
|---|---|
desc:export | A reference back to an object the receiver exports: how the sender names something it received in a preceding message (position 0 is the bootstrap object). |
desc:answer | A reference to a pending answer from a preceding op:deliver, the target of promise pipelining. |
desc:import-object | An object the sender hosts and is introducing. The receiver records it as an import. |
desc:import-promise | A promised reference the sender is introducing, settled later when the sender resolves it. |
desc:handoff-give | The gifter’s half of a three-party introduction: “go meet this peer, on my word.” |
desc:handoff-receive | The recipient’s half of that introduction, redeemed with the third party. |
desc:sig-envelope | A signed wrapper that makes a handoff unforgeable as it crosses between the three parties. |
Locators
A locator (ocapn-...) gives a peer’s address and, for a sturdyref, the object to fetch from it. The designator inside it is the peer’s name on its transport: an iroh node id, a public key for Noise and keyed transports, a Tor service id, or a host:port for testing-only tcp. A locator rides inside op:start-session as the location each side announces, and travels as an argument when one peer hands another a long-lived reference to bring back to life later. The ocapn:// URI you paste into a config is one of these records, in text.
| Locator | What it addresses |
|---|---|
ocapn-peer | A peer’s location: its transport (iroh, noise-tcp, tcp, and the rest), the designator to reach it at, and any connection hints. An ocapn://<designator>.<transport> URI is this record. |
ocapn-sturdyref | A peer location plus a swiss number: a restorable, long-lived reference to one object, the thing an ocapn://…/s/<swiss> URI names. |
Reserved characters inside a designator are URI-encoded, so a tcp peer’s host:port shows %3A where the colon is. The first two examples are sealed (iroh and noise-tcp), and plain tcp is testing-only:
ocapn://<64 hex chars>.iroh
ocapn://<64 hex chars>.noise-tcp?direct-addresses=127.0.0.1%3A9099
ocapn://127.0.0.1%3A46659.tcp
The id locator bundles several such routes under one durable key. Multi-home peers covers it.
Transports lists what a locator can name, and Codecs compares the wire encodings.