@eliware/elera-lib 0.1.3 → 0.1.4

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.3 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.4 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
@@ -26,12 +26,17 @@ accounts. Pool settings may be supplied with `MYSQL_CONNECT_TIMEOUT`,
 `MYSQL_SSL`. Configure primary and balanced routes explicitly; applications
 should not rely on ambiguous single-endpoint aliases.
 
+See examples/basic-client.mjs for a complete consumer example using only the
+public package API. Its usage notes are in examples/README.md.
+
 Routing bundles passed to `createDbFromBundle` use the normalized shape
 `routes.primary` and `routes.balanced`, each containing ordered `{ host, port,
-weight }` nodes. A bundle also carries `database`, `identity`, optional
-`credentials`, and `expiresAt`; `validateBundle` rejects expired or malformed
-route data. The checked-in contract fixture documents the supervisor-facing
-wire representation separately.
+weight }` nodes. A bundle may also carry an explicit `writer`, ordered
+`failover`, and `readers` assignment. The bundle carries `database`,
+`identity`, optional `credentials`, and `expiresAt`; `validateBundle` rejects
+expired, malformed, duplicated, or conflicting route data. The checked-in
+contract fixture documents the supervisor-facing wire representation
+separately.
 
 The implementation accepts optional routing bundles and injected credential
 providers, maintains bounded pools per route, supports ordered writer/reader
@@ -44,13 +49,13 @@ 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.
+to that node while existing operations continue. The drain window defaults to
+45 seconds and is capped at 45 seconds; 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

package/RELEASE_NOTES.md

@@ -1,5 +1,42 @@
 # Release notes
 
+## 0.1.4 — Explicit writer and failover routing
+
+This release strengthens generic client-side routing for supervisor-provided
+bundles. Applications still use the public library API; supervisor and CLI
+policy remain outside the package.
+
+### Added
+
+- Supports explicit `writer`, ordered `failover`, and `readers` assignments in
+  routing bundles.
+- Replaces active writer and reader pools immediately when a valid routing
+  update arrives through WebSocket or REST resynchronization.
+- Keeps application clients independent so updating one application's bundle
+  does not change another client's assignment.
+- Selects the writer first and fails over in the supplied order when a node is
+  drained or explicitly unavailable.
+- Completes in-flight work during drain while excluding the node from new work.
+- Enforces a 45-second maximum client-side drain window.
+
+### Fixed and hardened
+
+- Compares numeric and string bundle versions numerically and rejects stale
+  updates, including versions such as `v10` versus `v9`.
+- Validates routing hosts, ports, weights, duplicate nodes, and writer/failover
+  overlap before pool creation.
+- Preserves explicit writer, failover, and reader assignments during stream
+  refreshes.
+
+### Validation
+
+- Adds integration-style coverage for pool replacement, per-client assignment
+  isolation, writer failover, in-flight drain behavior, version ordering,
+  WebSocket reconnect, and REST fallback.
+- Maintains 100% statements, branches, functions, and lines coverage with zero
+  lint warnings.
+- Diff validation passes.
+
 ## 0.1.3 — Client-side routing drain lifecycle
 
 This patch adds generic client-side handling for supervisor-published routing

package/examples/README.md

@@ -0,0 +1,13 @@
+# Elera library example
+
+basic-client.mjs is a minimal consumer application. It imports only the
+public @eliware/elera-lib package API, opens a bounded SQL client from
+environment configuration, performs a health check and query, and closes the
+client in a finally block.
+
+Run it from a published-package consumer project with:
+
+    MYSQL_PRIMARY_HOST=127.0.0.1 MYSQL_USER=app MYSQL_PASSWORD=secret MYSQL_DATABASE=app node examples/basic-client.mjs
+
+The example is intentionally infrastructure-neutral. It does not contain
+Docker, Kubernetes, Supervisor, CLI, Galera, or test-lab setup.

package/examples/basic-client.mjs

@@ -0,0 +1,14 @@
+import { createDbFromEnvironment } from '@eliware/elera-lib';
+
+// Set MYSQL_PRIMARY_HOST, MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DATABASE
+// before running this example. The same public API works with a routing bundle.
+const db = await createDbFromEnvironment();
+
+try {
+  const health = await db.health('primary');
+  if (!health.ok) throw new Error('primary SQL route is not healthy');
+  const [rows] = await db.query('SELECT 1 AS healthy');
+  console.log(JSON.stringify({ health, rows }));
+} finally {
+  await db.close();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.3",
+    "version": "0.1.4",
     "description": "Generic MySQL and MariaDB client with resilient routing, client-side drains, and failover",
     "keywords": [
         "eliware",
@@ -35,6 +35,7 @@
     },
     "files": [
         "src",
+        "examples",
         "README.md",
         "RELEASE_NOTES.md",
         "LICENSE",

package/src/bundle.mjs

@@ -1,13 +1,17 @@
+import { validateRoutingNode, validateRoutingNodes } from './routing/node-validation.mjs';
 const routes = ['primary', 'balanced'];
 
 export function validateBundle(bundle) {
   if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
   if (!bundle.expiresAt || Number.isNaN(Date.parse(bundle.expiresAt))) throw new TypeError('routing bundle expiresAt is required');
+  const writer = bundle.writer !== undefined ? validateRoutingNode(bundle.writer, 'routing bundle writer') : undefined;
+  const failover = bundle.failover !== undefined ? validateRoutingNodes(bundle.failover, 'routing bundle failover') : [];
+  if (writer && failover.some((node) => node.host === writer.host && node.port === writer.port)) throw new TypeError('routing bundle failover duplicates writer');
+  if (bundle.readers !== undefined) validateRoutingNodes(bundle.readers, 'routing bundle readers');
   for (const route of routes) {
     if (bundle.routes?.[route] !== undefined && !Array.isArray(bundle.routes[route])) throw new TypeError(`bundle.routes.${route} must be an array`);
     for (const node of bundle.routes?.[route] ?? []) {
-      if (!node.host || !Number.isInteger(Number(node.port)) || Number(node.port) < 1 || Number(node.port) > 65535) throw new TypeError(`invalid ${route} bundle node`);
-      if (node.weight !== undefined && (!Number.isFinite(Number(node.weight)) || Number(node.weight) < 0)) throw new TypeError(`invalid ${route} bundle weight`);
+      validateRoutingNode(node, `routing bundle ${route} node`);
     }
   }
   return bundle;

package/src/client/bundle-profiles.mjs

@@ -0,0 +1,7 @@
+import { validateRoutingNode } from '../routing/node-validation.mjs';
+
+export function bundleProfiles(bundle, route, base) {
+  if (route === 'primary' && bundle.writer?.host) return [bundle.writer, ...(bundle.failover ?? [])].map((node, index) => { const valid = validateRoutingNode(node, `primary assignment[${index}]`); return { ...base, host: valid.host, port: valid.port, weight: valid.weight }; });
+  const nodes = route === 'balanced' && bundle.readers?.length ? bundle.readers : bundle.routes?.[route] ?? [];
+  return nodes.map((node) => { const valid = validateRoutingNode(node, `${route} route node`); return { ...base, host: valid.host, port: valid.port, weight: valid.weight }; });
+}

package/src/client/create-db.mjs

@@ -6,11 +6,10 @@ import { resolveCredentials, credentialContext } from '../credential-provider.mj
 import { validateBundle, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs';
 import { createRouteFactory } from './route-factory.mjs';
 import { classifyQuery, routeFor } from '../routing.mjs';
+import { compareBundleVersions } from '../routing/bundle-version.mjs';
+import { clientDrainTimeout } from '../lifecycle/drain-policy.mjs';
 
-const olderVersion = (candidate, current) => {
-  if (candidate === undefined || current === undefined) return false;
-  return String(candidate) < String(current);
-};
+const olderVersion = (candidate, current) => compareBundleVersions(candidate, current) < 0;
 
 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');
@@ -32,9 +31,9 @@ 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 }; 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))) }; },
+    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'); 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.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 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))) }; },
     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/client/route-factory.mjs

@@ -1,10 +1,6 @@
 import { bundleExpired } from '../bundle.mjs';
 import { createNodePool, createRoutePool } from '../pools.mjs';
-
-const bundleProfiles = (bundle, route, base) => {
-  const routes = bundle.routes?.[route] ?? [];
-  return routes.map((node) => ({ ...base, host: node.host, port: node.port, weight: node.weight }));
-};
+import { bundleProfiles } from './bundle-profiles.mjs';
 
 const routeProfiles = (bundle, route, fallback, now) => {
   if (!bundle) return [fallback];
@@ -14,5 +10,5 @@ const routeProfiles = (bundle, route, fallback, now) => {
 };
 
 export function createRouteFactory({ bundle, now, mysqlLib, log, quarantineMs }) {
-  return (route, fallback) => createRoutePool(routeProfiles(bundle, route, fallback, now).map((profile) => createNodePool({ profile, mysqlLib, log, now, quarantineMs })));
+  return (route, fallback) => createRoutePool(routeProfiles(bundle, route, fallback, now).map((profile) => createNodePool({ profile, mysqlLib, log, now, quarantineMs })), { preferred: route === 'primary' });
 }

package/src/index.d.ts

@@ -10,6 +10,7 @@ export interface ConnectionProfile {
 }
 
 export interface RoutingNode { host: string; port: number | string; weight?: number; }
+export interface WriterAssignment { host: string; port: number | string; }
 export interface RoutingBundle {
   apiVersion?: string;
   database?: string;
@@ -19,6 +20,9 @@ export interface RoutingBundle {
   expiresAt: string;
   refreshAfter?: string;
   routes: { primary?: RoutingNode[]; balanced?: RoutingNode[] };
+  writer?: WriterAssignment;
+  failover?: WriterAssignment[];
+  readers?: WriterAssignment[];
 }
 export interface CredentialProviderResult { user: string; password: string; }
 export type CredentialProvider = (context: { database: string; identity: string | null; route: string }) => Promise<CredentialProviderResult> | CredentialProviderResult;
@@ -45,7 +49,7 @@ export interface RoutingStream {
   connect(): Promise<void>;
   setOnUpdate(handler: (event: unknown) => void | Promise<void>): void;
   close(): void;
-  state(): { connected: boolean; mode: 'websocket' | 'rest' | 'disconnected'; expectedVersion: number };
+  state(): { connected: boolean; mode: 'websocket' | 'rest' | 'disconnected'; expectedVersion: number | string };
 }
 
 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>;
@@ -64,6 +68,11 @@ export function createAdminSql(options: { query: QueryFunction }): { transaction
 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; heartbeatMs?: number }): RoutingStream;
+export function writerAssignment(bundle: RoutingBundle): WriterAssignment;
+export function failoverNodes(bundle: RoutingBundle): WriterAssignment[];
+export function compareBundleVersions(left: number | string | undefined, right: number | string | undefined): number;
+export const CLIENT_DRAIN_TIMEOUT_MS: 45000;
+export function clientDrainTimeout(timeoutMs?: number): number;
 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/index.mjs

@@ -9,6 +9,9 @@ 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 { writerAssignment, failoverNodes } from './routing/assignment.mjs';
+export { compareBundleVersions } from './routing/bundle-version.mjs';
+export { CLIENT_DRAIN_TIMEOUT_MS, clientDrainTimeout } from './lifecycle/drain-policy.mjs';
 export { createQuiesceController } from './lifecycle/quiesce.mjs';
 export { createSqlVerifier } from './verification/sql.mjs';
 export { createMaterializer } from './lifecycle/materializer.mjs';

package/src/lifecycle/drain-policy.mjs

@@ -0,0 +1,7 @@
+export const CLIENT_DRAIN_TIMEOUT_MS = 45000;
+
+export function clientDrainTimeout(timeoutMs = CLIENT_DRAIN_TIMEOUT_MS) {
+  const requested = Number(timeoutMs);
+  if (!Number.isFinite(requested) || requested < 0) throw new TypeError('drain timeout must be a non-negative number');
+  return Math.min(requested, CLIENT_DRAIN_TIMEOUT_MS);
+}

package/src/pools/route-pool.mjs

@@ -1,9 +1,10 @@
-export function createRoutePool(nodes) {
+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 (preferred) return available[0];
     const total = available.reduce((sum, node) => sum + Math.max(0, node.weight), 0);
     if (!total) return available[cursor++ % available.length];
     let target = cursor++ % total;

package/src/routing/assignment.mjs

@@ -0,0 +1,9 @@
+export function writerAssignment(bundle) {
+  if (!bundle?.writer?.host) throw new TypeError('routing bundle writer is required');
+  return { host: bundle.writer.host, port: Number(bundle.writer.port ?? 3306) };
+}
+
+export function failoverNodes(bundle) {
+  if (!Array.isArray(bundle?.failover)) throw new TypeError('routing bundle failover is required');
+  return bundle.failover.map(({ host, port = 3306 }) => ({ host, port: Number(port) }));
+}

package/src/routing/bundle-version.mjs

@@ -0,0 +1,11 @@
+export function compareBundleVersions(left, right) {
+  if (left === undefined || right === undefined) return 0;
+  const a = String(left).match(/\d+/g)?.map(Number);
+  const b = String(right).match(/\d+/g)?.map(Number);
+  if (!a || !b) return String(left).localeCompare(String(right));
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference) return Math.sign(difference);
+  }
+  return 0;
+}

package/src/routing/node-validation.mjs

@@ -0,0 +1,14 @@
+export function validateRoutingNode(node, name = 'routing node') {
+  if (!node || typeof node !== 'object' || typeof node.host !== 'string' || node.host.trim() === '') throw new TypeError(`${name} host is required`);
+  const port = Number(node.port ?? 3306);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new TypeError(`${name} port is invalid`);
+  if (node.weight !== undefined && (!Number.isFinite(Number(node.weight)) || Number(node.weight) < 0)) throw new TypeError(`${name} weight is invalid`);
+  return { ...node, host: node.host.trim(), port };
+}
+
+export function validateRoutingNodes(nodes, name) {
+  if (!Array.isArray(nodes)) throw new TypeError(`${name} must be an array`);
+  const validated = nodes.map((node, index) => validateRoutingNode(node, `${name}[${index}]`));
+  if (new Set(validated.map(({ host, port }) => `${host}:${port}`)).size !== validated.length) throw new TypeError(`${name} contains duplicate nodes`);
+  return validated;
+}

package/src/routing/stream-client.mjs

@@ -1,4 +1,5 @@
 import { log as defaultLog } from '@eliware/common';
+import { compareBundleVersions } from './bundle-version.mjs';
 
 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');
@@ -14,10 +15,12 @@ export function createRoutingStream({ endpoint, token, application = 'default',
       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);
+          const event = JSON.parse(data); const version = event.version;
+          if (version !== undefined && expectedVersion !== 0 && compareBundleVersions(version, expectedVersion) <= 0) return;
+          const numericVersion = Number(version); const numericExpected = Number(expectedVersion);
+          if (Number.isInteger(numericVersion) && Number.isInteger(numericExpected) && numericExpected > 0 && numericVersion > numericExpected + 1) await fallback();
+          if (version !== undefined && (expectedVersion === 0 || compareBundleVersions(version, expectedVersion) > 0)) expectedVersion = version;
+          updateHandler?.(event);
         } catch (error) { onError?.(error); }
       };
       socket.onerror = (error) => { onError?.(error); };