Connections and Transport
Negotiate a session and preserve message boundaries, resource ownership, and file-descriptor lifetime.
A Hera connection carries messages through local Unix IPC and establishes the resource namespace for an authenticated client session. Surfaces and imported buffers belong to that session, so connection handling must preserve both message boundaries and resource ownership.
Connection Handshake
To begin a session, connect to the deployment's socket and send ClientToServer::Hello(ClientHello::new(name)). The server replies with ServerToClient::Hello, assigning a ClientId and reporting its protocol version. Verify that version before proceeding with application requests.
After the hello exchange, request a surface with CreateSurface and keep the identifier returned by SurfaceCreated. Other valid traffic, including advisory messages, can arrive while you wait. Structure the event loop to dispatch those messages as well, rather than assuming the next packet always answers the most recent request.
Platform Framing
The transport preserves message boundaries differently on the supported platforms. Linux uses Unix SOCK_SEQPACKET, where each packet supplies a boundary, while the macOS development implementation frames a Unix stream with a four-byte little-endian payload length. Both carry the same versioned payload codec.
Use Conn and the typed message helpers instead of layering the macOS prefix onto Linux packets or assuming stream reads always return a whole message.
File Descriptor Attachment
Descriptor passing follows those message boundaries. ImportBuffer and ImportFrameBuffer each require exactly one SCM_RIGHTS descriptor; the other current client messages and all current server messages require none. Each import must carry its own descriptor in the same message, so receivers cannot borrow one from an earlier packet or save extras for a later request.
The receive helpers validate descriptor counts after decoding. Malformed payload handling also clears received descriptors so a failed decode cannot leave stale resources in the next message's inbox.
For writes, pass borrowed descriptors to write_client_message_with_fds and keep their owners alive for the entire asynchronous write, including before the future is first polled.
Session Failure Boundaries
A disconnected transport is not a retained-scene acknowledgment. Reconnecting creates a new session; rebuild the necessary state rather than assuming old surfaces and buffers still exist.
If a stream write is cancelled after a partial frame, do not reuse that stream as if no bytes were sent. Hera Kit closes failed sessions and does not replay an ambiguous pending commit.
See commit outcomes for the state needed above the transport.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/ipc/src/transport/linux.rscrates/ipc/src/transport/macos.rscrates/ipc/src/message_io.rscrates/kit/src/host/mod.rs