@eliware/elera-lib 0.1.4 → 0.1.5

package/README.md

@@ -2,8 +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.4 alternative to `@eliware/mysql`; the
-existing package is intentionally unchanged.
+backup, or GitOps policy. It is a v0.1.5 alternative to `@eliware/mysql`; the
+existing package is intentionally unchanged. The current package version is
+0.1.5.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
 path. Both may accept writes; automatic routing sends only conservative,
@@ -68,6 +69,12 @@ schema, account, and grant checks. Neither API transports or orchestrates dump
 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.
+
 `createMaterializer` supports bounded plaintext use for a caller-provided
 operation. It creates a mode-restricted temporary file and removes its entire
 temporary directory in a `finally` block; this limits lifetime and cleanup but

package/RELEASE_NOTES.md

@@ -1,5 +1,28 @@
 # Release notes
 
+## 0.1.5 — Telemetry and convention alignment
+
+### Added
+
+- Adds opt-in generic in-memory client telemetry for query counts, failures,
+  retries, in-flight work, and latency.
+- Sends telemetry over an attached routing stream once per second without
+  sending SQL text or credentials.
+- Adds public TypeScript declarations and smoke coverage for the telemetry and
+  public client surface.
+- Uses Snowflake identifiers for non-security temporary materialization paths.
+
+### Refactored
+
+- Extracts telemetry timing into a focused client module.
+- Reorganizes `create-db` tests under the mirrored `tests/client/create-db/`
+  hierarchy while retaining a small cross-cutting contract test.
+
+### Validation
+
+- Tests pass with 100% statements, branches, functions, and lines coverage.
+- TypeScript typecheck passes with zero lint warnings.
+
 ## 0.1.4 — Explicit writer and failover routing
 
 This release strengthens generic client-side routing for supervisor-provided

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.4",
-    "description": "Generic MySQL and MariaDB client with resilient routing, client-side drains, and failover",
+    "version": "0.1.5",
+    "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
     "keywords": [
         "eliware",
         "elera",
@@ -11,6 +11,7 @@
         "database",
         "routing",
         "failover",
+        "telemetry",
         "websocket",
         "connection-pool"
     ],
@@ -53,6 +54,7 @@
     },
     "dependencies": {
         "@eliware/common": "^2.0.0",
+        "@eliware/snowflake": "^2.0.0",
         "mysql2": "^3.24.2"
     },
     "devDependencies": {

package/src/client/create-db.mjs

@@ -8,10 +8,12 @@ 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';
+import { createTelemetry } from '../telemetry.mjs';
+import { createTimedOperation } from './telemetry-wrapper.mjs';
 
 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() } = {}) {
+export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, quarantineMs = 5000, drainTimeoutMs = 45000, now = () => Date.now(), telemetry } = {}) {
   if (!primary || typeof primary !== 'object') throw new TypeError('primary connection profile is required');
   const credentials = await resolveCredentials(credentialProvider, credentialContext(primary, { identity }));
   let primaryConfig = validateProfile({ ...primary, ...credentials }, 'primary');
@@ -26,20 +28,22 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
   let primaryPool = makeRoute('primary', primaryConfig);
   let balancedPool = balancedConfig || activeBundle?.routes?.balanced ? makeRoute('balanced', balancedConfig ?? primaryConfig) : null;
   const choose = (sql, options = {}) => options.connection ?? (routeFor(sql, options.route ?? routing) === 'balanced' && balancedPool ? balancedPool : primaryPool);
+  const metrics = telemetry === true ? createTelemetry({ application: bundle?.application ?? identity ?? 'default', now }) : telemetry;
+  const timed = createTimedOperation({ metrics, now });
   const client = {
-    async query(sql, values, options) { 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') return balancedPool.query(sql, values); throw error; } },
+    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 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 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?.(); },
+    async attachRoutingStream(stream) { if (!stream?.connect) throw new TypeError('routing stream is required'); metrics?.start?.(stream); 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,
-    async close() { await Promise.all([primaryPool.close(), balancedPool?.close()]); },
+    async close() { metrics?.stop?.(); await Promise.all([primaryPool.close(), balancedPool?.close()]); },
     classify: classifyQuery,
-    config: { primary: redactedProfile(primaryConfig), balanced: balancedConfig && redactedProfile(balancedConfig) }
+    telemetry: metrics, config: { primary: redactedProfile(primaryConfig), balanced: balancedConfig && redactedProfile(balancedConfig) }
   };
   log.debug?.('SQL client created', { balanced: Boolean(balancedPool), routing });
   return client;

package/src/client/telemetry-wrapper.mjs

@@ -0,0 +1,15 @@
+const emptyMetrics = { begin: () => undefined, record: () => {} };
+
+export function createTimedOperation({ metrics = emptyMetrics, now = () => Date.now() } = {}) {
+  return async function timed(operation) {
+    const started = metrics.begin();
+    try {
+      const result = await operation();
+      metrics.record({ latencyMs: started === undefined ? 0 : now() - started });
+      return result;
+    } catch (error) {
+      metrics.record({ latencyMs: started === undefined ? 0 : now() - started, failed: true });
+      throw error;
+    }
+  };
+}

package/src/index.d.ts

@@ -28,12 +28,14 @@ export interface CredentialProviderResult { user: string; password: string; }
 export type CredentialProvider = (context: { database: string; identity: string | null; route: string }) => Promise<CredentialProviderResult> | CredentialProviderResult;
 export type QueryFunction = (sql: string, values?: unknown) => Promise<any>;
 export interface DbOptions { route?: 'auto' | 'primary' | 'balanced'; connection?: unknown; }
+export interface TelemetrySnapshot { type: 'client.telemetry'; application: string; queries: number; failures: number; retries: number; reconnects: number; failoverCount: number; inflight: number; totalLatencyMs: number; maxLatencyMs: number; avgLatencyMs: number; sentAt: string; }
+export interface Telemetry { begin(): number; record(event?: { latencyMs?: number; failed?: boolean; retry?: boolean; reconnect?: boolean; failover?: boolean }): void; snapshot(): TelemetrySnapshot; start(stream: Pick<RoutingStream, 'sendTelemetry'>): void; stop(): void; }
 
 export interface DbClient {
   query(sql: string, values?: unknown, options?: DbOptions): Promise<unknown>;
   execute(sql: string, values?: unknown, options?: DbOptions): Promise<unknown>;
   transaction<T>(callback: (transaction: Pick<DbClient, 'query' | 'execute'>) => Promise<T>): Promise<T>;
-  health(route?: 'primary' | 'balanced'): Promise<{ ok: boolean; route: string; latencyMs: number }>;
+  health(route?: 'primary' | 'balanced'): Promise<{ ok: boolean; route: string; latencyMs: number; telemetry?: TelemetrySnapshot }>;
   close(): Promise<void>;
   refresh(bundle: RoutingBundle): Promise<{ bundleVersion: number | string | null; refreshRequired: boolean }>;
   bundle(): RoutingBundle | undefined;
@@ -43,17 +45,19 @@ export interface DbClient {
   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 };
+  telemetry?: Telemetry;
 }
 
 export interface RoutingStream {
   connect(): Promise<void>;
   setOnUpdate(handler: (event: unknown) => void | Promise<void>): void;
   close(): void;
+  sendTelemetry(payload: unknown): void;
   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>;
-export function createDbFromEnvironment(options?: { env?: Record<string, string | undefined>; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string }): Promise<DbClient>;
+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';
 export function routeFor(sql: unknown, requested?: 'auto' | 'primary' | 'balanced'): 'primary' | 'balanced';
 export function validateProfile(profile: ConnectionProfile, name?: string): ConnectionProfile;
@@ -76,3 +80,4 @@ 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;
+export function createTelemetry(options?: { application?: string; intervalMs?: number; now?: () => number; setIntervalImpl?: typeof setInterval; clearIntervalImpl?: typeof clearInterval }): Telemetry;

package/src/index.mjs

@@ -15,3 +15,4 @@ export { CLIENT_DRAIN_TIMEOUT_MS, clientDrainTimeout } from './lifecycle/drain-p
 export { createQuiesceController } from './lifecycle/quiesce.mjs';
 export { createSqlVerifier } from './verification/sql.mjs';
 export { createMaterializer } from './lifecycle/materializer.mjs';
+export { createTelemetry } from './telemetry.mjs';

package/src/lifecycle/materializer.mjs

@@ -1,9 +1,9 @@
-import { randomUUID } from "node:crypto";
+import { generate as generateSnowflake } from "@eliware/snowflake";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-export function createMaterializer({ makeTemp = mkdtemp, write = writeFile, remove = rm, id = randomUUID } = {}) {
+export function createMaterializer({ makeTemp = mkdtemp, write = writeFile, remove = rm, id = generateSnowflake } = {}) {
   return {
     async withFile(content, operation) {
       if (typeof operation !== "function") throw new TypeError("materializer operation is required");

package/src/routing/stream-client.mjs

@@ -27,5 +27,5 @@ export function createRoutingStream({ endpoint, token, application = 'default',
       socket.onclose = () => { clearInterval(heartbeat); heartbeat = undefined; 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; 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; }, close: () => { closed = true; mode = 'disconnected'; clearTimeout(timer); clearInterval(heartbeat); socket?.close?.(); }, state: () => ({ connected: socket?.readyState === 1, mode, expectedVersion }) };
 }

package/src/telemetry.mjs

@@ -0,0 +1,8 @@
+export function createTelemetry({ application = 'default', intervalMs = 1000, now = () => Date.now(), setIntervalImpl = setInterval, clearIntervalImpl = clearInterval } = {}) {
+  const stats = { queries: 0, failures: 0, retries: 0, reconnects: 0, failoverCount: 0, inflight: 0, totalLatencyMs: 0, maxLatencyMs: 0 };
+  let timer;
+  const begin = () => { stats.inflight += 1; return now(); };
+  const record = ({ latencyMs = 0, failed = false, retry = false, reconnect = false, failover = false } = {}) => { stats.queries += 1; stats.inflight = Math.max(0, stats.inflight - 1); stats.totalLatencyMs += latencyMs; stats.maxLatencyMs = Math.max(stats.maxLatencyMs, latencyMs); if (failed) stats.failures += 1; if (retry) stats.retries += 1; if (reconnect) stats.reconnects += 1; if (failover) stats.failoverCount += 1; };
+  const snapshot = () => ({ type: 'client.telemetry', application, ...stats, avgLatencyMs: stats.queries ? stats.totalLatencyMs / stats.queries : 0, sentAt: new Date(now()).toISOString() });
+  return { begin, record, snapshot, start(stream) { if (timer) return; timer = setIntervalImpl(() => stream.sendTelemetry?.(snapshot()), intervalMs); timer.unref?.(); }, stop() { if (timer) clearIntervalImpl(timer); timer = undefined; } };
+}