@eliware/elera-lib 0.1.6 → 0.1.7

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.7 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged. The current package version is
-0.1.6.
+0.1.7.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
 path. Both may accept writes; automatic routing sends only conservative,
@@ -60,12 +60,21 @@ automatically.
 
 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,27 @@
 # Release notes
 
+## 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 +40,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.7",
     "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
     "keywords": [
         "eliware",

package/src/index.d.ts

@@ -54,9 +54,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';

package/src/index.mjs

@@ -9,6 +9,7 @@ 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/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 }) };
 }