Protocol
Use the versioned contract that connects declarative clients to Hera’s retained scene server.
Hera's protocol gives clients a shared way to describe surfaces, change retained scenes, import buffers, and receive input and frame outcomes. The hera-protocol crate defines these values and their validation independently of sockets or runtime operations; hera-ipc is responsible for carrying them across a Unix connection.
Compatibility Negotiation
A session establishes compatibility through its hello exchange. This checkout declares protocol version 23 in ClientHello::PROTOCOL_VERSION; clients send that value before normal requests and verify the server's reply. Use the crate constant so the handshake remains aligned with the types being serialized.
After negotiation, messages use bincode with fixed-width integer encoding and little-endian byte order. The codec also bounds decoding and rejects trailing bytes, making those settings part of the wire contract. Serde enum naming attributes do not change the payload into JSON.
Protocol Structure
- Connections and transport covers startup, framing, and descriptor boundaries.
- Messages and surfaces covers requests, notifications, and shell authority.
- Scene operations covers nodes, patches, and atomic updates.
- Commit outcomes distinguishes acceptance, submission, and presentation.
- Buffers and ownership covers imports, damage, and retirement.
- Input events covers targeting and stream continuity.
- Validation and compatibility covers admission bounds and contract changes.
API Boundaries
The application toolkit usually owns this connection on an application's behalf. Hera Kit provides AppHost to maintain transport and commit state, while React Native uses rn_host through the C ABI. Direct protocol integration is useful when building another toolkit, a specialized surface producer, or a custom transport.
Do not reproduce transport framing, descriptor accounting, or acknowledgment semantics in a toolkit unless it actually owns that responsibility. The shared IPC helpers provide those boundaries consistently.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/protocol/src/messages.rscrates/protocol/src/codec.rscrates/ipc/src/message_io.rs