Skip to main content

Module protocol

Module protocol 

Source
Expand description

Line-delimited JSON IPC protocol between the zero CLI and the zero-headlessd daemon.

§Framing

One JSON object per line. The newline \n is the record separator; no embedded newlines are permitted in the payload (serde_json’s default emitter satisfies this). Line framing was chosen over length-prefixed framing so that an operator debugging a stuck daemon can run

{ echo '{"kind":"status"}'; sleep 0.2; } | nc -U <zero_dir>/operators/<operator-slug>/sock

and see the reply without needing a framing parser. The M2 spec treats this as a hard operability requirement, not a nice-to-have.

§Extensibility

Each envelope is #[serde(tag = "kind", rename_all = …)] so adding a new variant is additive: old daemons will reject unknown kinds with a structured Response::Error rather than silently accepting them. The protocol version is bumped PROTOCOL_VERSION whenever the wire format changes in a non-additive way — matching versions is the dialer’s responsibility.

Structs§

ActionRecord
One durable record of a daemon decision. kind is a coarse-grained enum so /headless status can paint a terse “last 3 decisions” line without loading the full log.
StatusReply
Status payload — the spec’s three honest questions.

Enums§

ActionKind
EngineHealth
Engine reachability from the daemon’s perspective.
Request
Request frame sent by the CLI.
Response
Response frame returned by the daemon. Status is the only variant that carries a non-trivial payload; the others are ack/error shapes so a misbehaving daemon cannot pretend to have acted when it has not.
SupervisorState
Operator-intent flag — what the operator asked the daemon to do, not whether the daemon’s socket is currently listening (if you’re receiving a reply, it is).

Constants§

PROTOCOL_VERSION
Protocol version. Bump on non-additive changes (removing variants, changing field types). Additive changes (new variants, new optional fields) do not require a bump, but the daemon must tolerate unknown additive fields from newer clients without erroring.