Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(session): evict engines by identity in every teardown helper
Yudhi Armyndharis5d830d62e31f
diff --git a/docs/31-session-lifecycle-design.md b/docs/31-session-lifecycle-design.mdindex 5c12dfac2..7c7d3da1b 100644--- a/docs/31-session-lifecycle-design.md+++ b/docs/31-session-lifecycle-design.md@@ -58,8 +58,11 @@ rejects, and neither does a navigation that never completes because WhatsApp Weba plain `await` hangs the start forever. The engine's own `authTimeoutMs` poll does not cover thatcase: whatsapp-web.js only starts it in `inject()`, after the page has loaded.**Defense:** `Promise.race` deadline in `initializeEngine`; on timeout the engine is evicted +-force-destroyed + status DISCONNECTED + 504 to the caller. A REAL rejection is NOT treated as a-timeout: it propagates so `start()` records FAILED with the reason.+force-destroyed + status DISCONNECTED + 504 to the caller. The eviction, the recorded error and the+DISCONNECTED write apply only while that engine is still the live one: a stale deadline (a stop ++start replaced it mid-init) force-destroys its own engine and 504s, and leaves the replacement alone.+A REAL rejection is NOT treated as a timeout: it propagates so `start()` records FAILED with the+reason.**Pinned by:** `session.service.spec.ts` (start failure-path cases; the timeout/rejectionsplit lives in `session.service.spec.ts`'s init-timeout describes).**Do not "simplify" the two paths into one** — the distinction is why a bad proxy config returns@@ -162,7 +165,11 @@ Collected here so they survive refactors of the code around them:- `session-engine-controls.ts` (start): `session.config` is clamped to trusted keys because therow is client-writable; an unclamped spread would let a caller smuggle engine options.- `EngineRegistry`: identity-based `deleteIfLive` rather than `delete(id)` — see INV-3; every- site that bypassed this in review's history created the same phantom-callback bug.+ site that bypassed this in review's history created the same phantom-callback bug. The eviction+ helpers go through it too: `evictAndForceDestroy`, the init-timeout branch, and `start()`'s catch.+ `start()` identifies its own engine by capturing the registry entry right after calling+ `initializeEngine` (which registers it before its first await), not by a lookup in the catch: a+ mid-init disconnect can schedule a reconnect that registers a replacement first.## 31.4 What this document is NOTdiff --git a/src/modules/session/session-engine-controls.ts b/src/modules/session/session-engine-controls.tsindex 184e428ee..9a4c984d5 100644--- a/src/modules/session/session-engine-controls.ts+++ b/src/modules/session/session-engine-controls.ts@@ -222,13 +222,21 @@ export class SessionEngineControls {// Boot auto-start reaches here through this same method, so it re-arms too.this.stuckAuthRecoveryUsed.delete(id);+ // initializeEngine registers its engine synchronously, before its first await, so the entry+ // read right after the call is this start's own engine (undefined if creation threw first).+ // The catch must use this capture, not a later lookup: a disconnect of this engine mid-init can+ // schedule a reconnect that registers a replacement before initialize() rejects.+ const before = this.engines.get(id);+ const init = this.host.initializeEngine(id, session);+ const registered = this.engines.get(id);+ const mine = registered !== before ? registered : undefined;try {- await this.host.initializeEngine(id, session);+ await init;} catch (err) {- // engine.initialize() failed AFTER the engine was registered (initializeEngine sets it before- // initializing). Evict + tear it down so the session doesn't wedge at "already started" with a- // leaked Chromium/socket permanently holding a concurrency slot. initializingSessions serializes- // start(), so the engine in the map here is the one this start just created.+ // engine.initialize() failed AFTER the engine was registered. Evict + tear it down so the+ // session doesn't wedge at "already started" with a leaked Chromium/socket permanently holding+ // a concurrency slot. Identity-checked: a replacement registered by a reconnect is left alone,+ // and so is its status (whoever evicted this start's engine owns the teardown).//// Use forceDestroy(), not destroy(): initialize() failing usually means the underlying// browser/CDP connection is already broken (e.g. a "Target closed" crash mid-injection), so@@ -236,11 +244,9 @@ export class SessionEngineControls {// teardownEngineSafely's race, after which the orphaned Chromium process is never actually// killed. forceDestroy() SIGKILLs the OS process directly, the same recovery force-kill uses// for a wedged engine, which is exactly the state this catch block is handling.- const orphan = this.engines.get(id);- if (orphan) {- this.engines.delete(id);+ if (mine && this.engines.deleteIfLive(id, mine)) {this.sessionErrors.set(id, err instanceof Error ? err.message : String(err));- await this.fences.teardownEngineSafely(id, orphan, e => e.forceDestroy(), 'force-destroy');+ await this.fences.teardownEngineSafely(id, mine, e => e.forceDestroy(), 'force-destroy');// Fenced on ownership like the engine callbacks: initializeEngine can await a slow// Chromium launch for minutes, and this node's lease can lapse and be taken over inside// that window. FAILED is excluded from the boot reset AND from the takeover sweep, so@@ -249,10 +255,13 @@ export class SessionEngineControls {await this.host.updateStatus(id, SessionStatus.FAILED).catch(() => undefined);}}- // Drop the reconnect state this start() armed up front: no engine was registered, so- // nothing will ever fire it, and leaving it behind is dead state a later liveness check- // would have to reason about. A retry builds its own.- this.host.cancelReconnect(id);+ // Drop the reconnect state this start() armed up front when no engine is registered: nothing+ // will ever fire it, and leaving it behind is dead state a later liveness check would have to+ // reason about. A retry builds its own. A reconnect that already registered a replacement+ // keeps its state.+ if (!this.engines.has(id)) {+ this.host.cancelReconnect(id);+ }throw err;}diff --git a/src/modules/session/session-engine-lifecycle.service.ts b/src/modules/session/session-engine-lifecycle.service.tsindex 846a4c69c..03fc11785 100644--- a/src/modules/session/session-engine-lifecycle.service.ts+++ b/src/modules/session/session-engine-lifecycle.service.ts@@ -691,23 +691,26 @@ export class SessionEngineLifecycle {sessionId: id,action: 'engine_init_timeout',});- this.sessionErrors.set(id, err.message);// Evict from the map BEFORE tearing down. forceDestroy() → beginClientTeardown → setStatus// fires onStateChanged SYNCHRONOUSLY while the engine is still live, so isLiveEngine would// pass and the callback would run a redundant DISCONNECTED write against this path; removing// the engine first makes isLiveEngine return false. Unlike delete()/stop()/forceKill(), this- // path has no stoppingSessions + cancelReconnect wrap to fall back on. Matches the canonical- // delete-before-teardown at evictAndForceDestroy() and start()'s catch.+ // path has no stoppingSessions + cancelReconnect wrap to fall back on. Like+ // evictAndForceDestroy() and start()'s catch, the eviction is identity-checked (deleteIfLive):+ // a stop() + start() during a hung reconnect init may already have registered a new engine,+ // and this stale deadline must neither evict it nor overwrite its error and status. The+ // stale engine is force-destroyed either way, and the caller still gets the 504.//// Do NOT port this reorder to delete()/stop()/forceKill(): there, engines.has(id) staying// TRUE for the duration of the teardown await is the sole deterministic block on a concurrent// start() (start() clears stoppingSessions rather than rejecting on it), so delete-first would// open a start()-during-teardown orphan-engine window. Verified in the teardown-ordering audit.- this.engines.delete(id);+ const wasLive = this.engines.deleteIfLive(id, engine);+ if (wasLive) this.sessionErrors.set(id, err.message);// Force-kill whatever got launched so a retry doesn't collide with an orphaned browser.// teardownEngineSafely is itself time-bound, so this can't wedge a second time.await this.teardownEngineSafely(id, engine, e => e.forceDestroy(), 'force-destroy');- await this.updateStatus(id, SessionStatus.DISCONNECTED);+ if (wasLive) await this.updateStatus(id, SessionStatus.DISCONNECTED);// Map to a diagnostic 504 like the auth-timeout branch below, so a wedged init doesn't escape as a// bare 500 (#733 follow-up). This deadline covers EVERY cause and cannot tell them apart: the// auth-timeout below only fires once the page has LOADED (whatsapp-web.js navigates withdiff --git a/src/modules/session/session-lifecycle-fences.spec.ts b/src/modules/session/session-lifecycle-fences.spec.tsindex 872f10ceb..02eb5f39f 100644--- a/src/modules/session/session-lifecycle-fences.spec.ts+++ b/src/modules/session/session-lifecycle-fences.spec.ts@@ -170,5 +170,22 @@ describe('SessionLifecycleFences', () => {expect(forceDestroy).toHaveBeenCalledTimes(1);expect(destroy).not.toHaveBeenCalled();});++ it('leaves a replacement engine registered and still force-destroys the stale one', async () => {+ const { fences, engines } = makeFences();+ const staleKill = jest.fn().mockResolvedValue(undefined);+ const liveKill = jest.fn().mockResolvedValue(undefined);+ const stale = engine({ forceDestroy: staleKill });+ const live = engine({ forceDestroy: liveKill });+ engines.set('s1', live);++ fences.evictAndForceDestroy('s1', stale);++ expect(engines.get('s1')).toBe(live);+ await Promise.resolve();+ await Promise.resolve();+ expect(staleKill).toHaveBeenCalledTimes(1);+ expect(liveKill).not.toHaveBeenCalled();+ });});});diff --git a/src/modules/session/session-lifecycle-fences.ts b/src/modules/session/session-lifecycle-fences.tsindex 24494fd21..e06f4f4f7 100644--- a/src/modules/session/session-lifecycle-fences.ts+++ b/src/modules/session/session-lifecycle-fences.ts@@ -192,9 +192,12 @@ export class SessionLifecycleFences {* concurrency slot and makes a later start() see the session as "already started"; forceDestroy()* (not the graceful destroy()) is used because such an engine's browser/CDP connection is typically* already broken, so a graceful close would only time out before the process is reaped.+ *+ * The eviction is identity-checked (deleteIfLive): if a replacement engine is already registered+ * for `id`, it stays. The passed engine is force-destroyed either way, since it is dead or abandoned.*/evictAndForceDestroy(id: string, engine: IWhatsAppEngine): void {- this.engines.delete(id);+ this.engines.deleteIfLive(id, engine);void this.teardownEngineSafely(id, engine, e => e.forceDestroy(), 'force-destroy');}}diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.tsindex 44b6376d2..12831bee4 100644--- a/src/modules/session/session.service.spec.ts+++ b/src/modules/session/session.service.spec.ts@@ -1999,6 +1999,70 @@ describe('SessionService', () => {delete process.env.WWEBJS_AUTH_TIMEOUT_MS;}});++ it('registers the engine synchronously, before initializeEngine first awaits (start() captures it there)', () => {+ (repository.update as jest.Mock).mockReturnValue(new Promise(() => undefined));+ const init = (+ lifecycle as unknown as { initializeEngine: (id: string, s: Session) => Promise<void> }+ ).initializeEngine('sess-uuid-1', createMockSession());+ init.catch(() => undefined);+ expect(registry.get('sess-uuid-1')).toBe(mockEngine);+ });++ it('a stale init deadline leaves a replacement engine registered, alive, and its status and error untouched', async () => {+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession());+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });+ mockEngine.initialize.mockReturnValue(new Promise<void>(() => undefined));+ const replacement = { forceDestroy: jest.fn().mockResolvedValue(undefined) };+ const reconnectStates = (lifecycle as unknown as { reconnectStates: Map<string, unknown> }).reconnectStates;++ jest.useFakeTimers();+ try {+ let caught: unknown;+ const settled = service.start('sess-uuid-1').catch((e: unknown) => {+ caught = e;+ });+ await jest.advanceTimersByTimeAsync(1_000);+ // A stop() + start() (or a reconnect) registered a new engine while this init hangs.+ registry.set('sess-uuid-1', replacement as never);+ (repository.update as jest.Mock).mockClear();++ await jest.advanceTimersByTimeAsync(60_000);+ await settled;++ expect((caught as HttpException).getStatus()).toBe(HttpStatus.GATEWAY_TIMEOUT);+ expect(registry.get('sess-uuid-1')).toBe(replacement);+ expect(replacement.forceDestroy).not.toHaveBeenCalled();+ expect(mockEngine.forceDestroy).toHaveBeenCalled(); // the stale engine is still reaped+ expect(repository.update).not.toHaveBeenCalled(); // no DISCONNECTED, no FAILED over the replacement+ expect(intern().sessionErrors.get('sess-uuid-1')).toBeUndefined();+ expect(reconnectStates.has('sess-uuid-1')).toBe(true); // the replacement keeps its reconnect state+ } finally {+ jest.useRealTimers();+ }+ });++ it("start()'s catch leaves a replacement engine alone when its own engine was superseded mid-init", async () => {+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession());+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });+ let reject!: (e: Error) => void;+ mockEngine.initialize.mockReturnValue(new Promise<void>((_, r) => (reject = r)));+ const replacement = { forceDestroy: jest.fn().mockResolvedValue(undefined) };+ const reconnectStates = (lifecycle as unknown as { reconnectStates: Map<string, unknown> }).reconnectStates;++ const pending = service.start('sess-uuid-1');+ await new Promise(resolve => setImmediate(resolve));+ expect(mockEngine.initialize).toHaveBeenCalled();+ // A mid-init disconnect scheduled a reconnect, which registered its own engine.+ registry.set('sess-uuid-1', replacement as never);+ reject(new Error('Target closed'));+ await expect(pending).rejects.toThrow('Target closed');++ expect(registry.get('sess-uuid-1')).toBe(replacement);+ expect(replacement.forceDestroy).not.toHaveBeenCalled();+ expect(repository.update).not.toHaveBeenCalledWith('sess-uuid-1', { status: SessionStatus.FAILED });+ expect(reconnectStates.has('sess-uuid-1')).toBe(true);+ });});describe('scheduleReconnect (max attempts)', () => {