Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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;