Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(integration): describe ingress while a plugin restores

Yudhi Armyndharisd85bb2cb98c9
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index d3d607c75..c1c9316ac 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -7001,19 +7001,19 @@ response only; the `verifyToken` is also shown (unchanged).
#### GET /api/ingress/:pluginId/:instanceId/:path
-**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` the route's plugin is still being restored after startup, or a route declaring a `session-alive` preflight whose bound session has no running engine, or its engine has failed
+**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` a route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session without a running engine or with a failed one
#### POST /api/ingress/:pluginId/:instanceId/:path
-**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` the route's plugin is still being restored after startup, or a route declaring a `session-alive` preflight whose bound session has no running engine, or its engine has failed
+**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` a route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session without a running engine or with a failed one
#### PUT /api/ingress/:pluginId/:instanceId/:path
-**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` the route's plugin is still being restored after startup, or a route declaring a `session-alive` preflight whose bound session has no running engine, or its engine has failed
+**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` a route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session without a running engine or with a failed one
#### PATCH /api/ingress/:pluginId/:instanceId/:path
-**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` the route's plugin is still being restored after startup, or a route declaring a `session-alive` preflight whose bound session has no running engine, or its engine has failed
+**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong per-instance secret) · `413` payload too large · `415` body in a content type no parser reads · `429` rate limit exceeded · `503` a route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session without a running engine or with a failed one
#### DELETE /api/ingress/:pluginId/:instanceId/:path
@@ -7036,11 +7036,14 @@ declarative `ack` config (doc 25); the plugin itself always runs async. A re-del
already-persisted event is answered with the route's ack, with the same status and headers as the
first delivery, and is not enqueued again. The ack is rendered from the retry, so `{timestamp}` in
an ack body is the retry's time and `{rawBody}` is the retry's body. A retry still passes the checks
-that run before dedup: while the route's plugin is still being restored after startup, or a
-`session-alive` route's bound session has no running engine, or its engine has failed, it gets the
-`503`, with a `Retry-After` header.
-
-**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong secret) · `403` `GET` verification challenge failed on a route that declares `challenge` (`verifyToken` mismatch) · `404` unknown pluginId/instanceId, or no such claimed route · `413` body over the route's `maxBodyBytes` · `415` a body in a content type no parser reads (only `application/json` and `application/x-www-form-urlencoded` are read) · `429` rate limit: the per-instance bucket (`INGRESS_INSTANCE_LIMIT`, counted only for deliveries that pass signature verification) or the per-client-IP bucket (`INGRESS_IP_LIMIT`), both per `INGRESS_INSTANCE_TTL`; the global per-IP tiers skip this route, so these two are its bounds, and `Retry-After-instance` / `Retry-After-ingress-ip` names the one that shed the request, alongside a plain `Retry-After` carrying the same delay · `503` the route's plugin is still being restored after startup, or a route declaring a `session-alive` preflight whose bound session has no running engine, or its engine has failed (a session that is starting, reconnecting, waiting for a QR scan, or disconnected but still loaded is answered with the route's ack and queued): the delivery is not persisted, so the provider's retry is treated as a new delivery, and `Retry-After` carries the delay
+that run before dedup: on a route that declares a response contract it gets the `503`, with a
+`Retry-After` header, while the route's plugin is still being restored after startup, or while a
+`session-alive` route's bound session has no running engine or its engine has failed. A route without a
+response contract is accepted while its plugin restores: the delivery is stored and dispatched once the
+plugin is up (a queued job waits without spending a retry attempt; with the queue off the reconciler
+dispatches the stored row).
+
+**Errors:** `400` an encoded NUL (`%00`) in the path or query, or a JSON body that does not parse · `401` signature verification failed (missing, stale, or wrong secret) · `403` `GET` verification challenge failed on a route that declares `challenge` (`verifyToken` mismatch) · `404` unknown pluginId/instanceId, or no such claimed route · `413` body over the route's `maxBodyBytes` · `415` a body in a content type no parser reads (only `application/json` and `application/x-www-form-urlencoded` are read) · `429` rate limit: the per-instance bucket (`INGRESS_INSTANCE_LIMIT`, counted only for deliveries that pass signature verification) or the per-client-IP bucket (`INGRESS_IP_LIMIT`), both per `INGRESS_INSTANCE_TTL`; the global per-IP tiers skip this route, so these two are its bounds, and `Retry-After-instance` / `Retry-After-ingress-ip` names the one that shed the request, alongside a plain `Retry-After` carrying the same delay · `503` a route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session without a running engine or with a failed one (a session that is starting, reconnecting, waiting for a QR scan, or disconnected but still loaded is answered with the route's ack and queued): the delivery is not persisted, so the provider's retry is treated as a new delivery, and `Retry-After` carries the delay
## 6.5 Real-time API (WebSocket)
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index e5f113288..241423c07 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -106,11 +106,14 @@ Alongside this async pipeline, a route may additionally declare a `response` con
**before** the dedup persist — returning `503` only for a definitively-dead concrete-scoped WhatsApp
session (no live engine or `FAILED`), with a `Retry-After` so a provider that retries a 503 only when
that header is present comes back; recoverable statuses and `READY` pass through to a normal
- `202`+enqueue so the worker can still fail fast and the dedup row still holds the delivery. A declared
+ `202`+enqueue so the worker can still fail fast and the dedup row still holds the delivery. The same
+ `503` with `Retry-After`, again before the dedup persist, answers a route declaring `response` while its
+ plugin is still being restored after startup: no worker can take the delivery yet and the provider wants
+ its answer now (see §25.7 for a route without `response`). A declared
`ack` (`status`/`body`/`headers`) replaces the default `202 accepted`. For a route declaring `response`,
the ack is returned without awaiting enqueue so a queue-disabled deployment cannot block the provider's
deadline; the dedup row already persisted is the durability handle. A route with no `response` is
- byte-identical to today's default fast-ack.
+ byte-identical to today's default fast-ack, while its plugin restores included.
- **Plugin instance** — a first-class `instanceId` namespaced under a `pluginId`. One adapter can back
many instances (for example, one external account per WhatsApp number). Each instance owns a host-minted
ingress secret, a resolved session scope, and a config slice. It is a serializable field threaded
@@ -279,6 +282,19 @@ deliver. A `pending` row found without a payload (only possible for imported/cor
payloads are retired only with a recorded outcome) is excluded from the sweep and never replayed
empty; nothing logs it, and it stays `pending` until `INGRESS_DEDUP_RETENTION_DAYS` prunes it.
+**Plugin restore window.** The gateway opens its port before a slow plugin restore has finished (see
+[19](./19-plugin-architecture.md), Restore on boot), so a delivery can arrive for a plugin that has no
+worker yet. A route declaring a `response` contract is refused with `503` and `Retry-After: 5` (§25.4),
+and the provider's retry is accepted once the plugin is up. Any other route is accepted and persisted
+as usual. A queued job goes back to the delayed set after `INGRESS_RETRY_DELAY_MS` (at least a second),
+without spending a retry attempt, until the plugin is up, and jobs held together come back in the order they
+were held. With the queue off the delivery is acked and not dispatched: its row stays `pending`, and the
+reconciler dispatches it after the restore, on its first pass past `INGRESS_RECONCILE_GRACE_MS`, so up to
+about two minutes after the delivery with the defaults. The reconciler leaves the rows of a restoring plugin
+out of its batch, so they do not hold back another plugin's. With the reconciler disabled
+(`INGRESS_RECONCILE_INTERVAL_MS=0`) nothing would replay a held row, so the delivery is dispatched at once
+and, finding no worker, files a dead letter that an operator can redrive.
+
Table growth is bounded by construction rather than by operator hygiene: the per-instance ingress
throttle caps the row-creation rate, dispatched rows slim to a marker + hash, and the two retention
windows prune what remains — `INGRESS_DEDUP_RETENTION_DAYS` (default 7) for the dedup oracle and
diff --git a/openapi.json b/openapi.json
index 18897a2e5..f6e611e18 100644
--- a/openapi.json
+++ b/openapi.json
@@ -16965,7 +16965,7 @@
"description": "Rate limit exceeded: the per-instance bucket (INGRESS_INSTANCE_LIMIT) or the per-client-IP bucket (INGRESS_IP_LIMIT). The `Retry-After-instance` / `Retry-After-ingress-ip` header names which one shed the request, and a plain `Retry-After` carries the same delay for a client that reads only the standard name."
},
"503": {
- "description": "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay."
+ "description": "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores."
}
},
"tags": [
@@ -17032,7 +17032,7 @@
"description": "Rate limit exceeded: the per-instance bucket (INGRESS_INSTANCE_LIMIT) or the per-client-IP bucket (INGRESS_IP_LIMIT). The `Retry-After-instance` / `Retry-After-ingress-ip` header names which one shed the request, and a plain `Retry-After` carries the same delay for a client that reads only the standard name."
},
"503": {
- "description": "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay."
+ "description": "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores."
}
},
"tags": [
@@ -17099,7 +17099,7 @@
"description": "Rate limit exceeded: the per-instance bucket (INGRESS_INSTANCE_LIMIT) or the per-client-IP bucket (INGRESS_IP_LIMIT). The `Retry-After-instance` / `Retry-After-ingress-ip` header names which one shed the request, and a plain `Retry-After` carries the same delay for a client that reads only the standard name."
},
"503": {
- "description": "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay."
+ "description": "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores."
}
},
"tags": [
@@ -17166,7 +17166,7 @@
"description": "Rate limit exceeded: the per-instance bucket (INGRESS_INSTANCE_LIMIT) or the per-client-IP bucket (INGRESS_IP_LIMIT). The `Retry-After-instance` / `Retry-After-ingress-ip` header names which one shed the request, and a plain `Retry-After` carries the same delay for a client that reads only the standard name."
},
"503": {
- "description": "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay."
+ "description": "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores."
}
},
"tags": [
@@ -17233,7 +17233,7 @@
"description": "Rate limit exceeded: the per-instance bucket (INGRESS_INSTANCE_LIMIT) or the per-client-IP bucket (INGRESS_IP_LIMIT). The `Retry-After-instance` / `Retry-After-ingress-ip` header names which one shed the request, and a plain `Retry-After` carries the same delay for a client that reads only the standard name."
},
"503": {
- "description": "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay."
+ "description": "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores."
}
},
"tags": [
@@ -17300,7 +17300,7 @@
"description": "Rate limit exceeded: the per-instance bucket (INGRESS_INSTANCE_LIMIT) or the per-client-IP bucket (INGRESS_IP_LIMIT). The `Retry-After-instance` / `Retry-After-ingress-ip` header names which one shed the request, and a plain `Retry-After` carries the same delay for a client that reads only the standard name."
},
"503": {
- "description": "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay."
+ "description": "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores."
}
},
"tags": [
@@ -17367,7 +17367,7 @@
"description": "Rate limit exceeded: the per-instance bucket (INGRESS_INSTANCE_LIMIT) or the per-client-IP bucket (INGRESS_IP_LIMIT). The `Retry-After-instance` / `Retry-After-ingress-ip` header names which one shed the request, and a plain `Retry-After` carries the same delay for a client that reads only the standard name."
},
"503": {
- "description": "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay."
+ "description": "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores."
}
},
"tags": [
diff --git a/src/modules/integration/ingress.controller.ts b/src/modules/integration/ingress.controller.ts
index ae0b0863e..187821ac6 100644
--- a/src/modules/integration/ingress.controller.ts
+++ b/src/modules/integration/ingress.controller.ts
@@ -80,7 +80,7 @@ export class IngressController {
@ApiResponse({
status: 503,
description:
- "The route's plugin is still being restored after startup, or a route whose response contract declares a `session-alive` preflight has a bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay.",
+ "A route that declares a response contract, while its plugin is still being restored after startup or when its `session-alive` preflight finds the bound session with no running engine or a failed one (a starting, reconnecting or QR-pending session is answered with the route's ack). The delivery is not persisted, so the provider's retry is treated as a new one; `Retry-After` carries the delay. A route without a response contract is accepted while its plugin restores.",
})
async receive(
@Param('pluginId') pluginId: string,