Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(engine): answer 409 for wwebjs calls racing a teardown
Yudhi Armyndharisd0cdad533c2e
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.ts b/src/engine/adapters/whatsapp-web-js.adapter.tsindex 423d2045c..3d7f9eaca 100644--- a/src/engine/adapters/whatsapp-web-js.adapter.ts+++ b/src/engine/adapters/whatsapp-web-js.adapter.ts@@ -172,7 +172,14 @@ export class WhatsAppWebJsAdapter implements IWhatsAppEngine {// initializer: `config` is a parameter property, which field initializers read before assignment.this.host = {ensureReady: () => this.ensureReady(),- getClient: () => this.client!,+ // A delegate reads the client after ensureReady() and often after awaits of its own (a recipient+ // lookup, a media fetch, a chat lookup). A teardown in that gap leaves the client set but closing,+ // or nulls it, so readiness is checked again here: the retryable 409 instead of a closed-target or+ // TypeError 500 that a send also counts toward the send breaker.+ getClient: () => {+ this.ensureReady();+ return this.client!;+ },logger: this.logger,isPageTransportError: error => this.isPageTransportError(error),reportIfPageTransportError: (error, context) => this.reportIfPageTransportError(error, context),diff --git a/src/engine/adapters/wwebjs-client-teardown.spec.ts b/src/engine/adapters/wwebjs-client-teardown.spec.tsnew file mode 100644index 000000000..c554b1b15--- /dev/null+++ b/src/engine/adapters/wwebjs-client-teardown.spec.ts@@ -0,0 +1,200 @@+import { WhatsAppWebJsAdapter } from './whatsapp-web-js.adapter';+import { EngineStatus } from '../interfaces/whatsapp-engine.interface';+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';+import { countsTowardSendBreaker, sentNothing } from '../../modules/message/send-pacing.service';+import * as loadRemoteMediaModule from '../../common/media/load-remote-media';++/**+ * A teardown (stop, logout, a browser crash) lands while an operation is parked on an await of its own: a+ * recipient lookup, a media fetch, the lookup of a chat. The adapter is in one of two states by then. While+ * client.destroy() runs it still holds the client but already reports DISCONNECTED; once destroy() settles+ * the client is null. In both the operation must answer the retryable not-ready 409 without touching the+ * page: left alone, a closing page fails a send with a plain 500 that the send breaker counts, and a null+ * client fails every other operation with a TypeError 500.+ */++const CHAT = '[email protected]';+const MEDIA_URL = 'https://files.example.com/a.png';++interface Gate {+ /** Settled by `open`. */+ wait: Promise<void>;+ open: () => void;+ /** How many calls are parked on `wait`, so a test knows the operation is where it was meant to be. */+ parkedCalls: number;+ park: () => Promise<void>;+}++function gate(): Gate {+ let open!: () => void;+ const wait = new Promise<void>(resolve => {+ open = resolve;+ });+ const parked: Gate = {+ wait,+ open,+ parkedCalls: 0,+ park: () => {+ parked.parkedCalls += 1;+ return wait;+ },+ };+ return parked;+}++const PHASES = ['while destroy() runs', 'after destroy() settled'] as const;+type Phase = (typeof PHASES)[number];++/** A READY adapter around `client`, and a way to begin its teardown in either phase. */+function readyAdapter(client: Record<string, unknown>) {+ const destroyed = gate();+ const adapter = new WhatsAppWebJsAdapter({ sessionId: 's', sessionDataPath: './data/sessions', puppeteer: {} });+ (adapter as unknown as { status: EngineStatus }).status = EngineStatus.READY;+ (adapter as unknown as { client: unknown }).client = { ...client, destroy: jest.fn(() => destroyed.wait) };+ let teardown: Promise<void> | undefined;+ return {+ adapter,+ tearDown: async (phase: Phase): Promise<void> => {+ teardown = adapter.disconnect();+ if (phase === 'after destroy() settled') {+ destroyed.open();+ await teardown;+ }+ },+ finish: async (): Promise<void> => {+ destroyed.open();+ await teardown;+ },+ };+}++/** Let every pending microtask and the macrotasks queued before this call run. */+const settle = (): Promise<void> => new Promise(resolve => setImmediate(resolve));++type Outcome = { value: unknown } | { error: unknown };++/** How an operation ended, kept apart so a resolved value cannot be mistaken for a rejection. */+const outcomeOf = (operation: Promise<unknown>): Promise<Outcome> =>+ operation.then(+ value => ({ value }),+ (error: unknown) => ({ error }),+ );++const found = (wid: string): { _serialized: string } => ({ _serialized: wid });++interface Case {+ name: string;+ /** The client the operation runs against, with its first await parked on `parked`; `unreached` must stay uncalled. */+ build: (parked: Gate) => { client: Record<string, unknown>; unreached?: jest.Mock };+ run: (adapter: WhatsAppWebJsAdapter) => Promise<unknown>;+}++const mediaFetchParked = (parked: Gate): void => {+ jest+ .spyOn(loadRemoteMediaModule, 'loadRemoteMediaBuffer')+ .mockImplementation(() => parked.park().then(() => ({ data: Buffer.from([1]), mimetype: 'image/png' })));+};++const CASES: Case[] = [+ {+ name: 'a text send',+ build: parked => {+ const sendMessage = jest.fn();+ return {+ client: { getNumberId: () => parked.park().then(() => found(CHAT)), sendMessage },+ unreached: sendMessage,+ };+ },+ run: adapter => adapter.sendTextMessage(CHAT, 'hi'),+ },+ {+ name: 'an image status post',+ build: parked => {+ mediaFetchParked(parked);+ const sendMessage = jest.fn();+ return { client: { sendMessage }, unreached: sendMessage };+ },+ run: adapter => adapter.postImageStatus({ mimetype: 'image/png', data: MEDIA_URL }, {}),+ },+ {+ name: 'a profile picture upload',+ build: parked => {+ mediaFetchParked(parked);+ const setProfilePicture = jest.fn();+ return { client: { setProfilePicture }, unreached: setProfilePicture };+ },+ run: adapter => adapter.setProfilePicture({ mimetype: 'image/png', data: MEDIA_URL }),+ },+ {+ name: 'a group invite revoke',+ build: parked => {+ const evaluate = jest.fn();+ return {+ client: { getChatById: () => parked.park().then(() => ({ isGroup: true })), pupPage: { evaluate } },+ unreached: evaluate,+ };+ },+ run: adapter => adapter.revokeGroupInviteCode('[email protected]'),+ },+ {+ name: 'a chat label change',+ build: parked => {+ const addOrRemoveLabels = jest.fn();+ const chat = { getLabels: () => Promise.resolve([]) };+ return {+ client: { getChatById: () => parked.park().then(() => chat), addOrRemoveLabels },+ unreached: addOrRemoveLabels,+ };+ },+ run: adapter => adapter.addLabelToChat(CHAT, '7'),+ },+ {+ name: 'a chat mute',+ build: parked => {+ const muteChat = jest.fn();+ return { client: { getChatById: () => parked.park().then(() => ({})), muteChat }, unreached: muteChat };+ },+ run: adapter => adapter.muteChat(CHAT, Date.now() + 60_000),+ },+ {+ // The client is read again after the lookup, inside a catch that answers a missing group with null.+ name: 'a group info read',+ build: parked => {+ const group = {+ isGroup: true,+ id: { _serialized: '[email protected]' },+ name: 'G',+ participants: [],+ groupMetadata: {},+ };+ return { client: { getChatById: () => parked.park().then(() => group), info: { wid: found(CHAT) } } };+ },+ run: adapter => adapter.getGroupInfo('[email protected]'),+ },+];++describe('whatsapp-web.js operations that race a session teardown', () => {+ afterEach(() => jest.restoreAllMocks());++ describe.each(PHASES)('%s', phase => {+ it.each(CASES)('answers the not-ready 409 for $name, before it reaches the page', async testCase => {+ const parked = gate();+ const { client, unreached } = testCase.build(parked);+ const { adapter, tearDown, finish } = readyAdapter(client);++ const outcome = outcomeOf(testCase.run(adapter));+ await settle();+ expect(parked.parkedCalls).toBe(1);+ await tearDown(phase);+ parked.open();+ const result = await outcome;+ await finish();++ if (unreached) expect(unreached).not.toHaveBeenCalled();+ expect(result).toEqual({ error: expect.any(EngineNotReadyError) as unknown });+ const { error } = result as { error: unknown };+ expect(countsTowardSendBreaker(error)).toBe(false);+ expect(sentNothing(error)).toBe(true);+ });+ });+});diff --git a/src/engine/adapters/wwebjs-groups.ts b/src/engine/adapters/wwebjs-groups.tsindex 0255e03d7..843667957 100644--- a/src/engine/adapters/wwebjs-groups.ts+++ b/src/engine/adapters/wwebjs-groups.ts@@ -12,6 +12,7 @@ import {} from '../interfaces/whatsapp-engine.interface';import { GroupChat, GroupMetadataRaw, SerializedWid, readWid } from '../types/whatsapp-web-js.types';import { toParticipantWid } from '../identity/wa-id';+import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';import { EngineRefusedError } from '../../common/errors/engine-refused.error';import { EngineTransportError } from '../../common/errors/engine-transport.error';import { EngineNotSupportedError } from '../../common/errors/engine-not-supported.error';@@ -179,6 +180,11 @@ export class WwebjsGroups {linkedParentJID: extractLinkedParentJID(groupChat.groupMetadata),};} catch (error) {+ // A session that went away during the read (the client is read again after the lookup) is not a+ // missing group either: the retryable 409, not a 404.+ if (error instanceof EngineNotReadyError) {+ throw error;+ }// 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.diff --git a/src/engine/adapters/wwebjs-host.ts b/src/engine/adapters/wwebjs-host.tsindex 593b730ba..6d5a90d6a 100644--- a/src/engine/adapters/wwebjs-host.ts+++ b/src/engine/adapters/wwebjs-host.ts@@ -19,6 +19,7 @@ import { toCapturedPageError } from './wwebjs-lifecycle';*/export interface WwebjsEngineHost {ensureReady(): void;+ /** The live client; throws EngineNotReadyError when the session is no longer ready or the client is gone. */getClient(): Client;readonly logger: ReturnType<typeof createLogger>;isPageTransportError(error: unknown): boolean;@@ -36,10 +37,10 @@ export interface WwebjsEngineHost {}/**- * The client of a send path, read after ensureReady() and any awaits since (a recipient lookup, a media fetch).- * A teardown can null the adapter's client in that gap, and the host closure then hands back a null typed as a- * Client: the send would die as a TypeError 500 and count toward the send breaker. It answers the retryable 409- * a not-ready session gets instead.+ * The client of a send or status path, read after ensureReady() and any awaits since (a recipient lookup, a+ * media fetch). The adapter's getClient already refuses a session that is not ready; this keeps a host that+ * still has no client from handing the send a null typed as a Client, which would die as a TypeError 500 and+ * count toward the send breaker.*/export function requireClient(host: WwebjsEngineHost): Client {const client = host.getClient() as Client | null | undefined;