Concepts

A capability is a reference

Code that holds a reference to an object can call it. A session checks that the peer was granted the reference before allowing a call. CapTP is the protocol that keeps this true between two programs on a network. OCapN is its standardization. Spritely Goblins is an implementation of it, and the peer glowcap checks against.

Passing a reference delegates its access. To give someone less access, wrap the reference in an object that forwards only selected methods. This is attenuation. If the wrapper can stop forwarding calls, it can revoke the access it granted. Why OCapN illustrates delegation, attenuation, and revocation.

A capability is a reference. Pass it as an argument and the partner can call it. Without it, the partner cannot reach the object at all.

A call is a deliver message, and you immediately hold a promise for the answer. When the partner has the answer, it sends a message back that settles the promise. How a promise settles shows that message on the wire.

A single call, start to finish: you deliver it and immediately hold a promise, and the partner’s answer settles that promise to a result.

Getting the first reference: locators and sturdyrefs

To reach a peer, start with a locator, an address string:

ocapn://<designator>.<transport>

The designator names the peer: an iroh node id, a public key for Noise and keyed transports, a Tor service id, or a host:port for testing-only tcp. Optional ?key=value hints carry routing help, like the socket address for a keyed listener. Hints can only help you reach a peer. They give no access of their own.

Dialing a locator opens a session. The bootstrap object is the one capability available at first. You fetch a published name from it and get back a live reference. From there, new references come from the ones you already hold.

A sturdyref combines a locator with a swiss number, the secret name you fetch from the bootstrap object. You can save it in a config file. Redeeming it means dialing the peer and fetching that object.

Treat the swiss number as a bearer secret wherever the peer has made it fetchable. The examples use short names like "greeter" for readability. Give anything private a long random name.

A name can be published for one session or for every session on a Host, which manages a peer’s sessions. A Session publication answers only its partner. A Host-wide publication can also be handed to a third peer through an introduction. When both use the same name, the partner gets the one its own session published.

A sturdyref still works after a restart only if the peer comes back with the same identity and can still answer for that swiss number. A plain Host forgets its published names when the process exits, so the application publishes them again when it starts. Loam, glowcap’s storage layer, keeps objects and their names on disk, and restores an object when a peer fetches its name.

WordWhat it is
locatorA peer address, and how to dial it.
swiss numberThe secret name of one object at that peer.
live referenceA capability your program holds and can call.
The first URI is a peer locator: a designator, transport, and optional routing hints. The second adds a swiss number to name one object, making it a sturdyref.

The sturdyref diagrams go deeper. Transports explains what a locator can name, and a multi-home locator carries several transports under one key.

Promise pipelining

A remote call hands back a promise before any bytes return, and you can call methods on that promise right away. Those calls travel to the peer and queue against the pending answer, so they run on the peer as soon as it settles, with no extra round trip. A promise is also an argument: hand it to another call, and the receiver gets a promise for the same answer.

Ask a task board for a column, then ask that column for a card, and both questions cross the network in one flight. Chapter 06, pipeline and attenuate, runs that, and the promises and pipelining diagrams show the exchange.

Three-party handoff

Alice holds a reference to Carol’s object and wants Bob to have it. Alice could pass Bob’s calls along to Carol herself, but then every call between them would have to go through her. Instead, CapTP lets her write an introduction that Bob presents to Carol himself. After that, Bob and Carol talk directly.

The handoff runs in four stages:

  1. Alice deposits a gift with Carol and builds a signed give.
  2. Alice’s answer to Bob carries that give (the introduction).
  3. Bob redeems with Carol and gets a live reference.
  4. Bob and Carol talk directly, without Alice.

In glowcap you never handle the gift bytes. When a call’s answer is an introduction, glowcap redeems it for you, and the call you were already waiting on settles as the introduced capability. In the Rooms chat, Message name directly is this kind of introduction: the room hands you a live reference to the other member.

Chapter 02, introduce and redeem, runs the whole exchange, and the handoffs diagrams show the exchange.

Agreeing on a version and codec

Two peers agree on a CapTP version and a codec, together called the session’s dialect. Each glowcap peer offers its preferred version and codec plus the shared baseline, CapTP 1.0 over Syrup. Both peers apply the same selection rule to those preferences.

The opening message, or hello, always uses the baseline. Each peer includes its preferences as hints in the signed locator it announces.

Syrup and Cap’n Proto are codecs, two ways of writing the same message down. Session logic never changes with the codec. Codecs compares them.

Both peers apply the same selection rule to their preferences and choose the same version and codec.
The dialect depends on who answers: the standard baseline against Goblins, glowcap’s own choices between two glowcap peers.

With a Goblins peer, the choice is CapTP 1.0 over Syrup, the shared baseline for interop. If glowcap and Goblins disagree there, glowcap treats it as a glowcap bug. Two glowcap peers can negotiate up to glowcap-next, a profile tracking newer draft operations, usually with Cap’n Proto. The protocol guide lists the profile differences.

Distributed GC

Each session keeps tables of the references it has exported and the answers it is holding. An export slot counts how many times it was handed out. An answer slot holds one reference and is released all at once.

When your program drops a far reference, distributed garbage collection tells the peer with op:gc-exports or op:gc-answers, and the peer frees the unused slot. Rust does this by default for every session on a Host, because Drop runs at a known point. TypeScript, Python, and Racket release through finalizers that run on their own schedule, so you turn it on per session. It covers fetch results, fulfilled far answers, and capabilities nested inside delivered arguments. When it is off, table entries stay until the session ends. The GC diagrams show the exchange.

The diagram catalog shows the protocol flows in full. Modules maps these concepts to Session, Host, and Peer. To write a client, go to Start building.