@eliware/elera-lib 0.1.10 → 0.2.0

package/README.md

@@ -1,34 +1,28 @@
 # @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.10 alternative to `@eliware/mysql`; the
-existing package is intentionally unchanged. The current package version is
-0.1.10.
+primary/balanced MySQL or MariaDB routing without embedding HAProxy, backup, or
+GitOps policy.
 
-`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`.
+`primary` is the designated write path. `balanced` is an optional read path;
+automatic routing sends only conservative, single-statement read queries to it.
+Transactions always use `primary`.
 
 ```js
-import { createDbFromEnvironment } from '@eliware/elera-lib';
-const db = await createDbFromEnvironment();
+import { createDb } from '@eliware/elera-lib';
+const db = await createDb();
 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.
+Managed applications configure only `ELERA_API_ENDPOINT` and
+`ELERA_API_TOKEN`. Call `createDb({ endpoint, token })` explicitly or omit
+either value when it is available in the process environment.
 
-See examples/basic-client.mjs for a complete consumer example using only the
-public package API. Its usage notes are in examples/README.md.
+See `examples/basic-client.mjs` for a complete consumer example using only the
+public package API. Its usage notes are in `examples/README.md`. The managed
+client contract is defined in `contracts/managed-client.md`; it owns initial
+bundle retrieval, credential materialization, and routing-stream setup.
 
 Routing bundles passed to `createDbFromBundle` use the normalized shape
 `routes.primary` and `routes.balanced`, each containing ordered `{ host, port,
@@ -118,8 +112,8 @@ 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
+The package exports the managed SQL client and internal bundle composition
+primitives, 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

package/RELEASE_NOTES.md

@@ -1,5 +1,57 @@
 # Release notes
 
+## 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
+
+- Publishes declarations for the existing `profilesFromBundle`,
+  `createDbFromBundle`, and `validateTokenContext` exports.
+- Keeps runtime behavior unchanged while aligning declarations with the
+  supported JavaScript entry point.
+
+### Validation
+
+- Typecheck, tests, lint, syntax, contract, and package checks pass.
+- Maintains 100% statements, branches, functions, and lines coverage.
+
 ## 0.1.10 — Token-bound routing context
 
 ### Added
@@ -292,10 +344,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/examples/README.md

@@ -1,13 +1,13 @@
 # Elera library example
 
-basic-client.mjs is a minimal consumer application. It imports only the
-public @eliware/elera-lib package API, opens a bounded SQL client from
-environment configuration, performs a health check and query, and closes the
-client in a finally block.
+`basic-client.mjs` is a minimal managed consumer application. It imports only
+the public `@eliware/elera-lib` package API, opens a SQL client from the Elera
+endpoint and application token, performs a health check and query, and closes
+the client in a `finally` block.
 
-Run it from a published-package consumer project with:
+Run it with:
 
-    MYSQL_PRIMARY_HOST=127.0.0.1 MYSQL_USER=app MYSQL_PASSWORD=secret MYSQL_DATABASE=app node examples/basic-client.mjs
+    ELERA_API_ENDPOINT=http://supervisor-or-load-balancer:8080 ELERA_API_TOKEN=application-token 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,8 +1,7 @@
-import { createDbFromEnvironment } from '@eliware/elera-lib';
+import { createDb } 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();
+// Set ELERA_API_ENDPOINT and ELERA_API_TOKEN before running this example.
+const db = await createDb();
 
 try {
   const health = await db.health('primary');

package/package.json

@@ -1,14 +1,16 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.10",
-    "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
+    "version": "0.2.0",
+    "description": "Managed MySQL and MariaDB client using Elera endpoint and bearer-token routing",
     "keywords": [
         "eliware",
         "elera",
         "mysql",
         "mariadb",
+        "galera",
         "sql",
         "database",
+        "bearer-token",
         "routing",
         "failover",
         "telemetry",

package/src/client/create-db.mjs

@@ -37,8 +37,8 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
     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?.(); },
+    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]; activeBundle = candidate; if (writer) { primaryConfig = validateProfile({ ...primaryConfig, host: writer.host, port: writer.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); primaryPool = makeRoute('primary', primaryConfig); } else { for (const node of primaryPool.nodes) node.drain?.(drainTimeoutMs); } if (reader) { balancedConfig = validateProfile({ ...primaryConfig, host: reader.host, port: reader.port }, 'balanced'); balancedPool = makeRoute('balanced', balancedConfig); } else if (balancedPool) { for (const node of balancedPool.nodes) node.drain?.(drainTimeoutMs); } await Promise.all(previous.filter(Boolean).filter((pool) => pool !== primaryPool && pool !== balancedPool).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) 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)) 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 }))); },

package/src/client/from-bundle.mjs

@@ -9,6 +9,6 @@ export function profilesFromBundle(bundle) {
 
 export async function createDbFromBundle({ bundle, createClient, ...options } = {}) {
   const profiles = profilesFromBundle(bundle);
-  const factory = createClient ?? (await import('./create-db.mjs')).createDb;
+       const factory = createClient ?? (await import('./create-db.mjs')).createDb;
   return factory({ ...options, ...profiles, bundle, identity: bundle.identity });
 }

package/src/client/managed.mjs

@@ -0,0 +1,15 @@
+import { createDbFromBundle } from './from-bundle.mjs';
+import { fetchRoutingBundle } from '../routing/bundle-fetcher.mjs';
+import { createRoutingStream } from '../routing/stream-client.mjs';
+
+export async function createDb({ endpoint = process.env.ELERA_API_ENDPOINT, token = process.env.ELERA_API_TOKEN, fetchImpl = globalThis.fetch, fetchPath, WebSocketImpl = globalThis.WebSocket, ...options } = {}) {
+  const fetchBundle = () => fetchRoutingBundle({ endpoint, token, fetchImpl, path: fetchPath });
+  const bundle = await fetchBundle();
+  const stream = createRoutingStream({ endpoint, token, fetchBundle, WebSocketImpl, ...options });
+  const tokenContext = { application: bundle.application, database: bundle.database, credentialName: bundle.credentialName, identity: bundle.identity, scopes: bundle.scopes };
+  const client = await createDbFromBundle({ bundle, tokenContext, ...options });
+  const detach = await client.attachRoutingStream(stream);
+  const close = client.close.bind(client);
+  client.close = async () => { await detach?.(); await close(); };
+  return client;
+}

package/src/index.d.ts

@@ -11,8 +11,13 @@ export interface ConnectionProfile {
 
 export interface RoutingNode { host: string; port: number | string; weight?: number; }
 export interface WriterAssignment { host: string; port: number | string; }
+export interface RoutingPorts { sql?: number | string; http?: number | string; ws?: number | string; [name: string]: number | string | undefined; }
+export interface NodeIdentity { id?: string; name?: string; address?: string; ports?: RoutingPorts; }
 export interface RoutingBundle {
   apiVersion?: string;
+  applicationId?: string;
+  databaseId?: string;
+  identityId?: string;
   database?: string;
   identity?: string;
   application?: string;
@@ -26,6 +31,24 @@ export interface RoutingBundle {
   writer?: WriterAssignment;
   failover?: WriterAssignment[];
   readers?: WriterAssignment[];
+  nodeIdentity?: NodeIdentity;
+  ports?: RoutingPorts;
+}
+/** Application-facing configuration for the managed Elera client.
+ * Managed applications provide only the supervisor/load-balancer endpoint and
+ * their application-scoped bearer token. Bundle retrieval, credentials, and
+ * SQL routing are library responsibilities.
+ */
+export interface ManagedClientOptions {
+  endpoint?: string;
+  token?: string;
+  mysqlLib?: unknown;
+  log?: unknown;
+  routing?: 'auto' | 'primary' | 'balanced';
+  quarantineMs?: number;
+  drainTimeoutMs?: number;
+  now?: () => number;
+  telemetry?: true | Telemetry;
 }
 export interface CredentialProviderResult { user: string; password: string; }
 export type CredentialProvider = (context: { database: string; identity: string | null; route: string }) => Promise<CredentialProviderResult> | CredentialProviderResult;
@@ -65,7 +88,10 @@ export type RoutingEvent = { type: 'routing.update' | 'routing.resync' | 'routin
 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 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 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 createDb(options?: ManagedClientOptions & { fetchImpl?: typeof fetch; fetchPath?: string; WebSocketImpl?: typeof WebSocket }): Promise<DbClient>;
+export function validateTokenContext(bundle: RoutingBundle, tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }): RoutingBundle;
 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;
@@ -82,6 +108,8 @@ export function createAdminSql(options: { query: QueryFunction }): { transaction
 export function createMigrationRunner(options: { query: QueryFunction; migrations?: Array<{ version: number; name: string; statements: string[] }> }): { status(): Promise<{ applied: unknown[] }>; migrate(): Promise<unknown> };
 export function selectRouteNodes(options: { bundle: RoutingBundle; route?: 'primary' | 'balanced'; now?: number }): RoutingNode[];
 export function createRoutingStream(options: { endpoint: string; token?: string; fetchBundle: () => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number; telemetry?: Pick<Telemetry, 'recordReconnect'> }): RoutingStream;
+export const DEFAULT_BUNDLE_PATH: '/api/v1/routing/bundle';
+export function fetchRoutingBundle(options: { endpoint: string; token: string; path?: string; fetchImpl?: typeof fetch; signal?: AbortSignal }): Promise<RoutingBundle>;
 export function writerAssignment(bundle: RoutingBundle): WriterAssignment;
 export function failoverNodes(bundle: RoutingBundle): WriterAssignment[];
 export function compareBundleVersions(left: number | string | undefined, right: number | string | undefined): number;

package/src/index.mjs

@@ -1,7 +1,6 @@
-export { createDb } from './client/create-db.mjs';
+export { createDb } from './client/managed.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';
@@ -10,6 +9,7 @@ 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 { fetchRoutingBundle, DEFAULT_BUNDLE_PATH } from './routing/bundle-fetcher.mjs';
 export { validateRoutingEvent } from './routing/event-contract.mjs';
 export { writerAssignment, failoverNodes } from './routing/assignment.mjs';
 export { compareBundleVersions } from './routing/bundle-version.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/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 });
-}