vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

setup assistant creates ruth with logs and metrics; docs for the harness gate, ordering and pass

Browse source
This commit is contained in:
atlas 2026-11-01 18:27:55 +01:00
commit 8a60f52afa
1 changed files with 44 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/process/conventions.md
View file

@ -316,19 +316,30 @@ none. swarm-controller logs every refused `PUT` or `DELETE` on that route at `wa
**`logs` and `metrics`** — off for every agent until granted, and separate
because logs are the more sensitive. Grant one with
`swarmctl agent permissions set <agent>` (listing it with the others) or the
create-agent screen. An agent without it gets a 403 from the store's gateway
when `swarm-logs` or `swarm-metrics` queries; a bad secret is still a 401. The
controller refuses the grant, with a 409 naming the hive, unless the agent's
hive advertises `tolerant-permissions` in its status snapshot
(`swarm_wire::hive_status`): a hive that predates the permission would fail to
decode the record. It also mirrors the two grants to the store leaf
create-agent screen; the setup assistant creates ruth with both. An agent
without it gets a 403 from the store's gateway when `swarm-logs` or
`swarm-metrics` queries; a bad secret is still a 401.
An agent decodes its own record, in its harness
(`hive-agent/src/swarm_permissions.rs`, through `swarm_queue_client::agent_permissions::read`),
and a build that doesn't know a name would drop to no permissions. So
swarm-controller refuses a change that adds `logs` or `metrics` to an existing
agent, with a 409, unless both the agent's hive (`tolerant-permissions` in its
status snapshot) and its running harness (the same entry in its turn-state
header, `swarm_wire::hive_status`) advertise it. A harness not yet updated, a
stopped agent and one that hasn't sent its first header (up to a minute after
a restart) all refuse; keeping a grant it already holds needs no report. A
create has no harness yet and checks the hive only.
The controller mirrors the two grants to the store leaf
`swarm/agents/<agent>/observability` (`swarm_secret_client::observability`),
which the gateways read; the gateway denies when it can't read that leaf. A
revoked grant stops working within `authVerdictTtl` (60 seconds by default) of
the agent's last allowed query. Grant it only after the agent runs a harness
that skips names it doesn't know (its next update after the release that adds
these two); an older harness that reads such a record holds no permissions at
its next start.
which the gateways read, and the gateway denies when it can't read that leaf.
A change that drops a grant writes the leaf first and the record second, so a
failed write changes nothing; a change that adds one writes the record first,
so a failed write leaves the gateway denying. Every five minutes the controller
also makes each agent's leaf equal its record and logs a warning for each leaf
it corrects. A revoked grant stops working within `authVerdictTtl` (60
seconds by default) of the agent's last allowed query.
**Internet flag** — the record also carries `unrestricted_internet`, a
boolean that isn't a `Permission`. An absent value means on, so every agent