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>/sockand 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§
- Action
Record - One durable record of a daemon decision.
kindis a coarse-grained enum so/headless statuscan paint a terse “last 3 decisions” line without loading the full log. - Status
Reply - Status payload — the spec’s three honest questions.
Enums§
- Action
Kind - Engine
Health - Engine reachability from the daemon’s perspective.
- Request
- Request frame sent by the CLI.
- Response
- Response frame returned by the daemon.
Statusis 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. - Supervisor
State - 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.