Module worker_protocol 

Typed border for the nix-daemon worker protocol.

When a nix client (nix build, nix-env, nix-store --realise) needs to mutate the store, it doesn’t write /nix/store itself — it connects to the nix-daemon over a unix socket and speaks the worker protocol. cppnix’s libstore/worker-protocol.cc defines ~30 opcodes covering the full read+write surface of the store.

Today sui-daemon implements this protocol in Rust; this module names the wire contract as a typed Lisp spec so any future client (or any third-party daemon) rides on the same authored shape. Both engines (sui’s client side + sui-daemon’s server side) drive the same spec — they cannot drift.

Authoring surface

Two keyword forms compose:

• (defworker-protocol ...) declares the protocol version + handshake (magic bytes, version negotiation).
• (defworker-opcode ...) declares ONE opcode per form: numeric code, direction, request-field types, response-field types, feature gate. ~30 opcodes today; new ones land as additional (defworker-opcode) forms.

Example:

(defworker-protocol
  :name "cppnix-worker-protocol"
  :version 35
  :magic-client "0x6e697863"   ;; "nixc"
  :magic-server "0x6478696f")  ;; "dxio"

(defworker-opcode
  :name "QueryPathInfo"
  :code 29
  :direction ClientToDaemon
  :request-fields  (StorePath)
  :response-fields (PathInfo)
  :since-version 17)

Structs

DispatchOutcome

Result of dispatching a worker-protocol opcode against a handler.

WorkerOpcode

One worker-protocol opcode.

WorkerProtocol

One worker-protocol version. Typically there’s one entry per major nix release (v23, v25, v27, v33, v35).

Enums

OpcodeDirection

Direction of an opcode call.

WireType

Wire-level field type — the primitive types the worker protocol can serialise. Length-prefixed strings + 8-byte LE integers per cppnix’s worker-protocol.cc WORKER_MAGIC framing.

Constants

CANONICAL_WORKER_PROTOCOL_LISP

Traits

WorkerProtocolHandler

Abstract handler for the worker protocol’s server side. Each opcode dispatches to a corresponding method here; the default implementation returns a typed unhandled-opcode error so an incomplete handler surfaces missing opcodes loudly.

Functions

apply

Dispatch one wire-arriving opcode against a handler. Looks up the opcode by code in the canonical catalog, then routes to handler.dispatch.

load_canonical_opcodes

Compile every authored opcode.

load_canonical_protocols

Compile the canonical worker-protocol version envelope(s).

load_opcode_by_code

Return the opcode with the given code.

load_opcode_named

Return the opcode whose name matches.