Codecs
A codec turns CapTP messages into bytes and back. The session decides whether a reference is valid, so changing codecs changes only the wire format.
glowcap supports two codecs:
| Codec | Use it when | Tradeoff |
|---|---|---|
| Syrup | Always, unless a measured glowcap-to-glowcap workload says otherwise | Compact and interoperable. Finding an arbitrary field requires a scan |
| Cap’n Proto | Both peers are glowcap and large or partially read payloads benefit from fixed offsets | Constant-time field access. Larger frames and no outside interoperability |
Syrup
Syrup is the OCapN format and glowcap’s default. Use it to communicate with Spritely Goblins and the upstream OCapN test suite.
Its length-prefixed, variable-width records keep small control messages compact. The decoder finds a frame boundary and decodes the message in one forward pass. Reaching item i requires scanning the records before it.
Syrup is also glowcap’s signing format. The signature on a peer’s announced location and the certificates that authorize a three-party handoff are made over canonical Syrup bytes, even when two glowcap peers exchange their messages with Cap’n Proto.
Cap’n Proto
Cap’n Proto lays messages out in 8-byte words with fixed field offsets. That makes partial reads and random access cheap, but padding and pointer words make small messages larger.
Goblins does not speak this encoding, so use Syrup for Goblins interoperability. Codec and CapTP version are separate choices. glowcap’s own profile pairs Cap’n Proto with glowcap-next, which tracks newer draft operations. Cap’n Proto can also carry CapTP 1.0 between glowcap peers. Set codec = .capnp and the version you need in Zig SessionOptions, or use the matching Host or binding preference.
Choosing
Measure your own messages before switching. The performance page measures one small mixed-argument call, so its results may not predict your workload.
Either codec can hand the session a temporary view of a message. glowcap copies into owned memory only when it must keep that message after decode finishes. Concepts explains how peers negotiate the CapTP version and codec. The architecture doc shows where a Zig program can plug in another codec.