Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: correct two claims the code does not support
Yudhi Armyndharis6505e0a0fef9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7c26c57f6..1033409bf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -64,6 +64,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- PostgreSQL deployments: the data connection issues `SET TIME ZONE 'UTC'` per connection and verifies the result at boot. A deployment where that cannot hold (a pooler that drops session state) now fails to start, naming the effective zone; set the default instead with `ALTER DATABASE "<database>" SET TimeZone='UTC'`. SQLite deployments, and any gateway already running in UTC, are unaffected and no data moves.- PostgreSQL deployments whose **gateway** ran outside UTC before this release: the twelve columns the app writes itself hold that host's local wall time and now read as UTC, so they appear shifted by the offset. They are `sessions.connectedAt`, `sessions.lastActiveAt`, `sessions.claimedAt`, `sessions.leaseExpiresAt`, `webhooks.lastTriggeredAt`, `webhook_outbox_events.lastAttemptAt`, `ingress_events.lastDispatchAt`, `message_batches.started_at`, `message_batches.completed_at`, `lid_mappings.updatedAt`, `chat_states.updatedAt` and `baileys_stored_messages.createdAt`. The last three carry a `DEFAULT now()` that never fires, because their only writer passes the value. With the gateway stopped, convert each with the host's old zone, which resolves daylight saving per row: `UPDATE sessions SET "connectedAt" = ("connectedAt" AT TIME ZONE 'Asia/Jakarta') AT TIME ZONE 'UTC' WHERE "connectedAt" IS NOT NULL;`. `claimedAt` and `leaseExpiresAt` are cluster runtime state: clear them, do not convert them, with every node stopped and before the first start on this release, or the lease reads shifted by the old offset and the session is unusable until it lapses. East of UTC it reads hours into the future, so every node treats the session as held elsewhere and `POST /sessions/{id}/start` answers `409`; west of UTC it reads already lapsed, so a peer can adopt a session that is still running. `UPDATE sessions SET "nodeId" = NULL, "claimedAt" = NULL, "leaseExpiresAt" = NULL, "nodeUrl" = NULL;`. Leaving `lid_mappings.updatedAt` and `chat_states.updatedAt` unconverted also mis-ranks the boot preload of both caches, which orders by that column under a cap.- The remaining eighteen `createdAt`/`updatedAt` columns are written by PostgreSQL itself (`DEFAULT now()`) in the **server's** zone, not the gateway's. On a UTC server, which is the image default and what the bundled Compose file starts, they are already correct and must not be converted; convert them only if the server itself ran outside UTC, with the server's old zone.+- `messages.createdAt` is the exception among those eighteen and must not be converted in bulk. A live message takes the server default, but a row written by the Baileys history backfill carries the message's own time, bound by the gateway, so on a gateway that ran outside UTC that column holds both conventions at once and nothing in the row says which. The residual skew affects only the backfilled rows, and it shows up in chat ordering, the `today` counters and the media retention window for them.- A table that has had an archive from a **SQLite** gateway restored into it holds those rows in correct UTC while the app wrote its own in local time. The two are indistinguishable within the column, so a blanket `UPDATE` would move the rows that are already right; correct such a column row by row against a known archive, or leave it as it is.- An archive a **PostgreSQL** gateway outside UTC exported before this release is shifted the other way, and restoring it moved the whole table, `DEFAULT now()` columns included: the export read every value back through the local-time parser and the import bound the resulting ISO text into a column that drops the zone, so each restore took the table one offset backward. No row in such a table is correct, and the conversion above would move those rows a further offset the wrong way. Where the table holds nothing but restored rows, apply the inverse once per restore taken: `UPDATE sessions SET "createdAt" = ("createdAt" AT TIME ZONE 'UTC') AT TIME ZONE 'Asia/Jakarta';`. Where it also holds rows written after the restore, no blanket conversion is safe.- Re-export after upgrading for an archive whose stamps are the instants they claim; restoring a pre-release archive carries its shift in as it is.diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex 7bba84716..245eb47dd 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -180,6 +180,8 @@ Every timestamp column on the PostgreSQL data connection is `timestamp without tThree `@CreateDateColumn`/`@UpdateDateColumn` columns are filled by the app rather than by that default: `lid_mappings.updatedAt`, `chat_states.updatedAt` and `baileys_stored_messages.createdAt` reach the database through an `upsert` that passes the value, so the default behind them never fires and they follow the binding rule above instead of the session zone.+`messages.createdAt` is a fourth, and the only split one: a live message takes the server default, while a row written by the Baileys history backfill carries the message's own time, stamped in `message-history-projector.ts` so the chat panel orders history correctly. Both conventions are UTC from this release on, and the two cannot be told apart row by row, which is why the upgrade notes exclude that column from any blanket conversion.+Comparisons therefore mean the same thing on both dialects: a retention `LessThan(cutoff)`, a lease deadline written by another node, and a backup restored from any host all line up. SQLite is unaffected; it already stores ISO text in UTC.## 5.2 Entity Relationship Diagramdiff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 06e0f43b2..09c0511d3 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -803,7 +803,7 @@ Request an 8-char pairing code to link via phone number (alternative to QR).`status` is the lowercase session status.-**Errors:** `400` validation, or session not started, or already authenticated · `401` · `403` · `404` not found · `409` session not waiting to be linked yet; wait for `status` to read `qr_ready` and retry (after a code was accepted, wait for `ready` instead). On Baileys a session that already reads `qr_ready` can still answer `409` while its socket is closing, for up to the WebSocket close timeout (30 s); that is retryable and the status follows shortly. · `503` whatsapp-web.js only: every attempt landed while WhatsApp Web was reloading its own QR page, so the request never reached WhatsApp; retryable, and the last attempt's reason rides in the message.+**Errors:** `400` validation, or session not started, or already authenticated · `401` · `403` · `404` not found · `409` session not waiting to be linked yet; wait for `status` to read `qr_ready` and retry (after a code was accepted, wait for `ready` instead). On Baileys a session that already reads `qr_ready` can still answer `409` while its socket is closing, for up to the WebSocket close timeout (30 s); that is retryable and the status follows shortly. · `503` whatsapp-web.js only: the gateway stopped waiting after its attempt budget, usually because WhatsApp Web kept reloading its QR page; retryable, and the last attempt's reason rides in the message. An attempt that timed out may still have reached WhatsApp, and a retry starts the linking flow again, so the unlink warning above applies to the retry too.#### POST /api/sessions/:sessionId/presence/subscribediff --git a/openapi.json b/openapi.jsonindex f0a498d3a..0fa582d9f 100644--- a/openapi.json+++ b/openapi.json@@ -913,7 +913,7 @@"description": "The session is not waiting to be linked: the engine is still connecting, or reconnecting after a drop, so the request never reached WhatsApp. Wait for `status` to read `qr_ready` and retry. Once a code has been accepted the session moves through `authenticating` and `initializing` to `ready` and answers this until then; wait for `ready` in that case. A session that reads `ready` is already linked and answers `400` instead. One window answers this while the session still reads `qr_ready`: on the Baileys engine a socket that has begun closing stops accepting a pairing request before the status catches up, which on a silently dropped connection takes until the WebSocket's close timeout (30 s); retry, and the status follows shortly."},"503": {- "description": "The pairing code could not be generated: every attempt landed while WhatsApp Web was reloading its own page, so the request never reached WhatsApp. The condition is transient and the request is worth retrying; the last attempt's reason is carried in the message. The Baileys engine does not answer this, having no page to reload."+ "description": "The pairing code could not be generated: the gateway stopped waiting after its attempt budget, usually because WhatsApp Web kept reloading its QR page. The condition is transient and the request is worth retrying; the last attempt's reason is carried in the message. An attempt that timed out may still have reached WhatsApp, and a retry starts the linking flow again, so the unlink warning on this route applies to the retry too. The Baileys engine does not answer this, having no page to reload."}},"summary": "Request an 8-char pairing code to link via phone number (alternative to QR)",diff --git a/src/common/openapi/engine-status-responses.ts b/src/common/openapi/engine-status-responses.tsindex 46360d631..1f8b4eb81 100644--- a/src/common/openapi/engine-status-responses.ts+++ b/src/common/openapi/engine-status-responses.ts@@ -51,10 +51,12 @@ export const PAIRING_NOT_READY_409 =* attempt instead.*/export const PAIRING_TRANSPORT_503 =- 'The pairing code could not be generated: every attempt landed while WhatsApp Web was reloading its ' +- 'own page, so the request never reached WhatsApp. The condition is transient and the request is ' +- "worth retrying; the last attempt's reason is carried in the message. The Baileys engine does not " +- 'answer this, having no page to reload.';+ 'The pairing code could not be generated: the gateway stopped waiting after its attempt budget, ' ++ 'usually because WhatsApp Web kept reloading its QR page. The condition is transient and the ' ++ "request is worth retrying; the last attempt's reason is carried in the message. An attempt that " ++ 'timed out may still have reached WhatsApp, and a retry starts the linking flow again, so the ' ++ 'unlink warning on this route applies to the retry too. The Baileys engine does not answer this, ' ++ 'having no page to reload.';/*** The catalog and status services pass a `NotFoundException` factory to `EngineRegistry.require()`diff --git a/src/database/postgres-utc.ts b/src/database/postgres-utc.tsindex 3e6cfd78e..7dd26541f 100644--- a/src/database/postgres-utc.ts+++ b/src/database/postgres-utc.ts@@ -11,8 +11,9 @@ import { DataSource } from 'typeorm';* - the driver binds a JS Date as the PROCESS's local wall time (`sessions.connectedAt`, the lease* columns, the pending-delivery stamps: every column the app itself writes),* - the driver parses a naive timestamp back as PROCESS-local,- * - `DEFAULT now()`, which is what fills every `@CreateDateColumn`/`@UpdateDateColumn` (TypeORM does- * not bind those), writes the SERVER session's zone.+ * - `DEFAULT now()`, which is what fills a `@CreateDateColumn`/`@UpdateDateColumn` the app leaves+ * alone (TypeORM binds one only when a value is passed, as the contact and message-store upserts+ * and the Baileys history backfill do), writes the SERVER session's zone.** Off UTC the row therefore carries two conventions at once, and comparisons that mix them are wrong by* the offset: a retention `LessThan(cutoff)` binds the cutoff as local wall time and measures it against