Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.ts
index 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 attempts
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);
- // 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.ts
index 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.ts
index 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.ts
index 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 ─────────────────────────────────────────────────────