Relay
detent-relay is optional fan-out between the authority and the agents. It
holds one upstream subscription per configured bundle, keeps its own durable
copy, and serves many agents from it, so the authority sees one subscriber per
bundle instead of one per host.
Inside the Relay
Section titled “Inside the Relay”What, How, When, Where
Section titled “What, How, When, Where”What. One relay serves a fixed list of bundles. A bundle is one upstream scope: an authority identity, a principal, a policy epoch and a set of namespaces.
How. Upstream, each bundle’s source file uses the managed delivery
configuration, and relay sources always subscribe: an explicit
"delivery_mode": "poll" is rejected. Downstream, the relay listens with TLS
on 127.0.0.1:8318 by default and serves only POST /v2/distribution/session/open, /next and /close, plus GET /v1/health.
A downstream bearer token grants a list of bundle indices. An agent behind a
relay must set "delivery_mode": "subscription".
Each upstream update becomes a durable generation in the bundle’s directory and an entry in a bounded cache (64 recent edges and 64 MiB per bundle by default). An agent whose cursor the cache covers gets a delta; anything else gets a snapshot. Simultaneous agents borrow the same encoded payload.
When.
- First start: a bundle with
"mode": "fresh"provisions an empty store. Switch it to"existing"(or remove it) before the next restart. - Startup: the relay recovers every bundle and authenticates every upstream source; health reports ready only after both.
- Steady state: upstream updates become generations and cache entries. Cache pressure produces a gap, and the relay rebuilds a current snapshot with bounded work.
- Restart: it resumes from each bundle’s last durable selection.
Where. Between the authority and the agent hosts. Build with
-DDETENT_BUILD_RELAY=ON (off by default; requires OpenSSL 3.0). The
configuration is relay.json in the user configuration directory, or the
system one with --system. Bundle directories are private (0700, files
0600); system services put them under /var/lib/detent-relay on Linux or
/var/db/detent-relay on macOS and FreeBSD. The source is in
src/detent_relay/.
Read More
Section titled “Read More”- Durable Relay guide: configuration and services.
- Delivery and Local Images: the generation format the relay and agents share.
- Relay qualification and configuration in the repository.