@eliware/elera-lib 0.1.11 → 0.3.0

package/README.md

@@ -1,129 +1,32 @@
 # @eliware/elera-lib
 
-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.11 alternative to `@eliware/mysql`; the
-existing package is intentionally unchanged. The current package version is
-0.1.11.
-
-`primary` is the preferred connection path. `balanced` is an optional alternate
-path. Both may accept writes; automatic routing sends only conservative,
-single-statement read queries to `balanced`. Transactions always use `primary`.
-
-```js
-import { createDbFromEnvironment } from '@eliware/elera-lib';
-const db = await createDbFromEnvironment();
-await db.query('SELECT 1');
-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`. `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.
-
-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 may also carry an explicit `writer`, ordered
-`failover`, and `readers` assignment. The bundle carries `database`,
-`identity`, optional `application`, `credentialName`, `scopes`, and
-`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
-candidates, bundle refresh, and quarantine of unhealthy nodes. The WebSocket
-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.
-
-An application-scoped token should resolve to one application, database, and
-credential context. The library does not select databases or credentials from
-request arguments. Callers that already have that authorization context may
-pass `tokenContext` to `createDb`; bundle creation and refresh then reject
-cross-database, identity, credential, or scope mismatches.
-
-When a route node is drained, the client immediately stops assigning new work
-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.
-
-`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
-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
-WebSocket transports are adapters, not supervisor or CLI policy. Underlying
-`mysql2` pools and driver objects remain internal implementation details.
-
-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. 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, 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.
-The snapshot may include the application, database, credential name, and
-scopes associated with the already-authorized client, plus reconnect, failover,
-and cumulative reconnect-delay counters. It never includes bearer tokens or
-passwords.
-
-`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
-does not hide plaintext from the caller. The library does not persist secrets,
-age keys, or supervisor-specific artifact metadata.
-
-The package exports the SQL client and environment/bundle factories, query
-classification and route selection, routing-bundle validation, generic REST
-and WebSocket routing adapters, SQL administration and verification helpers,
-and lifecycle helpers for quiescing and temporary materialization. These
-helpers remain policy-neutral and do not provision users, manage clusters, or
-perform backup/restore orchestration.
+`@eliware/elera-lib` is Elera's shared protocol and helper package. It contains
+the contracts and policy primitives used by the supervisor, CLI, and
+`@eliware/elera-client`.
+
+It provides routing-bundle validation, version comparison, writer assignment,
+ordered failover helpers, routing-event validation, shared SQL and availability
+errors, the client drain policy, and transport-neutral in-memory telemetry.
+
+Application code that needs native SQL connections must install
+`@eliware/elera-client`. SQL pools, credentials, WebSocket connections,
+database selection, backups, CLI commands, and supervisor orchestration are
+not part of this package.
+
+Routing bundles use normalized `routes.primary` and `routes.balanced` arrays
+containing ordered `{ host, port, weight }` nodes. A bundle may also carry a
+writer, readers, ordered failover nodes, application/database/identity scope,
+credentials, version, and expiry. `validateBundle` rejects malformed,
+expired, duplicated, or conflicting route data.
+
+Routing events are validated before consumers act on them. Shared errors
+distinguish an unavailable server from an unavailable cluster. The drain policy
+caps client drain windows at 45 seconds. Telemetry is observational and never
+contains bearer tokens, passwords, SQL, or connection pools.
+
+The supervisor and CLI own policy, persistence, authentication, provisioning,
+recovery, and transport orchestration. `elera-lib` supplies reusable contracts
+and helpers only.
 
 ## Development
 

package/RELEASE_NOTES.md

@@ -1,5 +1,76 @@
 # Release notes
 
+## 0.3.0 — Shared protocol and helper boundary
+
+### Breaking changes
+
+- Narrows `@eliware/elera-lib` to shared Elera contracts, validation, routing,
+  lifecycle, telemetry, and error helpers.
+- Removes the managed SQL client, SQL pools, credential providers, and
+  application-facing database orchestration from this package. Those concerns
+  belong to `@eliware/elera-client` or repository-specific implementations.
+- Removes supervisor- and CLI-specific administration, provisioning, and
+  connection behavior from the public library.
+
+### Changed
+
+- Makes routing-bundle validation enforce the complete shared contract,
+  including application, database, identity, credentials, writer, readers,
+  failover, version, expiry, node identity, and service ports.
+- Aligns the checked-in routing schema and fixture with the shared wire
+  contract.
+- Synchronizes the public runtime exports and TypeScript declarations with the
+  reduced shared-library boundary.
+- Keeps REST/WebSocket transport behavior, routing failover, lifecycle policy,
+  and telemetry primitives transport- and application-policy-neutral.
+
+### Verification
+
+- Adds focused validation for the complete routing-bundle contract, routing
+  nodes, shared errors, and public exports.
+- Removes client-specific tests and implementation from the shared package so
+  they can be maintained by `@eliware/elera-client`.
+- Contract verification, tests, lint, and coverage checks pass for the shared
+  library.
+
+## 0.2.0 — Managed endpoint and token client
+
+### Breaking changes
+
+- Adds a new managed-client workflow; applications using it no longer provide
+  SQL hosts, database names, usernames, passwords, or routing profiles.
+- Managed bundle updates are now constrained to the authorization context
+  established by the initial bundle.
+
+### Added
+
+- Defines the managed application contract using only
+  `ELERA_API_ENDPOINT` and `ELERA_API_TOKEN`.
+- Adds authenticated `fetchRoutingBundle` REST retrieval with response
+  validation and a configurable bundle path.
+- Makes `createDb()` the sole application-facing managed workflow. It acquires the
+  initial bundle and attaches the routing stream automatically, using explicit
+  options or `ELERA_API_ENDPOINT` and `ELERA_API_TOKEN` by default.
+- Establishes application, database, identity, credential, and scope context
+  from the initial bundle and rejects cross-context updates.
+- Adds explicit routing-bundle metadata for application, database, and
+  identity IDs, node identity, and service ports.
+- Handles routing updates that temporarily remove all eligible writers or
+  readers without dereferencing missing routes.
+- Prevents concurrent stream connections and reconnects after a shutdown
+  deadline.
+
+### API boundary
+
+- The managed factory is the application-facing workflow and accepts only the
+  endpoint and application token.
+
+### Verification
+
+- Adds focused bundle-fetcher, managed-client, lifecycle, and
+  authorization-boundary tests.
+- Static syntax, schema, and diff validation pass for the committed changes.
+
 ## 0.1.11 — Public runtime declarations
 
 ### Changed
@@ -306,10 +377,9 @@ GitOps, backup, or CLI policy.
   policy.
 - Requires applications to provide their own credential and routing adapters.
 
-### Compatibility and validation
+### Validation
 
 - ESM package targeting Node.js 26 or newer.
 - TypeScript declarations are included with the package.
-- Existing `@eliware/mysql` is not modified or required.
 - Strict test coverage is maintained at 100% statements, branches, functions,
   and lines with zero lint warnings.

package/contracts/managed-client.md

@@ -0,0 +1,36 @@
+# Shared contract boundary
+
+This document describes the bundle and event contract consumed by Elera
+components. It is not an application-client API; application-facing SQL
+connections belong to `@eliware/elera-client`.
+
+## Routing bundles
+
+The supervisor publishes a complete `v1` bundle containing application,
+database, identity, credentials, writer, readers, ordered failover nodes,
+bundle version, expiry, node identity, and service ports. The normalized route
+arrays are `routes.primary` and `routes.balanced`.
+
+`validateBundle()` rejects missing required fields, malformed nodes or ports,
+expired timestamps, duplicate writer/failover nodes, and invalid route arrays.
+Consumers must validate a complete bundle before using it. Partial routing
+events must be merged with the active complete bundle by the consumer before
+validation.
+
+## Routing events
+
+`validateRoutingEvent()` defines the shared event boundary for routing updates,
+drains, recovery, and shutdown. Event handling and transport orchestration are
+owned by the consuming client or supervisor; this package supplies contracts
+and validation only.
+
+## Shared helpers
+
+The public package provides bundle and node validation, version comparison,
+writer/failover calculation, shared SQL errors, client drain policy, and
+transport-neutral telemetry. It does not retrieve bundles, open SQL pools,
+materialize application credentials, provision databases, manage Galera, or
+implement CLI and supervisor workflows.
+
+See `README.md` for the complete export boundary and
+`contracts/routing-bundle.schema.json` for the machine-readable contract.

package/contracts/routing-bundle.fixture.json

@@ -0,0 +1,17 @@
+{
+  "apiVersion": "v1",
+  "application": "billing",
+  "applicationId": "18446744073709551621",
+  "databaseId": "18446744073709551622",
+  "identityId": "18446744073709551623",
+  "database": "billing",
+  "identity": "billing-runtime",
+  "credentials": { "username": "billing_runtime", "password": "fixture-only" },
+  "writer": { "host": "sql0.internal", "port": 3306 },
+  "failover": [{ "host": "sql1.internal", "port": 3306 }],
+  "readers": [{ "host": "sql0.internal", "port": 3306, "weight": 100 }, { "host": "sql1.internal", "port": 3306, "weight": 80 }, { "host": "sql2.internal", "port": 3306, "weight": 60 }],
+  "nodeIdentity": "sql0.internal",
+  "ports": { "sql": 3306, "http": 8080 },
+  "bundleVersion": 1,
+  "expiresAt": "2099-01-01T00:00:00Z"
+}

package/contracts/routing-bundle.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://eliware.dev/contracts/routing-bundle.schema.json",
+  "type": "object",
+  "required": ["apiVersion", "application", "database", "identity", "credentials", "writer", "readers", "failover", "bundleVersion", "expiresAt", "nodeIdentity", "ports"],
+  "properties": { "apiVersion": { "const": "v1" }, "application": { "type": "string", "minLength": 1 }, "applicationId": { "type": "string", "minLength": 1 }, "databaseId": { "type": "string", "minLength": 1 }, "identityId": { "type": "string", "minLength": 1 }, "database": { "type": "string", "minLength": 1 }, "identity": { "type": "string", "minLength": 1 }, "credentials": { "type": "object", "required": ["username", "password"], "properties": { "username": { "type": "string", "minLength": 1 }, "password": { "type": "string" } }, "additionalProperties": false }, "writer": { "$ref": "#/$defs/node" }, "failover": { "$ref": "#/$defs/nodes" }, "readers": { "$ref": "#/$defs/nodes" }, "nodeIdentity": { "type": "string", "minLength": 1 }, "ports": { "$ref": "#/$defs/ports" }, "bundleVersion": { "type": ["string", "number"] }, "refreshAfter": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" } },
+  "$defs": { "node": { "type": "object", "required": ["host"], "properties": { "host": { "type": "string", "minLength": 1 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "weight": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "nodes": { "type": "array", "items": { "$ref": "#/$defs/node" } }, "ports": { "type": "object", "required": ["sql", "http"], "properties": { "sql": { "type": "integer", "minimum": 1, "maximum": 65535 }, "http": { "type": "integer", "minimum": 1, "maximum": 65535 }, "ws": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 65535 } } },
+  "additionalProperties": false
+}

package/examples/README.md

@@ -1,13 +1,11 @@
 # 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.
+`basic-client.mjs` demonstrates the shared `@eliware/elera-lib` contract
+helpers. Native SQL application examples belong to `@eliware/elera-client`.
 
-Run it from a published-package consumer project with:
+Run it with a complete bundle:
 
-    MYSQL_PRIMARY_HOST=127.0.0.1 MYSQL_USER=app MYSQL_PASSWORD=secret MYSQL_DATABASE=app node examples/basic-client.mjs
+    ELERA_BUNDLE_JSON='{"apiVersion":"v1","application":"billing","database":"billing","identity":"billing-runtime","credentials":{"username":"billing_runtime","password":"fixture-only"},"writer":{"host":"elera-0","port":3306},"readers":[{"host":"elera-0","port":3306}],"failover":[{"host":"elera-1","port":3306}],"bundleVersion":1,"expiresAt":"2099-01-01T00:00:00Z","nodeIdentity":"elera-0","ports":{"sql":3306,"http":8080},"routes":{"primary":[{"host":"elera-0","port":3306}],"balanced":[{"host":"elera-0","port":3306}]}}' node examples/basic-client.mjs
 
-The example is intentionally infrastructure-neutral. It does not contain
-Docker, Kubernetes, Supervisor, CLI, Galera, or test-lab setup.
+The example is infrastructure-neutral. It contains no Docker, Kubernetes,
+Supervisor, CLI, Galera, or test-lab setup.

package/examples/basic-client.mjs

@@ -1,14 +1,7 @@
-import { createDbFromEnvironment } from '@eliware/elera-lib';
+import { createTelemetry, validateBundle } 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();
+// Native SQL application examples live in @eliware/elera-client.
+const bundle = validateBundle(JSON.parse(process.env.ELERA_BUNDLE_JSON ?? '{}'));
+const telemetry = createTelemetry({ application: bundle.application, database: bundle.database });
 
-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();
-}
+console.log(JSON.stringify({ bundleVersion: bundle.bundleVersion, telemetry: telemetry.snapshot() }));

package/package.json

@@ -1,19 +1,21 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.11",
-    "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
+    "version": "0.3.0",
+    "description": "Shared Elera routing, event, lifecycle, telemetry, validation, and protocol helpers",
     "keywords": [
         "eliware",
         "elera",
         "mysql",
         "mariadb",
-        "sql",
-        "database",
+        "galera",
+        "protocol",
+        "contracts",
         "routing",
         "failover",
         "telemetry",
         "websocket",
-        "connection-pool"
+        "protocol-contracts",
+        "mysql-client"
     ],
     "repository": {
         "type": "git",
@@ -25,6 +27,7 @@
     },
     "license": "Apache-2.0",
     "type": "module",
+    "sideEffects": false,
     "engines": {
         "node": ">=26"
     },
@@ -36,6 +39,7 @@
     },
     "files": [
         "src",
+        "contracts",
         "examples",
         "README.md",
         "RELEASE_NOTES.md",
@@ -54,8 +58,7 @@
     },
     "dependencies": {
         "@eliware/common": "^2.0.0",
-        "@eliware/snowflake": "^2.0.0",
-        "mysql2": "^3.24.2"
+        "@eliware/snowflake": "^2.0.0"
     },
     "devDependencies": {
         "@eliware/test": "^2.0.0",

package/src/bundle.mjs

@@ -1,13 +1,28 @@
 import { validateRoutingNode, validateRoutingNodes } from './routing/node-validation.mjs';
 const routes = ['primary', 'balanced'];
+const requiredText = (value, name) => { if (typeof value !== 'string' || value.length === 0) throw new TypeError(`${name} is required`); };
+const validatePorts = (ports) => {
+  if (!ports || typeof ports !== 'object') throw new TypeError('routing bundle ports are required');
+  for (const name of ['sql', 'http']) validateRoutingNode({ host: name, port: ports[name] }, `routing bundle ports.${name}`);
+};
 
 export function validateBundle(bundle) {
   if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
+  if (bundle.apiVersion !== 'v1') throw new TypeError('routing bundle apiVersion must be v1');
+  requiredText(bundle.application, 'routing bundle application');
+  requiredText(bundle.database, 'routing bundle database');
+  requiredText(bundle.identity, 'routing bundle identity');
+  requiredText(bundle.nodeIdentity, 'routing bundle nodeIdentity');
+  if (!bundle.credentials || typeof bundle.credentials !== 'object') throw new TypeError('routing bundle credentials are required');
+  requiredText(bundle.credentials.username, 'routing bundle credentials.username');
+  if (typeof bundle.credentials.password !== 'string') throw new TypeError('routing bundle credentials.password is required');
+  if (bundle.bundleVersion === undefined || !['string', 'number'].includes(typeof bundle.bundleVersion)) throw new TypeError('routing bundle bundleVersion is required');
+  validatePorts(bundle.ports);
   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') : [];
+  const writer = validateRoutingNode(bundle.writer, 'routing bundle writer');
+  const failover = 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');
+  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] ?? []) {

package/src/index.d.ts

@@ -1,96 +1,21 @@
-import type { PoolOptions } from 'mysql2/promise';
-
-export interface ConnectionProfile {
-  host: string;
-  port?: number | string;
-  user?: string;
-  password?: string;
-  database: string;
-  options?: Partial<PoolOptions> & { socket?: string };
-}
-
-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;
-  identity?: string;
-  application?: string;
-  credentialName?: string;
-  scopes?: string[];
-  credentials?: { username?: string; password?: string };
-  bundleVersion?: number | string;
-  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;
-export type QueryFunction = (sql: string, values?: unknown) => Promise<any>;
-export interface DbOptions { route?: 'auto' | 'primary' | 'balanced'; connection?: unknown; }
+export interface RoutingNode { host: string; port: number | string; weight?: number; nodeId?: string; }
+export interface RoutingBundle { apiVersion?: string; applicationId?: string; databaseId?: string; identityId?: string; application?: string; database?: string; identity?: string; credentialName?: string; scopes?: string[]; credentials?: { username?: string; password?: string }; bundleVersion?: number | string; expiresAt: string; refreshAfter?: string; routes: { primary?: RoutingNode[]; balanced?: RoutingNode[] }; writer?: RoutingNode; failover?: RoutingNode[]; readers?: RoutingNode[]; nodeIdentity?: Record<string, unknown>; ports?: Record<string, number | string>; }
 export interface TelemetrySnapshot { type: 'client.telemetry'; application: string; credentialName?: string; database?: string; scopes?: string[]; queries: number; failures: number; retries: number; reconnects: number; failoverCount: number; reconnectDelayMs: 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; recordReconnect(event?: { delayMs?: number; 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; telemetry?: TelemetrySnapshot }>;
-  close(): Promise<void>;
-  refresh(bundle: RoutingBundle): Promise<{ bundleVersion: number | string | null; refreshRequired: boolean }>;
-  bundle(): RoutingBundle | undefined;
-  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 };
-  telemetry?: Telemetry;
-}
-
-export interface RoutingStream {
-  connect(): Promise<void>;
-  setOnUpdate(handler: (event: unknown) => void | Promise<void>): void;
-  close(): void;
-  sendTelemetry(payload: unknown): void;
-  setTelemetry?(telemetry?: Pick<Telemetry, 'recordReconnect'>): void;
-  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; tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }; 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 profilesFromBundle(bundle: RoutingBundle): { primary: ConnectionProfile; balanced?: ConnectionProfile };
-export function createDbFromBundle(options: { bundle: RoutingBundle; createClient?: typeof createDb; credentialProvider?: CredentialProvider; tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number; telemetry?: true | Telemetry }): Promise<DbClient>;
-export function validateTokenContext(bundle: RoutingBundle, tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }): RoutingBundle;
-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;
-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 interface Telemetry { snapshot(): TelemetrySnapshot; begin(): number; record(event?: unknown): void; recordReconnect(event?: unknown): void; }
 export function validateBundle(bundle: RoutingBundle): RoutingBundle;
 export function bundleExpired(bundle: RoutingBundle, now?: number): boolean;
 export function bundleNeedsRefresh(bundle: RoutingBundle, now?: number): boolean;
-export function createAdminSql(options: { query: QueryFunction }): { transaction<T>(work: (context: { query: QueryFunction }) => Promise<T>): Promise<T>; migration(statements?: string[]): Promise<unknown> };
-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; fetchBundle: () => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number; telemetry?: Pick<Telemetry, 'recordReconnect'> }): RoutingStream;
-export function writerAssignment(bundle: RoutingBundle): WriterAssignment;
-export function failoverNodes(bundle: RoutingBundle): WriterAssignment[];
+export function validateRoutingEvent(event: unknown): unknown;
 export function compareBundleVersions(left: number | string | undefined, right: number | string | undefined): number;
+export function writerAssignment(bundle: RoutingBundle): RoutingNode;
+export function failoverNodes(bundle: RoutingBundle): RoutingNode[];
+export function validateRoutingNode(node: RoutingNode, name?: string): RoutingNode;
+export function validateRoutingNodes(nodes: RoutingNode[], name?: string): RoutingNode[];
 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;
-export function createTelemetry(options?: { application?: string; credentialName?: string; database?: string; scopes?: string[]; intervalMs?: number; now?: () => number; setIntervalImpl?: typeof setInterval; clearIntervalImpl?: typeof clearInterval }): Telemetry;
+export function createTelemetry(options?: Record<string, unknown>): Telemetry;
+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;

package/src/index.mjs

@@ -1,20 +1,8 @@
-export { createDb } from './client/create-db.mjs';
-export { validateTokenContext } from './client/authorization-context.mjs';
-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, 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';
-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 { writerAssignment, failoverNodes } from './routing/assignment.mjs';
+export { validateRoutingNode, validateRoutingNodes } from './routing/node-validation.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';
 export { createTelemetry } from './telemetry.mjs';

package/src/routing/bundle-fetcher.mjs

@@ -0,0 +1,20 @@
+import { validateBundle } from '../bundle.mjs';
+
+const DEFAULT_BUNDLE_PATH = '/api/v1/routing/bundle';
+
+function bundleUrl(endpoint, path) {
+  if (!endpoint) throw new TypeError('Elera API endpoint is required');
+  return new URL(path, endpoint.endsWith('/') ? endpoint : `${endpoint}/`).toString();
+}
+
+export async function fetchRoutingBundle({ endpoint, token, path = DEFAULT_BUNDLE_PATH, fetchImpl = globalThis.fetch, signal } = {}) {
+  if (!token) throw new TypeError('Elera API token is required');
+  if (typeof fetchImpl !== 'function') throw new TypeError('fetch implementation is required');
+  const response = await fetchImpl(bundleUrl(endpoint, path), { method: 'GET', headers: { accept: 'application/json', authorization: `Bearer ${token}` }, signal });
+  if (!response?.ok) throw new Error(`routing bundle request failed with HTTP ${response?.status ?? 0}`);
+  let bundle;
+  try { bundle = await response.json(); } catch (error) { throw new Error('routing bundle response was not valid JSON', { cause: error }); }
+  return validateBundle(bundle);
+}
+
+export { DEFAULT_BUNDLE_PATH };

package/src/routing/stream-client.mjs

@@ -4,16 +4,18 @@ import { validateRoutingEvent } from './event-contract.mjs';
 
 export function createRoutingStream({ endpoint, token, 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 reconnectDeadlineAt;
+  let socket; let closed = false; let connecting = 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?token=${encodeURIComponent(token ?? '')}`;
   async function fallback() { try { const bundle = await fetchBundle(); 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 || (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 || connecting || socket?.readyState === 1 || (reconnectDeadlineAt !== undefined && now() >= reconnectDeadlineAt)) return;
     if (closed || typeof WebSocketImpl !== 'function') { await fallback(); schedule(); return; }
     try {
+      connecting = true;
       socket = new WebSocketImpl(streamUrl());
-      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.onopen = () => { connecting = false; 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 = validateRoutingEvent(JSON.parse(data));
@@ -36,8 +38,8 @@ export function createRoutingStream({ endpoint, token, fetchBundle, WebSocketImp
         } catch (error) { onError?.(error); }
       };
       socket.onerror = (error) => { onError?.(error); };
-      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(); }
+      socket.onclose = () => { connecting = false; clearInterval(heartbeat); heartbeat = undefined; socket = undefined; mode = 'disconnected'; if (!closed) { disconnectedAt = now(); lastReconnectWasPlanned = plannedReconnect; if (!plannedReconnect) void fallback(); plannedReconnect = false; schedule(); } };
+    } catch (error) { connecting = false; socket = undefined; 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, endpoint, reconnectDeadlineAt }) };
 }

package/src/client/authorization-context.mjs

@@ -1,9 +0,0 @@
-export function validateTokenContext(bundle, tokenContext = {}) {
-  if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
-  for (const field of ['application', 'database', 'credentialName']) {
-    if (tokenContext[field] !== undefined && bundle[field] !== tokenContext[field]) throw new Error(`routing bundle ${field} does not match token context`);
-  }
-  if (tokenContext.identity !== undefined && bundle.identity !== tokenContext.identity) throw new Error('routing bundle identity does not match token context');
-  if (tokenContext.scopes !== undefined && (!Array.isArray(bundle.scopes) || tokenContext.scopes.some((scope) => !bundle.scopes.includes(scope)))) throw new Error('routing bundle scopes exceed token context');
-  return bundle;
-}

package/src/client/bundle-profiles.mjs

@@ -1,7 +0,0 @@
-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

@@ -1,53 +0,0 @@
-import { log as defaultLog } from '@eliware/common';
-import * as mysql from 'mysql2/promise';
-import { validateProfile, redactedProfile } from '../config.mjs';
-import { asSqlError } from '../errors.mjs';
-import { resolveCredentials, credentialContext } from '../credential-provider.mjs';
-import { validateBundle as validateBundleShape, 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';
-import { createTelemetry } from '../telemetry.mjs';
-import { createTimedOperation } from './telemetry-wrapper.mjs';
-import { validateTokenContext } from './authorization-context.mjs';
-
-const olderVersion = (candidate, current) => compareBundleVersions(candidate, current) < 0;
-
-export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, tokenContext, 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');
-  if (!primaryConfig.user || typeof primaryConfig.password !== 'string') throw new TypeError('primary.user and primary.password are required');
-  let balancedConfig = balanced ? validateProfile({ ...primaryConfig, ...balanced, ...credentials }, 'balanced') : undefined;
-  if (credentials.user || credentials.password) {
-    primaryConfig = validateProfile({ ...primaryConfig, ...credentials }, 'primary');
-    if (balancedConfig) balancedConfig = validateProfile({ ...balancedConfig, ...credentials }, 'balanced');
-  }
-  const validateBundle = (candidate) => validateTokenContext(validateBundleShape(candidate), tokenContext);
-  let activeBundle = bundle ? validateBundle(bundle) : undefined;
-  const makeRoute = (route, fallback) => createRouteFactory({ bundle: activeBundle, now, mysqlLib, log, quarantineMs })(route, fallback);
-  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 ?? 'default', credentialName: bundle?.credentialName, database: bundle?.database, scopes: bundle?.scopes, now }) : telemetry;
-  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 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 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,
-    async close() { metrics?.stop?.(); await Promise.all([primaryPool.close(), balancedPool?.close()]); },
-    classify: classifyQuery,
-    telemetry: metrics, config: { primary: redactedProfile(primaryConfig), balanced: balancedConfig && redactedProfile(balancedConfig) }
-  };
-  log.debug?.('SQL client created', { balanced: Boolean(balancedPool), routing });
-  return client;
-}

package/src/client/environment.mjs

@@ -1,7 +0,0 @@
-import { createDb } from './create-db.mjs';
-
-export async function createDbFromEnvironment({ env = process.env, ...options } = {}) {
-  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: { socketPath: 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/client/from-bundle.mjs

@@ -1,14 +0,0 @@
-import { validateBundle } from '../bundle.mjs';
-
-export function profilesFromBundle(bundle) {
-  const valid = validateBundle(bundle);
-  const credentials = valid.credentials ?? {};
-  const base = { host: valid.routes.primary[0]?.host, port: valid.routes.primary[0]?.port, user: credentials.username, password: credentials.password, database: valid.database };
-  return { primary: base, balanced: valid.routes.balanced?.[0] ? { ...base, host: valid.routes.balanced[0].host, port: valid.routes.balanced[0].port } : undefined };
-}
-
-export async function createDbFromBundle({ bundle, createClient, ...options } = {}) {
-  const profiles = profilesFromBundle(bundle);
-  const factory = createClient ?? (await import('./create-db.mjs')).createDb;
-  return factory({ ...options, ...profiles, bundle, identity: bundle.identity });
-}

package/src/client/route-factory.mjs

@@ -1,14 +0,0 @@
-import { bundleExpired } from '../bundle.mjs';
-import { createNodePool, createRoutePool } from '../pools.mjs';
-import { bundleProfiles } from './bundle-profiles.mjs';
-
-const routeProfiles = (bundle, route, fallback, now) => {
-  if (!bundle) return [fallback];
-  if (bundleExpired(bundle, now())) return [fallback];
-  const profiles = bundleProfiles(bundle, route, fallback);
-  return profiles.length ? profiles : [fallback];
-};
-
-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 })), { preferred: route === 'primary' });
-}

package/src/client/telemetry-wrapper.mjs

@@ -1,15 +0,0 @@
-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/config.mjs

@@ -1,31 +0,0 @@
-const integer = (value, name, { min = 0, max = 65535 } = {}) => {
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < min || number > max) throw new TypeError(`${name} must be an integer between ${min} and ${max}`);
-  return number;
-};
-
-export function validateProfile(profile, name = 'connection') {
-  if (!profile || typeof profile !== 'object') throw new TypeError(`${name} profile is required`);
-  if (!profile.host || typeof profile.host !== 'string') throw new TypeError(`${name}.host is required`);
-  if (profile.user !== undefined && typeof profile.user !== 'string') throw new TypeError(`${name}.user must be a string`);
-  if (profile.password !== undefined && typeof profile.password !== 'string') throw new TypeError(`${name}.password must be a string`);
-  if (!profile.database || typeof profile.database !== 'string') throw new TypeError(`${name}.database is required`);
-  const port = integer(profile.port ?? 3306, `${name}.port`, { min: 1 });
-  const options = profile.options ?? {};
-  const connectionLimit = integer(options.connectionLimit ?? 10, `${name}.options.connectionLimit`, { min: 1, max: 1000 });
-  const queueLimit = integer(options.queueLimit ?? 0, `${name}.options.queueLimit`, { max: 1000000 });
-  const connectTimeout = integer(options.connectTimeout ?? 10000, `${name}.options.connectTimeout`, { max: 3600000 });
-  const acquireTimeout = integer(options.acquireTimeout ?? 10000, `${name}.options.acquireTimeout`, { max: 3600000 });
-  if (options.ssl !== undefined && typeof options.ssl !== 'object' && typeof options.ssl !== 'string') throw new TypeError(`${name}.options.ssl must be an object or string`);
-  return { ...profile, port, options: { ...options, connectionLimit, queueLimit, connectTimeout, acquireTimeout } };
-}
-
-export function redactedProfile(profile) {
-  const { password: _password, options = {}, ...safe } = profile;
-  const safeOptions = { ...options };
-  if (safeOptions.ssl && typeof safeOptions.ssl === 'object') {
-    safeOptions.ssl = { ...safeOptions.ssl };
-    for (const key of ['key', 'privateKey', 'passphrase']) delete safeOptions.ssl[key];
-  }
-  return { ...safe, options: safeOptions };
-}

package/src/credential-provider.mjs

@@ -1,12 +0,0 @@
-export async function resolveCredentials(provider, context) {
-  if (provider === undefined) return {};
-  if (typeof provider !== 'function') throw new TypeError('credentialProvider must be a function');
-  const result = await provider(context);
-  if (!result || typeof result !== 'object') throw new TypeError('credentialProvider must return an object');
-  if (typeof result.user !== 'string' || typeof result.password !== 'string') throw new TypeError('credentialProvider must return user and password');
-  return result;
-}
-
-export function credentialContext(primary, options) {
-  return { database: primary.database, identity: options.identity ?? null, route: options.route ?? 'primary' };
-}

package/src/pools/node-pool.mjs

@@ -1,23 +0,0 @@
-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.socketPath === undefined) delete driverOptions.socketPath;
-  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; let forcedUnavailable = false; let lifecycle = 'ready'; let active = 0; let idleResolve; let drainTimer;
-  const begin = () => { active += 1; };
-  const end = () => { active = Math.max(0, active - 1); if (!active) idleResolve?.(); };
-  const run = async (work) => { begin(); try { return await work(); } finally { end(); } };
-  const drain = (timeoutMs = 45000) => { lifecycle = 'draining'; forcedUnavailable = true; unavailableUntil = Number.POSITIVE_INFINITY; clearTimeout(drainTimer); drainTimer = setTimeout(() => { void forceClose(); }, timeoutMs); drainTimer.unref?.(); return { state: lifecycle, active }; };
-  const waitForIdle = async (timeoutMs = 45000) => { if (!active) return true; await Promise.race([new Promise((resolve) => { idleResolve = resolve; }), new Promise((resolve) => setTimeout(resolve, timeoutMs))]); idleResolve = undefined; return active === 0; };
-  const forceClose = async () => { lifecycle = 'unavailable'; await pool.end(); };
-  const recover = () => { clearTimeout(drainTimer); drainTimer = undefined; lifecycle = 'recovering'; forcedUnavailable = false; unavailableUntil = 0; lifecycle = 'ready'; return lifecycle; };
-  return { host: profile.host, port: profile.port, weight: Number(profile.weight ?? 100), get available() { return lifecycle === 'ready' && !forcedUnavailable && now() >= unavailableUntil; }, set available(value) { if (value) recover(); else drain(); }, get failures() { return failures; }, get state() { return lifecycle; }, get active() { return active; }, drain, recover, waitForIdle, forceClose,
-    async query(sql, values) { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const result = await run(() => sessionStatements.length ? withConnection((connection, statement, params) => connection.query(statement, params), sql, values) : 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) { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const result = await run(() => sessionStatements.length ? withConnection((connection, statement, params) => connection.execute(statement, params), sql, values) : pool.execute(sql, values)); failures = 0; return result; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
-    async getConnection() { if (!this.available) throw new Error(`SQL node ${profile.host} is unavailable`); try { const connection = await pool.getConnection(); begin(); const release = connection.release.bind(connection); let released = false; connection.release = () => { if (released) return; released = true; end(); release(); }; return connection; } catch (error) { if (connectionFailure(error)) unavailableUntil = now() + quarantineMs; throw asSqlError(error); } },
-    async health() { try { await pool.query('SELECT 1'); failures = 0; unavailableUntil = 0; return { ok: true, host: profile.host, port: profile.port }; } catch (error) { if (connectionFailure(error)) { failures += 1; unavailableUntil = now() + quarantineMs; } throw asSqlError(error); } },
-    async close() { clearTimeout(drainTimer); lifecycle = 'unavailable'; await pool.end(); } };
-}

package/src/pools/route-pool.mjs

@@ -1,47 +0,0 @@
-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 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];
-    let target = cursor++ % total;
-    let selected = available[available.length - 1];
-    for (const node of available) {
-      const weight = Math.max(0, node.weight);
-      if (target < weight) {
-        selected = node;
-        break;
-      }
-      target -= weight;
-    }
-    return selected;
-  };
-  const setAvailability = (host, available) => {
-    for (const node of nodes) if (node.host === host) node.available = available;
-  };
-  const lifecycle = (host, state) => nodes.filter((node) => node.host === host).map((node) => state === 'draining' ? node.drain() : node.recover());
-  const drain = (host, timeoutMs) => { for (const node of nodes.filter((value) => value.host === host)) node.drain?.(timeoutMs); return lifecycle(host, 'draining'); };
-  const recover = (host) => lifecycle(host, 'recovering');
-  const waitForIdle = (timeoutMs) => Promise.all(nodes.map((node) => node.waitForIdle?.(timeoutMs) ?? true));
-  const forceClose = (host) => Promise.all(nodes.filter((node) => !host || node.host === host).map((node) => node.forceClose?.() ?? node.close()));
-  const query = (sql, values) => choose().query(sql, values);
-  const execute = (sql, values) => choose().execute(sql, values);
-  const health = async () => {
-    const results = [];
-    for (const node of nodes) {
-      try {
-        results.push(await node.health());
-      } catch (error) {
-        results.push({ ok: false, host: node.host, port: node.port, error: error.message });
-      }
-    }
-    return results;
-  };
-  const close = async () => Promise.all(nodes.map((node) => node.close()));
-  return { nodes, choose, setAvailability, drain, recover, waitForIdle, forceClose, query, execute, health, close };
-}

package/src/pools.mjs

@@ -1,3 +0,0 @@
-export { createNodePool } from './pools/node-pool.mjs';
-export { createRoutePool } from './pools/route-pool.mjs';
-/* istanbul ignore file -- barrel exports only. */

package/src/routing.mjs

@@ -1,15 +0,0 @@
-const READ_PATTERN = /^(SELECT|SHOW|DESCRIBE|DESC|EXPLAIN)\b/i;
-
-export function classifyQuery(sql) {
-  if (typeof sql !== 'string') return 'primary';
-  const statement = sql.trim().replace(/^(--[^\n]*\n|#[^\n]*\n|\/\*[\s\S]*?\*\/\s*)+/, '').trim();
-  if (!READ_PATTERN.test(statement) || statement.includes(';')) return 'primary';
-  if (/\b(FOR\s+UPDATE|LOCK\s+IN\s+SHARE\s+MODE|INTO\s+(OUTFILE|DUMPFILE)|CALL)\b/i.test(statement)) return 'primary';
-  return 'balanced';
-}
-
-export function routeFor(sql, requested = 'auto') {
-  if (requested === 'primary' || requested === 'balanced') return requested;
-  if (requested !== 'auto') throw new TypeError(`Unsupported SQL route: ${requested}`);
-  return classifyQuery(sql);
-}