Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(integration): describe ingress while a plugin restores
Yudhi Armyndharisd85bb2cb98c9
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 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-delalready-persisted event is answered with the route's ack, with the same status and headers as thefirst delivery, and is not enqueued again. The ack is rendered from the retry, so `{timestamp}` inan 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.mdindex 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 WhatsAppsession (no live engine or `FAILED`), with a `Retry-After` so a provider that retries a 503 only whenthat 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'sdeadline; 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 backmany instances (for example, one external account per WhatsApp number). Each instance owns a host-mintedingress 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/corpayloads are retired only with a recorded outcome) is excluded from the sweep and never replayedempty; 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 ingressthrottle caps the row-creation rate, dispatched rows slim to a marker + hash, and the two retentionwindows prune what remains — `INGRESS_DEDUP_RETENTION_DAYS` (default 7) for the dedup oracle anddiff --git a/openapi.json b/openapi.jsonindex 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.tsindex 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,