@eliware/elera-lib 0.1.0 → 0.1.1

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.0 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.1 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
@@ -19,7 +19,9 @@ await db.close();
 Environment variables: `MYSQL_PRIMARY_HOST` (or `MYSQL_HOST`),
 `MYSQL_PRIMARY_PORT` (or `MYSQL_PORT`), optional `MYSQL_BALANCED_HOST`,
 optional `MYSQL_BALANCED_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD`, and
-`MYSQL_DATABASE`. Pool settings may be supplied with `MYSQL_CONNECT_TIMEOUT`,
+`MYSQL_DATABASE`. `MYSQL_SOCKET` optionally selects a Unix-domain socket for
+the primary connection, which is useful for local socket-authenticated MariaDB
+accounts. Pool settings may be supplied with `MYSQL_CONNECT_TIMEOUT`,
 `MYSQL_ACQUIRE_TIMEOUT`, `MYSQL_CONNECTION_LIMIT`, `MYSQL_QUEUE_LIMIT`, and
 `MYSQL_SSL`. Configure primary and balanced routes explicitly; applications
 should not rely on ambiguous single-endpoint aliases.
@@ -34,8 +36,9 @@ wire representation separately.
 The implementation accepts optional routing bundles and injected credential
 providers, maintains bounded pools per route, supports ordered writer/reader
 candidates, bundle refresh, and quarantine of unhealthy nodes. The WebSocket
-routing-event transport is implemented as a generic adapter. These are generic
-client capabilities: the
+routing-event transport is implemented as a generic adapter. Nodes can be
+immediately excluded or re-admitted with `client.setNodeAvailability(route,
+host, available)`. These are generic client capabilities: the
 library does not know about supervisors, Elera, HAProxy, GitOps, backups, or
 CLI commands. Applications provide those integrations through ordinary
 configuration and callbacks.
@@ -48,7 +51,8 @@ WebSocket transports are adapters, not supervisor or CLI policy. Underlying
 For maintenance workflows, `createQuiesceController` provides a generic
 connection-admission drain and `createSqlVerifier` provides generic connectivity,
 schema, account, and grant checks. Neither API transports or orchestrates dump
-contents.
+contents. The stream reports `websocket`, `rest`, or `disconnected` mode so
+callers can observe transport health without implementing transport policy.
 
 `createMaterializer` supports bounded plaintext use for a caller-provided
 operation. It creates a mode-restricted temporary file and removes its entire

package/RELEASE_NOTES.md

@@ -1,5 +1,35 @@
 # Release notes
 
+## 0.1.1 — Runtime integration readiness
+
+This unreleased patch prepares the generic client for supervisor control-plane
+connections and application-side routing changes. It does not add supervisor,
+CLI, Galera, backup, or GitOps policy to the library.
+
+### Connection and routing lifecycle
+
+- Supports optional `MYSQL_SOCKET` Unix-domain socket connections for local
+  MariaDB control-plane use while preserving TCP configuration.
+- Adds explicit route-node availability control for immediate drain and
+  recovery exclusion without exposing pool internals.
+- Keeps manually excluded nodes unavailable until explicitly restored, rather
+  than allowing a quarantine timer to re-admit them.
+
+### Routing stream behavior
+
+- Reports whether routing updates are currently using WebSocket, REST fallback,
+  or have no usable transport.
+- Prevents late REST fallback results from changing state after stream shutdown.
+- Prevents reconnect scheduling and fallback callbacks from reviving a closed
+  stream.
+
+### Validation
+
+- Adds regression coverage for socket environment mapping, route exclusion,
+  stream shutdown, fallback state, and child lifecycle behavior.
+- Maintains 100% statements, branches, functions, and lines coverage with zero
+  lint warnings.
+
 ## 0.1.0 — Baseline release
 
 `@eliware/elera-lib` is a generic MariaDB/MySQL client library for applications

package/package.json

@@ -1,12 +1,28 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.0",
-    "description": "Eliware SQL client with primary and balanced connection routing",
-    "license": "Apache-2.0",
+    "version": "0.1.1",
+    "description": "Generic MySQL and MariaDB client with primary, balanced, and resilient routing",
+    "keywords": [
+        "eliware",
+        "elera",
+        "mysql",
+        "mariadb",
+        "sql",
+        "database",
+        "routing",
+        "failover",
+        "websocket",
+        "connection-pool"
+    ],
     "repository": {
         "type": "git",
         "url": "https://github.com/eliware/elera-lib.git"
     },
+    "homepage": "https://github.com/eliware/elera-lib#readme",
+    "bugs": {
+        "url": "https://github.com/eliware/elera-lib/issues"
+    },
+    "license": "Apache-2.0",
     "type": "module",
     "engines": {
         "node": ">=26"
@@ -48,4 +64,4 @@
     "publishConfig": {
         "access": "public"
     }
-}
+}

package/src/client/create-db.mjs

@@ -28,7 +28,8 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
     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] : []) { primaryPool.setAvailability(host, event.type === 'routing.recovery'); balancedPool?.setAvailability(host, event.type === 'routing.recovery'); } }); await stream.connect(); return () => stream.close?.(); },
+    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?.(); },
+    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()]); },
     classify: classifyQuery,

package/src/client/environment.mjs

@@ -1,7 +1,7 @@
 import { createDb } from './create-db.mjs';
 
 export async function createDbFromEnvironment({ env = process.env, ...options } = {}) {
-  const primary = { host: env.MYSQL_PRIMARY_HOST ?? env.MYSQL_HOST, port: env.MYSQL_PRIMARY_PORT ?? env.MYSQL_PORT, user: env.MYSQL_USER, password: env.MYSQL_PASSWORD, database: env.MYSQL_DATABASE, options: { connectTimeout: env.MYSQL_CONNECT_TIMEOUT, acquireTimeout: env.MYSQL_ACQUIRE_TIMEOUT, connectionLimit: env.MYSQL_CONNECTION_LIMIT, queueLimit: env.MYSQL_QUEUE_LIMIT, ssl: env.MYSQL_SSL } };
+  const primary = { host: env.MYSQL_PRIMARY_HOST ?? env.MYSQL_HOST ?? 'localhost', port: env.MYSQL_PRIMARY_PORT ?? env.MYSQL_PORT, user: env.MYSQL_USER, password: env.MYSQL_PASSWORD, database: env.MYSQL_DATABASE, options: { socket: env.MYSQL_SOCKET, connectTimeout: env.MYSQL_CONNECT_TIMEOUT, acquireTimeout: env.MYSQL_ACQUIRE_TIMEOUT, connectionLimit: env.MYSQL_CONNECTION_LIMIT, queueLimit: env.MYSQL_QUEUE_LIMIT, ssl: env.MYSQL_SSL } };
   const balanced = env.MYSQL_BALANCED_PORT ? { host: env.MYSQL_BALANCED_HOST ?? primary.host, port: env.MYSQL_BALANCED_PORT } : undefined;
   return createDb({ ...options, primary, balanced });
 }

package/src/index.d.ts

@@ -6,7 +6,7 @@ export interface ConnectionProfile {
   user?: string;
   password?: string;
   database: string;
-  options?: Partial<PoolOptions>;
+  options?: Partial<PoolOptions> & { socket?: string };
 }
 
 export interface RoutingNode { host: string; port: number | string; weight?: number; }
@@ -35,14 +35,15 @@ export interface DbClient {
   bundle(): RoutingBundle | undefined;
   classify(sql: string): 'primary' | 'balanced';
   attachRoutingStream(stream: RoutingStream): Promise<() => void>;
+  setNodeAvailability(route: 'primary' | 'balanced', host: string, available: boolean): void;
   config: { primary: ConnectionProfile; balanced?: ConnectionProfile };
 }
 
 export interface RoutingStream {
   connect(): Promise<void>;
-  setOnUpdate(handler: (event: unknown) => void): void;
+  setOnUpdate(handler: (event: unknown) => void | Promise<void>): void;
   close(): void;
-  state(): { connected: boolean; expectedVersion: number };
+  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>;

package/src/pools/node-pool.mjs

@@ -2,11 +2,12 @@ import { asSqlError } from '../errors.mjs';
 const connectionFailure = (error) => asSqlError(error).retryable;
 export function createNodePool({ profile, mysqlLib, log, now = () => Date.now(), quarantineMs = 5000 }) {
   const { acquireTimeout: _acquireTimeout, ...driverOptions } = profile.options ?? {};
+  if (driverOptions.socket === undefined) delete driverOptions.socket;
   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;
-  return { host: profile.host, port: profile.port, weight: Number(profile.weight ?? 100), get available() { return now() >= unavailableUntil; }, set available(value) { unavailableUntil = value ? 0 : now() + quarantineMs; }, get failures() { return failures; },
+  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); } },

package/src/routing/stream-client.mjs

@@ -2,16 +2,16 @@ 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() } = {}) {
   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 socket; let closed = false; let timer; 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); onUpdate?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
+  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 }); } }
   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 = () => { delay = reconnectMs; };
+      socket.onopen = () => { mode = 'websocket'; delay = reconnectMs; };
       socket.onmessage = async ({ data }) => {
         try {
           const event = JSON.parse(data); const version = Number(event.version ?? 0);
@@ -20,8 +20,8 @@ export function createRoutingStream({ endpoint, token, application = 'default',
         } catch (error) { onError?.(error); }
       };
       socket.onerror = (error) => { onError?.(error); };
-      socket.onclose = () => { socket = undefined; void fallback(); schedule(); };
-    } catch (error) { onError?.(error); await fallback(); schedule(); }
+      socket.onclose = () => { 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; clearTimeout(timer); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, expectedVersion }) };
+  return { connect, setOnUpdate: (handler) => { updateHandler = handler; }, close: () => { closed = true; mode = 'disconnected'; clearTimeout(timer); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, mode, expectedVersion }) };
 }