Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(engine): answer 409 when a page reload cuts a wwebjs call
Yudhi Armyndharisa4b1ee49c1aa
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1dfe525e2..7ed5f8adb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -70,6 +70,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Preserve literal request values in custom ingress acknowledgments.- Honor inclusive millisecond lower bounds in built-in search.- Preserve replacement plugin search providers during worker recovery.+- Answer 409 instead of a bare 500 when WhatsApp Web reloads its page under a running whatsapp-web.js read, and no longer report a group, contact, label or invite lookup cut short that way as not found (404); accepting an invite answers 503 because the join may have landed.- Answer 409 naming the path and the cause on `GET /api/infra/storage/files/count` and `/export` when the local storage directory holds a symbolic link, a directory the app cannot read or one nested 20 levels deep, instead of silently leaving those files out of the count and the archive.- Normalize CRLF line endings in SDK contract parsers so Windows checkouts do not produce false contract mismatches (#1885). Thanks @Purushotham-Prajapati-24.- Exclude local repository metadata from Java SDK Maven Central bundles built with Maven 3.10 (#1879).diff --git a/src/engine/adapters/whatsapp-web-js.adapter.ts b/src/engine/adapters/whatsapp-web-js.adapter.tsindex 2bb8bc2c5..580761369 100644--- a/src/engine/adapters/whatsapp-web-js.adapter.ts+++ b/src/engine/adapters/whatsapp-web-js.adapter.ts@@ -59,7 +59,7 @@ import { WwebjsChats } from './wwebjs-chats';import { WwebjsCatalog } from './wwebjs-catalog';import { registerWwebjsGroupEvents } from './wwebjs-group-events';import { WwebjsOnboardingWatcher } from './wwebjs-onboarding';-import { WwebjsLifecycle } from './wwebjs-lifecycle';+import { PAGE_RELOADING_MESSAGE, WwebjsLifecycle } from './wwebjs-lifecycle';import { WwebjsReadyReconcile } from './wwebjs-reconcile';import { WwebjsStuckAuth } from './wwebjs-stuck-auth';import { WwebjsCalls } from './wwebjs-calls';@@ -962,9 +962,7 @@ export class WhatsAppWebJsAdapter implements IWhatsAppEngine {// breaker for its 15-minute cooldown). Answer the same retryable 409 the pre-READY states get,// naming the reload so the operator can tell this state from a plain disconnect (#1081).if (this.lifecycle.isInNavigationReinjectWindow()) {- throw new EngineNotReadyError(- 'WhatsApp Web is reloading its page and the session is re-injecting. Retry in a few seconds.',- );+ throw new EngineNotReadyError(PAGE_RELOADING_MESSAGE);}}diff --git a/src/engine/adapters/wwebjs-chats.ts b/src/engine/adapters/wwebjs-chats.tsindex 4fdaec38f..520c3532e 100644--- a/src/engine/adapters/wwebjs-chats.ts+++ b/src/engine/adapters/wwebjs-chats.ts@@ -5,7 +5,7 @@ import { ChatSummary, ChatState } from '../interfaces/whatsapp-engine.interface'import { EngineTransportError } from '../../common/errors/engine-transport.error';import { chatKind, isChannelJid } from '../identity/wa-id';import { WwebjsMessaging } from './wwebjs-messaging';-import { type WwebjsEngineHost } from './wwebjs-host';+import { type WwebjsEngineHost, rethrowIfNavigation } from './wwebjs-host';import { isProtocolTimeout } from './wwebjs-lifecycle';import { mapWwebjsMessageType } from './message-mapper';@@ -58,6 +58,7 @@ function rethrowTransportFailure(activity: string,timedOutMessage = `WhatsApp Web did not answer in time while ${activity}`,): void {+ rethrowIfNavigation(host, error);if (host.isPageTransportError(error)) {host.reportIfPageTransportError(error, context);throw new EngineTransportError(`Transport died while ${activity}`);@@ -253,6 +254,7 @@ export class WwebjsChats {try {return await op();} catch (error) {+ rethrowIfNavigation(this.host, error);if (this.host.isPageTransportError(error)) {this.host.reportIfPageTransportError(error, context);throw new EngineTransportError(`Transport died during ${context}`);diff --git a/src/engine/adapters/wwebjs-contacts.ts b/src/engine/adapters/wwebjs-contacts.tsindex 8fa3523bf..430a63b09 100644--- a/src/engine/adapters/wwebjs-contacts.ts+++ b/src/engine/adapters/wwebjs-contacts.ts@@ -5,7 +5,7 @@ import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error'import { EngineTransportError } from '../../common/errors/engine-transport.error';import { parseWaId, userPart } from '../identity/wa-id';import { readWid, type SerializedWid } from '../types/whatsapp-web-js.types';-import { type WwebjsEngineHost, withPage } from './wwebjs-host';+import { type WwebjsEngineHost, rethrowIfNavigation, withPage } from './wwebjs-host';import { isProtocolTimeout } from './wwebjs-lifecycle';/** The raw whatsapp-web.js contact element type, kept local so the wwebjs `Contact` type never leaks. */@@ -181,6 +181,7 @@ export class WwebjsContacts {unreadable = read?.failed ?? 0;firstError = read?.firstError;} catch (error) {+ rethrowIfNavigation(this.host, error);// A dead page surfaces here as a raw Puppeteer error; convert it to the documented transport// failure the way wwebjs-chats.ts does, so a transport death answers 503 instead of a bare 500.if (this.host.isPageTransportError(error)) {@@ -237,6 +238,7 @@ export class WwebjsContacts {const contact = await this.client().getContactById(contactId);return this.toContact(contact);} catch (error) {+ rethrowIfNavigation(this.host, error);// Unlike the avatar lookup, a throw here can legitimately mean the contact is absent:// `window.WWebJS.getContact` has no try/catch and reads `contact.isBusiness` straight off// `Contact.find`, so an unknown id throws a TypeError on null. Null (→ 404) stays the answer@@ -370,6 +372,7 @@ export class WwebjsContacts {try {url = await this.client().getProfilePicUrl(contactId);} catch (error) {+ rethrowIfNavigation(this.host, error);const pageDown = this.host.isPageTransportError(error) || isProtocolTimeout(error);const viaLid = byLid && !pageDown ? await this.profilePictureByLid(contactId) : undefined;if (viaLid) return viaLid;diff --git a/src/engine/adapters/wwebjs-groups.ts b/src/engine/adapters/wwebjs-groups.tsindex 857cf0dab..c2b82792b 100644--- a/src/engine/adapters/wwebjs-groups.ts+++ b/src/engine/adapters/wwebjs-groups.ts@@ -19,8 +19,8 @@ import { EngineNotSupportedError } from '../../common/errors/engine-not-supporteimport { GroupNotFoundError } from '../../common/errors/group-not-found.error';import { InvalidInviteCodeError } from '../../common/errors/invalid-invite-code.error';import { toMessageMedia } from './wwebjs-messaging';-import { type WwebjsEngineHost, withPage, reportPageDeath } from './wwebjs-host';-import { isProtocolTimeout } from './wwebjs-lifecycle';+import { type WwebjsEngineHost, rethrowIfNavigation, withPage, reportPageDeath } from './wwebjs-host';+import { isNavigationError, isProtocolTimeout } from './wwebjs-lifecycle';import { listChats } from './wwebjs-chats';/**@@ -188,6 +188,7 @@ export class WwebjsGroups {// A dead page and a genuinely-missing group both land in this catch; only the second may// become null (→ service 404). A transport death surfaced as "group not found" sends// operators debugging the wrong layer — report it and answer 503 instead.+ rethrowIfNavigation(this.host, error);if (this.host.isPageTransportError(error)) {this.host.reportIfPageTransportError(error, 'getGroupInfo');throw new EngineTransportError(`Transport died while reading group ${groupId}`);@@ -434,6 +435,7 @@ export class WwebjsGroups {} catch (error) {// A dead page and a refused invite both land here; only the second is a 404. Folding a// transport death into "no such invite" sends operators debugging the wrong layer.+ rethrowIfNavigation(this.host, error);if (this.host.isPageTransportError(error)) {this.host.reportIfPageTransportError(error, 'getGroupJoinInfo');throw new EngineTransportError(`Transport died while previewing invite ${inviteCode}`);@@ -490,6 +492,10 @@ export class WwebjsGroups {if (isProtocolTimeout(error)) {throw new EngineTransportError('WhatsApp Web did not answer the group invite acceptance in time');}+ // A reload cut the call: the same unknown outcome, and not a refused invite either.+ if (isNavigationError(error)) {+ throw new EngineTransportError('WhatsApp Web reloaded its page during the group invite acceptance');+ }this.host.logger.warn(`Failed to accept group invite: ${String(error)}`);groupId = undefined;}diff --git a/src/engine/adapters/wwebjs-host.ts b/src/engine/adapters/wwebjs-host.tsindex 73a460816..d96cea7a1 100644--- a/src/engine/adapters/wwebjs-host.ts+++ b/src/engine/adapters/wwebjs-host.ts@@ -8,7 +8,7 @@ import { type createLogger } from '../../common/services/logger.service';import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';import { EngineTransportError } from '../../common/errors/engine-transport.error';import { type WhatsAppWebJsConfig } from './whatsapp-web-js.adapter';-import { toCapturedPageError } from './wwebjs-lifecycle';+import { PAGE_RELOADING_MESSAGE, isNavigationError, toCapturedPageError } from './wwebjs-lifecycle';/*** Shared host surface for the delegates extracted from WhatsAppWebJsAdapter (./wwebjs-groups,@@ -54,10 +54,24 @@ export function requireClient(host: WwebjsEngineHost): Client {return client;}+/**+ * Answer the retryable 409 the adapter gives inside the navigation window when the error says the page+ * navigated under the call, and return for any other error. A call already in flight when WhatsApp Web+ * reloads dies with Puppeteer's navigation error before the window is stamped, so it would otherwise be a+ * bare 500, or, where a catch folds a failed lookup into "not found", a 404 for a group, contact or label+ * that exists. A navigation is not a death: nothing is reported.+ */+export function rethrowIfNavigation(host: WwebjsEngineHost, error: unknown): void {+ // A page the host already reads as dead is reported as dead, whatever the message says.+ if (isNavigationError(error) && !host.isPageTransportError(error))+ throw new EngineNotReadyError(PAGE_RELOADING_MESSAGE);+}+/*** Run a client operation, classifying a dead page/transport as the documented 503 plus an early* death signal instead of an opaque 500 under a status that still says READY - the split every- * chats read already makes (#1081). Other errors propagate unchanged.+ * chats read already makes (#1081), and a page that navigated under the call as the 409 of+ * {@link rethrowIfNavigation}. Other errors propagate unchanged.** Lives here rather than per delegate: ./wwebjs-channels, ./wwebjs-profile and ./wwebjs-status each* held a byte-identical private copy, and ./wwebjs-contacts needed a fourth.@@ -66,6 +80,7 @@ export async function withPage<T>(host: WwebjsEngineHost, context: string, op: (try {return await op();} catch (error) {+ rethrowIfNavigation(host, error);if (host.isPageTransportError(error)) {host.reportIfPageTransportError(error, context);throw new EngineTransportError(`Transport died during ${context}`);diff --git a/src/engine/adapters/wwebjs-labels.ts b/src/engine/adapters/wwebjs-labels.tsindex 9d5ef69b2..28e9e83d9 100644--- a/src/engine/adapters/wwebjs-labels.ts+++ b/src/engine/adapters/wwebjs-labels.ts@@ -7,7 +7,7 @@ import { isChannelJid, chatKind } from '../identity/wa-id';import { ChatLabelsUnsupportedError } from '../../common/errors/chat-labels-unsupported.error';import { LabelNotFoundError } from '../../common/errors/label-not-found.error';import { EngineTransportError } from '../../common/errors/engine-transport.error';-import { type WwebjsEngineHost, withPage } from './wwebjs-host';+import { type WwebjsEngineHost, rethrowIfNavigation, withPage } from './wwebjs-host';import { isProtocolTimeout } from './wwebjs-lifecycle';/**@@ -58,6 +58,7 @@ export class WwebjsLabels {chats = await (this.client() as unknown as BusinessClient).getChatsByLabelId(labelId);} catch (error) {// Same split the group read makes: a dead page is a 503, not "no such label".+ rethrowIfNavigation(this.host, error);if (this.host.isPageTransportError(error)) {this.host.reportIfPageTransportError(error, 'getChatsByLabel');throw new EngineTransportError(`Transport died while listing chats for label ${labelId}`);diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.tsindex 3c64dc991..6813a4048 100644--- a/src/engine/adapters/wwebjs-lifecycle.ts+++ b/src/engine/adapters/wwebjs-lifecycle.ts@@ -69,6 +69,26 @@ export function isProtocolTimeout(error: unknown): boolean {return PROTOCOL_TIMEOUT_PATTERN.test(error instanceof Error ? error.message : String(error));}+/** What a request answers 409 while WhatsApp Web reloads its page, whichever side of the window stamp it lands. */+export const PAGE_RELOADING_MESSAGE =+ 'WhatsApp Web is reloading its page and the session is re-injecting. Retry in a few seconds.';++/**+ * Whether a page call was cut short by the page navigating away under it (WhatsApp Web reloading). Puppeteer+ * rewrites its three CDP shapes of this into 'Execution context was destroyed, most likely because of a+ * navigation.', and a call that lands on the new document before WhatsApp Web has booted dies on the missing+ * `window.require`. The page is alive and re-injecting, so unlike a death this is not reported, and a retry+ * a few seconds later succeeds. Not an HttpException, and not a failure captured inside the page, whose text+ * quotes WhatsApp Web and says nothing about our page.+ */+export function isNavigationError(error: unknown): boolean {+ if (error instanceof HttpException) {+ return false;+ }+ const message = error instanceof Error ? error.message : String(error);+ return !message.startsWith(CAPTURED_PAGE_ERROR_PREFIX) && isNavigationShapedInitRejection(message);+}+/*** The start of a send failure that scripts/patch-wwebjs-send-error.js captured inside the page, where* it summarises a thrown value puppeteer would otherwise hand over as `t: t`. The patcher builds thediff --git a/src/engine/adapters/wwebjs-navigation-error.spec.ts b/src/engine/adapters/wwebjs-navigation-error.spec.tsnew file mode 100644index 000000000..4e0e78323--- /dev/null+++ b/src/engine/adapters/wwebjs-navigation-error.spec.ts@@ -0,0 +1,186 @@+import { NotFoundException } from '@nestjs/common';+import type { Client } from 'whatsapp-web.js';+import { WwebjsChats } from './wwebjs-chats';+import { WwebjsContacts } from './wwebjs-contacts';+import { WwebjsGroups } from './wwebjs-groups';+import { WwebjsLabels } from './wwebjs-labels';+import { type WwebjsEngineHost, withPage } from './wwebjs-host';+import { type WwebjsMessaging } from './wwebjs-messaging';+import {+ CAPTURED_PAGE_ERROR_PREFIX,+ PAGE_RELOADING_MESSAGE,+ WwebjsLifecycle,+ isNavigationError,+} from './wwebjs-lifecycle';+import { createLogger } from '../../common/services/logger.service';+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';+import { EngineTransportError } from '../../common/errors/engine-transport.error';++/**+ * A call already in flight when WhatsApp Web reloads its page dies with Puppeteer's navigation error before+ * the re-inject window is stamped, so it was a bare 500, and where a catch folds a failed lookup into "not+ * found" it was a 404 or null for a group, contact or label that exists. The page is alive: nothing is+ * reported, and the answer is the retryable 409 the adapter already gives inside the window.+ */+const logger = createLogger('wwebjs-navigation-error.spec');++const NAVIGATION = 'Execution context was destroyed, most likely because of a navigation.';++describe('isNavigationError', () => {+ it.each([+ NAVIGATION,+ 'Evaluation failed: TypeError: window.require is not a function',+ 'execution context was destroyed',+ ])('reads %p as a navigation', message => {+ expect(isNavigationError(new Error(message))).toBe(true);+ });++ it('is not a dead page, so the death path never sees it', () => {+ const pattern = (WwebjsLifecycle as unknown as { PAGE_TRANSPORT_ERROR_PATTERN: RegExp })+ .PAGE_TRANSPORT_ERROR_PATTERN;+ expect(pattern.test(NAVIGATION)).toBe(false);+ });++ it.each([+ 'Protocol error (Runtime.callFunctionOn): Target closed',+ "Runtime.callFunctionOn timed out. Increase the 'protocolTimeout' setting in launch/connect calls",+ 'Evaluation failed: TypeError: Cannot read properties of null',+ '',+ ])('does not read %p as a navigation', message => {+ expect(isNavigationError(new Error(message))).toBe(false);+ });++ it('does not take the words from an error this application built', () => {+ // MessageNotFoundError and its siblings carry the caller's own text, so a request could name its way in.+ expect(isNavigationError(new NotFoundException(`Message ${NAVIGATION} not found in chat [email protected]`))).toBe(false);+ });++ it('does not take the words from a failure captured inside the page', () => {+ expect(isNavigationError(new Error(`${CAPTURED_PAGE_ERROR_PREFIX}{"message":"${NAVIGATION}"}`))).toBe(false);+ });+});++describe('a call the page navigation cut short', () => {+ const navigation = new Error(NAVIGATION);+ const ordinary = new Error('Evaluation failed: something else');++ function makeHost(client: unknown): { host: WwebjsEngineHost; reportIfPageTransportError: jest.Mock } {+ const reportIfPageTransportError = jest.fn();+ const host = {+ ensureReady: jest.fn(),+ getClient: () => client as Client,+ isPageTransportError: () => false,+ reportIfPageTransportError,+ logger,+ config: {},+ } as unknown as WwebjsEngineHost;+ return { host, reportIfPageTransportError };+ }++ const reload = (): unknown => expect.objectContaining({ message: PAGE_RELOADING_MESSAGE });++ it('withPage answers the 409 and reports nothing', async () => {+ const { host, reportIfPageTransportError } = makeHost({});++ const result = withPage(host, 'getNumberId', () => Promise.reject(navigation));++ await expect(result).rejects.toBeInstanceOf(EngineNotReadyError);+ await expect(result).rejects.toEqual(reload());+ expect(reportIfPageTransportError).not.toHaveBeenCalled();+ });++ it('a page the host reads as dead stays a death, whatever the message says', async () => {+ const { host, reportIfPageTransportError } = makeHost({});+ (host as unknown as { isPageTransportError: () => boolean }).isPageTransportError = () => true;++ await expect(withPage(host, 'getNumberId', () => Promise.reject(navigation))).rejects.toBeInstanceOf(+ EngineTransportError,+ );+ expect(reportIfPageTransportError).toHaveBeenCalledWith(navigation, 'getNumberId');+ });++ it('withPage still propagates an ordinary failure unchanged', async () => {+ const { host } = makeHost({});++ await expect(withPage(host, 'getNumberId', () => Promise.reject(ordinary))).rejects.toBe(ordinary);+ });++ it('the chat and group lists answer the 409', async () => {+ const client = { info: {}, pupPage: { evaluate: jest.fn().mockRejectedValue(navigation) } };+ const { host, reportIfPageTransportError } = makeHost(client);++ await expect(new WwebjsChats(host, {} as unknown as WwebjsMessaging).getChats()).rejects.toBeInstanceOf(+ EngineNotReadyError,+ );+ await expect(new WwebjsGroups(host).getGroups()).rejects.toBeInstanceOf(EngineNotReadyError);+ expect(reportIfPageTransportError).not.toHaveBeenCalled();+ });++ it('a group read is not "group not found"', async () => {+ const getChatById = jest.fn().mockRejectedValue(navigation);+ const { host } = makeHost({ info: {}, getChatById });++ await expect(new WwebjsGroups(host).getGroupInfo('[email protected]')).rejects.toBeInstanceOf(EngineNotReadyError);++ getChatById.mockRejectedValue(ordinary);+ await expect(new WwebjsGroups(host).getGroupInfo('[email protected]')).resolves.toBeNull();+ });++ it('an invite preview is not "no such invite"', async () => {+ const getInviteInfo = jest.fn().mockRejectedValue(navigation);+ const { host } = makeHost({ getInviteInfo });++ await expect(new WwebjsGroups(host).getGroupJoinInfo('code')).rejects.toBeInstanceOf(EngineNotReadyError);+ });++ it('an invite acceptance answers the unknown-outcome 503, not an invalid invite', async () => {+ const acceptInvite = jest.fn().mockRejectedValue(navigation);+ const { host } = makeHost({ acceptInvite });++ await expect(new WwebjsGroups(host).joinGroupViaInviteCode('code')).rejects.toBeInstanceOf(EngineTransportError);+ });++ it('a contact read is not "no such contact"', async () => {+ const getContactById = jest.fn().mockRejectedValue(navigation);+ const { host } = makeHost({ getContactById });++ await expect(new WwebjsContacts(host).getContactById('[email protected]')).rejects.toBeInstanceOf(EngineNotReadyError);++ getContactById.mockRejectedValue(ordinary);+ await expect(new WwebjsContacts(host).getContactById('[email protected]')).resolves.toBeNull();+ });++ it('the contact list, the avatar and the number lookup answer the 409', async () => {+ const getProfilePicUrl = jest.fn().mockRejectedValue(navigation);+ const getNumberId = jest.fn().mockRejectedValue(navigation);+ const client = {+ info: {},+ pupPage: { evaluate: jest.fn().mockRejectedValue(navigation) },+ getProfilePicUrl,+ getNumberId,+ };+ const { host, reportIfPageTransportError } = makeHost(client);+ const contacts = new WwebjsContacts(host);++ await expect(contacts.getContacts()).rejects.toBeInstanceOf(EngineNotReadyError);+ await expect(contacts.getProfilePicture('[email protected]')).rejects.toBeInstanceOf(EngineNotReadyError);+ await expect(contacts.getNumberId('628123')).rejects.toBeInstanceOf(EngineNotReadyError);+ expect(reportIfPageTransportError).not.toHaveBeenCalled();+ });++ it('a chat write answers the 409', async () => {+ const getChatById = jest.fn().mockRejectedValue(navigation);+ const { host } = makeHost({ getChatById });++ await expect(+ new WwebjsChats(host, {} as unknown as WwebjsMessaging).muteChat('[email protected]', null),+ ).rejects.toBeInstanceOf(EngineNotReadyError);+ });++ it('a label read is not "no such label"', async () => {+ const getChatsByLabelId = jest.fn().mockRejectedValue(navigation);+ const { host } = makeHost({ getChatsByLabelId });++ await expect(new WwebjsLabels(host).getChatsByLabel('7')).rejects.toBeInstanceOf(EngineNotReadyError);+ });+});