Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(session): announce a stop after the engine is released
Yudhi Armyndharis9ba40b04f94d
diff --git a/src/modules/session/session-engine-controls.ts b/src/modules/session/session-engine-controls.tsindex 982d30389..3304e7557 100644--- a/src/modules/session/session-engine-controls.ts+++ b/src/modules/session/session-engine-controls.ts@@ -9,6 +9,7 @@ import { Template } from '../template/entities/template.entity';import { BaileysStoredMessage } from '../../engine';import { EngineFactory } from '../../engine/engine.factory';import { EngineRegistry } from '../../engine/engine-registry.service';+import { IWhatsAppEngine } from '../../engine/interfaces/whatsapp-engine.interface';import { SessionErrorStore } from './session-error-store.service';import { SessionRestrictionStore } from './session-restriction-store.service';import { PresenceStore } from './presence-store.service';@@ -62,6 +63,8 @@ export interface SessionEngineControlsHost {/** Ownership gate, same contract as SessionEngineWiringHost.ownsSession. */ownsSession(id: string): boolean;stoppingSessions: Set<string>;+ /** The engine each operator-initiated teardown is retiring; see the lifecycle field of the same name. */+ operatorTeardowns: Map<string, IWhatsAppEngine>;reconnectStates: Map<string, ReconnectState>;stuckAuthRecoveryUsed: Set<string>;initializingSessions: Set<string>;@@ -93,6 +96,7 @@ export class SessionEngineControls {private readonly fences: SessionLifecycleFences;private readonly broadcaster: SessionStatusBroadcaster;private readonly stoppingSessions: Set<string>;+ private readonly operatorTeardowns: Map<string, IWhatsAppEngine>;private readonly reconnectStates: Map<string, ReconnectState>;private readonly stuckAuthRecoveryUsed: Set<string>;private readonly initializingSessions: Set<string>;@@ -110,6 +114,7 @@ export class SessionEngineControls {this.fences = host.fences;this.broadcaster = host.broadcaster;this.stoppingSessions = host.stoppingSessions;+ this.operatorTeardowns = host.operatorTeardowns;this.reconnectStates = host.reconnectStates;this.stuckAuthRecoveryUsed = host.stuckAuthRecoveryUsed;this.initializingSessions = host.initializingSessions;@@ -283,38 +288,49 @@ export class SessionEngineControls {// behaviour: a later start() clears it; it guards against a late reconnect resurrecting the id.)const engine = this.engines.get(id);if (engine) {- // Await THIS engine's in-flight INITIALIZING write before teardown / the final DISCONNECTED- // write so a delayed pre-initialize status update can never settle after the retirement and- // become the last persisted status. Identity-checked: only the captured engine's promise.- await this.fences.awaitInitialStatus(id, engine);- let tornDown = await this.fences.teardownEngineSafely(id, engine, e => e.disconnect(), 'disconnect');- if (!tornDown) {- // The graceful disconnect threw or timed out, so the engine may be half-attached (a leaked- // Chromium process or a live socket). Escalate to the hard kill — the same forceDestroy()- // forceKill() uses for a wedged engine — before reporting the stop.- this.logger.warn(`Graceful disconnect failed for session ${session.name}; escalating to force-destroy`, {- sessionId: id,- action: 'stop_escalate_force_destroy',- });- tornDown = await this.fences.teardownEngineSafely(id, engine, e => e.forceDestroy(), 'force-destroy');- }- // Reconciled regardless of the outcome: a wedged engine must not keep holding a concurrency- // slot or read as "already started" to a later start().- this.engines.deleteIfLive(id, engine);- if (!tornDown) {- // The hard kill failed too, so the engine's process may still be alive. Local state is- // settled (Map reconciled, status DISCONNECTED — mirroring logout()'s incomplete path), but- // the stop is reported as incomplete instead of claimed clean: a retryable 502 with a stable- // code, and no success log (the controller audits SESSION_STOPPED only after this resolves).- await this.host.updateStatus(id, SessionStatus.DISCONNECTED);- throw new BadGatewayException({- statusCode: HttpStatus.BAD_GATEWAY,- message:- 'Session was stopped locally, but the engine teardown did not complete — the engine ' +- 'process may still be running. Retry the stop; restart the node to reap a leaked process.',- error: 'Bad Gateway',- code: 'SESSION_STOP_INCOMPLETE',- });+ // This teardown's own DISCONNECTED is not announced from the engine callback (see+ // operatorTeardowns): the adapter reports it before the eviction, so consumers would learn the+ // session is down while it still reads as engine-loaded. The write below announces it instead.+ this.operatorTeardowns.set(id, engine);+ try {+ // Await THIS engine's in-flight INITIALIZING write before teardown / the final DISCONNECTED+ // write so a delayed pre-initialize status update can never settle after the retirement and+ // become the last persisted status. Identity-checked: only the captured engine's promise.+ await this.fences.awaitInitialStatus(id, engine);+ let tornDown = await this.fences.teardownEngineSafely(id, engine, e => e.disconnect(), 'disconnect');+ if (!tornDown) {+ // The graceful disconnect threw or timed out, so the engine may be half-attached (a leaked+ // Chromium process or a live socket). Escalate to the hard kill — the same forceDestroy()+ // forceKill() uses for a wedged engine — before reporting the stop.+ this.logger.warn(`Graceful disconnect failed for session ${session.name}; escalating to force-destroy`, {+ sessionId: id,+ action: 'stop_escalate_force_destroy',+ });+ tornDown = await this.fences.teardownEngineSafely(id, engine, e => e.forceDestroy(), 'force-destroy');+ }+ // Reconciled regardless of the outcome: a wedged engine must not keep holding a concurrency+ // slot or read as "already started" to a later start().+ this.engines.deleteIfLive(id, engine);+ if (!tornDown) {+ // The hard kill failed too, so the engine's process may still be alive. Local state is+ // settled (Map reconciled, status DISCONNECTED — mirroring logout()'s incomplete path), but+ // the stop is reported as incomplete instead of claimed clean: a retryable 502 with a stable+ // code, and no success log (the controller audits SESSION_STOPPED only after this resolves).+ await this.host.updateStatus(id, SessionStatus.DISCONNECTED);+ throw new BadGatewayException({+ statusCode: HttpStatus.BAD_GATEWAY,+ message:+ 'Session was stopped locally, but the engine teardown did not complete — the engine ' ++ 'process may still be running. Retry the stop; restart the node to reap a leaked process.',+ error: 'Bad Gateway',+ code: 'SESSION_STOP_INCOMPLETE',+ });+ }+ } finally {+ // Identity-checked, so a verb that captured a different instance keeps its own mark.+ if (this.operatorTeardowns.get(id) === engine) {+ this.operatorTeardowns.delete(id);+ }}}@@ -372,15 +388,24 @@ export class SessionEngineControls {// Cancel any reconnection attemptsthis.host.cancelReconnect(id);- // Await THIS engine's in-flight INITIALIZING write before teardown / the final DISCONNECTED- // write so a delayed pre-initialize status update can never settle after the retirement.- await this.fences.awaitInitialStatus(id, engine);- // The credential fence is keyed by session NAME (see awaitPendingTeardown). Captured immutably- // here so a raw logout that outlives its deadline race is tracked under the right name even if- // the row is later deleted/recreated.- const unlinked = await this.fences.teardownEngineSafely(id, engine, e => e.logout(), 'logout', session.name);- this.engines.deleteIfLive(id, engine);- await this.host.updateStatus(id, SessionStatus.DISCONNECTED);+ // Announced by the write below rather than from the engine callback, as in stop().+ this.operatorTeardowns.set(id, engine);+ let unlinked: boolean;+ try {+ // Await THIS engine's in-flight INITIALIZING write before teardown / the final DISCONNECTED+ // write so a delayed pre-initialize status update can never settle after the retirement.+ await this.fences.awaitInitialStatus(id, engine);+ // The credential fence is keyed by session NAME (see awaitPendingTeardown). Captured immutably+ // here so a raw logout that outlives its deadline race is tracked under the right name even if+ // the row is later deleted/recreated.+ unlinked = await this.fences.teardownEngineSafely(id, engine, e => e.logout(), 'logout', session.name);+ this.engines.deleteIfLive(id, engine);+ await this.host.updateStatus(id, SessionStatus.DISCONNECTED);+ } finally {+ if (this.operatorTeardowns.get(id) === engine) {+ this.operatorTeardowns.delete(id);+ }+ }if (!unlinked) {this.logger.warn(`Session stopped locally but the logout operation did not complete: ${session.name}`, {@@ -439,17 +464,25 @@ export class SessionEngineControls {this.stoppingSessions.add(id);this.host.cancelReconnect(id);- // Await THIS engine's in-flight INITIALIZING write before teardown / the final DISCONNECTED- // write so a delayed pre-initialize status update can never settle after the retirement.- await this.fences.awaitInitialStatus(id, engine);- await this.fences.teardownEngineSafely(id, engine, e => e.forceDestroy(), 'force-destroy');- this.engines.deleteIfLive(id, engine);+ // Announced by the write below rather than from the engine callback, as in stop().+ this.operatorTeardowns.set(id, engine);+ try {+ // Await THIS engine's in-flight INITIALIZING write before teardown / the final DISCONNECTED+ // write so a delayed pre-initialize status update can never settle after the retirement.+ await this.fences.awaitInitialStatus(id, engine);+ await this.fences.teardownEngineSafely(id, engine, e => e.forceDestroy(), 'force-destroy');+ this.engines.deleteIfLive(id, engine);- this.logger.warn(`Session force-killed: ${session.name}`, {- sessionId: id,- action: 'force_kill',- });- await this.host.updateStatus(id, SessionStatus.DISCONNECTED);+ this.logger.warn(`Session force-killed: ${session.name}`, {+ sessionId: id,+ action: 'force_kill',+ });+ await this.host.updateStatus(id, SessionStatus.DISCONNECTED);+ } finally {+ if (this.operatorTeardowns.get(id) === engine) {+ this.operatorTeardowns.delete(id);+ }+ }return this.requireSession(id);}diff --git a/src/modules/session/session-engine-event-wiring.ts b/src/modules/session/session-engine-event-wiring.tsindex 0c2c37e8f..ed771c175 100644--- a/src/modules/session/session-engine-event-wiring.ts+++ b/src/modules/session/session-engine-event-wiring.ts@@ -43,6 +43,12 @@ export const RECONNECT_LOOP_REASON = 'Reconnecting after a dropped connection';export interface SessionEngineWiringHost {/** Liveness gate: true only while `engine` is still the live engine registered for `id`. */isLiveEngine(id: string, engine: IWhatsAppEngine): boolean;+ /**+ * True while an operator-initiated teardown (stop/logout/forceKill) is retiring exactly this+ * engine instance. Its DISCONNECTED is that teardown's own, reported before the eviction; the verb+ * announces the settled one once the engine is gone.+ */+ isOperatorTeardown(id: string, engine: IWhatsAppEngine): boolean;/*** Ownership gate: true while this node may still speak for `id`. Orthogonal to isLiveEngine —* between a lapsed lease and the teardown the heartbeat schedules, isLiveEngine is still true@@ -347,6 +353,13 @@ export class SessionEngineEventWiring {};const newStatus = statusMap[engineState];if (!newStatus) return;+ // An operator-initiated teardown reports DISCONNECTED on entry, before the engine is+ // evicted: whatsapp-web.js sets the status and only then awaits browser.close(). Announced+ // here it would tell every consumer the session is down while GET /sessions still reports+ // the engine as loaded, and the verb's own write after the eviction is dropped as a+ // duplicate, so the settled view would never be announced at all. Skipped for the exact+ // instance being torn down; stop/logout/forceKill each write DISCONNECTED afterwards.+ if (newStatus === SessionStatus.DISCONNECTED && host.isOperatorTeardown(id, engine)) return;// A FAILED reported inside a service-level reconnect's init window is parked with onError.const persist = (): void => persistStatus(newStatus);if (newStatus === SessionStatus.FAILED && host.parkReconnectInitFailure(id, persist)) return;diff --git a/src/modules/session/session-engine-lifecycle.service.ts b/src/modules/session/session-engine-lifecycle.service.tsindex 3d7bf8722..4f2d5ace9 100644--- a/src/modules/session/session-engine-lifecycle.service.ts+++ b/src/modules/session/session-engine-lifecycle.service.ts@@ -241,6 +241,17 @@ export class SessionEngineLifecycle {// engine B the control action did not capture.private readonly pendingInitialStatuses = new Map<string, { engine: IWhatsAppEngine; promise: Promise<void> }>();+ // The engine an operator-initiated teardown (stop/logout/forceKill) is currently retiring, keyed+ // by id and holding the EXACT instance. An adapter reports DISCONNECTED synchronously on entry to+ // its teardown, before the engine is evicted (whatsapp-web.js then awaits browser.close(), which+ // takes seconds), so that report is announced while GET /sessions still answers+ // `engineLoaded: true`, and the verb's own DISCONNECTED write afterwards is dropped by the+ // broadcaster's de-dup, leaving the corrected view unannounced. The wiring consults this to skip+ // the engine-driven DISCONNECTED for the instance being torn down; the verb announces it after the+ // eviction. Identity-keyed, never on the id alone: a replacement engine from a concurrent start()+ // must still announce, and a mark outliving a refused verb must not mute a later real disconnect.+ private readonly operatorTeardowns = new Map<string, IWhatsAppEngine>();+// The ONE-SHOT budget for an automatic stuck-auth credential reset, hoisted out of the adapter// instance and keyed by session id. recoverFromStuckAuth() (a generation that authenticated but// never reached readiness) claims this synchronously before it wipes LocalAuth; a claim returns true@@ -319,6 +330,7 @@ export class SessionEngineLifecycle {// promise and add settlement hops the retirement-race specs assert against).this.wiringHost = {isLiveEngine: (id, engine) => this.isLiveEngine(id, engine),+ isOperatorTeardown: (id, engine) => this.operatorTeardowns.get(id) === engine,ownsSession: id => this.ownsSession(id),handleEngineReady: (id, engine, phone, pushName) => this.handleEngineReady(id, engine, phone, pushName),rejectRebind: (id, engine, sessionName, previousPhone, incomingPhone) =>@@ -380,6 +392,7 @@ export class SessionEngineLifecycle {purgeAuthDirsIfDeleted: id => this.purgeAuthDirsIfDeleted(id),updateStatus: (id, status) => this.updateStatus(id, status),stoppingSessions: this.stoppingSessions,+ operatorTeardowns: this.operatorTeardowns,reconnectStates: this.reconnectStates,stuckAuthRecoveryUsed: this.stuckAuthRecoveryUsed,initializingSessions: this.initializingSessions,diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.tsindex 816f822eb..2a6e019c1 100644--- a/src/modules/session/session.service.spec.ts+++ b/src/modules/session/session.service.spec.ts@@ -6089,6 +6089,55 @@ describe('SessionService', () => {status: SessionStatus.DISCONNECTED,});});++ // whatsapp-web.js reports DISCONNECTED synchronously on entry to its teardown and only then+ // awaits browser.close(), so the engine is still registered when the callback fires. Announcing+ // there tells every consumer the session is down while GET /sessions still answers+ // engineLoaded: true, and the write after the eviction is dropped as a duplicate, so the+ // corrected view is never announced at all.+ it('announces the stop only after the engine is evicted', async () => {+ const session = createMockSession();+ (repository.findOne as jest.Mock).mockResolvedValue(session);+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });++ await service.start('sess-uuid-1');+ const callbacks = (mockEngine.initialize.mock.calls as [EngineEventCallbacks][])[0][0];++ const engineStillRegistered: boolean[] = [];+ (eventsGateway.emitSessionStatus as jest.Mock).mockImplementation((id: string) => {+ engineStillRegistered.push(registry.has(id));+ });+ mockEngine.disconnect.mockImplementation(async () => {+ callbacks.onStateChanged?.(EngineStatus.DISCONNECTED);+ await Promise.resolve(); // the real teardown awaits browser.close() after reporting+ });++ await service.stop('sess-uuid-1');++ const emits = (eventsGateway.emitSessionStatus as jest.Mock).mock.calls as [string, SessionStatus][];+ const disconnectedEmits = emits.filter(c => c[1] === SessionStatus.DISCONNECTED);+ expect(disconnectedEmits).toHaveLength(1);+ expect(engineStillRegistered).toEqual([false]);+ });++ // The suppression is keyed to the engine instance being torn down, so a mark left behind by a+ // stop that never ran cannot mute a later disconnect the session really had.+ it('still announces a disconnect after a stop that failed to find the session', async () => {+ const session = createMockSession();+ (repository.findOne as jest.Mock).mockResolvedValue(session);+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });+ await service.start('sess-uuid-1');+ const callbacks = (mockEngine.initialize.mock.calls as [EngineEventCallbacks][])[0][0];++ (repository.findOne as jest.Mock).mockResolvedValueOnce(null);+ await expect(service.stop('sess-uuid-1')).rejects.toThrow(NotFoundException);++ (eventsGateway.emitSessionStatus as jest.Mock).mockClear();+ callbacks.onStateChanged?.(EngineStatus.DISCONNECTED);+ await new Promise(resolve => setImmediate(resolve));++ expect(eventsGateway.emitSessionStatus).toHaveBeenCalledWith('sess-uuid-1', SessionStatus.DISCONNECTED);+ });});// ── getQRCode ─────────────────────────────────────────────────────