@eliware/elera-lib 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 The alternative SQL client for Eliware applications. It provides generic
 primary/balanced MySQL or MariaDB routing without embedding Elera, HAProxy,
-backup, or GitOps policy. It is a v0.1.2 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.3 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
@@ -43,6 +43,15 @@ library does not know about supervisors, Elera, HAProxy, GitOps, backups, or
 CLI commands. Applications provide those integrations through ordinary
 configuration and callbacks.
 
+When a route node is drained, the client immediately stops assigning new work
+to that node while existing operations continue. The default drain window is
+45 seconds and can be changed with `drainTimeoutMs`; remaining pool
+connections are then force-closed. `client.drain(host)` returns `wait()` and
+`forceClose()` operations, while `client.nodeStates()` exposes lifecycle and
+active-operation state. Only conservative, single-statement reads are eligible
+for automatic retry after a connection failure; uncertain writes are never
+retried automatically.
+
 The public client intentionally exposes SQL operations, health, routing,
 lifecycle, and optional routing-event synchronization methods. REST and
 WebSocket transports are adapters, not supervisor or CLI policy. Underlying

package/RELEASE_NOTES.md

@@ -1,5 +1,31 @@
 # Release notes
 
+## 0.1.3 — Client-side routing drain lifecycle
+
+This patch adds generic client-side handling for supervisor-published routing
+drains and topology resynchronization. It does not add Supervisor, CLI, Galera,
+backup, or GitOps policy to the library.
+
+### Added
+
+- Tracks active operations and acquired connections per route node.
+- Exposes node lifecycle state and client drain status.
+- Immediately excludes draining nodes from new work and force-closes remaining
+  pool connections after the configurable 45-second default drain window.
+- Handles recovery events for primary and balanced routes.
+- Retries eligible read operations only; uncertain writes are not retried.
+- Rejects stale routing events and applies REST resync bundles through the
+  active routing handler.
+- Adds WebSocket heartbeat scheduling and cleanup during reconnect and close.
+
+### Validation
+
+- Adds regression coverage for drain completion, forced cutoff, connection
+  accounting, safe retry behavior, stale events, REST resync, and heartbeats.
+- Maintains 100% statements, branches, functions, and lines coverage with zero
+  lint warnings.
+- Typecheck and diff validation pass.
+
 ## 0.1.2 — Unix-socket connection correction
 
 This patch corrects the mysql2 option used for local MariaDB Unix-domain

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.2",
-    "description": "Generic MySQL and MariaDB client with primary, balanced, and resilient routing",
+    "version": "0.1.3",
+    "description": "Generic MySQL and MariaDB client with resilient routing, client-side drains, and failover",
     "keywords": [
         "eliware",
         "elera",

package/src/client/create-db.mjs

@@ -7,7 +7,12 @@ import { validateBundle, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs
 import { createRouteFactory } from './route-factory.mjs';
 import { classifyQuery, routeFor } from '../routing.mjs';
 
-export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, quarantineMs = 5000, now = () => Date.now() } = {}) {
+const olderVersion = (candidate, current) => {
+  if (candidate === undefined || current === undefined) return false;
+  return String(candidate) < String(current);
+};
+
+export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, quarantineMs = 5000, drainTimeoutMs = 45000, now = () => Date.now() } = {}) {
   if (!primary || typeof primary !== 'object') throw new TypeError('primary connection profile is required');
   const credentials = await resolveCredentials(credentialProvider, credentialContext(primary, { identity }));
   let primaryConfig = validateProfile({ ...primary, ...credentials }, 'primary');
@@ -23,12 +28,14 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
   let balancedPool = balancedConfig || activeBundle?.routes?.balanced ? makeRoute('balanced', balancedConfig ?? primaryConfig) : null;
   const choose = (sql, options = {}) => options.connection ?? (routeFor(sql, options.route ?? routing) === 'balanced' && balancedPool ? balancedPool : primaryPool);
   const client = {
-    async query(sql, values, options) { const selected = choose(sql, options); try { return await selected.query(sql, values); } catch (error) { if (error.retryable && routeFor(sql, options?.route ?? routing) === 'balanced') return balancedPool.query(sql, values); throw error; } },
+    async query(sql, values, options) { const selected = choose(sql, options); try { return await selected.query(sql, values); } catch (error) { const requestedRoute = options?.route ?? routing; if (error.retryable && balancedPool && routeFor(sql, requestedRoute) === 'balanced' && classifyQuery(sql) === 'balanced') return balancedPool.query(sql, values); throw error; } },
     async execute(sql, values, options) { return choose(sql, options).execute(sql, values); },
     async transaction(callback) { const node = primaryPool.choose(); const connection = await node.getConnection(); try { await connection.beginTransaction(); const tx = { query: (sql, values) => connection.query(sql, values), execute: (sql, values) => connection.execute(sql, values) }; const result = await callback(tx); await connection.commit(); return result; } catch (error) { await connection.rollback().catch(() => {}); throw asSqlError(error); } finally { connection.release(); } },
     async health(route = 'primary') { const started = now(); const selected = route === 'balanced' && balancedPool ? balancedPool : primaryPool; const nodes = await selected.health(); return { ok: nodes.some((node) => node.ok), route: selected === balancedPool ? 'balanced' : 'primary', nodes, latencyMs: now() - started }; },
-    async refresh(nextBundle) { const candidate = validateBundle(nextBundle); if (bundleExpired(candidate, now())) throw new Error('routing bundle is expired'); const previous = [primaryPool, balancedPool]; const credentials = candidate.credentials ?? { username: primaryConfig.user, password: primaryConfig.password }; primaryConfig = validateProfile({ ...primaryConfig, host: candidate.routes.primary[0]?.host, port: candidate.routes.primary[0]?.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); balancedConfig = candidate.routes.balanced?.[0] ? validateProfile({ ...primaryConfig, host: candidate.routes.balanced[0].host, port: candidate.routes.balanced[0].port }, 'balanced') : undefined; activeBundle = candidate; primaryPool = makeRoute('primary', primaryConfig); balancedPool = balancedConfig ? makeRoute('balanced', balancedConfig) : null; await Promise.all(previous.filter(Boolean).map((pool) => pool.close())); return { bundleVersion: activeBundle.bundleVersion ?? null, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; },
-    async attachRoutingStream(stream) { if (!stream?.connect) throw new TypeError('routing stream is required'); stream.setOnUpdate?.(async (event) => { if (event.type === 'routing.update' && event.routes?.primary?.length) await client.refresh({ ...activeBundle, database: event.database ?? activeBundle?.database ?? primaryConfig.database, credentials: event.credentials ?? activeBundle?.credentials, routes: event.routes, bundleVersion: event.bundleVersion ?? activeBundle?.bundleVersion, expiresAt: activeBundle?.expiresAt ?? new Date(now() + 60000).toISOString() }); for (const host of event.type === 'routing.drain' ? [event.node] : event.type === 'routing.recovery' ? [event.node] : []) client.setNodeAvailability('primary', host, event.type === 'routing.recovery'); }); await stream.connect(); return () => stream.close?.(); },
+    async refresh(nextBundle) { const candidate = validateBundle(nextBundle); if (bundleExpired(candidate, now())) throw new Error('routing bundle is expired'); if (olderVersion(candidate.bundleVersion, activeBundle?.bundleVersion)) return { bundleVersion: activeBundle?.bundleVersion, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; const previous = [primaryPool, balancedPool]; const credentials = candidate.credentials ?? { username: primaryConfig.user, password: primaryConfig.password }; primaryConfig = validateProfile({ ...primaryConfig, host: candidate.routes.primary[0]?.host, port: candidate.routes.primary[0]?.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); balancedConfig = candidate.routes.balanced?.[0] ? validateProfile({ ...primaryConfig, host: candidate.routes.balanced[0].host, port: candidate.routes.balanced[0].port }, 'balanced') : undefined; activeBundle = candidate; primaryPool = makeRoute('primary', primaryConfig); balancedPool = balancedConfig ? makeRoute('balanced', balancedConfig) : null; await Promise.all(previous.filter(Boolean).map((pool) => pool.close())); return { bundleVersion: activeBundle.bundleVersion ?? null, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; },
+    async attachRoutingStream(stream) { if (!stream?.connect) throw new TypeError('routing stream is required'); stream.setOnUpdate?.(async (event) => { const update = event.type === 'routing.update' ? event : event.type === 'routing.resync' ? event.bundle : undefined; if (update?.routes?.primary?.length) await client.refresh({ ...activeBundle, database: update.database ?? activeBundle?.database ?? primaryConfig.database, credentials: update.credentials ?? activeBundle?.credentials, routes: update.routes, bundleVersion: update.bundleVersion ?? update.version ?? activeBundle?.bundleVersion, expiresAt: update.expiresAt ?? activeBundle?.expiresAt ?? new Date(now() + 60000).toISOString() }); if (event.type === 'routing.drain' || event.type === 'routing.recovery') for (const pool of [primaryPool, balancedPool].filter(Boolean)) (event.type === 'routing.drain' ? pool.drain : pool.recover)(event.node, drainTimeoutMs); }); await stream.connect(); return () => stream.close?.(); },
+    drain(host, timeoutMs = drainTimeoutMs) { const pools = [primaryPool, balancedPool].filter(Boolean); pools.forEach((pool) => pool.drain(host, timeoutMs)); return { host, timeoutMs, wait: () => Promise.all(pools.map((pool) => pool.waitForIdle(timeoutMs))), forceClose: () => Promise.all(pools.map((pool) => pool.forceClose(host))) }; },
+    nodeStates() { return [primaryPool, balancedPool].filter(Boolean).flatMap((pool) => pool.nodes.map((node) => ({ host: node.host, port: node.port, route: pool === primaryPool ? 'primary' : 'balanced', state: node.state, active: node.active, available: node.available }))); },
     setNodeAvailability(route, host, available) { const pool = route === 'balanced' ? balancedPool : primaryPool; pool?.setAvailability(host, available); },
     bundle: () => activeBundle,
     async close() { await Promise.all([primaryPool.close(), balancedPool?.close()]); },

package/src/index.d.ts

@@ -36,6 +36,8 @@ export interface DbClient {
   classify(sql: string): 'primary' | 'balanced';
   attachRoutingStream(stream: RoutingStream): Promise<() => void>;
   setNodeAvailability(route: 'primary' | 'balanced', host: string, available: boolean): void;
+  drain(host: string, timeoutMs?: number): { host: string; timeoutMs: number; wait(): Promise<unknown[]>; forceClose(): Promise<unknown[]> };
+  nodeStates(): Array<{ host: string; port: number; route: 'primary' | 'balanced'; state: 'ready' | 'draining' | 'unavailable' | 'recovering'; active: number; available: boolean }>;
   config: { primary: ConnectionProfile; balanced?: ConnectionProfile };
 }
 
@@ -46,7 +48,7 @@ export interface RoutingStream {
   state(): { connected: boolean; mode: 'websocket' | 'rest' | 'disconnected'; expectedVersion: number };
 }
 
-export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; now?: () => number }): Promise<DbClient>;
+export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number }): Promise<DbClient>;
 export function createDbFromEnvironment(options?: { env?: Record<string, string | undefined>; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string }): Promise<DbClient>;
 export function classifyQuery(sql: unknown): 'primary' | 'balanced';
 export function routeFor(sql: unknown, requested?: 'auto' | 'primary' | 'balanced'): 'primary' | 'balanced';
@@ -61,7 +63,7 @@ export function bundleNeedsRefresh(bundle: RoutingBundle, now?: number): boolean
 export function createAdminSql(options: { query: QueryFunction }): { transaction<T>(work: (context: { query: QueryFunction }) => Promise<T>): Promise<T>; migration(statements?: string[]): Promise<unknown> };
 export function createMigrationRunner(options: { query: QueryFunction; migrations?: Array<{ version: number; name: string; statements: string[] }> }): { status(): Promise<{ applied: unknown[] }>; migrate(): Promise<unknown> };
 export function selectRouteNodes(options: { bundle: RoutingBundle; route?: 'primary' | 'balanced'; now?: number }): RoutingNode[];
-export function createRoutingStream(options: { endpoint: string; token?: string; application?: string; fetchBundle: (application: string) => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number }): RoutingStream;
+export function createRoutingStream(options: { endpoint: string; token?: string; application?: string; fetchBundle: (application: string) => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number }): RoutingStream;
 export function createQuiesceController(options?: { close?: () => Promise<void>; onChange?: (state: string) => void }): { state(): { state: string; active: number }; enter(): () => void; begin(): Promise<void>; end(): Promise<void>; close(): Promise<void> };
 export function createSqlVerifier(options: { query: QueryFunction }): { connectivity(): Promise<{ verified: boolean }>; schema(database: string): Promise<{ database: string; verified: boolean }>; account(user: string, host?: string): Promise<{ user: string; host: string; verified: boolean; grants: string[] }>; all(options?: { database?: string; user?: string; host?: string }): Promise<unknown> };
 export function createMaterializer(options?: Record<string, unknown>): unknown;

package/src/pools/node-pool.mjs

@@ -6,11 +6,18 @@ export function createNodePool({ profile, mysqlLib, log, now = () => Date.now(),
   const pool = mysqlLib.createPool({ host: profile.host, port: profile.port, user: profile.user, password: profile.password, database: profile.database, waitForConnections: true, ...driverOptions });
   const sessionStatements = profile.options?.sessionStatements ?? [];
   const withConnection = async (operation, sql, values) => { const connection = await pool.getConnection(); try { for (const statement of sessionStatements) await connection.query(statement); return operation(connection, sql, values); } finally { connection.release(); } };
-  let failures = 0; let unavailableUntil = 0; let forcedUnavailable = false;
-  return { host: profile.host, port: profile.port, weight: Number(profile.weight ?? 100), get available() { return !forcedUnavailable && now() >= unavailableUntil; }, set available(value) { forcedUnavailable = !value; if (value) unavailableUntil = 0; else unavailableUntil = now() + quarantineMs; }, get failures() { return failures; },
-    async query(sql, values) { try { const result = sessionStatements.length ? await withConnection((connection, statement, params) => connection.query(statement, params), sql, values) : await pool.query(sql, values); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; log?.warn?.('SQL node quarantined', { host: profile.host, port: profile.port, error: error.message }); } throw asSqlError(error); } },
-    async execute(sql, values) { try { const result = sessionStatements.length ? await withConnection((connection, statement, params) => connection.execute(statement, params), sql, values) : await pool.execute(sql, values); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
-    async getConnection() { try { return await pool.getConnection(); } catch (error) { if (connectionFailure(error)) unavailableUntil = now() + quarantineMs; throw asSqlError(error); } },
+  let failures = 0; let unavailableUntil = 0; let forcedUnavailable = false; let lifecycle = 'ready'; let active = 0; let idleResolve; let drainTimer;
+  const begin = () => { active += 1; };
+  const end = () => { active = Math.max(0, active - 1); if (!active) idleResolve?.(); };
+  const run = async (work) => { begin(); try { return await work(); } finally { end(); } };
+  const drain = (timeoutMs = 45000) => { lifecycle = 'draining'; forcedUnavailable = true; unavailableUntil = Number.POSITIVE_INFINITY; clearTimeout(drainTimer); drainTimer = setTimeout(() => { void forceClose(); }, timeoutMs); drainTimer.unref?.(); return { state: lifecycle, active }; };
+  const waitForIdle = async (timeoutMs = 45000) => { if (!active) return true; await Promise.race([new Promise((resolve) => { idleResolve = resolve; }), new Promise((resolve) => setTimeout(resolve, timeoutMs))]); idleResolve = undefined; return active === 0; };
+  const forceClose = async () => { lifecycle = 'unavailable'; await pool.end(); };
+  const recover = () => { clearTimeout(drainTimer); drainTimer = undefined; lifecycle = 'recovering'; forcedUnavailable = false; unavailableUntil = 0; lifecycle = 'ready'; return lifecycle; };
+  return { host: profile.host, port: profile.port, weight: Number(profile.weight ?? 100), get available() { return lifecycle === 'ready' && !forcedUnavailable && now() >= unavailableUntil; }, set available(value) { if (value) recover(); else drain(); }, get failures() { return failures; }, get state() { return lifecycle; }, get active() { return active; }, drain, recover, waitForIdle, forceClose,
+    async query(sql, values) { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const result = await run(() => sessionStatements.length ? withConnection((connection, statement, params) => connection.query(statement, params), sql, values) : pool.query(sql, values)); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; log?.warn?.('SQL node quarantined', { host: profile.host, port: profile.port, error: error.message }); } throw asSqlError(error); } },
+    async execute(sql, values) { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const result = await run(() => sessionStatements.length ? withConnection((connection, statement, params) => connection.execute(statement, params), sql, values) : pool.execute(sql, values)); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
+    async getConnection() { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const connection = await pool.getConnection(); begin(); const release = connection.release.bind(connection); let released = false; connection.release = () => { if (released) return; released = true; end(); release(); }; return connection; } catch (error) { if (connectionFailure(error)) unavailableUntil = now() + quarantineMs; throw asSqlError(error); } },
     async health() { try { await pool.query('SELECT 1'); failures = 0; unavailableUntil = 0; return { ok: true, host: profile.host, port: profile.port }; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
-    async close() { await pool.end(); } };
+    async close() { clearTimeout(drainTimer); lifecycle = 'unavailable'; await pool.end(); } };
 }

package/src/pools/route-pool.mjs

@@ -21,6 +21,11 @@ export function createRoutePool(nodes) {
   const setAvailability = (host, available) => {
     for (const node of nodes) if (node.host === host) node.available = available;
   };
+  const lifecycle = (host, state) => nodes.filter((node) => node.host === host).map((node) => state === 'draining' ? node.drain() : node.recover());
+  const drain = (host, timeoutMs) => { for (const node of nodes.filter((value) => value.host === host)) node.drain?.(timeoutMs); return lifecycle(host, 'draining'); };
+  const recover = (host) => lifecycle(host, 'recovering');
+  const waitForIdle = (timeoutMs) => Promise.all(nodes.map((node) => node.waitForIdle?.(timeoutMs) ?? true));
+  const forceClose = (host) => Promise.all(nodes.filter((node) => !host || node.host === host).map((node) => node.forceClose?.() ?? node.close()));
   const query = (sql, values) => choose().query(sql, values);
   const execute = (sql, values) => choose().execute(sql, values);
   const health = async () => {
@@ -35,5 +40,5 @@ export function createRoutePool(nodes) {
     return results;
   };
   const close = async () => Promise.all(nodes.map((node) => node.close()));
-  return { nodes, choose, setAvailability, query, execute, health, close };
+  return { nodes, choose, setAvailability, drain, recover, waitForIdle, forceClose, query, execute, health, close };
 }

package/src/routing/stream-client.mjs

@@ -1,27 +1,28 @@
 import { log as defaultLog } from '@eliware/common';
 
-export function createRoutingStream({ endpoint, token, application = 'default', fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, now = () => Date.now() } = {}) {
+export function createRoutingStream({ endpoint, token, application = 'default', fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, heartbeatMs = 45000, now = () => Date.now() } = {}) {
   if (!endpoint || typeof fetchBundle !== 'function') throw new TypeError('endpoint and fetchBundle are required');
-  let socket; let closed = false; let timer; let expectedVersion = 0; let delay = reconnectMs; let updateHandler = onUpdate; let mode = 'disconnected';
+  let socket; let closed = false; let timer; let heartbeat; let expectedVersion = 0; let delay = reconnectMs; let updateHandler = onUpdate; let mode = 'disconnected';
   const log = arguments[0]?.log ?? defaultLog;
   const streamUrl = () => `${endpoint.replace(/^http/i, 'ws').replace(/\/$/, '')}/api/v1/routing/stream?application=${encodeURIComponent(application)}&token=${encodeURIComponent(token ?? '')}`;
-  async function fallback() { try { const bundle = await fetchBundle(application); if (closed) return; mode = 'rest'; onUpdate?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { if (closed) return; mode = 'disconnected'; onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
+  async function fallback() { try { const bundle = await fetchBundle(application); if (closed) return; mode = 'rest'; updateHandler?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { if (closed) return; mode = 'disconnected'; onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
   function schedule() { if (closed || timer) return; timer = setTimeout(() => { timer = undefined; void connect(); }, delay); delay = Math.min(maxReconnectMs, delay * 2); }
   async function connect() {
     if (closed || typeof WebSocketImpl !== 'function') { await fallback(); schedule(); return; }
     try {
       socket = new WebSocketImpl(streamUrl());
-      socket.onopen = () => { mode = 'websocket'; delay = reconnectMs; };
+      socket.onopen = () => { mode = 'websocket'; delay = reconnectMs; heartbeat = setInterval(() => socket?.send?.(JSON.stringify({ type: 'heartbeat', sentAt: now() })), heartbeatMs); };
       socket.onmessage = async ({ data }) => {
         try {
           const event = JSON.parse(data); const version = Number(event.version ?? 0);
+          if (version && expectedVersion && version <= expectedVersion) return;
           if (expectedVersion && version > expectedVersion + 1) await fallback();
           expectedVersion = Math.max(expectedVersion, version); updateHandler?.(event);
         } catch (error) { onError?.(error); }
       };
       socket.onerror = (error) => { onError?.(error); };
-      socket.onclose = () => { socket = undefined; mode = 'disconnected'; if (!closed) { void fallback(); schedule(); } };
+      socket.onclose = () => { clearInterval(heartbeat); heartbeat = undefined; socket = undefined; mode = 'disconnected'; if (!closed) { void fallback(); schedule(); } };
     } catch (error) { mode = 'disconnected'; onError?.(error); await fallback(); schedule(); }
   }
-  return { connect, setOnUpdate: (handler) => { updateHandler = handler; }, close: () => { closed = true; mode = 'disconnected'; clearTimeout(timer); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, mode, expectedVersion }) };
+  return { connect, setOnUpdate: (handler) => { updateHandler = handler; }, close: () => { closed = true; mode = 'disconnected'; clearTimeout(timer); clearInterval(heartbeat); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, mode, expectedVersion }) };
 }