@eliware/elera-lib 0.1.7 → 0.1.9

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.7 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.9 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged. The current package version is
-0.1.7.
+0.1.9.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
 path. Both may accept writes; automatic routing sends only conservative,
@@ -58,6 +58,14 @@ 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. A single-node route fails with the exported
+`ServerUnavailableError` using code `SERVER_UNAVAILABLE`; a multi-node route
+with no eligible candidates fails with `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`. If the event
@@ -88,11 +96,12 @@ contents. The stream reports `websocket`, `rest`, or `disconnected` mode so
 callers can observe transport health without implementing transport policy.
 
 Applications may opt into generic in-memory telemetry with
-`createDb({ ..., telemetry: true })`. Query counts, failures, retries,
-in-flight work, and latency are exposed through `client.telemetry` and sent
-over an attached routing stream once per second. Telemetry is observational
-only; it does not carry SQL or credentials. Reconnect, failover, and cumulative
-reconnect-delay counters are included in the telemetry snapshot.
+`createDb({ ..., telemetry: true })`. Query, execute, and transaction counts,
+failures, retries, in-flight work, and latency are exposed through
+`client.telemetry` and sent over an attached routing stream once per second.
+Telemetry is observational only; it does not carry SQL or credentials.
+Reconnect, failover, and cumulative reconnect-delay counters are included in
+the telemetry snapshot.
 
 `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,34 @@
 # Release notes
 
+## 0.1.9 — Standalone outage classification and complete operation telemetry
+
+### Added
+
+- Exposes `ServerUnavailableError` with the stable `SERVER_UNAVAILABLE` code when a standalone SQL route has no eligible server.
+- Keeps multi-node route exhaustion classified as `CLUSTER_UNAVAILABLE`.
+- Records telemetry for `execute()` and transaction operations alongside query latency and failure metrics.
+
+### Validation
+
+- Adds regression coverage for standalone drain classification and operation telemetry.
+- Maintains 100% statements, branches, functions, and lines coverage with zero lint warnings.
+
+## 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

package/package.json

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

package/src/client/create-db.mjs

@@ -32,12 +32,13 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
   const timed = createTimedOperation({ metrics, now });
   const client = {
     async query(sql, values, options) { return timed(async () => { 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') { metrics?.record?.({ retry: true }); 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 execute(sql, values, options) { return timed(async () => choose(sql, options).execute(sql, values)); },
+    async transaction(callback) { return timed(async () => { 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,20 @@ 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 class ServerUnavailableError extends SqlClientError {
+  constructor(message = 'The SQL server is unavailable', options = {}) {
+    super(message, { code: 'SERVER_UNAVAILABLE', retryable: false, ...options });
+    this.name = 'ServerUnavailableError';
+  }
+}
+
 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 };
@@ -67,6 +68,8 @@ 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 class ServerUnavailableError 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,7 +3,7 @@ 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, ServerUnavailableError, classifyError, asSqlError } from './errors.mjs';
 export { validateBundle, bundleExpired, bundleNeedsRefresh } from './bundle.mjs';
 export { createAdminSql } from './admin/sql.mjs';
 export { createMigrationRunner } from './admin/migrations.mjs';

package/src/pools/route-pool.mjs

@@ -1,9 +1,11 @@
-export function createRoutePool(nodes, { preferred = false } = {}) {
+import { ClusterUnavailableError, ServerUnavailableError } from '../errors.mjs';
+
+export function createRoutePool(nodes, { preferred = false, unavailableError = nodes.length === 1 ? ServerUnavailableError : ClusterUnavailableError } = {}) {
   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 unavailableError('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];