The modules
Modules depend on the layers below them. Teal marks the protocol core, which performs no I/O. The neutral layers manage local objects, sessions, and durable state. Amber marks the I/O adapters, C ABI, and language bindings.
Most applications use driver.Session and a transport. The modules below matter when you need to host many sessions, supply an event loop, add a codec, or drive the protocol without I/O. Architecture explains how they fit together.
Choose the right level
| Name | Job |
|---|---|
| Peer | The caller-owned engine handle. You feed inbound frames, call step, drain outbound frames, and read events. It opens no sockets. |
| Host | Manages one identity across many CapTP sessions. It routes introductions between sessions and settles the promises callers wait on. Its socket-free core lives in driver/core. The browser package and C embedders that own their I/O drive the Host themselves. |
| Session | The one-partner application object: connect / listen, fetch, blocking call. It is a view onto a conversation its Host owns. |
| Server | The listening side. It publishes objects, and each accept returns a Session for one partner that connected. |
| HostRuntime | The loop behind Session and Server. One thread serves every session of one Host, with one identity, over the transports you register. |
| HostTurn | The argument passed to an object’s handle method. It carries the turn’s arena for building replies and the Host for calling other objects. |
Use Session unless you need a lower-level responsibility from the table. Every Session is backed by a Host, which redeems introductions and returns a live capability. Concepts explains three-party introductions.
The protocol core
The core is synchronous. It holds no sockets and starts no background work, so you can test it without a host runtime.
- foundation owns shared primitives: a
Frameowns bytes, aFrameViewborrows them, and IDs are plain values. - model is the CapTP vocabulary, independent of the bytes that carried it.
- codec turns model values into wire bytes and back. Syrup is what Goblins speaks. Cap’n Proto is the second encoding. Codecs compares them.
- session owns the import, export, and answer tables and decides what is valid. A codec never decides whether a reference is allowed.
- engine advances the protocol state machine and produces events and outbound frames.
Above the core
- actors provides a
Vat, a container of objects shaped like Goblins’.$calls an object in the same vat immediately.<-sends to one that may be remote and returns a promise. It adds nothing to the protocol that the engine lacks. - driver/core serves many sessions at once, with no sockets of its own. A build check keeps I/O out of it.
- net is where
std.Ioenters. It holds the transports: iroh QUIC,noise-tcp, WebRTC, onion, and the cleartexttcp,keyed-tcp, andinproc, among others (Transports). - loam is optional storage for objects and the capabilities they hold. Its core does no I/O. An optional SQLite or LMDB module supplies the disk. Loam explains records, sleepy actors, and durable names.
Vat: one single-threaded container of objects, the unit Spritely Goblins and the wider ocap world organize around. Every call into a vat runs as one turn, start to finish, before the next begins.
Near-call (
$) and eventual-send (<-): from E. Near runs immediately in your vat. Eventual queues a later turn and returns a promise. That is also the only way to call across a session.
Why Zig
glowcap’s Zig APIs take explicit allocators, so applications control how memory is allocated and released. Performance publishes what glowcap costs.
glowcap tests memory handling with leak checks, allocation budgets, and fuzzing of input from peers. These checks do not prove memory safety.
Public entry points
Choose an API compares the entry points available to applications.
- c_abi is the C interface: opaque handles, fixed-width return codes,
ptr + lenbyte views, and explicit release functions.libglowcap_hostis the CapTP host the bindings wrap. The Rust, Python, TypeScript, and Racket bindings also loadlibglowcap_driverto run the loop. - driver is Zig above
driver/core:Session,Server, andHostRuntime.
Bindings provide the application API in Rust, TypeScript, Python, and Racket, each over the C ABI.