Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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 Web
a plain `await` hangs the start forever. The engine's own `authTimeoutMs` poll does not cover that
case: 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/rejection
split 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 the
row 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 NOT
diff --git a/src/modules/session/session-engine-controls.ts b/src/modules/session/session-engine-controls.ts
index 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.ts
index 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 with
diff --git a/src/modules/session/session-lifecycle-fences.spec.ts b/src/modules/session/session-lifecycle-fences.spec.ts
index 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.ts
index 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.ts
index 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)', () => {