Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(infra): note that /api/infra/health answers 503 during teardown

Yudhi Armyndharisb0ecb96e39b3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 50f48c3e5..a3f5122c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -75,7 +75,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Refuse bulk batches once shutdown begins, and answer `503` for a batch saved during shutdown instead of sending it.
- Stop in-flight webhook replay, ingress replay and pending-message sweeps at shutdown, waiting a bounded time for a replay in hand.
- Close queue workers, waiting up to 10 s for running jobs, before plugins shut down, so no new job is taken against stopped plugins.
-- Answer new HTTP requests other than health probes with `503` once teardown begins after SIGTERM, SIGINT or `POST /api/infra/restart`.
+- Answer new HTTP requests other than health probes with `503` once teardown begins after SIGTERM, SIGINT or `POST /api/infra/restart`; a Socket.IO handshake is still admitted until the server closes.
- Disable plugins in parallel at shutdown, capping the whole plugin phase, including waits for enables in progress, at 10 s.
- Bound the webhook redrive wait at shutdown by `WEBHOOK_SHUTDOWN_DRAIN_MS`, like the delivery drain and reconciler.
- Exit with status 1 when teardown runs 67 s past the shutdown delay, so a stalled close no longer runs into the kill deadline or hangs `POST /api/infra/restart`.
diff --git a/dashboard/src/services/api.ts b/dashboard/src/services/api.ts
index ba4b5cb64..3182ba493 100644
--- a/dashboard/src/services/api.ts
+++ b/dashboard/src/services/api.ts
@@ -1233,7 +1233,7 @@ export const infraApi = {
body: JSON.stringify({ profiles: profiles || [], profilesToRemove: profilesToRemove || [] }),
}),
// Readiness, not the plain /infra/health ping. The restart poll must not be able to latch onto the
- // process it just asked to shut down: /infra/health answers 200 for the whole drain and teardown,
+ // process it just asked to shut down: /infra/health answers 200 for the whole drain,
// while /health/ready reports 503 as soon as draining starts and stays 503 until both databases
// answer. Public (no API key), like /infra/health.
healthCheck: () => request<{ status: 'ok' | 'error'; details: Record<string, { status: string }> }>('/health/ready'),
diff --git a/dashboard/src/utils/restartPoll.ts b/dashboard/src/utils/restartPoll.ts
index b99d6e455..8db5495a7 100644
--- a/dashboard/src/utils/restartPoll.ts
+++ b/dashboard/src/utils/restartPoll.ts
@@ -1,8 +1,8 @@
/**
* How many one-second readiness polls to allow before a restart is declared failed.
*
- * The poll used to latch onto the OLD process — `/infra/health` answers 200 throughout the drain and
- * the engine teardown that follows — so it "succeeded" in about three seconds and the fixed 60-attempt
+ * The poll used to latch onto the OLD process — `/infra/health` answers 200 throughout the drain, while
+ * the old process is still shutting down — so it "succeeded" in about three seconds and the fixed 60-attempt
* deadline was never approached. Polling readiness instead means the poll genuinely waits for the new
* process, and the deadline becomes the thing that decides whether the operator sees the dashboard or
* an error screen.
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index a7cff1bd0..6d1124d81 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5461,7 +5461,7 @@ Admin-facing operations: infrastructure status & config, the data/storage migrat
#### GET /api/infra/health
-Public liveness probe.
+Public liveness probe. It answers `200` through the shutdown drain and `503` from the moment teardown begins, like every route except `/api/health` and `/api/health/*`; probe `GET /api/health/live` for liveness that survives teardown.
**Auth:** public
diff --git a/docs/07-api-collection.md b/docs/07-api-collection.md
index 41cdc5730..d59a81ea2 100644
--- a/docs/07-api-collection.md
+++ b/docs/07-api-collection.md
@@ -1385,7 +1385,7 @@ ADMIN-only operations (except the public health check and the MCP transport). As
#### GET /api/infra/health
-Public liveness probe.
+Public liveness probe. It answers `503` from the moment shutdown teardown begins; `GET /api/health/live` keeps answering.
```bash
curl "$BASE/api/infra/health"
diff --git a/src/configure-app.ts b/src/configure-app.ts
index 31f202d30..9363a64b5 100644
--- a/src/configure-app.ts
+++ b/src/configure-app.ts
@@ -225,7 +225,8 @@ export function configureApp(app: INestApplication, options: ConfigureAppOptions
// Once the shutdown grace has elapsed, teardown runs every destroy hook before the listener
// closes, and a request admitted then would run against services being torn down. Refuse new
// requests from that point; admitted ones run until teardown ends and are then cut by the HTTP close
- // (forceCloseConnections in main.ts). The health probes stay answered so
+ // (forceCloseConnections in main.ts). Socket.IO answers its handshake ahead of Express, so a new
+ // event-stream client is admitted until that close. The health probes stay answered so
// readiness keeps reporting its draining state. Ahead of the budget, so no body is read.
const shutdown = optional(ShutdownService);
app.use((req: Request, res: Response, next: NextFunction) => {