← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesstack72
#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, theGET /andGET /healthsection: 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/healthnever ends a drain; load balancers should use/ready, which turns 503shutting_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/readyturns 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 withSO_REUSEPORTand 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.mdandhow-to/swamp-serve/run-multi-instance-deployment.md, rolling restarts:- Until startup completes, run starts and resumes get
not_ready(503 withRetry-After: 2, also to verified webhook deliveries); while draining they getdraining/shutting_down(503,Retry-After: 5). swamp … --serverretries 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.
- Until startup completes, run starts and resumes get
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
Shipped
Click a lifecycle step above to view its details.
03Sludge Pulse
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.