Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesstack72

Relationships

↔ sibling #4794↔ sibling #4829↔ sibling #4900

#4577 Docs: swamp serve restart behaviour from #4566 (/health draining body, --reuse-port, --shutdown-listener-grace, startup not_ready refusals)

Opened by stack72 · 11/10/2026· Shipped 11/19/2026

swamp-club#4566 (PR swamp-club/swamp#3706) changes user-facing serve behaviour that the manual under content/manual/ describes or should describe.

Now wrong

  • reference/swamp-serve/rest-api.md, the GET / and GET /health section: the body is { "status": "ok", "version": "1" } while serving, and { "status": "draining", "version": "1" } once shutdown begins. The status code stays 200 in both cases, so a liveness probe on /health never ends a drain; load balancers should use /ready, which turns 503 shutting_down.

Missing

  • reference/swamp-serve/serve-flags.md: two new settings, both set at startup and not on reload:
    • --shutdown-listener-grace / SWAMP_SHUTDOWN_LISTENER_GRACE / shutdown-listener-grace (default 1 s, 0 with --reuse-port, never more than --shutdown-drain-timeout): how long serve keeps listening after /ready turns 503. The listener closes once in-flight runs drain and the grace has passed. Set it above the load balancer's health-check window.
    • --reuse-port / SWAMP_REUSE_PORT / reuse-port (default false): listens with SO_REUSEPORT and opens the port only once startup completes, so a new serve can start beside the old one. Linux only; elsewhere serve warns and a second serve fails before startup does any work.
  • how-to/swamp-serve/deploy-on-kubernetes.md and how-to/swamp-serve/run-multi-instance-deployment.md, rolling restarts:
    • Until startup completes, run starts and resumes get not_ready (503 with Retry-After: 2, also to verified webhook deliveries); while draining they get draining / shutting_down (503, Retry-After: 5).
    • swamp … --server retries refusals serve did not act on for 30 s before a run has an id and reattaches for up to 120 s; @swamp-club/swamp-lib (packages/client) retries within 30 s.
    • Webhook senders do not retry: zero failed deliveries needs a preStop sleep, a proxy that retries 503 on another node, --reuse-port, or a second instance.
    • An overlapping restart on one Linux host: start the new serve with --reuse-port, wait for its /ready, then stop the old one. Queued runs belong to the process that queued them and are replayed once it stops. Not supported on a v3 datastore until team mode.
  • how-to/worker-fleets/*: a worker now keeps retrying for up to 5 minutes before enrolment while serve looks like it is restarting (refused connection, 502–504), instead of giving up after 3 failures.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 5 MOREISSUE_LINKED+ 6 MOREREVIEW+ 8 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/19/2026, 6:06:01 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack7211/19/2026, 5:05:07 PM
stack72 linked sibling of #457611/10/2026, 7:25:10 AM
stack72 removed sibling of #457611/10/2026, 7:27:58 AM
stack72 linked sibling of #479411/19/2026, 5:05:29 PM
stack72 linked sibling of #482911/19/2026, 5:05:32 PM
stack72 linked sibling of #490011/19/2026, 5:05:35 PM
Editable. Press Enter to edit.

system commented 11/10/2026, 7:20:05 AM

Classified automatically when this issue was filed.

  • Type: Bug

If you feel this classification is incorrect, add a ripple to tell us so.

Sign in to post a ripple.