Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import * as qrcode from 'qrcode';
import * as path from 'path';
import { HttpException } from '@nestjs/common';
import { Client, LocalAuth, WAState } from 'whatsapp-web.js';
import {
type AccountRestriction,
type EngineEventCallbacks,
EngineStatus,
} from '../interfaces/whatsapp-engine.interface';
import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { EnginePageError } from '../../common/errors/engine-page.error';
import { type createLogger } from '../../common/services/logger.service';
import { DEFAULT_PUPPETEER_ARGS, MAX_TIMER_MS, withPinnedBrowserLocale } from '../../config/configuration';
import { resolveWebVersionPin } from '../wa-web-version';
import { resolveAuthTimeoutMs, resolveEngineInitTimeoutMs } from '../engine-init-timeout';
import { killOrphanedChromiumProcesses, removeStaleSingletonFiles } from './chromium-profile-hygiene';
import { isSupportedProxyUrl, buildProxyLaunchConfig } from './wwebjs-proxy';
import { backportProblem } from './wwebjs-backport-check';
import { unappliedPatches, unappliedPatchesMessage } from './engine-patch-status';
import { type EvaluatablePage, reportMissingCallHook } from './wwebjs-call-hook-check';
import { reportRunningWebBuild } from './wwebjs-running-build';
import { type WhatsAppWebJsConfig } from './whatsapp-web-js.adapter';
import { AUTH_FAILURE_REASON, STALE_PROFILE_ADVICE } from '../terminal-engine-failure';
import { wwjsAuthDir } from '../auth-dir-paths';
/**
* Detect Puppeteer's "Execution context was destroyed" error. During `Client.inject()` this is most
* often a persistent browser profile left stale by an OpenWA upgrade that changed the Chromium/Chrome
* binary (e.g. the v0.8.12 amd64 Debian Chromium → Chrome for Testing switch, #663 / #708) — but it is
* not exclusively that: Puppeteer also raises it on a page navigation or a renderer crash (see
* puppeteer-core `ExecutionContext` / `IsolatedWorld`), so the caller advises rather than asserts.
* Pure so the detection is unit-testable without mocking the whatsapp-web.js `Client`.
*/
export function isExecutionContextDestroyedError(reason: string): boolean {
return /execution context was destroyed/i.test(reason);
}
/**
* A first-inject rejection that reads as "the page navigated out from under the in-flight evaluate":
* the exec-context class above plus the 'window.require is not a function' variant (an evaluate
* landing on a document whose WA bundle has not booted yet). Deliberately SEPARATE from the
* stale-profile advisory classifier: the advisory names a remedy (delete the profile) that is wrong
* for the window.require shape (see src/config/process-error-monitor.ts) — this predicate only
* decides whether one in-place retry is worth it, both shapes being transient when a reload caused
* them. whatsapp-web.js registers its own re-inject handler only AFTER the first inject succeeds
* (Client.js:502 vs :504), so a navigation landing during it is caught by nothing upstream (#1081).
*/
function isNavigationShapedInitRejection(reason: string): boolean {
return isExecutionContextDestroyedError(reason) || /window\.require is not a function/i.test(reason);
}
/**
* A per-command CDP timeout is NOT a death: the renderer is merely slower than the budget, and
* the next command may succeed. On Puppeteer 24.38.0 this message carries none of the dead-page
* signatures, so isPageTransportError's carve-out changes no current behaviour: it pins the intent.
* It is still no answer from WhatsApp, so a caller must not read it as "no such resource" either.
*
* Matched on the FULL puppeteer phrase, not a bare `timed out`: a broad exclusion would also
* swallow a genuine death whose message happens to mention a timeout.
*/
const PROTOCOL_TIMEOUT_PATTERN = /timed out\. increase the 'protocoltimeout'/i;
/** Whether the error is Puppeteer's per-command protocolTimeout expiring (never an HttpException). */
export function isProtocolTimeout(error: unknown): boolean {
if (error instanceof HttpException) {
return false;
}
return PROTOCOL_TIMEOUT_PATTERN.test(error instanceof Error ? error.message : String(error));
}
/** What a request answers 409 while WhatsApp Web reloads its page, whichever side of the window stamp it lands. */
export const PAGE_RELOADING_MESSAGE =
'WhatsApp Web is reloading its page and the session is re-injecting. Retry in a few seconds.';
/**
* Whether a page call was cut short by the page navigating away under it (WhatsApp Web reloading). Puppeteer
* rewrites its three CDP shapes of this into 'Execution context was destroyed, most likely because of a
* navigation.', and a call that lands on the new document before WhatsApp Web has booted dies on the missing
* `window.require`. The page is alive and re-injecting, so unlike a death this is not reported, and a retry
* a few seconds later succeeds. Not an HttpException, and not a failure captured inside the page, whose text
* quotes WhatsApp Web and says nothing about our page. A page that stays without `window.require` is not
* hidden by this answer: it is not reported here, but the liveness probe fails outside the re-inject window
* and the watchdog reconnects. Left unread, the same message became a false 404 or 400 at the catches that
* fold a failed lookup into "not found", or a bare 500.
*/
export function isNavigationError(error: unknown): boolean {
if (error instanceof HttpException) {
return false;
}
const message = error instanceof Error ? error.message : String(error);
return !message.startsWith(CAPTURED_PAGE_ERROR_PREFIX) && isNavigationShapedInitRejection(message);
}
/**
* The start of a send failure that scripts/patch-wwebjs-send-error.js captured inside the page, where
* it summarises a thrown value puppeteer would otherwise hand over as `t: t`. The patcher builds the
* message from its own copy of this string (it runs at install time, before any of this is compiled),
* and wwebjs-send-page-error.spec.ts pins the two equal.
*/
export const CAPTURED_PAGE_ERROR_PREFIX = 'page threw ';
/** A summary field the patcher could not read, or read off a value that lacks it. */
const EMPTY_SUMMARY_FIELD = new Set(['', 'undefined', 'null', '(unreadable)']);
/**
* Turn a captured page error into an {@link EnginePageError} that tells the caller what WhatsApp Web
* threw; anything else, a summary that does not parse included, comes back unchanged. The thrown
* value can be anything, so the name falls back to its constructor and the message to its string.
*/
export function toCapturedPageError(error: unknown): unknown {
if (!(error instanceof Error) || !error.message.startsWith(CAPTURED_PAGE_ERROR_PREFIX)) return error;
let info: Record<string, unknown>;
try {
info = JSON.parse(error.message.slice(CAPTURED_PAGE_ERROR_PREFIX.length)) as Record<string, unknown>;
} catch {
return error;
}
if (!info || typeof info !== 'object') return error;
const pick = (...keys: string[]): string => {
for (const key of keys) {
const value = info[key];
if (typeof value === 'string' && !EMPTY_SUMMARY_FIELD.has(value)) return value;
}
return '';
};
const build = pick('build');
return new EnginePageError(
{ name: pick('name', 'ctor') || 'Error', message: pick('message', 'str'), ...(build ? { build } : {}) },
error,
);
}
/**
* requestPairingCode retry budget. WhatsApp Web reloads the QR page while UNPAIRED, so a pairing
* request can land mid-navigation and either reject fast ("Execution context was destroyed") or hang
* until Puppeteer's protocol timeout. Each attempt is bounded, and only the navigation/timeout shapes
* are retried; four attempts across ~1 minute cover several reload cycles, the page reboots in 2-3s.
*/
export const PAIRING_CODE_MAX_ATTEMPTS = 4;
export const PAIRING_CODE_ATTEMPT_TIMEOUT_MS = 15_000;
export const PAIRING_CODE_RETRY_DELAY_MS = 3_000;
/** Sentinel for a per-attempt pairing timeout, so it is retried like a navigation error rather than propagated. */
class PairingCodeAttemptTimeoutError extends Error {
constructor() {
super('requestPairingCode attempt timed out');
this.name = 'PairingCodeAttemptTimeoutError';
}
}
// A post-READY page navigation (WhatsApp Web's ~5-minute first reload on a fresh pairing, a
// service-worker update, …) destroys the page's JS world; whatsapp-web.js re-injects on its own
// framenavigated handler (Client.js:504-513), but until WA Web has booted again getState() REJECTS,
// so the liveness probe reads a healing page as dead and every delegate evaluate dies as a raw
// TypeError under a status that still says READY (#1081). Sizing — floor: the pre-boot phase alone
// (page load + WA Web bundle boot, the stretch where getState() rejects) takes tens of seconds on a
// slow host, and upstream's re-inject then polls up to 30s for window.WWebJS (Client.js:332-343);
// ceiling: one watchdog interval (60s), so a page that navigates and then wedges loses at most one
// probe to the grace and still dies within one extra interval. NOT a sibling of
// READY_RECONCILE_BRIDGE_RELOAD_GRACE_MS above: that one is capped by the 90s reconcile deadline,
// this one by keeping the watchdog's safety net alive — do not "harmonize" them.
export const NAVIGATION_REINJECT_GRACE_MS = 60_000;
// Hard bound per recovery episode (first navigation → the next completed re-inject): a page stuck in
// a navigation loop re-stamps the rolling grace faster than it expires, which would suppress the
// watchdog forever and leave a zombie session READY that only ever answers 409. Past this cap the
// probe reports the truth again and the watchdog takes over.
export const NAVIGATION_EPISODE_CAP_MS = 3 * NAVIGATION_REINJECT_GRACE_MS;
// The single in-adapter retry of a navigation-killed first inject only runs while at least this much
// of the lifecycle's outer init deadline remains — a retry the outer race SIGKILLs mid-launch would
// surface as a bare 504 with no reason. Below it, fail with today's exact terminal shape instead.
const INIT_RETRY_MIN_REMAINING_MS = 20_000;
// WhatsApp Web states that mean WhatsApp has judged the account or its egress, mapped to the neutral
// restriction kinds. This is the ONLY channel the library offers: there is no dedicated event, error
// type or cause code for account standing (whatsapp-web.js 1.34.7), just a `WAState` string on the
// `disconnected` event.
//
// Deliberately only three of the twelve states. UNPAIRED/UNPAIRED_IDLE and LOGOUT are unlinks,
// CONFLICT is another device taking over, DEPRECATED_VERSION is our own client being too old, and
// TIMEOUT is a fault — none is a statement about the account's standing, and reporting them as
// restrictions would be exactly the false positive that makes the signal worthless to act on.
const WA_STATE_RESTRICTIONS: Readonly<Record<string, AccountRestriction['kind']>> = {
TOS_BLOCK: 'tos_block',
SMB_TOS_BLOCK: 'tos_block',
PROXYBLOCK: 'proxy_block',
};
/**
* Host surface for {@link WwebjsLifecycle}. The adapter keeps the public engine methods as thin
* forwarders and builds ONE object literal of these closures, so the delegate drives connection
* state only through the seams named here: the sibling delegates it coordinates (reconcile,
* onboarding watcher, call cache, stuck-auth) and the adapter-owned callbacks and domain-event
* registration.
*/
export interface WwebjsLifecycleHost {
readonly logger: ReturnType<typeof createLogger>;
readonly config: WhatsAppWebJsConfig;
/** Live callbacks bag — read per event, since initialize() installs it after delegates are built. */
getCallbacks(): EngineEventCallbacks;
/** Arm / disarm the post-authentication readiness reconciliation (./wwebjs-reconcile). */
scheduleReadyReconcile(): void;
clearReadyReconcile(): void;
/** Arm / disarm the onboarding-modal watcher (./wwebjs-onboarding). */
startOnboardingWatcher(): void;
clearOnboardingWatcher(): void;
/** Drop every cached ringing call id: the client that saw those calls is going away. */
clearLiveCalls(): void;
/** Stand-in promise for the LocalAuth profile removal (./wwebjs-stuck-auth), routed through the
* adapter's own method so an instance-level replacement stays authoritative. */
clearLocalAuth(): Promise<void>;
/** Register the domain client events (messages, groups, calls) on a freshly built client. */
attachDomainEvents(client: Client): void;
}
/**
* Connection lifecycle extracted from WhatsAppWebJsAdapter: the initialize launch (with its single
* navigation-killed retry), the client-event wiring for connection state, puppeteer death detection,
* teardown in its four flavors, the liveness probe, and the state behind them. The adapter keeps the
* public IWhatsAppEngine members as thin forwarders and injects the host surface via closures, so
* the delegate never touches adapter state beyond the seams the host names.
*
* The state fields below are public where the adapter aliases them by reference (host closures and
* an unmodified spec poking `adapter.client` / `adapter.status` / … through a cast keep working
* byte-identically — the same aliasing BaileysAdapter does for `sock`); the rest stay private.
*/
export class WwebjsLifecycle {
/** Live whatsapp-web.js client, null once torn down. Aliased by the adapter's `client` accessor. */
client: Client | null = null;
/** Current engine status. Aliased by the adapter's `status` accessor. */
status: EngineStatus = EngineStatus.DISCONNECTED;
/** Last encoded QR, cleared on authentication. Aliased by the adapter's `qrCode` accessor. */
qrCode: string | null = null;
/** Own-account phone number, read once at readiness. */
private phoneNumber: string | null = null;
/** Own-account push name, read once at readiness. */
private pushName: string | null = null;
/** Set once teardown begins so a late 'authenticated' can't resurrect a disconnecting adapter. Not
* reset — an adapter is single-use after teardown (the session creates a fresh one to reconnect).
* Aliased by the adapter's `tearingDown` accessor. */
tearingDown = false;
/** Set by logout() before it starts the native unlink, which itself registers the real
* `client.logout()` promise as the credential teardown. The 'disconnected' LOGOUT handler consults
* this to avoid registering a second, redundant stand-in for the same profile rm — while still
* registering one for a WhatsApp-initiated logout, including one that lands after another teardown
* path has already latched the flags below. Aliased by the adapter's `logoutInitiated` accessor. */
logoutInitiated = false;
/** Set once a WhatsApp-initiated LOGOUT has started this session's credential removal, so a repeat of
* the same unlink cannot start a second one (#1072). Never reset — an adapter is single-use, and the
* profile is gone after the first removal either way. */
private credentialTeardownStarted = false;
/** Set once the adapter ACTIVELY transitions to DISCONNECTED (engine disconnect, puppeteer death,
* stuck-auth recovery, teardown). Same single-use contract as `tearingDown`, but it latches earlier:
* on LOGOUT whatsapp-web.js keeps the browser and re-runs inject(), while the lifecycle only replaces
* the engine after the reconnect backoff — so for those seconds the old client can still emit a QR or
* re-authenticate, and neither belongs to the session any more (#982). Aliased by the adapter's
* `disconnectReported` accessor. */
disconnectReported = false;
/** Set when this engine's page asked for a QR (whatsapp-web.js emits 'qr' only for an UNPAIRED page,
* and a pairing code needs QR_READY), so it tells a fresh pairing from a restore of saved
* credentials. The readiness deadline may clear credentials only for a fresh pairing. */
qrShown = false;
// Navigation re-inject window (#1081): stamped by our framenavigated listener, closed by the
// library's re-emitted 'ready' and by teardown. Timestamps, never timers — several suites pin
// exact jest timer counts, and a timer would also outlive the single-use adapter.
private lastMainFrameNavigationAt = 0;
private navigationEpisodeStartedAt = 0;
/** Counts the navigations stamped, so a probe can tell that one landed while it was waiting. */
private navigationCount = 0;
/** The WhatsApp Web build this init asked whatsapp-web.js to pin, undefined when it asked for none.
* Compared against the build the page reports at READY (./wwebjs-running-build). */
private requestedWebVersion: string | undefined;
constructor(private readonly host: WwebjsLifecycleHost) {}
async initialize(): Promise<void> {
this.setStatus(EngineStatus.INITIALIZING);
const initStartedAt = Date.now();
// An install that skipped the message-id backport fails later with errors that name no cause
// (#889) — say so here instead, while the operator is still looking at the startup logs.
const backportProblemText = backportProblem();
if (backportProblemText) {
this.host.logger.error(backportProblemText);
}
// The other whatsapp-web.js patchers fail the same way and were equally silent about it.
const unapplied = unappliedPatches('wwebjs');
if (unapplied.length) {
this.host.logger.error(unappliedPatchesMessage('wwebjs', unapplied));
}
try {
// Build puppeteer args, including proxy if configured
const puppeteerArgs = this.host.config.puppeteer?.args
? [...this.host.config.puppeteer.args]
: withPinnedBrowserLocale(DEFAULT_PUPPETEER_ARGS);
// Add proxy configuration if provided. A stored proxy that does not parse to a supported scheme
// fails the session, as on Baileys (#859): launching without it would send the session's traffic
// out of the host's own address instead of the egress the operator chose.
let proxyAuthentication: { username: string; password: string } | undefined;
if (this.host.config.proxy) {
if (isSupportedProxyUrl(this.host.config.proxy.url)) {
// Chromium ignores credentials in --proxy-server; pass a credential-less server and hand the
// username/password to wwjs's proxyAuthentication (page.authenticate) for HTTP/HTTPS proxies (#628).
const proxyLaunch = buildProxyLaunchConfig(this.host.config.proxy.url);
puppeteerArgs.push(`--proxy-server=${proxyLaunch.serverArg}`);
proxyAuthentication = proxyLaunch.proxyAuthentication;
if (proxyLaunch.socksAuthUnsupported) {
this.host.logger.warn(
`Proxy for session ${this.host.config.sessionId} has credentials on a SOCKS proxy, but Chromium ` +
`cannot authenticate SOCKS proxies. Use an IP-authorized proxy or an HTTP/HTTPS proxy instead.`,
);
}
this.host.logger.log(`Using proxy: ${proxyLaunch.serverArg}`);
} else {
throw new Error(
`The session proxy URL is not a supported http(s)/socks4/socks5 URL; fix or clear it with ` +
`PATCH /api/sessions/${this.host.config.sessionId}/proxy`,
);
}
}
// Marker arg: Chromium silently ignores unknown flags, so this exists purely as a label that
// lets killOrphanedChromiumProcesses() identify this session's browser processes in `ps`
// output later (after a hard kill of the OpenWA process orphaned them).
puppeteerArgs.push(`--openwa-session=${this.host.config.sessionId}`);
// Pin the WA-Web version (fixes the 1.34.x "stuck at authenticating" hang on some setups,
// #251/#488). DEFAULT: auto-resolve a settled build from the wa-version registry and pin its
// remote HTML (no integrity check — resolveWebVersionPin logs a loud warning); only
// WWEBJS_WEB_VERSION=off leaves whatsapp-web.js to use the first-party build from WhatsApp.
// The pinned HTML is downloaded (bounded) onto the writable data volume and served from there,
// so an unreachable mirror is named in the log instead of silently loading the live build.
const versionPin = await resolveWebVersionPin(
undefined,
path.join(path.resolve(this.host.config.sessionDataPath), '.wa-web-cache'),
);
// Assigned on every init, including the unpinned case, so a pin from an earlier init is never
// compared against the page this one loads.
this.requestedWebVersion = versionPin?.webVersion;
if (this.tearingDown) {
this.setStatus(EngineStatus.DISCONNECTED);
return;
}
if (versionPin) {
this.host.logger.log(`Pinning WhatsApp Web version ${versionPin.webVersion}`);
}
// Extend the first-boot init wait on slow setups (WSL2/low-resource), #353. Opt-in:
// unset keeps whatsapp-web.js's 30000ms default.
const authTimeoutMs = resolveAuthTimeoutMs();
if (authTimeoutMs) {
this.host.logger.log(`Using auth timeout ${authTimeoutMs}ms`);
}
// One retry for a navigation-killed first inject (#1081): a WhatsApp Web reload landing
// mid-inject rejects initialize() with nothing upstream ever retrying (see
// isNavigationShapedInitRejection): on a start() the onError channel below is terminal, and a
// service-level reconnect still lands this shape in FAILED since it carries the stale-profile advice.
// Structurally a single second try — skipped when the lifecycle's outer init race is nearly
// spent (a retry the race SIGKILLs mid-launch would surface as a bare 504 with no reason), and
// abandoned when attempt 1's browser cannot be destroyed (see resetForInitRetry).
try {
await this.runInitAttempt(puppeteerArgs, authTimeoutMs, proxyAuthentication, versionPin);
} catch (attemptError) {
const attemptReason = attemptError instanceof Error ? attemptError.message : String(attemptError);
const budgetLeftMs = resolveEngineInitTimeoutMs() - (Date.now() - initStartedAt);
if (
this.tearingDown ||
!isNavigationShapedInitRejection(attemptReason) ||
budgetLeftMs < INIT_RETRY_MIN_REMAINING_MS
) {
throw attemptError;
}
this.host.logger.warn(
`"${attemptReason}" killed the first inject — a page navigation landed before ` +
`whatsapp-web.js installed its re-inject handler. Retrying the launch once (#1081).`,
{ sessionId: this.host.config.sessionId, action: 'init_navigation_retry' },
);
const cleaned = await this.resetForInitRetry();
if (this.tearingDown) {
this.setStatus(EngineStatus.DISCONNECTED);
return;
}
if (!cleaned) {
this.host.logger.warn(
"Attempt 1's browser did not die within the destroy bound — abandoning the retry rather " +
'than launching a second Chromium into the same profile',
{ sessionId: this.host.config.sessionId, action: 'init_navigation_retry_abandoned' },
);
throw attemptError;
}
await this.runInitAttempt(puppeteerArgs, authTimeoutMs, proxyAuthentication, versionPin);
}
} catch (error) {
// A stop, delete or force-kill closed the browser under the launch, which is what rejected it:
// settle like the other teardown exits instead of reporting the stop as a failed start.
if (this.tearingDown) {
if (this.status !== EngineStatus.DISCONNECTED) this.setStatus(EngineStatus.DISCONNECTED);
return;
}
this.setStatus(EngineStatus.FAILED);
const reason = error instanceof Error ? error.message : String(error);
// What the dashboard renders as `lastError` is exactly this string and nothing else — the log
// below never reaches it. Carry a one-line remedy with the reason for the one failure we can
// actually advise on, so the session card stops being a dead end (#1081).
let surfacedReason = reason;
if (isExecutionContextDestroyedError(reason)) {
// #708: Puppeteer's "Execution context was destroyed" during inject reads like a Puppeteer bug.
// During initialize() its dominant cause is a browser profile left stale by an upgrade that
// changed the Chromium/Chrome binary (e.g. v0.8.12 amd64: Debian Chromium → Chrome for Testing,
// #663) — but it can also follow a page navigation or a renderer crash, so advise, don't assert.
// The profile dir is the same one clearLocalAuth() removes on a clean re-pair. Safe to compute
// here: sessionDataPath is a required config field already resolved in the try block above, so
// this can't throw and mask the original error we are about to rethrow.
this.host.logger.warn(
`"${reason}" during initialize. If this followed an OpenWA upgrade that changed the ` +
`Chromium/Chrome binary (v0.8.12 amd64 switched Debian Chromium → Chrome for Testing), the ` +
`session's browser profile is likely stale — delete the profile dir ` +
`"${wwjsAuthDir(this.host.config.sessionDataPath, this.host.config.sessionId)}" ` +
`and start again to re-scan. If no upgrade happened, Puppeteer also raises this on a page ` +
`navigation or renderer crash (check for memory pressure or a WhatsApp Web reload). ` +
`See docs/12-troubleshooting-faq.md.`,
);
// Kept short and with the raw Puppeteer text FIRST: operators search on that string, and the
// dashboard truncates a long reason. The profile path stays in the log above — it is too long
// for a card, and naming the wrong remedy is worse than pointing at the FAQ, since deleting a
// profile forces an irreversible re-pair.
surfacedReason =
`${reason} ${STALE_PROFILE_ADVICE} If this followed an ` +
`upgrade, the session's browser profile is likely stale — see docs/12-troubleshooting-faq.md.`;
}
this.host.getCallbacks().onError?.(surfacedReason);
throw error;
}
}
/**
* One construction+launch attempt: everything from `new Client(...)` through the puppeteer death
* listeners. Extracted so the navigation retry (#1081) repeats the FULL sequence — a second
* attempt without setupEventHandlers() would have no qr/authenticated/ready handlers at all, and
* without the pre-launch sweeps it would trip over attempt 1's stale Singleton files. A LIVE
* attempt-1 browser never reaches attempt 2: resetForInitRetry() abandons the retry instead.
*/
private async runInitAttempt(
puppeteerArgs: string[],
authTimeoutMs: number | undefined,
proxyAuthentication: { username: string; password: string } | undefined,
versionPin: Awaited<ReturnType<typeof resolveWebVersionPin>>,
): Promise<void> {
// Range-checked at the sink, not only in configuration.ts: a plugin config written through
// `PUT /api/plugins/whatsapp-web.js/config` is validated as an object and merged over the env
// blob at every boot, so it can carry a value the config layer never saw. Both bounds are
// load-bearing. `common/CallbackRegistry.js` arms the timer under `if (timeout)`, so 0 arms
// none and a wedged renderer holds the command, and the request behind it, indefinitely; above
// MAX_TIMER_MS Node's timer overflows and fires after 1 ms, so the browser never launches.
const configuredProtocolTimeout = this.host.config.puppeteer?.protocolTimeoutMs;
const protocolTimeout =
typeof configuredProtocolTimeout === 'number' &&
configuredProtocolTimeout > 0 &&
configuredProtocolTimeout <= MAX_TIMER_MS
? configuredProtocolTimeout
: undefined;
const client = new Client({
authStrategy: new LocalAuth({
clientId: this.host.config.sessionId,
dataPath: path.resolve(this.host.config.sessionDataPath),
}),
puppeteer: {
headless: this.host.config.puppeteer?.headless ?? true,
args: puppeteerArgs,
// Do NOT let Puppeteer install its own process signal handlers. By default it handles
// SIGINT (→ synchronous process.exit(130), which would skip the graceful drain entirely)
// and SIGTERM/SIGHUP (→ kills Chromium at signal time, defeating the drain window). We own
// signal handling in main.ts. Puppeteer's unconditional `exit` hook still SIGKILLs this
// browser when the process actually exits, so nothing is orphaned.
handleSIGINT: false,
handleSIGTERM: false,
handleSIGHUP: false,
// Only override the executable when explicitly configured; otherwise let
// whatsapp-web.js fall back to Puppeteer's bundled Chromium.
...(this.host.config.puppeteer?.executablePath
? { executablePath: this.host.config.puppeteer.executablePath }
: {}),
// Per-CDP-command budget, spread only when the host configured a usable one (see above).
// Absent, puppeteer-core nullish-coalesces to its own 180 000 ms (`cdp/Connection.js`).
...(protocolTimeout !== undefined ? { protocolTimeout } : {}),
},
...(authTimeoutMs !== undefined ? { authTimeoutMs } : {}),
...(proxyAuthentication ? { proxyAuthentication } : {}),
// Unpinned, whatsapp-web.js defaults to a local HTML cache at the cwd-relative
// './.wwebjs_cache/' and writes it after the link, before `ready`. The image's /app is not
// writable (root-owned, read-only in compose and Helm), so that write throws and the session
// never reaches ready. 'none' caches nothing and serves WhatsApp's live build. A pin is a
// strict local cache under SESSION_DATA_PATH (see resolveWebVersionPin), which the library
// only reads: it persists nothing when the cache served the page.
...(versionPin ?? { webVersionCache: { type: 'none' as const } }),
});
this.client = client;
this.setupEventHandlers();
if (this.tearingDown) {
this.client = null;
this.setStatus(EngineStatus.DISCONNECTED);
return;
}
// Kill any Chromium that survived a hard kill of a previous OpenWA process lifetime (its
// Puppeteer exit hook never ran, leaving an orphaned browser holding the profile). Safe here:
// this runs before this attempt's browser exists, so the only thing it can kill is an orphan —
// including attempt 1's browser when the bounded inter-attempt destroy did not finish it.
await killOrphanedChromiumProcesses(this.host.config.sessionId, this.host.logger);
// Clear stale Chromium Singleton* files left by a hard kill before launching — see
// removeStaleSingletonFiles. This runs after the orphan kill above and before this attempt's
// browser exists, so it cannot pull the files out from under a running Chromium.
await removeStaleSingletonFiles(this.host.config.sessionId, this.host.config.sessionDataPath, this.host.logger);
if (this.tearingDown) return;
try {
await client.initialize();
} finally {
// A stop, delete or logout that landed mid-launch ran Client.destroy() before whatsapp-web.js
// assigned pupBrowser, so it closed nothing. The handle exists now: close the browser here, or
// it stays logged in with no owner until the process exits.
if (this.tearingDown || this.client !== client) {
await client.destroy().catch(() => undefined);
}
}
if (this.tearingDown || this.client !== client) return;
// whatsapp-web.js 1.34.x never observes the Chromium process/page it drives, so a crashed
// browser leaves the client looking READY forever ("silent death"). Attach death listeners
// to the puppeteer handles so a dead browser surfaces as a normal disconnect → reconnect.
this.attachPuppeteerLifecycleListeners();
}
/**
* Reset between a failed first init attempt and its single retry (#1081). Deliberately NOT
* beginClientTeardown(): that would latch tearingDown (the adapter is single-use after teardown)
* and write DISCONNECTED, whose disconnectReported latch permanently drops the retry's
* qr/authenticated events. The reconcile clear matters most: the patched hasSynced level-check can
* fire AUTHENTICATED before the navigation-killed evaluate rejects initialize(), leaving attempt
* 1's 90s deadline live — its non-bridge branch deletes credentials (recoverFromStuckAuth), which
* must never run underneath a retry that is about to succeed.
*
* Returns false when attempt 1's browser could not be destroyed within the bound — the caller
* must then abandon the retry: launching a second Chromium into the same LocalAuth profile risks
* corrupting the only credential copy (an irreversible re-pair), and the marker-based orphan
* sweep is explicitly best-effort, so it cannot be trusted as the escalation for a LIVE browser.
*/
private async resetForInitRetry(): Promise<boolean> {
const failed = this.client;
this.client = null;
this.host.clearReadyReconcile();
this.qrCode = null;
this.setStatus(EngineStatus.INITIALIZING);
if (!failed) return true;
// The old client may still emit late events from persisted page bindings. The qr, authenticated
// and ready listeners fence on the source client, but disconnected, auth_failure and the domain
// events do not, so silence it before the new attempt starts.
failed.removeAllListeners();
// Bounded DIRECT destroy — never this.destroy()/forceDestroy(), both of which latch the
// teardown flags above.
let timeout: ReturnType<typeof setTimeout> | undefined;
try {
await Promise.race([
failed.destroy(),
new Promise<never>((_, reject) => {
timeout = setTimeout(() => reject(new Error('init-retry destroy timed out')), 5_000);
timeout.unref?.();
}),
]);
return true;
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
this.host.logger.warn('Destroying the failed first init attempt did not complete cleanly', {
error: message,
});
// A FAST rejection means the browser was already gone (destroy found nothing live to close) —
// safe to relaunch. A TIMEOUT means a live, wedged Chromium still holds the profile.
return message !== 'init-retry destroy timed out';
} finally {
if (timeout) clearTimeout(timeout);
}
}
setupEventHandlers(): void {
if (!this.client) return;
// Every listener below belongs to THIS client. Stuck-auth recovery and teardown null (or replace)
// this.client while the old page can still flush a buffered event through its bindings, so the
// qr, authenticated and ready listeners fence on this identity before touching this.client.
const source = this.client;
const canPublishQr = (): boolean =>
this.client === source &&
!this.tearingDown &&
!this.disconnectReported &&
![EngineStatus.AUTHENTICATING, EngineStatus.READY, EngineStatus.ACTION_REQUIRED, EngineStatus.FAILED].includes(
this.getStatus(),
);
// eslint-disable-next-line @typescript-eslint/no-misused-promises
this.client.on('qr', async (qr: string) => {
// A 'qr' buffered by a wedged page can flush during the awaited client.destroy(), after
// recoverFromStuckAuth() nulls this.client, or from a client that whatsapp-web.js re-injected
// after a LOGOUT (#982) — in the last case the browser is still alive and will keep serving QRs
// until the lifecycle replaces the engine. Ignore all of them so a late event can't resurrect a
// finished adapter to QR_READY and publish a QR that links a phantom device. Mirrors the
// 'authenticated' guard below; the normal first QR is unaffected (initialize() moves the status to
// INITIALIZING before any client exists, so the latch is still clear).
if (!canPublishQr()) return;
this.qrShown = true;
// qrcode.toDataURL() is an awaited macrotask: a 'disconnected' (or a teardown nulling this.client)
// that lands during the encode leaves the pre-await guard stale. Encode to a LOCAL so the stored
// qrCode is only touched once the fence re-proves the source client and the finished flags.
try {
const encodedQr = await qrcode.toDataURL(qr);
// Post-await fence: the encode resolved, but the source client may have disconnected or been
// replaced while we were waiting. Re-check the live client identity and the finished flags before
// assigning state, publishing a QR, or driving any downstream callback/webhook — a late encode for
// a dead/finished adapter must be dropped. Authentication or an operator-required state reached
// during encoding also makes this QR obsolete.
if (!canPublishQr()) return;
this.qrCode = encodedQr;
this.setStatus(EngineStatus.QR_READY);
this.host.getCallbacks().onQRCode?.(this.qrCode);
} catch (error) {
this.host.logger.error('Error generating QR code', String(error));
}
});
this.client.on('authenticated', () => {
// Only the first authentication starts the reconcile window. Ignore a re-fired 'authenticated'
// while already AUTHENTICATING (so it can't restart the 90s deadline), once READY/FAILED, at
// ACTION_REQUIRED (a re-inject must not clear it, which only stop then start does), or any
// time after the adapter is finished — teardown, or a reported disconnect the lifecycle has not
// replaced the engine for yet (#982). The initial status is DISCONNECTED too, so "finished" is
// carried by the flags, never by the status alone.
if (
this.client !== source ||
this.tearingDown ||
this.disconnectReported ||
this.status === EngineStatus.AUTHENTICATING ||
this.status === EngineStatus.READY ||
this.status === EngineStatus.ACTION_REQUIRED ||
this.status === EngineStatus.FAILED
) {
return;
}
this.setStatus(EngineStatus.AUTHENTICATING);
this.qrCode = null;
this.host.scheduleReadyReconcile();
});
this.client.on('ready', () => {
// A late 'ready' from a client that is no longer the live one (stuck-auth recovery nulled it, or
// teardown finished) must be dropped outright: dereferencing this.client would throw, and
// reading it optionally would promote a client-less adapter to READY.
if (this.client !== source || this.tearingDown || this.disconnectReported) return;
// The library re-emits 'ready' at the end of EVERY completed (re)inject pipeline — for a
// post-navigation re-inject this is the completion edge, and the only one it offers. Close the
// navigation window HERE, before the guards below: markReadyFromClientInfo early-returns while
// already READY, so a clear behind it would never run for the re-inject case (#1081).
this.clearNavigationReinjectWindow();
// whatsapp-web.js can emit `ready` BEFORE its message listeners are attached: its post-auth
// callback runs once per hasSynced trigger, and any run that finds `window.WWebJS` already
// defined skips the attach and bare-emits `ready` — including while the first run's attach is
// still in flight (observed live). Promoting on that premature emit binds READY to a session
// whose inbound bridge may never come up. The patched client's `eventsAttached` flag
// (scripts/patch-wwebjs-ready-sync.js) distinguishes the cases: `false` → ignore this emit
// and let the attach's own completion re-emit `ready` (it always does), with the readiness
// reconciliation as the backstop when the attach failed instead. `undefined` (unpatched
// tree) keeps the legacy behaviour.
if ((source as Client & { eventsAttached?: boolean }).eventsAttached === false) {
this.host.logger.warn('Ignoring premature ready: the message event bridge is not attached yet', {
sessionId: this.host.config.sessionId,
action: 'premature_ready_ignored',
});
return;
}
this.markReadyFromClientInfo();
});
// Message/group/call domain events: registered through the adapter's attachDomainEvents seam,
// which wires ./wwebjs-message-events, ./wwebjs-group-events and the call-cache delegate.
this.host.attachDomainEvents(this.client);
this.client.on('disconnected', reason => {
// A LOGOUT means whatsapp-web.js is ABOUT to delete this session's profile. The only site that
// emits this reason is the `framenavigated` listener, which emits and THEN awaits
// `authStrategy.logout()` → `LocalAuth.logout()` → `fs.rm(userDataDir)` — with the browser still
// open (only the explicit `Client.logout()` closes it first, and that path emits nothing). That
// rm happens whatever this listener does, so it MUST be surfaced to the lifecycle before the
// latch check below can drop out — otherwise a stop()/destroy() that latched first hides an
// in-flight rm, the name fence sees nothing pending, and a later start() under the same name can
// have its freshly written profile deleted by it (the #994 hazard, through a narrower window).
//
// Skipped when THIS adapter's logout() started it: that path already registered the real
// `client.logout()` promise, which covers the same rm and settles no earlier. Skipped again on
// every repeat, because the listener above carries no guard of its own — it resets its
// `lastLoggedOut` flag only after three awaits and never checks for the main frame, so one unlink
// can raise this event more than once (#1072). Sitting above the duplicate-event latch is what
// makes that reachable, so the guard has to be its own one-shot rather than that latch.
if (reason === 'LOGOUT' && !this.logoutInitiated && !this.credentialTeardownStarted) {
this.credentialTeardownStarted = true;
// Idempotent stand-in for the library's own rm, which we cannot get a handle on:
// `fs.rm(force: true)` races it safely and gives the lifecycle something to await.
this.host.getCallbacks().onCredentialTeardownStarted?.(this.host.clearLocalAuth());
}
// A deliberate teardown (logout/disconnect/destroy/forceDestroy via beginClientTeardown) also
// raises this event: client.logout() triggers the in-page Cmd 'logout' → framenavigated →
// DISCONNECTED 'LOGOUT' while we are still awaiting it. The unlink is already acknowledged by
// the API response and the session service writes DISCONNECTED itself, so report nothing here
// (mirrors the puppeteer-death gate). A WhatsApp-initiated unlink arrives with
// tearingDown=false and still flows through to the status/callback below.
//
// setStatus(DISCONNECTED) below latches disconnectReported synchronously on the first event, so a
// duplicate native 'disconnected' (whatsapp-web.js can fire it more than once for one drop) must
// no-op HERE — before log/status/callback — otherwise clearReadyReconcile(), setStatus, and
// onDisconnected re-run and the lifecycle schedules a second reconnect.
if (this.tearingDown || this.disconnectReported) return;
this.host.clearReadyReconcile();
// #982: LOGOUT is not a transient drop. The lifecycle's reconnect cannot restore the link; it
// can only come back with a fresh QR. Say that here rather than leaving the operator with an
// opaque engine token that reads like any other drop.
if (reason === 'LOGOUT') {
this.host.logger.warn(
'WhatsApp unlinked this device (LOGOUT). whatsapp-web.js is deleting the stored credentials ' +
'for this session, so reconnecting cannot restore the link — the session comes back with a ' +
'fresh QR and must be re-scanned. If this was not expected, check Linked devices on the phone.',
);
}
this.setStatus(EngineStatus.DISCONNECTED);
// Report the account judgement BEFORE the disconnect so a consumer reacting to the disconnect
// already knows why it happened. Only the state token is passed through — the adapter draws no
// conclusion about recoverability from it and leaves the reconnect decision exactly as it was.
const restriction = WA_STATE_RESTRICTIONS[reason];
if (restriction) {
this.host.getCallbacks().onAccountRestriction?.({ kind: restriction, code: reason });
}
this.host.getCallbacks().onDisconnected?.(reason);
});
this.client.on('auth_failure', (message?: string) => {
this.host.clearReadyReconcile();
this.setStatus(EngineStatus.FAILED);
// Authentication failure is terminal: the stored credentials are invalid and
// reconnecting will not help — the operator must re-scan the QR code. Route it
// through onError (FAILED, no reconnect) rather than onDisconnected (reconnect).
this.host.getCallbacks().onError?.(message ? `${AUTH_FAILURE_REASON}: ${message}` : AUTH_FAILURE_REASON);
});
}
/**
* Attach to the loosely-typed whatsapp-web.js puppeteer handles (same cast pattern as
* isClientRuntimeReady/forceDestroy). whatsapp-web.js itself never listens to these, so without
* this a dead Chromium is invisible: browser process death, renderer crash ("Aw Snap"), and a
* closed tab all mean the session is gone, no matter what status the client still reports.
*/
attachPuppeteerLifecycleListeners(): void {
if (!this.client) return;
const { pupBrowser, pupPage } = this.client as unknown as {
pupBrowser?: { on: (event: 'disconnected', cb: () => void) => void };
pupPage?: {
on: (event: 'error' | 'close' | 'framenavigated', cb: (frame?: { url?: () => string }) => void) => void;
mainFrame?: () => unknown;
};
};
pupBrowser?.on('disconnected', () => this.handlePuppeteerDeath('Browser process closed or crashed'));
pupPage?.on('error', () => this.handlePuppeteerDeath('Page crashed'));
pupPage?.on('close', () => this.handlePuppeteerDeath('Page closed'));
// A page NAVIGATION fires none of the above: the page is healing, not dead — whatsapp-web.js
// re-injects on its own framenavigated handler and re-emits 'ready' when done. Stamp the window
// so probeLiveness and ensureReady treat it as alive-but-recovering (#1081). Never stamp the
// LOGOUT navigation shapes (post_logout URL, or upstream's latched lastLoggedOut): there the
// credential teardown driven by the DISCONNECTED('LOGOUT') event is the path that must win.
pupPage?.on('framenavigated', frame => {
try {
// mainFrame is feature-detected: the spec harnesses' EventEmitter pages have no frames.
if (typeof pupPage.mainFrame === 'function' && frame !== pupPage.mainFrame()) return;
if (typeof frame?.url === 'function' && frame.url().includes('post_logout=1')) return;
} catch {
return; // the frame detached before this handler ran — nothing worth stamping
}
// lastLoggedOut is a runtime field the wwjs typings do not declare (same loose-cast pattern as
// the pupBrowser/pupPage handles above).
if ((this.client as unknown as { lastLoggedOut?: boolean } | null)?.lastLoggedOut) return;
this.navigationCount++;
const now = Date.now();
if (this.navigationEpisodeStartedAt === 0) this.navigationEpisodeStartedAt = now;
this.lastMainFrameNavigationAt = now;
// `graced: false` here means the episode cap already expired — the stamp is recorded but the
// probe/ensureReady grace is NOT being granted, so the log must not claim it is.
this.host.logger.warn('Page navigated; whatsapp-web.js is re-injecting', {
sessionId: this.host.config.sessionId,
action: 'page_navigation_reinject_window',
graced: this.isInNavigationReinjectWindow(),
});
});
}
/**
* Route a Chromium/page death (detected via the puppeteer handles) through the exact same path as
* the client's own 'disconnected' event. A deliberate teardown also fires the browser's
* 'disconnected', and a real crash usually fires page 'error' and browser 'disconnected' together
* — so ignore calls during teardown or once the status already is DISCONNECTED/FAILED (first
* signal wins, no double-report).
*/
private handlePuppeteerDeath(reason: string): void {
// No client means the stuck-auth recovery (or an init retry) already let go of this browser and
// killed it on purpose; that recovery reports the disconnect itself once the profile is cleared.
if (
this.tearingDown ||
!this.client ||
this.status === EngineStatus.DISCONNECTED ||
this.status === EngineStatus.FAILED
) {
return;
}
this.host.clearReadyReconcile();
this.setStatus(EngineStatus.DISCONNECTED);
this.host.getCallbacks().onDisconnected?.(reason);
}
/** How many times, and how far apart, {@link reportOnceGone} looks for puppeteer to mark a page gone. */
private static readonly PAGE_GONE_POLLS = 25;
private static readonly PAGE_GONE_POLL_MS = 20;
/**
* Error-message signatures of a dead page/transport: Puppeteer raises these when the browser
* process, the renderer, or the CDP connection is gone (e.g. 'Protocol error: Target closed').
*/
private static readonly PAGE_TRANSPORT_ERROR_PATTERN =
/protocol error|target closed|targetclosederror|detached frame|session closed|connection closed/i;
/** Whether the error carries a dead page/transport signature (see PAGE_TRANSPORT_ERROR_PATTERN). */
isPageTransportError(error: unknown): boolean {
// An HttpException is never a dead page. It is an error THIS application constructed, and its
// message carries caller-supplied text verbatim: MessageNotFoundError reads
// `Message ${messageId} not found in chat ${chatId}`, and GroupNotFoundError, LabelNotFoundError
// and ChannelNotFoundError have the same shape. Matching the pattern against
// one of those hands the CALLER the classifier. A request naming a messageId of "Target closed"
// made its own 404 read as a transport death: the session was torn down and reconnected, and the
// caller got a 503. The reactions read needs no role at all, so the lowest-privilege key could
// do it at will.
//
// Excluding the class loses no real signal. Puppeteer and whatsapp-web.js throw plain Errors,
// and a page-side throw arrives as one too (puppeteer-core rebuilds it in cdp/utils.js
// createEvaluationError). It also settles the nested case: an EngineTransportError arriving from
// an inner catch was already reported where it was built, and handlePuppeteerDeath latches on
// status, so re-reporting would be a no-op regardless.
if (error instanceof HttpException) {
return false;
}
if (isProtocolTimeout(error)) {
return false;
}
const message = error instanceof Error ? error.message : String(error);
// A captured page error is never a dead page: the page was alive enough to run the catch that
// built it. Its summary quotes WhatsApp Web's own text, and that text can say "connection closed"
// about WhatsApp's socket, which the pattern would otherwise read as ours going down.
if (message.startsWith(CAPTURED_PAGE_ERROR_PREFIX)) {
return false;
}
return WwebjsLifecycle.PAGE_TRANSPORT_ERROR_PATTERN.test(message);
}
/**
* Report a failed client/page operation as a session death when the error matches
* PAGE_TRANSPORT_ERROR_PATTERN. A wedged page can fire NO events while still reporting CONNECTED
* (whatsapp-web.js #5728), so the watchdog takes minutes to notice — an operation failing with one
* of these errors is a much earlier death signal. Detection
* only: the error itself still propagates to the caller exactly as before, and
* handlePuppeteerDeath's guard makes this safe during teardown and against double-reporting.
*/
reportIfPageTransportError(error: unknown, context: string): void {
if (!this.isPageTransportError(error)) {
return;
}
this.reportDeath(error, context);
}
/**
* For a best-effort read that carries on after a failure, which must not take the session down on an
* error's text: a page-side exception can quote "connection closed" about WhatsApp Web's own socket while
* the page is fine. Puppeteer rejects a call pending on a dying page a few milliseconds BEFORE it marks
* the page closed or the browser disconnected (measured with Chromium stopped by SIGTERM and with a tab
* closed from outside; a killed browser already reads disconnected), so the page gets a short while to
* show it is gone. A page that still reads alive after that is not reported and the caller carries on.
*/
async reportOnceGone(error: unknown, context: string): Promise<void> {
if (!this.isPageTransportError(error)) return;
// Counted in polls rather than elapsed time: every poll hands the event loop a turn, which is when
// puppeteer's close events are delivered, even if the process was starved for longer than the wait.
for (let polls = 0; polls < WwebjsLifecycle.PAGE_GONE_POLLS; polls++) {
if (this.status !== EngineStatus.READY || this.isPageGone()) break;
await new Promise(resolve => setTimeout(resolve, WwebjsLifecycle.PAGE_GONE_POLL_MS));
}
// Not READY any more means a death listener or a teardown got there first and owns the report.
if (this.status !== EngineStatus.READY) return;
if (!this.isPageGone()) {
this.host.logger.warn(`Page transport error during ${context} while the page is alive, not a death`, {
error: error instanceof Error ? error.message : String(error),
action: 'page_transport_error_page_alive',
});
return;
}
this.reportDeath(error, context);
}
private reportDeath(error: unknown, context: string): void {
// Inside the navigation re-inject window the same signatures ride a HEALING page: an in-flight
// evaluate killed by the navigation keeps its 'Protocol error' prefix (puppeteer only rewrites
// the shapes that END with a context-gone suffix), and a navigating page transiently detaches
// frames. Reporting that as death would tear down the session whatsapp-web.js is about to
// re-inject — faster than the watchdog the grace protects against (#1081). Log the match so the
// theory stays falsifiable from field logs; the error still propagates to the caller, and a
// REAL browser death still reports through the pupBrowser/pupPage death listeners untouched.
if (this.isInNavigationReinjectWindow()) {
this.host.logger.warn(
`Page transport error during ${context} inside the navigation re-inject window — not a death`,
{
error: error instanceof Error ? error.message : String(error),
action: 'page_transport_error_graced',
},
);
return;
}
this.host.logger.warn(`Page transport error during ${context} — treating the session as dead`, {
error: error instanceof Error ? error.message : String(error),
});
this.handlePuppeteerDeath(`Page transport error during ${context}`);
}
/** Whether puppeteer itself reports the page closed or the browser disconnected (not an error's text). */
private isPageGone(): boolean {
const { pupBrowser, pupPage } = (this.client ?? {}) as unknown as {
pupBrowser?: { connected?: boolean };
pupPage?: { isClosed?: () => boolean };
};
return pupPage?.isClosed?.() === true || pupBrowser?.connected === false;
}
markReadyFromClientInfo(): void {
if (
[EngineStatus.READY, EngineStatus.DISCONNECTED, EngineStatus.FAILED, EngineStatus.ACTION_REQUIRED].includes(
this.status,
)
)
return;
this.host.clearReadyReconcile();
try {
const info = this.client?.info;
this.phoneNumber = info?.wid?.user || null;
this.pushName = info?.pushname || null;
this.setStatus(EngineStatus.READY);
this.host.getCallbacks().onReady?.(this.phoneNumber || '', this.pushName || '');
} catch (error) {
this.host.logger.error('Error getting client info', String(error));
this.setStatus(EngineStatus.READY);
this.host.getCallbacks().onReady?.('', '');
}
// A freshly-linked account may show a "What's new" onboarding modal that, left unacknowledged,
// gets the companion unlinked (~5m later → disconnected: LOGOUT, #982). Dismiss it best-effort
// and fall back to ACTION_REQUIRED. Started after READY so a non-ready session never arms it.
this.host.startOnboardingWatcher();
const page = (this.client as unknown as { pupPage?: EvaluatablePage } | null)?.pupPage;
// whatsapp-web.js patches the call collection only when the page's module for it exposes an
// `.on` function. A WhatsApp Web build that keeps the module but drops that method skips the
// hook while the rest of the evaluate completes, so the session looks healthy, keeps delivering
// messages, and reports no call at all. That quiet case is the one worth a line in the log; a
// build that removes the module instead makes the library's own require throw, aborting the
// evaluate and taking the inbound message bridge with it, which is loud on its own. Warn once
// per ready; nothing else changes, since only detection is lost. Fire-and-forget: a diagnostic
// must never delay or fail the promotion to READY.
//
// Skipped on a tree missing the ready-sync patch: without it the session can reach READY while
// that same evaluate is still running, so the probe would read a page whose hook simply has not
// been installed YET and warn about a problem that does not exist. An unpatched tree already
// reports itself at startup, which is the honest signal there.
if (!unappliedPatches('wwebjs').includes('patch-wwebjs-ready-sync')) {
void reportMissingCallHook(page, this.host.logger, this.host.config.sessionId);
}
// The pin logged at startup is only what was requested: a page load that bypasses the library's
// request interceptor can run another build (see ./wwebjs-running-build). Log the build this page
// actually reports, and warn when it is not the pinned one. Same fire-and-forget contract as the
// call-hook probe, and not gated on the ready-sync patch: `window.Debug.VERSION` is WhatsApp
// Web's own, set before whatsapp-web.js injects anything. Once per READY, so a post-READY
// navigation (which re-emits 'ready' while already READY) is not re-read.
void reportRunningWebBuild(page, this.host.logger, this.host.config.sessionId, this.requestedWebVersion);
}
/** The single status-transition funnel: latches disconnectReported and fires the callback. Public
* because the sibling delegates (reconcile, stuck-auth, onboarding watcher) drive transitions
* through their host slices. */
setStatus(status: EngineStatus): void {
// Latch before anything observes the transition. The constructor's initial DISCONNECTED is a field
// initializer and never reaches here, so this only ever fires on a real transition — startup is
// unaffected while a finished adapter is marked finished for good.
if (status === EngineStatus.DISCONNECTED) {
this.disconnectReported = true;
}
// The cached QR belongs to the page that produced it, so it dies with the QR_READY window. Same
// funnel placement as the Baileys engine: only the 'authenticated' and init-retry exits cleared the
// cache by hand, so a browser or page death, a failed init, an auth failure and teardown all left a
// dead QR to be served over GET /qr for the whole reconnect backoff.
if (status !== EngineStatus.QR_READY) {
this.qrCode = null;
}
this.status = status;
this.host.getCallbacks().onStateChanged?.(status);
}
private beginClientTeardown(): Client | null {
this.tearingDown = true;
// The cached ringing call ids belong to the client that is going away, so drop them all.
this.host.clearLiveCalls();
// Before the clientless early-return: a teardown must always close the navigation window, or a
// stale stamp could grace the next generation's probe (single-use contract notwithstanding).
this.clearNavigationReinjectWindow();
const client = this.client;
if (!client) return null;
this.host.clearReadyReconcile();
this.host.clearOnboardingWatcher();
if (this.status !== EngineStatus.DISCONNECTED) {
this.setStatus(EngineStatus.DISCONNECTED);
}
return client;
}
private finishClientTeardown(client: Client): void {
if (this.client === client) {
this.client = null;
}
this.host.clearReadyReconcile();
this.host.clearOnboardingWatcher();
this.clearNavigationReinjectWindow();
}
async disconnect(): Promise<void> {
const client = this.beginClientTeardown();
if (!client) return;
try {
// Use destroy instead of logout to preserve session data
// This allows reconnecting without needing to scan QR again
await client.destroy();
} catch (error) {
this.host.logger.warn('Destroy client failed:', { error: String(error) });
// Already destroyed or not initialized - ignore
} finally {
this.finishClientTeardown(client);
}
}
async logout(): Promise<void> {
// Mark the credential removal as caller-owned before anything can emit 'disconnected'. The
// lifecycle tracks this call's removal from the outside — SessionService passes the session name
// to teardownEngineSafely, which registers the whole engine.logout() promise (a superset of the
// in-page unlink AND the profile rm that follows it), and that is the single owner for BOTH
// engines, since the Baileys adapter reports nothing here either. So this method must NOT
// register a second, narrower promise for the same removal, and the 'disconnected' LOGOUT handler
// must not add its stand-in on top. Set even with no live client: the throw path sends nothing,
// so no event can arrive, and a caller-initiated logout is still what happened.
this.logoutInitiated = true;
const client = this.beginClientTeardown();
// No live client means there is nothing to send the unlink through. Resolving here would report a
// confirmed unlink for a request that never reached WhatsApp — the caller writes an audit row on
// success, and the device would stay listed under the account holder's Linked Devices. The
// session-level "is it started?" check cannot catch this: an engine stays registered while its
// client is gone (a stuck-auth recovery nulls it, then waits out the reconnect backoff).
if (!client) {
throw new Error('No live WhatsApp Web client — the unlink was not sent');
}
try {
// client.logout() chains authStrategy.logout() (LocalAuth) → fs.rm of this session's profile
// dir. The lifecycle already tracks that removal through this method's own promise (see the
// note above logoutInitiated), so nothing is registered here.
await client.logout();
} catch (error) {
this.host.logger.warn('Logout failed:', { error: String(error) });
// Fall back to destroy so the session still dies locally — but rethrow so the caller
// learns the unlink never reached WhatsApp: the device may still be listed under the
// account holder's Linked Devices, and reporting success would write a false audit row.
try {
await client.destroy();
} catch (destroyError) {
this.host.logger.warn('Client destroy also failed during logout fallback', { error: String(destroyError) });
}
throw error;
} finally {
this.finishClientTeardown(client);
}
}
async destroy(): Promise<void> {
const client = this.beginClientTeardown();
if (!client) return;
try {
await client.destroy();
} finally {
this.finishClientTeardown(client);
}
}
/**
* Force-recover a wedged session: SIGKILL THIS client's own Chromium process directly (not a
* process-wide `pkill`, which would also kill other sessions), then best-effort `client.destroy()`
* for the rest of the cleanup. Both steps are wrapped so a missing process handle or a hung destroy
* can't prevent the engine from being torn down and the status reset.
*/
async forceDestroy(): Promise<void> {
const client = this.beginClientTeardown();
if (!client) return;
try {
// pupBrowser is the Puppeteer Browser; .process() is the Chromium ChildProcess (null if already gone).
const proc = (
client as unknown as { pupBrowser?: { process?: () => { kill?: (sig: string) => void } | null } }
).pupBrowser?.process?.();
proc?.kill?.('SIGKILL');
} catch (err) {
this.host.logger.warn('forceDestroy: failed to kill the browser process', { error: String(err) });
}
try {
await client.destroy();
} catch (err) {
this.host.logger.warn('forceDestroy: client.destroy() failed after the kill (continuing)', {
error: String(err),
});
} finally {
this.finishClientTeardown(client);
}
}
getStatus(): EngineStatus {
return this.status;
}
getQRCode(): string | null {
return this.qrCode;
}
getPhoneNumber(): string | null {
return this.phoneNumber;
}
getPushName(): string | null {
return this.pushName;
}
/**
* Whether a recent main-frame navigation is still inside its bounded re-inject window. Two bounds:
* the rolling per-navigation grace, and the per-episode cap that stops a navigation LOOP from
* re-stamping its way past the watchdog forever. Consulted only AFTER the READY-status gates in
* probeLiveness()/ensureReady() — a teardown or LOGOUT drops the status first, and the grace must
* never outrank that (#1081).
*/
isInNavigationReinjectWindow(): boolean {
if (this.lastMainFrameNavigationAt === 0) return false;
const now = Date.now();
return (
now - this.lastMainFrameNavigationAt < NAVIGATION_REINJECT_GRACE_MS &&
now - this.navigationEpisodeStartedAt < NAVIGATION_EPISODE_CAP_MS
);
}
private clearNavigationReinjectWindow(): void {
this.lastMainFrameNavigationAt = 0;
this.navigationEpisodeStartedAt = 0;
}
/**
* Active liveness probe for the session watchdog: race a real getState() round-trip against a 10s
* timeout. Probe failure or timeout means dead — a wedged page can keep reporting CONNECTED
* (whatsapp-web.js #5728), so turning consecutive probe failures into a reconnect decision stays
* the calling watchdog's job. One exception: inside the bounded navigation re-inject window a
* failing probe answers alive, since the page is healing, not dead (#1081).
*/
async probeLiveness(): Promise<boolean> {
// The watchdog also probes an ACTION_REQUIRED session, observe-only (it never reconnects one): the page
// is still up while the operator acts. Answering false without asking made every such session look
// dead on the first tick, and hid a page that really had died.
const probeable = this.status === EngineStatus.READY || this.status === EngineStatus.ACTION_REQUIRED;
if (!probeable || !this.client) return false;
const navigationsBefore = this.navigationCount;
let timeout: ReturnType<typeof setTimeout> | undefined;
try {
const state = await Promise.race([
this.client.getState(),
new Promise<never>((_, reject) => {
timeout = setTimeout(() => reject(new Error('liveness probe timed out')), 10_000);
timeout.unref?.();
}),
]);
if (state === WAState.CONNECTED) {
// Observed recovery closes the navigation episode. Without this, an episode whose re-inject
// died silently (no 'ready' re-emit, but WA Web's socket back up) would keep a stale episode
// anchor forever, denying the grace to every LATER navigation via the episode cap. Only an episode
// this answer can speak for: a navigation stamped while getState() was pending is a newer one.
if (navigationsBefore === this.navigationCount) this.clearNavigationReinjectWindow();
return true;
}
return this.isInNavigationReinjectWindow();
} catch {
// Inside the navigation window the evaluate rejecting (context destroyed, window.require not
// yet a function) means the page is healing, not dead — answer alive so the watchdog does not
// tear down a session whatsapp-web.js is about to re-inject (#1081). The window is bounded, so
// a page that navigated and then wedged still dies within one extra watchdog interval.
return this.isInNavigationReinjectWindow();
} finally {
// Never leave the timeout dangling when getState() settles first (Jest open-handle hygiene).
if (timeout) clearTimeout(timeout);
}
}
/**
* Request an 8-char pairing code so the user can link via "Link with phone number" instead of
* scanning the QR.
*
* Gated on QR_READY, not on the client merely existing. `this.client` is assigned before
* `client.initialize()` (see runInitAttempt), so for the whole Chromium launch — seconds on a
* modest host — a client is present while its `pupPage` is still null, and whatsapp-web.js's
* requestPairingCode reaches `exposeFunctionIfAbsent(this.pupPage, …)` and throws a raw TypeError
* that surfaces as a 500. QR_READY is the precise window this can work in anyway: the library
* emits 'qr' only once the Store is injected and the in-page socket reports UNPAIRED, which are
* the same preconditions the pairing flow needs.
*/
async requestPairingCode(phoneNumber: string): Promise<string> {
if (!this.client || this.status !== EngineStatus.QR_READY) {
throw new EngineNotReadyError('Session is not waiting to be linked. Start it and wait for the QR stage.');
}
// WhatsApp Web reloads the QR page while UNPAIRED (roughly every 20s). A requestPairingCode that
// lands mid-navigation runs its in-page evaluate against a destroyed context: it either rejects
// with "Execution context was destroyed" or hangs until Puppeteer's protocol timeout (minutes),
// and the dashboard sits on "Creating pairing code..." with nothing ever returned. The navigation
// is transient (the page reboots in a few seconds), so bound each attempt and retry only the
// navigation/timeout shapes while the session is still at the QR stage. A real failure (an invalid
// number, an already-linked account) is not navigation-shaped and propagates on the first attempt.
let lastError: unknown;
for (let attempt = 1; attempt <= PAIRING_CODE_MAX_ATTEMPTS; attempt++) {
let timer: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
this.client.requestPairingCode(phoneNumber),
new Promise<never>((_resolve, reject) => {
timer = setTimeout(() => reject(new PairingCodeAttemptTimeoutError()), PAIRING_CODE_ATTEMPT_TIMEOUT_MS);
timer.unref?.();
}),
]);
} catch (error) {
lastError = error;
const reason = error instanceof Error ? error.message : String(error);
const transient =
error instanceof PairingCodeAttemptTimeoutError ||
isExecutionContextDestroyedError(reason) ||
isProtocolTimeout(error) ||
/callfunctionon timed out/i.test(reason);
if (!transient) {
throw error;
}
if (attempt < PAIRING_CODE_MAX_ATTEMPTS) {
// Nothing cancels the abandoned attempt, and nothing needs to. The library's own
// requestPairingCode clears the in-page re-request interval as the first act of its
// evaluate, so the next attempt stops the previous flow itself. Its `cancelPairingCode`
// would on top of that return the page to QR mode, which is the opposite of what a retry
// wants, and it is an unbounded page evaluate against the page that is already unwell, so
// awaiting it would add a full Puppeteer protocol timeout to each gap. The abandoned flow
// is not inert: each tick of its interval asks WhatsApp for a fresh code and notifies the
// phone, and its CODE_RECEIVED event reaches nothing here. What bounds it is the page, not
// us: the interval dies with the next WhatsApp Web reload, which happens every few seconds
// while the session is UNPAIRED, and with the session itself.
await new Promise<void>(resolve => {
const t = setTimeout(resolve, PAIRING_CODE_RETRY_DELAY_MS);
t.unref?.();
});
// The reboot may have ended the QR window (linked, or torn down). Do not retry a dead session.
if (!this.client || this.status !== EngineStatus.QR_READY) {
throw new EngineNotReadyError('Session is no longer waiting to be linked.');
}
}
} finally {
if (timer) {
clearTimeout(timer);
}
}
}
// Every attempt hit a transient navigation/timeout, so the budget ran out on the transport rather
// than on anything the caller sent. Reported as EngineTransportError (503) so a caller reads it as
// retryable: a plain Error here surfaced as a 500, which says the gateway is broken and that
// retrying is pointless. The last attempt's reason rides along as the detail.
throw new EngineTransportError(
`Pairing code could not be generated after ${PAIRING_CODE_MAX_ATTEMPTS} attempts: ` +
`${lastError instanceof Error ? lastError.message : String(lastError)}`,
);
}
}