@eliware/elera-lib 0.1.6 → 0.1.8

package/README.md

@@ -2,9 +2,9 @@
 
 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.6 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.8 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged. The current package version is
-0.1.6.
+0.1.8.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
 path. Both may accept writes; automatic routing sends only conservative,
@@ -58,14 +58,29 @@ state. Only conservative, single-statement reads are eligible for automatic
 retry after a connection failure; uncertain writes are never retried
 automatically.
 
+`client.availability()` reports whether a primary route is usable. It returns
+`state: 'cluster-unavailable'` when every primary candidate is draining or
+unavailable; the `routes` fields report primary and balanced availability
+independently. New operations in that state fail with the exported
+`ClusterUnavailableError` using code `CLUSTER_UNAVAILABLE`.
+
 When an attached routing stream receives a `routing.shutdown` event, the
 client drains the identified node, performs a REST bundle resynchronization,
-and closes the retiring WebSocket with restart code `1012`. It then reconnects
-through the configured endpoint, which should normally be the application's
-load-balancer address. Reconnects, failovers, and measured reconnect delay are
-included in telemetry. If the WebSocket remains unavailable, REST
-resynchronization and bounded reconnect backoff continue until the caller
-closes the stream.
+and closes the retiring WebSocket with restart code `1012`. If the event
+contains `loadBalancerEndpoint`, that endpoint replaces the current endpoint
+before resynchronization and reconnect. `reconnectDeadlineMs` bounds the
+planned reconnect window; after it expires, no new reconnect is scheduled.
+Reconnects, failovers, and measured reconnect delay are included in telemetry.
+If the WebSocket remains unavailable before the deadline, REST
+resynchronization and bounded reconnect backoff continue until the deadline or
+until the caller closes the stream.
+
+Routing events are validated before application. Shutdown events may include
+`node`, `reason`, `reconnect`, `reconnectDeadlineMs`, and
+`loadBalancerEndpoint`; invalid event fields are reported through `onError` and
+do not change routing state. `routing.update` replaces the writer and reader
+pools atomically, while `routing.drain` excludes only the named node from new
+work and allows active operations to finish.
 
 The public client intentionally exposes SQL operations, health, routing,
 lifecycle, and optional routing-event synchronization methods. REST and

package/RELEASE_NOTES.md

@@ -1,5 +1,43 @@
 # Release notes
 
+## 0.1.8 — Explicit outage state and recovery observability
+
+### Added
+
+- Exposes `ClusterUnavailableError` with the stable `CLUSTER_UNAVAILABLE` code
+  when no eligible SQL node can serve a route.
+- Adds `DbClient.availability()` so applications can distinguish an available
+  client from a fully unavailable primary route, including per-route status.
+- Covers standalone node drain, total primary-route outage, and route recovery.
+- Updates the TypeScript declarations for the new runtime API and error type.
+
+### Validation
+
+- Maintains 100% statements, branches, functions, and lines coverage.
+- Tests and TypeScript typechecking pass with zero lint warnings.
+
+## 0.1.7 — Routing shutdown contract completion
+
+### Added
+
+- Validates supervisor routing-control events before applying them.
+- Supports node-specific shutdown events so only the retiring SQL node is
+  drained by the client.
+- Honors an optional `loadBalancerEndpoint` supplied during shutdown before
+  REST resynchronization and WebSocket reconnect.
+- Honors `reconnectDeadlineMs` and stops scheduling reconnect attempts after
+  the deadline expires.
+- Exposes the active endpoint and reconnect deadline in routing-stream state.
+- Publishes typed routing-event declarations for TypeScript consumers.
+
+### Validation
+
+- Adds regression coverage for node-specific shutdown draining, endpoint
+  replacement, deadline expiry, malformed events, and reconnect behavior.
+- Maintains 100% statements, branches, functions, and lines coverage with
+  zero lint warnings.
+- Typecheck and diff validation pass.
+
 ## 0.1.6 — Graceful routing shutdown handoff
 
 ### Added
@@ -18,7 +56,8 @@
 
 ### Validation
 
-- 24 test suites pass with 116 tests.
+- The complete test suite passes with 100% statements, branches, functions,
+  and lines coverage.
 - Syntax and diff validation pass.
 
 ## 0.1.5 — Telemetry and convention alignment

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.6",
+    "version": "0.1.8",
     "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
     "keywords": [
         "eliware",

package/src/client/create-db.mjs

@@ -35,9 +35,10 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
     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'); 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 }; const writer = candidate.writer ?? candidate.routes.primary?.[0]; const reader = candidate.readers?.[0] ?? candidate.routes.balanced?.[0]; primaryConfig = validateProfile({ ...primaryConfig, host: writer?.host, port: writer?.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); balancedConfig = reader ? validateProfile({ ...primaryConfig, host: reader.host, port: reader.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 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 }; const writer = candidate.writer ?? candidate.routes.primary?.[0]; const reader = candidate.readers?.[0] ?? candidate.routes.balanced?.[0]; primaryConfig = validateProfile({ ...primaryConfig, host: writer.host, port: writer.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); balancedConfig = reader ? validateProfile({ ...primaryConfig, host: reader.host, port: reader.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'); metrics?.start?.(stream); stream.setTelemetry?.(metrics); stream.setOnUpdate?.(async (event) => { const update = event.type === 'routing.update' ? event : event.type === 'routing.resync' ? event.bundle : undefined; if (update && (update.writer || update.routes?.primary?.length)) await client.refresh({ ...activeBundle, ...update, database: update.database ?? activeBundle?.database ?? primaryConfig.database, credentials: update.credentials ?? activeBundle?.credentials, routes: update.routes ?? activeBundle?.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.shutdown') for (const pool of [primaryPool, balancedPool].filter(Boolean)) (event.type === 'routing.drain' ? pool.drain : pool.drain)(event.node, drainTimeoutMs); if (event.type === 'routing.recovery') for (const pool of [primaryPool, balancedPool].filter(Boolean)) pool.recover(event.node, drainTimeoutMs); }); await stream.connect(); return () => stream.close?.(); },
     drain(host, timeoutMs = drainTimeoutMs) { const effectiveTimeout = clientDrainTimeout(timeoutMs); const pools = [primaryPool, balancedPool].filter(Boolean); pools.forEach((pool) => pool.drain(host, effectiveTimeout)); return { host, timeoutMs: effectiveTimeout, wait: () => Promise.all(pools.map((pool) => pool.waitForIdle(effectiveTimeout))), forceClose: () => Promise.all(pools.map((pool) => pool.forceClose(host))) }; },
+    availability() { const states = this.nodeStates(); const primaryAvailable = states.some((node) => node.route === 'primary' && node.available); return { state: primaryAvailable ? 'available' : 'cluster-unavailable', routes: { primary: primaryAvailable, balanced: states.some((node) => node.route === 'balanced' && node.available) } }; },
     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,

package/src/errors.mjs

@@ -4,6 +4,13 @@ export class SqlClientError extends Error {
   }
 }
 
+export class ClusterUnavailableError extends SqlClientError {
+  constructor(message = 'No eligible SQL nodes are available', options = {}) {
+    super(message, { code: 'CLUSTER_UNAVAILABLE', retryable: false, ...options });
+    this.name = 'ClusterUnavailableError';
+  }
+}
+
 export function classifyError(error) {
   const code = error?.code;
   if (['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'PROTOCOL_CONNECTION_LOST', 'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR'].includes(code)) return { code: 'CONNECTION_ERROR', retryable: true };

package/src/index.d.ts

@@ -42,6 +42,7 @@ export interface DbClient {
   classify(sql: string): 'primary' | 'balanced';
   attachRoutingStream(stream: RoutingStream): Promise<() => void>;
   setNodeAvailability(route: 'primary' | 'balanced', host: string, available: boolean): void;
+  availability(): { state: 'available' | 'cluster-unavailable'; routes: { primary: boolean; balanced: boolean } };
   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 };
@@ -54,9 +55,12 @@ export interface RoutingStream {
   close(): void;
   sendTelemetry(payload: unknown): void;
   setTelemetry?(telemetry?: Pick<Telemetry, 'recordReconnect'>): void;
-  state(): { connected: boolean; mode: 'websocket' | 'rest' | 'disconnected'; expectedVersion: number | string };
+  state(): { connected: boolean; mode: 'websocket' | 'rest' | 'disconnected'; expectedVersion: number | string; endpoint: string; reconnectDeadlineAt?: number };
 }
 
+export type RoutingEvent = { type: 'routing.update' | 'routing.resync' | 'routing.drain' | 'routing.recovery'; node?: string; version?: number | string; [key: string]: unknown } | { type: 'routing.shutdown'; node?: string; reason?: string; reconnect?: boolean; reconnectDeadlineMs?: number; loadBalancerEndpoint?: string };
+export function validateRoutingEvent(event: unknown): RoutingEvent;
+
 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; telemetry?: true | Telemetry }): 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; telemetry?: true | Telemetry }): Promise<DbClient>;
 export function classifyQuery(sql: unknown): 'primary' | 'balanced';
@@ -64,6 +68,7 @@ export function routeFor(sql: unknown, requested?: 'auto' | 'primary' | 'balance
 export function validateProfile(profile: ConnectionProfile, name?: string): ConnectionProfile;
 export function redactedProfile(profile: ConnectionProfile): ConnectionProfile;
 export class SqlClientError extends Error { code?: string; retryable?: boolean; cause?: unknown; }
+export class ClusterUnavailableError extends SqlClientError {}
 export function classifyError(error: unknown): { retryable: boolean; code?: string };
 export function asSqlError(error: unknown): SqlClientError;
 export function validateBundle(bundle: RoutingBundle): RoutingBundle;

package/src/index.mjs

@@ -3,12 +3,13 @@ export { createDbFromBundle, profilesFromBundle } from './client/from-bundle.mjs
 export { createDbFromEnvironment } from './client/environment.mjs';
 export { classifyQuery, routeFor } from './routing.mjs';
 export { validateProfile, redactedProfile } from './config.mjs';
-export { SqlClientError, classifyError, asSqlError } from './errors.mjs';
+export { SqlClientError, ClusterUnavailableError, classifyError, asSqlError } from './errors.mjs';
 export { validateBundle, bundleExpired, bundleNeedsRefresh } from './bundle.mjs';
 export { createAdminSql } from './admin/sql.mjs';
 export { createMigrationRunner } from './admin/migrations.mjs';
 export { selectRouteNodes } from './routing/node-set.mjs';
 export { createRoutingStream } from './routing/stream-client.mjs';
+export { validateRoutingEvent } from './routing/event-contract.mjs';
 export { writerAssignment, failoverNodes } from './routing/assignment.mjs';
 export { compareBundleVersions } from './routing/bundle-version.mjs';
 export { CLIENT_DRAIN_TIMEOUT_MS, clientDrainTimeout } from './lifecycle/drain-policy.mjs';

package/src/pools/route-pool.mjs

@@ -1,9 +1,11 @@
+import { ClusterUnavailableError } from '../errors.mjs';
+
 export function createRoutePool(nodes, { preferred = false } = {}) {
   let cursor = 0;
   const candidates = () => nodes.filter((node) => node.available);
   const choose = () => {
     const available = candidates();
-    if (!available.length) throw new Error('no eligible SQL nodes available');
+    if (!available.length) throw new ClusterUnavailableError('no eligible SQL nodes available');
     if (preferred) return available[0];
     const total = available.reduce((sum, node) => sum + Math.max(0, node.weight), 0);
     if (!total) return available[cursor++ % available.length];

package/src/routing/event-contract.mjs

@@ -0,0 +1,11 @@
+const eventTypes = new Set(['routing.update', 'routing.resync', 'routing.drain', 'routing.recovery', 'routing.shutdown']);
+
+export function validateRoutingEvent(event) {
+  if (!event || typeof event !== 'object' || !eventTypes.has(event.type)) throw new TypeError('unsupported routing event');
+  if (event.type === 'routing.shutdown') {
+    if (event.node !== undefined && typeof event.node !== 'string') throw new TypeError('routing shutdown node must be a string');
+    if (event.reconnectDeadlineMs !== undefined && (!Number.isFinite(Number(event.reconnectDeadlineMs)) || Number(event.reconnectDeadlineMs) < 0)) throw new TypeError('routing shutdown deadline must be non-negative');
+    if (event.loadBalancerEndpoint !== undefined && typeof event.loadBalancerEndpoint !== 'string') throw new TypeError('routing shutdown endpoint must be a string');
+  }
+  return event;
+}

package/src/routing/stream-client.mjs

@@ -1,23 +1,26 @@
 import { log as defaultLog } from '@eliware/common';
 import { compareBundleVersions } from './bundle-version.mjs';
+import { validateRoutingEvent } from './event-contract.mjs';
 
 export function createRoutingStream({ endpoint, token, application = 'default', fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, heartbeatMs = 45000, now = () => Date.now(), telemetry } = {}) {
   if (!endpoint || typeof fetchBundle !== 'function') throw new TypeError('endpoint and fetchBundle are required');
-  let socket; let closed = false; let timer; let heartbeat; let expectedVersion = 0; let delay = reconnectMs; let updateHandler = onUpdate; let mode = 'disconnected'; let plannedReconnect = false; let lastReconnectWasPlanned = false; let disconnectedAt;
+  let socket; let closed = false; let timer; let heartbeat; let expectedVersion = 0; let delay = reconnectMs; let updateHandler = onUpdate; let mode = 'disconnected'; let plannedReconnect = false; let lastReconnectWasPlanned = false; let disconnectedAt; let reconnectDeadlineAt;
   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'; 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); }
+  function schedule() { if (closed || timer || (reconnectDeadlineAt !== undefined && now() >= reconnectDeadlineAt)) return; const wait = Math.min(delay, Math.max(0, reconnectDeadlineAt === undefined ? delay : reconnectDeadlineAt - now())); timer = setTimeout(() => { timer = undefined; void connect(); }, wait); 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'; if (disconnectedAt !== undefined) { telemetry?.recordReconnect?.({ delayMs: Math.max(0, now() - disconnectedAt), failover: lastReconnectWasPlanned }); disconnectedAt = undefined; lastReconnectWasPlanned = false; } delay = reconnectMs; heartbeat = setInterval(() => socket?.send?.(JSON.stringify({ type: 'heartbeat', sentAt: now() })), heartbeatMs); };
+      socket.onopen = () => { mode = 'websocket'; reconnectDeadlineAt = undefined; if (disconnectedAt !== undefined) { telemetry?.recordReconnect?.({ delayMs: Math.max(0, now() - disconnectedAt), failover: lastReconnectWasPlanned }); disconnectedAt = undefined; lastReconnectWasPlanned = false; } delay = reconnectMs; heartbeat = setInterval(() => socket?.send?.(JSON.stringify({ type: 'heartbeat', sentAt: now() })), heartbeatMs); };
       socket.onmessage = async ({ data }) => {
         try {
-          const event = JSON.parse(data);
+          const event = validateRoutingEvent(JSON.parse(data));
           if (event.type === 'routing.shutdown') {
             updateHandler?.(event);
+            if (typeof event.loadBalancerEndpoint === 'string' && event.loadBalancerEndpoint) endpoint = event.loadBalancerEndpoint;
+            reconnectDeadlineAt = Number.isFinite(Number(event.reconnectDeadlineMs)) ? now() + Math.max(0, Number(event.reconnectDeadlineMs)) : undefined;
             plannedReconnect = true;
             delay = reconnectMs;
             await fallback();
@@ -36,5 +39,5 @@ export function createRoutingStream({ endpoint, token, application = 'default',
       socket.onclose = () => { clearInterval(heartbeat); heartbeat = undefined; socket = undefined; mode = 'disconnected'; if (!closed) { disconnectedAt = now(); lastReconnectWasPlanned = plannedReconnect; if (!plannedReconnect) void fallback(); plannedReconnect = false; schedule(); } };
     } catch (error) { mode = 'disconnected'; onError?.(error); await fallback(); schedule(); }
   }
-  return { connect, sendTelemetry: (payload) => { if (socket?.readyState === 1) socket.send(JSON.stringify(payload)); }, setOnUpdate: (handler) => { updateHandler = handler; }, setTelemetry: (value) => { telemetry = value; }, close: () => { closed = true; mode = 'disconnected'; clearTimeout(timer); clearInterval(heartbeat); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, mode, expectedVersion }) };
+  return { connect, sendTelemetry: (payload) => { if (socket?.readyState === 1) socket.send(JSON.stringify(payload)); }, setOnUpdate: (handler) => { updateHandler = handler; }, setTelemetry: (value) => { telemetry = value; }, close: () => { closed = true; mode = 'disconnected'; clearTimeout(timer); clearInterval(heartbeat); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, mode, expectedVersion, endpoint, reconnectDeadlineAt }) };
 }