@pineliner/odb-client 1.1.5 → 1.2.0

package/dist/index.js

@@ -2048,6 +2048,417 @@ class ODBLiteConnection {
         return this.client.httpClient.getNamespaces();
     }
 }
+function toHrana(v) {
+    if (null == v) return {
+        type: 'null'
+    };
+    if ('bigint' == typeof v) return {
+        type: 'integer',
+        value: v.toString()
+    };
+    if ('number' == typeof v) return Number.isInteger(v) ? {
+        type: 'integer',
+        value: String(v)
+    } : {
+        type: 'float',
+        value: v
+    };
+    if ('string' == typeof v) return {
+        type: 'text',
+        value: v
+    };
+    if (v instanceof Uint8Array) return {
+        type: 'blob',
+        base64: Buffer.from(v).toString('base64')
+    };
+    if ('boolean' == typeof v) return {
+        type: 'integer',
+        value: v ? '1' : '0'
+    };
+    return {
+        type: 'text',
+        value: String(v)
+    };
+}
+function fromHrana(v) {
+    switch(v.type){
+        case 'null':
+            return null;
+        case 'integer':
+            {
+                const n = Number(v.value);
+                return Number.isSafeInteger(n) ? n : BigInt(v.value);
+            }
+        case 'float':
+            return v.value;
+        case 'text':
+            return v.value;
+        case 'blob':
+            return new Uint8Array(Buffer.from(v.base64, 'base64'));
+    }
+}
+function toBatch(steps) {
+    return {
+        steps: steps.map((s, i)=>({
+                condition: 0 === i ? void 0 : {
+                    type: 'ok',
+                    step: i - 1
+                },
+                stmt: {
+                    sql: s.sql,
+                    args: (s.params ?? []).map(toHrana)
+                },
+                expect: s.expect ? {
+                    affected: s.expect
+                } : void 0
+            }))
+    };
+}
+class FrameWriter {
+    socket;
+    pending = Buffer.alloc(0);
+    constructor(socket){
+        this.socket = socket;
+    }
+    send(payload) {
+        const header = Buffer.allocUnsafe(4);
+        header.writeUInt32LE(payload.length, 0);
+        const frame = Buffer.concat([
+            header,
+            payload
+        ]);
+        this.pending = this.pending.length ? Buffer.concat([
+            this.pending,
+            frame
+        ]) : frame;
+        this.flush();
+    }
+    flush() {
+        while(this.pending.length > 0){
+            const n = this.socket.write(this.pending);
+            if (n <= 0) return;
+            this.pending = n < this.pending.length ? this.pending.subarray(n) : Buffer.alloc(0);
+        }
+    }
+}
+class FrameReader {
+    buf = Buffer.alloc(0);
+    push(chunk) {
+        this.buf = this.buf.length ? Buffer.concat([
+            this.buf,
+            chunk
+        ]) : chunk;
+        const out = [];
+        while(this.buf.length >= 4){
+            const len = this.buf.readUInt32LE(0);
+            if (this.buf.length < 4 + len) break;
+            out.push(this.buf.subarray(4, 4 + len));
+            this.buf = this.buf.subarray(4 + len);
+        }
+        return out;
+    }
+}
+class SocketClient {
+    target;
+    socket;
+    reader = new FrameReader();
+    writer;
+    pending = new Map();
+    nextId = 1;
+    ready;
+    constructor(target){
+        this.target = target;
+        this.ready = this.connect();
+        this.ready.catch(()=>{});
+    }
+    async connect() {
+        const Bun = globalThis.Bun;
+        if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)');
+        const opts = this.target.unix ? {
+            unix: this.target.unix
+        } : {
+            hostname: this.target.hostname ?? '127.0.0.1',
+            port: this.target.port ?? 8787
+        };
+        this.socket = await Bun.connect({
+            ...opts,
+            socket: {
+                data: (_s, chunk)=>{
+                    for (const frame of this.reader.push(chunk)){
+                        const msg = JSON.parse(frame.toString('utf8'));
+                        const resolve = this.pending.get(msg.id);
+                        if (resolve) {
+                            this.pending.delete(msg.id);
+                            resolve(msg.results);
+                        }
+                    }
+                },
+                drain: (_s)=>this.writer.flush(),
+                close: ()=>{
+                    this.socket = void 0;
+                }
+            }
+        });
+        this.writer = new FrameWriter(this.socket);
+    }
+    async pipeline(tenant, requests) {
+        if (!this.socket) {
+            this.ready = this.connect();
+            this.ready.catch(()=>{});
+        }
+        await this.ready;
+        const id = this.nextId++;
+        return new Promise((resolve)=>{
+            this.pending.set(id, resolve);
+            this.writer.send(Buffer.from(JSON.stringify({
+                id,
+                tenant,
+                requests
+            }), 'utf8'));
+        });
+    }
+    close() {
+        this.socket?.end?.();
+        this.socket = void 0;
+    }
+}
+function toQueryResult(res) {
+    if ('error' === res.type) throw new Error(res.error.message);
+    const r = res.response.result;
+    const rows = r.rows.map((row)=>{
+        const obj = {};
+        r.cols.forEach((c, i)=>{
+            obj[c.name ?? `c${i}`] = fromHrana(row[i] ?? {
+                type: 'null'
+            });
+        });
+        return obj;
+    });
+    return {
+        rows,
+        rowsAffected: r.affected_row_count,
+        lastInsertRowid: r.last_insert_rowid ? Number(r.last_insert_rowid) : void 0
+    };
+}
+class OdbliteSocketConnection {
+    client;
+    tenant;
+    databaseName;
+    databaseHash;
+    sql;
+    buffer;
+    constructor(client, tenant, buffer){
+        this.client = client;
+        this.tenant = tenant;
+        this.databaseName = tenant;
+        this.databaseHash = tenant;
+        this.buffer = buffer;
+        const self = this;
+        this.sql = function(strings, ...values) {
+            if (strings && 'object' == typeof strings && 'raw' in strings) {
+                const text = strings.reduce((a, s, i)=>a + s + (i < values.length ? '?' : ''), '');
+                const returns = /^\s*SELECT/i.test(text) || /\bRETURNING\b/i.test(text);
+                return (returns ? self.query(text, values) : self.execute(text, values)).then((r)=>r.rows);
+            }
+            throw new Error('sql() fragment helper not implemented in odblite-socket');
+        };
+    }
+    async one(requests) {
+        const [res] = await this.client.pipeline(this.tenant, requests);
+        if (!res) throw new Error('odblite-socket: empty pipeline response');
+        return res;
+    }
+    async query(sql, params = []) {
+        return toQueryResult(await this.one([
+            {
+                type: 'execute',
+                stmt: {
+                    sql,
+                    args: params.map(toHrana)
+                }
+            }
+        ]));
+    }
+    async execute(sql, params = []) {
+        const s = 'string' == typeof sql ? sql : sql.sql;
+        const p = 'string' == typeof sql ? params : sql.args ?? [];
+        if (this.buffer) {
+            this.buffer.push({
+                sql: s,
+                params: p
+            });
+            return {
+                rows: [],
+                rowsAffected: 0
+            };
+        }
+        return toQueryResult(await this.one([
+            {
+                type: 'execute',
+                stmt: {
+                    sql: s,
+                    args: p.map(toHrana)
+                }
+            }
+        ]));
+    }
+    async atomic(steps) {
+        const res = await this.one([
+            {
+                type: 'batch',
+                batch: toBatch(steps)
+            }
+        ]);
+        if ('error' === res.type) throw new Error(res.error.message);
+        return res.response.result;
+    }
+    prepare(sql) {
+        return {
+            execute: async (params = [])=>this.execute(sql, params),
+            all: async (params = [])=>(await this.query(sql, params)).rows,
+            get: async (params = [])=>(await this.query(sql, params)).rows[0] ?? null
+        };
+    }
+    async transaction(fn) {
+        if (this.buffer) return fn(this);
+        const buffer = [];
+        const out = await fn(new OdbliteSocketConnection(this.client, this.tenant, buffer));
+        if (buffer.length) {
+            const res = await this.atomic(buffer.map((b)=>({
+                    sql: b.sql,
+                    params: b.params
+                })));
+            const err = res.step_errors?.find((e)=>e);
+            if (err) throw new Error(`transaction batch failed: ${err.message}`);
+        }
+        return out;
+    }
+    begin(fn) {
+        return this.transaction(fn);
+    }
+    savepoint(fn) {
+        return this.transaction(fn);
+    }
+    async ensureNamespaces(namespaces) {
+        return {
+            success: true,
+            databaseName: this.tenant,
+            namespaces
+        };
+    }
+    async getNamespaces() {
+        const ns = (await this.query("SELECT name FROM pragma_database_list WHERE name != 'main'")).rows.map((r)=>r.name);
+        return {
+            success: true,
+            databaseName: this.tenant,
+            exists: true,
+            namespaces: ns,
+            registered: true,
+            registeredNamespaces: ns
+        };
+    }
+    async close() {}
+}
+class OdbliteSocketAdapter {
+    type = 'odblite-socket';
+    client;
+    constructor(config){
+        this.client = new SocketClient(config);
+    }
+    async connect(config) {
+        const tenant = config?.databaseHash ?? config?.databaseName;
+        if (!tenant) throw new Error('odblite-socket: databaseHash (or databaseName) required');
+        return new OdbliteSocketConnection(this.client, String(tenant));
+    }
+    async disconnect() {
+        this.client.close();
+    }
+    async isHealthy() {
+        try {
+            await Promise.race([
+                this.client.pipeline('_health', [
+                    {
+                        type: 'get_autocommit'
+                    }
+                ]),
+                new Promise((_, rej)=>setTimeout(()=>rej(new Error('probe timeout')), 1500))
+            ]);
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+}
+const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock';
+function parseSocketTarget(s) {
+    const v = (s ?? '').trim();
+    if (!v) return {
+        unix: DEFAULT_UNIX_SOCKET
+    };
+    if (v.includes('/')) return {
+        unix: v
+    };
+    const m = v.match(/^(?:([^:]+):)?(\d+)$/);
+    if (m) return {
+        hostname: m[1] || '127.0.0.1',
+        port: Number(m[2])
+    };
+    return {
+        unix: v
+    };
+}
+class OdbliteAutoAdapter {
+    type = 'odblite';
+    chosen;
+    constructor(opts){
+        this.chosen = this.pick(opts);
+    }
+    async pick(opts) {
+        const hasBun = void 0 !== globalThis.Bun && !!globalThis.Bun.connect;
+        if (hasBun) for (const target of this.candidates(opts))try {
+            const socket = new OdbliteSocketAdapter(target);
+            if (await socket.isHealthy()) {
+                console.log(`[odb-client] transport → SOCKET (router_v2 @ ${target.unix ?? `${target.hostname}:${target.port}`})`);
+                return socket;
+            }
+            await socket.disconnect();
+        } catch  {}
+        console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)');
+        return new ODBLiteAdapter(opts.http);
+    }
+    candidates(opts) {
+        if (opts.socket?.unix || opts.socket?.port) return [
+            opts.socket
+        ];
+        const env = globalThis.process?.env?.ODB_SOCKET;
+        if (env) return [
+            parseSocketTarget(env)
+        ];
+        const out = [
+            {
+                unix: DEFAULT_UNIX_SOCKET
+            }
+        ];
+        try {
+            const host = new URL(opts.http?.serviceUrl).hostname;
+            const port = Number(globalThis.process?.env?.ODB_SOCKET_PORT ?? 8787);
+            if (host) out.push({
+                hostname: host,
+                port
+            });
+        } catch  {}
+        return out;
+    }
+    async connect(config) {
+        return (await this.chosen).connect(config);
+    }
+    async disconnect(tenantId) {
+        return (await this.chosen).disconnect(tenantId);
+    }
+    async isHealthy() {
+        return (await this.chosen).isHealthy();
+    }
+}
 function parseSQL(sqlContent, options = {}) {
     const separatePragma = options.separatePragma ?? true;
     const statements = splitStatements(sqlContent);
@@ -2157,7 +2568,14 @@ class DatabaseManager {
                 break;
             case 'odblite':
                 if (!config.odblite) throw new Error('odblite config required for odblite backend');
-                this.adapter = new ODBLiteAdapter(config.odblite);
+                this.adapter = new OdbliteAutoAdapter({
+                    socket: config.odbliteSocket,
+                    http: config.odblite
+                });
+                break;
+            case 'odblite-socket':
+                if (!config.odbliteSocket) throw new Error('odbliteSocket config required for odblite-socket backend');
+                this.adapter = new OdbliteSocketAdapter(config.odbliteSocket);
                 break;
             default:
                 throw new Error(`Unknown backend type: ${config.backend}`);
@@ -2275,6 +2693,12 @@ class DatabaseManager {
                     databaseName: `${this.config.databasePath}_${name}`,
                     ...this.config.odblite
                 };
+            case 'odblite-socket':
+                return {
+                    databaseName: name,
+                    databaseHash: name,
+                    ...this.config.odbliteSocket
+                };
             default:
                 throw new Error(`Unknown backend: ${this.config.backend}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pineliner/odb-client",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Isomorphic client for ODB-Lite with postgres.js-like template string SQL support",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/database/adapters/odblite-socket.ts

@@ -0,0 +1,255 @@
+import type { BackendType, Connection, DatabaseAdapter, PreparedStatement, QueryResult } from '../types'
+import { ODBLiteAdapter } from './odblite'
+import { SocketClient, type SocketTarget } from './socket/client'
+import {
+  toHrana,
+  fromHrana,
+  toBatch,
+  type AtomicStep,
+  type BatchResult,
+  type StmtResult,
+  type StreamRequest,
+  type StreamResult,
+} from './socket/protocol'
+
+/**
+ * odblite-socket — the FAST cross-process backend: raw socket + JSON framing to
+ * router_v2 (bun:sqlite engine). REPLACES the HTTP `odblite` backend (one hop, no
+ * HTTP parse) — it does NOT layer on it. Same `Connection` interface, so it's a
+ * drop-in: app-router flips `backend: 'odblite'` → `'odblite-socket'`.
+ *
+ * Write discipline (the separate-process model forces it): a unit of write work
+ * is ONE batch in ONE round-trip — the server runs BEGIN…COMMIT on its side, the
+ * client never holds the write slot across the wire. So `atomic(steps)` is the
+ * write primitive; `transaction(fn)` BUFFERS writes and flushes them as one
+ * atomic batch on commit (no read-your-own-uncommitted-writes mid-tx — that would
+ * re-create the slot-starvation the design avoids). Read-compute-write → read
+ * first, compute, write one atomic().
+ */
+function toQueryResult(res: StreamResult): QueryResult {
+  if (res.type === 'error') throw new Error(res.error.message)
+  const r = (res as any).response.result as StmtResult
+  const rows = r.rows.map((row) => {
+    const obj: Record<string, any> = {}
+    r.cols.forEach((c, i) => {
+      obj[c.name ?? `c${i}`] = fromHrana(row[i] ?? { type: 'null' })
+    })
+    return obj
+  })
+  return { rows, rowsAffected: r.affected_row_count, lastInsertRowid: r.last_insert_rowid ? Number(r.last_insert_rowid) : undefined }
+}
+
+class OdbliteSocketConnection implements Connection {
+  databaseName?: string
+  databaseHash?: string
+  public sql: any
+  private readonly buffer?: { sql: string; params: any[] }[]
+
+  constructor(
+    private readonly client: SocketClient,
+    private readonly tenant: string,
+    buffer?: { sql: string; params: any[] }[],
+  ) {
+    this.databaseName = tenant
+    this.databaseHash = tenant
+    this.buffer = buffer
+    const self = this
+    this.sql = function (strings: any, ...values: any[]): any {
+      if (strings && typeof strings === 'object' && 'raw' in strings) {
+        const text = (strings as string[]).reduce((a, s, i) => a + s + (i < values.length ? '?' : ''), '')
+        const returns = /^\s*SELECT/i.test(text) || /\bRETURNING\b/i.test(text)
+        return (returns ? self.query(text, values) : self.execute(text, values)).then((r: any) => r.rows)
+      }
+      throw new Error('sql() fragment helper not implemented in odblite-socket')
+    }
+  }
+
+  /** One request → its single result, failing loud on an empty response. */
+  private async one(requests: StreamRequest[]): Promise<StreamResult> {
+    const [res] = await this.client.pipeline(this.tenant, requests)
+    if (!res) throw new Error('odblite-socket: empty pipeline response')
+    return res
+  }
+
+  async query<T = any>(sql: string, params: any[] = []): Promise<QueryResult<T>> {
+    return toQueryResult(await this.one([{ type: 'execute', stmt: { sql, args: params.map(toHrana) } }])) as QueryResult<T>
+  }
+
+  async execute(sql: string | { sql: string; args?: any[] }, params: any[] = []): Promise<QueryResult> {
+    const s = typeof sql === 'string' ? sql : sql.sql
+    const p = typeof sql === 'string' ? params : (sql.args ?? [])
+    if (this.buffer) {
+      this.buffer.push({ sql: s, params: p }) // deferred → flushed as one batch on commit
+      return { rows: [], rowsAffected: 0 }
+    }
+    return toQueryResult(await this.one([{ type: 'execute', stmt: { sql: s, args: p.map(toHrana) } }]))
+  }
+
+  /** Guarded atomic batch — the primary remote write primitive (one round-trip). */
+  async atomic(steps: AtomicStep[]): Promise<BatchResult> {
+    const res = await this.one([{ type: 'batch', batch: toBatch(steps) }])
+    if (res.type === 'error') throw new Error(res.error.message)
+    return (res as any).response.result as BatchResult
+  }
+
+  prepare(sql: string): PreparedStatement {
+    return {
+      execute: async (params = []) => this.execute(sql, params),
+      all: async (params = []) => (await this.query(sql, params)).rows,
+      get: async (params = []) => (await this.query(sql, params)).rows[0] ?? null,
+    }
+  }
+
+  async transaction<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    if (this.buffer) return fn(this) // nested → same buffer
+    const buffer: { sql: string; params: any[] }[] = []
+    const out = await fn(new OdbliteSocketConnection(this.client, this.tenant, buffer))
+    if (buffer.length) {
+      const res = await this.atomic(buffer.map((b) => ({ sql: b.sql, params: b.params })))
+      const err = res.step_errors?.find((e) => e)
+      if (err) throw new Error(`transaction batch failed: ${err.message}`)
+    }
+    return out
+  }
+  begin<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    return this.transaction(fn)
+  }
+  savepoint<T>(fn: (tx: Connection) => Promise<T>): Promise<T> {
+    return this.transaction(fn)
+  }
+
+  // router_v2 auto-ATTACHes a tenant's namespaces on open → these are no-ops.
+  async ensureNamespaces(namespaces: string[]) {
+    return { success: true, databaseName: this.tenant, namespaces }
+  }
+  async getNamespaces() {
+    const ns = (await this.query("SELECT name FROM pragma_database_list WHERE name != 'main'")).rows.map((r: any) => r.name)
+    return { success: true, databaseName: this.tenant, exists: true, namespaces: ns, registered: true, registeredNamespaces: ns }
+  }
+
+  async close(): Promise<void> {
+    /* the SocketClient is shared + owned by the adapter; per-connection close is a no-op */
+  }
+}
+
+export interface OdbliteSocketConfig extends SocketTarget {}
+
+export class OdbliteSocketAdapter implements DatabaseAdapter {
+  readonly type: BackendType = 'odblite-socket'
+  private readonly client: SocketClient
+
+  constructor(config: OdbliteSocketConfig) {
+    this.client = new SocketClient(config)
+  }
+
+  async connect(config: any): Promise<Connection> {
+    const tenant = config?.databaseHash ?? config?.databaseName
+    if (!tenant) throw new Error('odblite-socket: databaseHash (or databaseName) required')
+    return new OdbliteSocketConnection(this.client, String(tenant))
+  }
+
+  async disconnect(): Promise<void> {
+    this.client.close()
+  }
+
+  async isHealthy(): Promise<boolean> {
+    try {
+      await Promise.race([
+        this.client.pipeline('_health', [{ type: 'get_autocommit' }]),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('probe timeout')), 1500)),
+      ])
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/** Default same-host unix socket (free — v1 only uses /tmp/odblite-internal.sock). */
+export const DEFAULT_UNIX_SOCKET = '/tmp/odblite.sock'
+
+/**
+ * Resolve the odblite-socket target from a string. `ODB_SOCKET` may be:
+ *   - a UNIX path  (`/tmp/odblite.sock`)        — same host, or a SHARED VOLUME mount
+ *   - `host:port`  (`odblite:8787`)             — TCP, the CROSS-CONTAINER Docker case
+ *   - `:port` / `port`                          — TCP on localhost
+ * A /tmp unix socket does NOT cross Docker containers, so container-to-container
+ * deployments set `ODB_SOCKET=odblite:8787` (TCP over the Docker network).
+ */
+export function parseSocketTarget(s?: string): SocketTarget {
+  const v = (s ?? '').trim()
+  if (!v) return { unix: DEFAULT_UNIX_SOCKET }
+  if (v.includes('/')) return { unix: v } // a path → unix socket
+  const m = v.match(/^(?:([^:]+):)?(\d+)$/) // host:port | :port | port → TCP
+  if (m) return { hostname: m[1] || '127.0.0.1', port: Number(m[2]) }
+  return { unix: v }
+}
+
+/**
+ * OdbliteAutoAdapter — the default for the `odblite` backend: ZERO config change,
+ * autodetected as a cascade  unix socket → TCP socket → HTTP. At startup it probes
+ * each in order and uses the FIRST that answers:
+ *   1. unix socket  /tmp/odblite.sock        — same host (fastest)
+ *   2. TCP socket   <ODB_LITE_URL host>:8787 — cross-container Docker; host is
+ *      DERIVED from the existing ODB_LITE_URL, so Docker needs no new config
+ *   3. HTTP         ODB_LITE_URL              — the universal fallback
+ * Explicit `ODB_SOCKET` (unix path or host:port) or an `odbliteSocket` config
+ * pins a single socket target instead of the cascade. So same-host dev and
+ * cross-container prod both "just work", and a missing/down socket → HTTP.
+ * (Browser / non-Bun → straight to HTTP.)
+ */
+export class OdbliteAutoAdapter implements DatabaseAdapter {
+  readonly type: BackendType = 'odblite'
+  private readonly chosen: Promise<DatabaseAdapter>
+
+  constructor(opts: { socket?: OdbliteSocketConfig; http: any }) {
+    this.chosen = this.pick(opts)
+  }
+
+  private async pick(opts: { socket?: OdbliteSocketConfig; http: any }): Promise<DatabaseAdapter> {
+    const hasBun = typeof (globalThis as any).Bun !== 'undefined' && !!(globalThis as any).Bun.connect
+    if (hasBun) {
+      for (const target of this.candidates(opts)) {
+        try {
+          const socket = new OdbliteSocketAdapter(target)
+          if (await socket.isHealthy()) {
+            console.log(`[odb-client] transport → SOCKET (router_v2 @ ${target.unix ?? `${target.hostname}:${target.port}`})`)
+            return socket
+          }
+          await socket.disconnect()
+        } catch {
+          /* try the next candidate */
+        }
+      }
+    }
+    console.log('[odb-client] transport → HTTP (no router_v2 socket reachable)')
+    return new ODBLiteAdapter(opts.http)
+  }
+
+  /** Ordered socket targets to probe. Explicit override → a single target; else the
+   *  zero-config cascade unix (same host) → TCP (host derived from ODB_LITE_URL). */
+  private candidates(opts: { socket?: OdbliteSocketConfig; http: any }): SocketTarget[] {
+    if (opts.socket?.unix || opts.socket?.port) return [opts.socket]
+    const env = (globalThis as any).process?.env?.ODB_SOCKET
+    if (env) return [parseSocketTarget(env)]
+    const out: SocketTarget[] = [{ unix: DEFAULT_UNIX_SOCKET }]
+    try {
+      const host = new URL(opts.http?.serviceUrl).hostname // e.g. odb-lite from http://odb-lite:8671
+      const port = Number((globalThis as any).process?.env?.ODB_SOCKET_PORT ?? 8787)
+      if (host) out.push({ hostname: host, port })
+    } catch {
+      /* serviceUrl unparseable → no TCP candidate, HTTP will catch it */
+    }
+    return out
+  }
+
+  async connect(config: any): Promise<Connection> {
+    return (await this.chosen).connect(config)
+  }
+  async disconnect(tenantId?: string): Promise<void> {
+    return (await this.chosen).disconnect(tenantId)
+  }
+  async isHealthy(): Promise<boolean> {
+    return (await this.chosen).isHealthy()
+  }
+}