← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesstack72
Relationships
↔ sibling #4560#4588 swamp serve reload applies every setting that can change in place, validated and reported (auth lists, audit, limits; no --hot-reload needed)
Opened by stack72 · 11/10/2026· Shipped 11/10/2026
Part of swamp-club#4439 (the reload half). The rolling-restart half shipped as swamp-club#4566; webhook route files shipped as swamp-club#4547 and follow-ups.
Problem
swamp serve reload re-applies only pulled extensions, the trust list, extension workflow directories, trigger overrides and webhook routes. Every other serve setting needs a restart, including the ones operators change routinely:
auth.admins,auth.allowed-users,auth.allowed-collectives,auth.restricted-*. With swamp-club#4530, removing someone from the lists refuses their credentials at once, but the lists themselves only change on restart.trust-proxy,trusted-hosts,dashboard,remote-only,auto-resume, run limits and timeouts.- Audit sinks, alerts and policy.
The reload path has also drifted and is loose:
- SIGHUP,
swamp serve reload --serverand the config poller take different paths: SIGHUP does not rebuild audit sinks, the WebSocket reload does not discover new extensions, and the config poller re-applies neither triggers nor webhooks. - Reload reads the raw config file with
readServeConfigFile, without the validation startup applies and without the startup flags and env (swamp-club#4560 is one symptom: trigger overrides are installed unvalidated). - Reload only exists when serve started with
--hot-reload, and serve refuses that flag on Windows. /api/v1/serve/configand the cluster instance info keep reporting the startup values.
Proposed solution
- One reload path for SIGHUP, the WebSocket
serve.reloadrequest and the config poller, built on the webhook route reload (apply triggers, keep-last-good on a broken file). - A validated re-merge. Re-run the startup merge with the startup flags and env (flags and env still win), plus the auth and off-loopback checks. A file that fails validation changes nothing and is reported.
- Apply in place, setting by setting:
- auth lists (admins re-materialised as grants; usernames resolved with the club API key or the cache, otherwise reported as needing a restart),
restricted-*,groups-field; trust-proxy,trusted-hosts,dashboard,enable-internal-api,remote-only,auto-resume;- run limits,
queue-timeout,ws-idle-timeout,max-signal-wait-timeout,shutdown-drain-timeout,verify-on-enroll,dispatch-env-allow; - audit sinks, alerts, policy and fail-open;
scheduleon or off,grant-reloadmode, and the poll, heartbeat, reconciliation, continuation-sweep, token-GC and group-refresh intervals.
- auth lists (admins re-materialised as grants; usernames resolved with the club API key or the cache, otherwise reported as needing a restart),
- Report every changed setting as applied, needs restart (naming why), or overridden by a flag or env var, in log and JSON modes. A change is never silently ignored.
- No
--hot-reloaddependency. The WebSocket reload works on every platform and SIGHUP on POSIX; the flag stays accepted. - Live values reported:
/api/v1/serve/configand the cluster instance info show the values in force after a reload.
Stays restart-only, and is reported as such: host and port, TLS, auth.mode, the OAuth provider and client, token-secrets, the repo, datastore and --config path, and @env= values.
Acceptance
- Changing each reloadable setting in serve.yaml and running
swamp serve reload(local and--server) applies it without a restart; the reload output names it. - Removing a person from
allowed-usersand reloading refuses their credentials without a restart. - A setting overridden by a flag reports "overridden"; a restart-only setting reports "needs restart"; an invalid file changes nothing.
- swamp-club#4560 no longer reproduces.
Out of scope
- Runs surviving restarts, worker dispatch survival, protocol version ranges (#4439, later part).
- Rolling upgrades on a v3 datastore (needs datastore Phase 5 team mode).
- Rebinding the listener or swapping a TLS certificate in place (an overlapping restart with
--reuse-portcovers these).
02Bog Flow
Shipped
Click a lifecycle step above to view its details.
03Sludge Pulse