Relationships
#4602 serve: swamp serve reload applies the access lists, audit, intervals and proxy settings without a restart
Opened by stack72 · 11/10/2026· Shipped 11/10/2026
Second half of #4588, part of #4439: everything in serve.yaml except the listener, the auth mode and the datastore should change with swamp serve reload, not a restart.
#4588 (swamp PR #3716) built the reload path: serve.yaml is validated like startup, a refused file changes nothing, every changed setting is reported as applied, needs a restart (with the reason) or pinned by a flag or env var, and reload works on every serve without --hot-reload. Its setting catalogue (src/serve/serve_settings_reload.ts) still marks the settings below "not applied by reload yet; restart serve to change it". This issue moves them to applied.
Settings to reload
- Auth lists (OAuth mode).
auth.adminsandauth.allowed-usersare resolved from usernames as at startup (club API key, else the cached name map). A name that cannot be resolved is reported as needing a restart and the previous entry is kept. The lists are spliced into the live auth config, which every per-request reader and the token admission checker read at call time. Admin grants are re-materialised (a removed admin loses the grant, a new one gains it) and the policy snapshot reloads.allowed-collectives,restricted-model-types,restricted-commands(with the ineffective-restriction check) andgroups-fieldare spliced too; a changedallowed-collectivesre-registers the instance with swamp-club.auth.modeand the OAuth provider and client stay restart-only. - Audit pipeline beyond sinks. Alert rules (replace the rule engine), audit policy, fail-open. Adding or removing the audit stores, WAL or HMAC stays restart-only (hash chain and WAL continuity).
- Intervals. Poll, heartbeat, reconciliation, continuation-sweep, token-GC and group-refresh intervals re-arm their timers;
stale-ttlbecomes one live value. - trust-proxy and trusted-hosts, plus
dispatch-env-allow,verify-on-enrolland remote-only mode. Each value read on several request paths gets a test that changes it through reload and observes it on every path that reads it; a value without that coverage stays restart-only.
Turning scheduling on or off, max-concurrent-scheduled-runs and grant reload mode moved to #4604.
Review notes from #4588 to fix here
queue-timeoutis reported as applied, but the worker pool reader keeps the startup value, so fan-out lanes over workers still use the old queue timeout. The reader should read the live value.- More serves now write
.swamp/serve.pid(every serve without a terminal). After a kill -9 or OOM kill the file stays, and a localswamp serve reloadsends SIGHUP to whatever process holds that PID. Check the target is a swamp serve before signalling (for example a start-time token written beside the PID). - Retention GC backs off at the startup
max-concurrent-runs, not the live cap. - The max-run-duration abort log reads the limit when the timer fires, not when the run was registered.
- A reload that lowers
shutdown-drain-timeoutdoes not re-bound the listener grace. triggersis reported as applied on a serve without the scheduler, where nothing applies it.- On SIGHUP, a refused serve.yaml is logged as a warning rather than an error.
Docs
design/enablers/access-control.md: admission lists change on reload. The swamp skill's serve guide: "and restarting serve" becomes "and running swamp serve reload". design/primitives/serve.md: the settings that move to applied.
Departures from the list above
- Admins. Every
auth.adminschange stays a restart, and admin grants are not re-materialised on reload. Removing an admin on reload moved to #4604 with the grant work, because it is a grant write that must land on the leader and survive a change of leader. - Unresolvable names. A new allowed-user that cannot be resolved is deferred, retried on each reload and reported. Removals in the same edit always apply, rather than keeping the previous list. An allowed-users list emptied by removals and deferrals, with no collectives, keeps an entry that matches no one, so admission stays closed.
- Restart-only for good:
stale-ttlandheartbeat-interval(every instance judges its peers' liveness by them),remote-only(every step of a running run reads it),tls.ca-certandauth.keep-oauth-client-in-vault. - Moved to #4604:
grants-file,grants-dirand the three explicit-grant rules. - Starting or stopping a timed service by changing an interval to or from 0, or for a service that was never started, is reported as needing a restart.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.