feat(swarmctl): add agent create, queueing the swarm-controller creation DAG

`swarmctl agent create <name> --hive <hive>` POSTs `/api/agents` to
swarm-controller over the daemon's unix socket and prints the queued
job's node id.

It deliberately does not wait. The endpoint queues a DAG whose last node
*publishes* a deploy message; the hive's `hive-c0re` then converges on
its own clock, out of the controller's sight. So even a fully settled
graph would not mean the agent is up, and there is nothing this CLI
could wait for that would let it claim otherwise. Printing the id is
exactly what the response says and all of what it says.

Transport is a bare hyper HTTP/1.1 client handshaked onto a tokio
`UnixStream` via `hyper_util::rt::TokioIo` — the same crate family
`hivectl/src/watch.rs` and `hive-agent/src/web_ui/proxy.rs` already use,
all of it already workspace-pinned. The request/response shapes are a
local mirror rather than a shared crate: the controller's own types are
private to its binary and this crate does not link it, the same
separation `hivectl` keeps from `hive-c0re`.

Errors are reduced to one actionable line — the controller answers
RFC 9457 problem+json, so an unknown `--hive` reaches the operator as
the roster of hives that would have worked rather than a body dump.
Response `warnings` are printed when non-empty.

The nix module wraps the binary with `SWARM_CONTROLLER_SOCKET`, read
from the same `socketPath` the daemon binds.

Refs #4399
This commit is contained in:
atlas 2026-09-14 18:54:14 +02:00 committed by mara
commit 30fa54cbc6
9 changed files with 521 additions and 17 deletions

View file

@ -169,10 +169,16 @@ hand-maintained per-file tree drifts out of sync with the code.
**no identity** and a TLS handshake failure that names no cause.
- **`swarmctl/`** — swarm-level operator CLI, installed by the
swarm-controller module on the host that runs the daemon. Runs as
**root and acts directly** — no socket, no HTTP route, no priv helper;
the crate's README records why the rootless shape was examined and
rejected. Does not link `swarm-controller`, mirroring `hivectl` ÷
`hive-c0re`. ⚠️ Its user store is authelia's own **`users.yml`, read and
**root and acts directly** — it serves no socket, publishes no HTTP
route and has no priv helper; the crate's README records why the
rootless shape was examined and rejected. `agent create` is the one
verb that talks to a service rather than acting locally: it POSTs
`/api/agents` to swarm-controller over the daemon's unix socket and
prints the queued job id without waiting (the DAG settling would not
mean the agent is up). Does not link `swarm-controller` — its wire
shapes are a local mirror kept in this crate, not a shared crate, so
the two binaries can be deployed independently. ⚠️ Its user store is
authelia's own **`users.yml`, read and
written in place** — one file, shared with `swarm-authelia-bridge`; see
that crate's README for what both writers must uphold. Full, always-current
verb reference (CI-enforced against the clap tree, same pattern as