Skip to main content
← 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 --server and 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/config and the cluster instance info keep reporting the startup values.

Proposed solution

  1. One reload path for SIGHUP, the WebSocket serve.reload request and the config poller, built on the webhook route reload (apply triggers, keep-last-good on a broken file).
  2. 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.
  3. 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;
    • schedule on or off, grant-reload mode, and the poll, heartbeat, reconciliation, continuation-sweep, token-GC and group-refresh intervals.
  4. 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.
  5. No --hot-reload dependency. The WebSocket reload works on every platform and SIGHUP on POSIX; the flag stays accepted.
  6. Live values reported: /api/v1/serve/config and 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-users and 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-port covers these).
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 7 MOREREVIEW+ 8 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/10/2026, 6:47:38 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack7211/10/2026, 4:24:04 PM
stack72 linked sibling of #456011/10/2026, 4:24:28 PM

Sign in to post a ripple.