The local API
benchd owns one host-local Unix socket and one private state store, and serves the same
operations as the bench CLI over HTTP on that socket. The bench CLI is its only implemented
client: pass --socket to any operation. There is no TCP listener (read from the source; no test
asserts it, see the Security model). Never expose the socket through a
TCP proxy.
The request and response shapes are proposed contract data, pinned from the suite’s contract repository. They are implemented and tested here; no suite product consumes them yet, and a shared response schema and published SDK for v1 are still pending.
Endpoints
Section titled “Endpoints”| Method | Path | What it is |
|---|---|---|
GET |
/healthz |
A health check, open to any authorized peer (operator or reader). Returns the service name and API version. |
POST |
/v1/operations |
Scalar (single-repository) operations, version superbench.v1. |
POST |
/v2/operations |
Grouped workspace operations, version superbench.v2. See v2 operations. |
Operation requests are POST with Content-Type: application/json; the health check is a GET. Three further v2 extensions exist in source but are
proposed and disabled in the public Serve entry point: cancellation (an operation of
cancel on /v2/operations), POST /v2/receipts/lookup for historical receipt evidence, and
POST /v2/registrations/observe. No request can turn them on.
Who may call
Section titled “Who may call”The daemon reads the caller’s uid from the kernel (SO_PEERCRED on Linux, LOCAL_PEERCRED on
macOS); supplied identity headers grant nothing.
- Operators (
--operator-uids, by default the daemon’s uid and root) may run every operation. They are trusted to execute arbitrary commands as the daemon user. - Readers (
--reader-uids) may runstatusandhost_statusonly. - Anyone else gets
forbidden.
The uid lists do not grant filesystem access by themselves: the socket is mode 0660 and its parent must not be group- or world-writable, so arrange a trusted local group. Lease tokens are holder capabilities, separate from the caller’s uid.
Request IDs and receipts
Section titled “Request IDs and receipts”Growth operations (create, recover, lease, run, setup) require a request_id. The CLI
generates one and prints it to stderr when --request-id is omitted; save it before issuing work
whose reply might be lost.
- Retry with the same ID and the same body. The same ID with a different body is a
conflict. - IDs and responses are scoped to the authenticated uid.
- A completed reply is cached durably and replayed exactly, including a historical lease token. A
replayed token does not restore an ended lease; use
statusfor the current state. - A retry while the operation is still running gets
in_progress. A disconnected client does not cancel the work. - After a daemon restart, unfinished receipts become
operation_in_doubtand are never run again automatically. Inspect status, stop the recorded execution if needed, checkpoint and release with the retained capability. Changing the ID is not reconciliation.
Checkpoint, release and stop do not create growth receipts, so a full receipt store never blocks reconciliation. Receipts are not collected; do not delete them to retry uncertain work.
Shutdown
Section titled “Shutdown”SIGTERM cancels supervised runs, which fence before keeping their lease for inspection. SIGKILL can
leave descendants alive; restart and stop --admin recover them from the durable execution scope.
HTTP shutdown has a ten-second grace period, which does not release ownership of an unfinished
operation. No timeout proves that a writer stopped.
Bounds
Section titled “Bounds”Requests are at most 64 KiB. Every v1 response is at most 1 MiB; on v2, read-only responses are at
most 1 MiB and durable growth responses at most 64 KiB. Unknown fields, duplicate keys, null optional values, trailing documents and invalid
UTF-8 are refused. At most 64 concurrent connections, and 8 active operations by default
(--max-active, 1 to 64). An overlarge status fails; query one key. There is no pagination.