Free, Open Source, Self-Hosted WhatsApp API Gateway
31 — Session Lifecycle: Invariant Catalog
Status: living design note. This document maps the race windows the session lifecycle defends against to the code that defends them and the spec that pins each one. It is the companion to
docs/03§Engine Lifecycle State Machine, which describes the WHAT; this describes the WHY-NOT-THE-OBVIOUS-THING. Anchors reference spec files by name (stable) — not line numbers (they rot).
The lifecycle is split across three files with one rule each:
| File | Owns |
|---|---|
session-engine-lifecycle.service.ts |
Engine creation/initialization, status transitions, the reconnect loop (executeReconnect), teardown |
session-engine-controls.ts |
The seven control verbs (start/stop/logout/forceKill/delete/shutdown/stopOrphanEngines) |
session-ownership.service.ts + src/modules/takeover/session-takeover.service.ts |
Cross-node leases, adoption, orphan reaping |
31.1 The invariant catalog
Each entry: the interleaving that would break a naive implementation → where it is defended → which spec pins it. If you change one of these files, re-read the rows that cite it.
INV-1 — Double-start cannot orphan the first engine
Interleaving: two POST /start for the same session race; both pass the "not already
starting" read; two engines come up; one is leaked forever (registry holds the second).
Defense: initializingSessions is reserved SYNCHRONOUSLY (before any await) in
session-engine-controls.ts — the second request observes the reservation and fails fast.
Pinned by: session.service.spec.ts (the maxConcurrent/double-start cases, incl. the concurrent-start
claim-holding verbs at
'%s() keeps the claim when a concurrent start still holds the session here').
The naive fix that is wrong: checking session.status instead — status is written to the DB
and read back with an await in between; the reservation map is the only synchronous view.
INV-2 — INITIALIZING is persisted before initialize(), and retirement can await that write
Interleaving: a stop/logout lands while initialize() is in flight; the control sees status
READY (stale) and skips teardown of an engine that is actually mid-boot.
Defense: the INITIALIZING row is written and its promise tracked
(session-engine-lifecycle.service.ts, initializeEngine); a retiring control awaits the
pending write before deciding what it is retiring.
Pinned by: session.service.spec.ts (the stop/delete-during-start teardown cases).
INV-3 — Ownership is re-validated by object identity, not by session id
Interleaving: control A starts engine #1; engine #1 fails and is destroyed; control B (a
retry) starts engine #2; a stale callback from #1 arrives and mutates registry state owned by #2.
Defense: EngineRegistry keys by session id but validates liveness by object identity
(isLive / deleteIfLive) — a superseded engine's late callback cannot act.
Pinned by: engine-registry.service.spec.ts (isLive / deleteIfLive cases); the registry
is the single most repeated invariant in the module.
INV-4 — Init timeout evicts and 504s; init rejection propagates as FAILED
Interleaving: whatsapp-web.js calls page.goto(..., {timeout: 0}) — a hung browser never
rejects, and neither does a navigation that never completes because WhatsApp Web is unreachable, so
a plain await hangs the start forever. The engine's own authTimeoutMs poll does not cover that
case: whatsapp-web.js only starts it in inject(), after the page has loaded.
Defense: Promise.race deadline in initializeEngine; on timeout the engine is evicted +
force-destroyed + status DISCONNECTED + 504 to the caller. The eviction, the recorded error and the
DISCONNECTED write apply only while that engine is still the live one: a stale deadline (a stop +
start replaced it mid-init) force-destroys its own engine and 504s, and leaves the replacement alone.
A REAL rejection is NOT treated as a timeout: it propagates so start() records FAILED with the
reason.
Pinned by: session.service.spec.ts (start failure-path cases; the timeout/rejection
split lives in session.service.spec.ts's init-timeout describes).
Do not "simplify" the two paths into one — the distinction is why a bad proxy config returns
FAILED + reason while an init that never completes returns 504 + eviction.
INV-5 — Delete racing a start re-purges auth directories after init resolves
Interleaving: delete runs (purges dirs, removes the session's messages, outbox rows and
delivery failures in batches, then the session row and its other child rows in one
transaction); the in-flight start's initialize() resolves and re-creates the auth dir; a phantom
session lingers on disk.
Defense: the post-init guards in start() (session-engine-controls.ts) and executeReconnect
(session-engine-lifecycle.service.ts) call isSessionRetired, which treats a stop mark or a missing
row as retired (delete clears its mark before a slow init resolves), then tear down the
just-registered engine and re-purge with purgeAuthDirsIfDeleted.
Pinned by: session.service.spec.ts ('re-purges the auth dirs when a start completes after its
row was deleted (init re-created them)' for start(), and 'tears down an engine created when a
delete lands during init (session row gone, mark cleared)' for executeReconnect). The opposite half,
that a stop retirement does not purge, is pinned by 'tears down the just-initialized engine if a
stop/delete lands during start() (no resurrection to READY)'.
INV-6 — Lease loss tears down local engines only; it never writes session rows
Interleaving: node A holds session X's lease; node B adopts it after A's lease lapses; a
stale in-flight write from A would clobber B's status.
Defense: on lease loss, stopOrphanEngines destroys local engines; the session row is the
owning node's alone (session.service.ts boot path). The one exception is the takeover sweep's
markLapsedDisconnected, which marks a row disconnected only under the predicate it read (same
nodeId, same status, lease expired more than two TTLs ago, and for a qr_ready row still no
phone), so a row B has claimed, or a pairing that completed meanwhile, matches nothing. A qr_ready
row with a phone is never marked: the adoption sweep would take the resulting disconnected row over.
Pinned by: src/modules/takeover/session-takeover.service.spec.ts +
session-ownership.service.spec.ts + session-ownership-status-fence.spec.ts + the real-database
predicate spec for markLapsedDisconnected in src/modules/session/session.service.spec.ts.
INV-7 — FAILED sessions are deliberately NOT adopted by takeover
Interleaving: a session that failed on node A (real engine error) would be adopted by node B
and quietly retried, hiding the failure from the operator.
Defense: the adoption sweep skips FAILED rows — a human decides.
Pinned by: src/modules/takeover/session-takeover.service.spec.ts ('skips sessions not
worth resuming: unauthenticated, mid-pairing, or operator-flagged failed').
INV-8 — Logout teardown races nothing: the browser must be gone before dir removal
Interleaving: client.logout() chains authStrategy.logout() → fs.rm(userDataDir) while
the Chromium process still holds file handles → rm fails or races a browser re-write.
Defense: whatsapp-web.js's own Client.logout() closes the browser and polls up to ~1 s for it
to disconnect before LocalAuth removes the profile dir. OpenWA's part is the name-keyed
credential-teardown fence: teardownEngineSafely registers the whole engine.logout() promise under
the session name, and start(), delete() and executeReconnect wait for it through
awaitPendingTeardown (bounded at 10 s and fail-closed: a timeout is a 409 for start()/delete()
and a failed attempt for a reconnect), so no new engine or purge races the rm.
Pinned by: logout-teardown-race.spec.ts, which enumerates that fence's interleavings. Read it
before touching anything in the logout/forceKill path.
INV-9 — The reconnect loop bounds itself: backoff with jitter, clamp ≤ 5 min and ≤ setTimeout's 32-bit range, alert every 5 consecutive attempts
Defense: reconnect-policy.ts — a pure decision function (attempt budget, loop alerts)
consumed by the lifecycle, which resets the budget only when the session held READY for
STABLE_READY_MS (5 min) before its next drop or its next READY, so a session that flaps keeps
backing off and still alerts. The stretch ends where the engine first reports a non-READY state
(readyEndedAt), so a Baileys in-engine reconnect between two READYs is not counted as READY time;
the clamps exist because a naive delay * 2^attempt reaches values
setTimeout silently truncates, and overflows to Infinity on a long enough streak.
Pinned by: reconnect-policy.spec.ts, session.service.spec.ts (scheduleReconnect cases).
INV-10 — Boot auto-start is sequential, staggered (2s per Chromium), and detached from bootstrap
Why: ten Chromium instances launching simultaneously on boot would hold the HTTP port closed
for minutes; detaching from bootstrap means the API answers while engines warm.
Pinned by: session.service.spec.ts (boot auto-start ordering/staggering cases).
31.2 Status-transition ownership
Every transition has a known, enumerated set of writers. When debugging a status surprise, find the writer before anything else:
| Transition | Writers |
|---|---|
→ INITIALIZING |
initializeEngine (persisted before initialize()) |
→ QR_READY / AUTHENTICATING |
engine callbacks (wired in the lifecycle delegate), via the registry's liveness check |
→ READY |
handleEngineReady (also drops a recorded failure reason, see INV-7's rationale comment) |
→ DISCONNECTED |
init-timeout eviction, graceful stop, logout, forceKill, a delete whose teardown fence times out, the engine onDisconnected callback and the liveness watchdog (handleEngineDisconnected), the boot reset, a backup import (active rows restored as disconnected), engine-reported DISCONNECTED via onStateChanged, the takeover sweep's markLapsedDisconnected (INV-6) |
→ ACTION_REQUIRED |
engine-reported ACTION_REQUIRED via onStateChanged (ownership-fenced status write; the whatsapp-web.js onboarding-modal fallback), and onActionRequired records the reason |
→ FAILED |
five terminal paths only, all ownership-fenced: see below |
FAILED is the one worth spelling out, because it is terminal (neither the boot reset nor the
takeover sweep resumes a FAILED row, INV-7) and because more than one path reaches it:
start()'s own rejection path, wheninitializeEnginethrows (session-engine-controls.ts).- The engine's
onErrorcallback, which is terminal by definition: it cancels any pending reconnect before persisting, because a re-scan is required (session-engine-event-wiring.ts). - The engine reporting
EngineStatus.FAILEDthroughonStateChanged, which the status map forwards verbatim (session-engine-event-wiring.ts). - A reconnect chain that EXHAUSTS its attempts, so the session is not left silently stuck
DISCONNECTEDwith no engine (session-engine-lifecycle.service.ts). rejectRebind, when a different WhatsApp account scans a bound session's QR: it logs that account out and landsFAILEDwith the reason (session-engine-lifecycle.service.ts).
What still holds, and is load-bearing, is the narrower claim: no reconnect ATTEMPT writes FAILED.
Only the exhaustion of the whole chain does. A loop that marked each failed attempt would turn every
transient network blip into an operator-visible terminal state and defeat INV-7's signal. All five
paths are fenced on ownsSession, so a dying generation cannot park a peer's session in a status
nothing resets automatically.
31.3 Comments that exist because the obvious fix is wrong
Collected here so they survive refactors of the code around them:
session-engine-lifecycle.service.ts(init deadline region): the do-not-reorder note — the ownership re-validation window between the status write andinitialize()is narrowed, not closed; moving the re-validation after init reopens INV-2.session-engine-controls.ts(start): the reconnect knobs read from the client-writablesession.configare coerced and clamped byresolveReconnectConfig, so a poisoned value cannot become a NaN delay (a zero-delay relaunch storm) or a NaN attempt cap that never trips.EngineRegistry: identity-baseddeleteIfLiverather thandelete(id)— see INV-3; every site that bypassed this in the past created the same phantom-callback bug. The eviction helpers go through it too:evictAndForceDestroy, the init-timeout branch, andstart()'s catch.start()identifies its own engine by capturing the registry entry right after callinginitializeEngine(which registers it before its first await), not by a lookup in the catch: a mid-init disconnect can schedule a reconnect that registers a replacement first.
31.4 What this document is NOT
- Not a state machine diagram (docs/03 has it).
- Not exhaustive per-file documentation — the source comments carry the local detail; this maps the SYSTEM of invariants and where each lives.
- Not a spec: where this document and a spec disagree, the spec is right — fix this document.