A reading path
Cap’n Proto: schemas, wire layout and capability RPC
A reading path through Cap’n Proto schema compatibility, message validation, promise pipelining and Haskell bindings, with primary specifications.
Start with the boundary you are changing
A field number belongs to the schema’s compatibility contract. A pointer belongs to the message layout. A capability grants authority to call an interface. Treating all three as “serialization” hides the decisions that need separate review. Begin with schema evolution when changing a stored format; begin with validation when receiving untrusted messages.
Follow the call, then inspect the binding
Promise pipelining changes when a dependent call may be sent. It does not remove the dependency on the eventual result. After reading the RPC note, trace ownership and lifetime rules in the chosen language binding. The Haskell note distinguishes a wire-protocol claim from an API guarantee made by a particular library version.
History and hands-on material
The 2019 schema-language critique and 2021 Haskell release announcement have their own historical reference pages. They identify the works that old links cited. The current notes below are independent explanations. Schema fragments are illustrative; the project page labels executable examples separately.
Work through the notes
Changing a Cap’n Proto schema without renumbering history
Cap’n Proto field ordinals preserve a schema’s evolution history. Adding a field can keep old messages readable, provided the new declaration respects ordinal ordering and defaults.
Download the accompanying exampleA fast wire layout still needs a trust boundary
Cap’n Proto’s word-aligned layout supports efficient traversal, but a receiver still has to validate bounds and resource use. Serialization also says nothing by itself about who sent a message or what that sender may do.
Promise pipelining removes a wait, not a dependency
Promise pipelining lets a client send a call against a result that has not arrived yet. It can collapse sequential network waits into one round trip, while preserving the dependency and its failure modes.
Download the accompanying examplePass a capability instead of looking up ambient authority
A capability combines an object reference with permission to use it. Passing a narrow read-only handle can make authority explicit and limited to the resource and operations the recipient needs.
Read the ownership boundary before upgrading an RPC binding
Before upgrading a Haskell Cap’n Proto binding, separate schema-generated types, message data ownership, serialization, and RPC behavior. Then check project status, protocol assumptions, and the API changes an upgrade may introduce.