@compforge/harness-toolbox 0.4.4 → 0.4.5

package/README.md

@@ -173,6 +173,9 @@ the root owns cancellation and must join child work before disposing clients.
 
 Catch ToolboxError from the root entry or `@compforge/harness-toolbox/errors`; use `kind` and
 `code` for decisions. Native `cause` may contain sensitive details and is debug-only.
+Connection acquisition deadlines and Redis handshake/command deadlines raise `TimeoutError`
+from `@compforge/harness-toolbox/errors`. It extends `ToolboxError`, retaining
+`kind: "timeout"` and `code: "ETIMEDOUT"`; OpenSearch preserves it unchanged.
 
 For coordinated common/toolbox development, install and build common before installing toolbox:
 
@@ -384,3 +387,10 @@ ResourceAccess, use explicit deadlines/item/page budgets, and retain read covera
 Use `client.clusterResources()` for Nodes and all-namespace Pods; normal client methods retain their
 configured namespace. A forbidden cluster read records `permission_denied`; it does not block a
 separate namespace-scoped Workload read. See [compute collection](../../../docs/toolbox.md#kubernetes-compute-evidence).
+
+### Connection acquisition deadlines
+
+MySQL, OpenSearch and Redis use the same acquisition lifecycle. `connectTimeoutMs` includes route mapping
+and handshake/probe; optional `acquireTimeoutMs` bounds all routes together (default: per-route budget × route count).
+Cancellation preserves the caller reason and prevents late mappings from starting a handshake. Query and command
+timeouts remain separate, and failed operations are never replayed on another transport.

package/dist/chunk-835fssgz.js

@@ -0,0 +1,37 @@
+// src/mysql/connection.ts
+import { createConnection } from "mysql2";
+async function connectMysql(options, signal) {
+  signal?.throwIfAborted();
+  const native = createConnection(options);
+  const connection = native.promise();
+  let abort;
+  try {
+    await new Promise((resolve, reject) => {
+      abort = () => {
+        destroyMysqlConnection(connection);
+        reject(signal.reason);
+      };
+      signal?.addEventListener("abort", abort, { once: true });
+      native.connect((error) => error ? reject(error) : resolve());
+      if (signal?.aborted)
+        abort();
+    });
+    signal?.throwIfAborted();
+    return connection;
+  } catch (error) {
+    destroyMysqlConnection(connection);
+    throw error;
+  } finally {
+    signal?.removeEventListener("abort", abort);
+  }
+}
+function destroyMysqlConnection(connection) {
+  const native = connection.connection;
+  try {
+    connection.destroy();
+  } finally {
+    native.stream.destroy();
+  }
+}
+
+export { connectMysql, destroyMysqlConnection };

package/dist/{chunk-0s27bgga.js → chunk-ae84rzq5.js}

@@ -1,6 +1,6 @@
 import {
   KubernetesError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 
 // src/kubernetes/workload.ts
 function failure(message, kind) {

package/dist/{chunk-age65q4n.js → chunk-db4an9td.js}

@@ -1,6 +1,6 @@
 import {
   destroyMysqlConnection
-} from "./chunk-136egyff.js";
+} from "./chunk-835fssgz.js";
 
 // src/mysql/readonly.ts
 function validateQueryLimits(limits) {

package/dist/{chunk-ftkrjqkc.js → chunk-dpcge1xt.js}

@@ -1,6 +1,6 @@
 import {
   KubernetesError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 
 // src/kubernetes/resources.ts
 function resourcePath(query, name) {

package/dist/{chunk-grpygk6f.js → chunk-dx6yvj81.js}

@@ -2,10 +2,10 @@ import {
   BoundedFileClient,
   fileClientOptions,
   filePaths
-} from "./chunk-kkts16w9.js";
+} from "./chunk-ww11q58v.js";
 import {
   FileError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 
 // src/file/pod.ts
 import { posix } from "node:path";

package/dist/{chunk-sqbew04a.js → chunk-f3vq900j.js}

@@ -2,10 +2,10 @@ import {
   BoundedFileClient,
   fileClientOptions,
   filePaths
-} from "./chunk-kkts16w9.js";
+} from "./chunk-ww11q58v.js";
 import {
   FileError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 
 // src/file/local.ts
 import { constants } from "node:fs";

package/dist/{chunk-yp6tcw22.js → chunk-f98qrpx1.js}

@@ -1,9 +1,13 @@
+import {
+  acquireConnection,
+  awaitWithSignal
+} from "./chunk-gm4swndx.js";
 import {
   discoverRedisTopology
 } from "./chunk-5tbzf9wd.js";
 import {
-  ToolboxError
-} from "./chunk-20kv4wc3.js";
+  TimeoutError
+} from "./chunk-rkt41za2.js";
 import {
   isConnectionNetworkError
 } from "./chunk-h8fwx0k7.js";
@@ -41,26 +45,6 @@ function parseRedisInfo(raw) {
   }
   return result;
 }
-async function abortable(pending, signal, cancel) {
-  if (signal.aborted) {
-    cancel?.();
-    pending.catch(() => {});
-    signal.throwIfAborted();
-  }
-  let abort;
-  const cancelled = new Promise((_, reject) => {
-    abort = () => {
-      cancel?.();
-      reject(signal.reason);
-    };
-    signal.addEventListener("abort", abort, { once: true });
-  });
-  try {
-    return await Promise.race([pending, cancelled]);
-  } finally {
-    signal.removeEventListener("abort", abort);
-  }
-}
 
 class RedisConnection {
   endpoint;
@@ -101,7 +85,7 @@ class RedisConnection {
       lastError = err instanceof Error ? err : new Error(String(err));
     });
     const timeout = new AbortController;
-    const timer = setTimeout(() => timeout.abort(new ToolboxError("Redis handshake timed out", { kind: "timeout", code: "ETIMEDOUT" })), config.connectTimeoutMs ?? config.timeoutMs);
+    const timer = setTimeout(() => timeout.abort(new TimeoutError("Redis handshake timed out")), config.connectTimeoutMs ?? config.timeoutMs);
     const signal = AbortSignal.any([
       timeout.signal,
       ...config.signal ? [config.signal] : [],
@@ -112,7 +96,7 @@ class RedisConnection {
         client.destroy();
     };
     try {
-      await abortable(client.connect(), signal, close);
+      await awaitWithSignal(client.connect(), signal, close);
       signal.throwIfAborted();
       return new RedisConnection(endpoint, client, config.timeoutMs, () => lastError, config.signal);
     } catch (error) {
@@ -132,10 +116,10 @@ class RedisConnection {
       throw new Error(`Redis connection is closed${reason ? `: ${reason}` : ""}`);
     }
     const timeout = new AbortController;
-    const timer = setTimeout(() => timeout.abort(new ToolboxError(`Redis ${operationName} timed out after ${this.timeoutMs}ms (${this.endpoint.host}:${this.endpoint.port})`, { kind: "timeout", code: "ETIMEDOUT" })), this.timeoutMs);
+    const timer = setTimeout(() => timeout.abort(new TimeoutError(`Redis ${operationName} timed out after ${this.timeoutMs}ms (${this.endpoint.host}:${this.endpoint.port})`)), this.timeoutMs);
     const signal = this.signal ? AbortSignal.any([this.signal, timeout.signal]) : timeout.signal;
     try {
-      return await abortable(Promise.resolve().then(() => {
+      return await awaitWithSignal(Promise.resolve().then(() => {
         signal.throwIfAborted();
         return operation();
       }), signal, () => this.close());
@@ -229,58 +213,34 @@ class RedisAccess {
     });
     return pending;
   }
-  async#open(endpoint, database, credentials) {
-    const timeout = new AbortController;
-    const attemptBudget = this.baseConfig.connectTimeoutMs ?? this.baseConfig.timeoutMs;
-    const budget = this.baseConfig.acquireTimeoutMs ?? attemptBudget * this.#transports.length;
-    const deadline = performance.now() + budget;
-    const timer = setTimeout(() => timeout.abort(new ToolboxError(`Redis connection timed out after ${budget}ms (${endpoint.host}:${endpoint.port})`, { kind: "timeout", code: "ETIMEDOUT" })), budget);
-    const signal = AbortSignal.any([this.#signal, timeout.signal]);
-    let reason;
-    try {
-      for (let index = 0;index < this.#transports.length; index++) {
-        signal.throwIfAborted();
-        const transport = this.#transports[index];
-        const attempt = new AbortController;
-        const remaining = Math.min(attemptBudget, Math.max(1, Math.ceil(deadline - performance.now())));
-        const attemptTimer = setTimeout(() => attempt.abort(new ToolboxError(`Redis connection attempt timed out (${transport.name})`, { kind: "timeout", code: "ETIMEDOUT" })), remaining);
-        const attemptSignal = AbortSignal.any([signal, attempt.signal]);
-        try {
-          const mapped = await abortable(transport.connect(endpoint), attemptSignal);
-          attemptSignal.throwIfAborted();
-          const pending = this.connectionFactory(endpoint, mapped, {
-            ...this.baseConfig,
-            ...credentials,
-            database,
-            connectTimeoutMs: remaining,
-            signal: this.#signal,
-            connectSignal: attemptSignal
-          });
-          const prepared = pending.then((connection2) => {
-            if (attemptSignal.aborted) {
-              connection2.close();
-              attemptSignal.throwIfAborted();
-            }
-            return connection2;
-          });
-          const connection = await abortable(prepared, attemptSignal);
-          this.lifecycle.onRoute?.({ transport: mapped.host === endpoint.host && mapped.port === endpoint.port ? "direct" : transport.name, reason });
-          return connection;
-        } catch (failure) {
-          signal.throwIfAborted();
-          const error = attemptSignal.aborted ? attemptSignal.reason : failure;
-          const network = isConnectionNetworkError(error) || error instanceof SocketClosedUnexpectedlyError || error instanceof ConnectionTimeoutError;
-          if (!network || index === this.#transports.length - 1)
-            throw error;
-          reason = error instanceof SocketClosedUnexpectedlyError ? "connection_lost" : error instanceof ConnectionTimeoutError ? "ETIMEDOUT" : String(error.code);
-        } finally {
-          clearTimeout(attemptTimer);
-        }
+  #open(endpoint, database, credentials) {
+    return acquireConnection(this.#transports, {
+      name: "Redis connection",
+      signal: this.#signal,
+      connectTimeoutMs: this.baseConfig.connectTimeoutMs ?? this.baseConfig.timeoutMs,
+      acquireTimeoutMs: this.baseConfig.acquireTimeoutMs,
+      onRoute: this.lifecycle.onRoute,
+      open: async (transport, attempt) => {
+        const mapped = await transport.connect(endpoint);
+        const connection = await this.connectionFactory(endpoint, mapped, {
+          ...this.baseConfig,
+          ...credentials,
+          database,
+          connectTimeoutMs: attempt.remainingMs(),
+          signal: this.#signal,
+          connectSignal: attempt.signal
+        });
+        return { connection, transport: mapped.host === endpoint.host && mapped.port === endpoint.port ? "direct" : transport.name };
+      },
+      close: (connection) => connection.close(),
+      retryReason: (error) => {
+        if (error instanceof SocketClosedUnexpectedlyError)
+          return "connection_lost";
+        if (error instanceof ConnectionTimeoutError)
+          return "ETIMEDOUT";
+        return isConnectionNetworkError(error) ? String(error.code) : undefined;
       }
-      throw new Error("Redis requires a TCP transport");
-    } finally {
-      clearTimeout(timer);
-    }
+    });
   }
   close() {
     return this.#closing ??= (async () => {
@@ -319,7 +279,7 @@ class RedisClient {
   initialize() {
     this.signal.throwIfAborted();
     return this.#initialization ??= (async () => {
-      this.#target = await this.source.resolve();
+      this.#target = await awaitWithSignal(this.source.resolve(), this.signal);
       this.signal.throwIfAborted();
       if (!this.source.transports.length || this.source.transports.some((transport) => transport.kind !== "tcp")) {
         throw new Error("Redis requires TCP transports");

package/dist/{chunk-c2n8zvyn.js → chunk-g2bac2jd.js}

@@ -1,18 +1,18 @@
+import {
+  resolveWorkload
+} from "./chunk-ae84rzq5.js";
 import {
   ServicePortForwarder
 } from "./chunk-2171tajs.js";
 import {
   KubernetesResourceTransport
-} from "./chunk-4ms037k2.js";
+} from "./chunk-x0yhfg29.js";
 import {
   KubernetesExecTransport
-} from "./chunk-shsabpc1.js";
-import {
-  resolveWorkload
-} from "./chunk-0s27bgga.js";
+} from "./chunk-r3rnsvwv.js";
 import {
   KubernetesError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   KubectlExecutor
 } from "./chunk-hmah9t8e.js";

package/dist/chunk-gm4swndx.js

@@ -0,0 +1,106 @@
+import {
+  TimeoutError,
+  ToolboxError
+} from "./chunk-rkt41za2.js";
+
+// src/connection/acquire.ts
+async function awaitWithSignal(pending, signal, cancel) {
+  if (signal.aborted) {
+    cancel?.();
+    pending.catch(() => {});
+    signal.throwIfAborted();
+  }
+  let abort;
+  const cancelled = new Promise((_, reject) => {
+    abort = () => {
+      cancel?.();
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", abort, { once: true });
+  });
+  try {
+    return await Promise.race([pending, cancelled]);
+  } finally {
+    signal.removeEventListener("abort", abort);
+  }
+}
+async function acquireConnection(routes, options) {
+  const budget = options.acquireTimeoutMs ?? options.connectTimeoutMs * routes.length;
+  if (!routes.length)
+    throw new ToolboxError(`${options.name} requires a transport`, { kind: "invalid_argument" });
+  if ([options.connectTimeoutMs, budget].some((value) => !Number.isFinite(value) || value <= 0 || value > 2147483647)) {
+    throw new ToolboxError(`${options.name} timeouts must be positive milliseconds within timer range`, { kind: "invalid_argument" });
+  }
+  options.signal?.throwIfAborted();
+  const timeout = new AbortController;
+  const timedOut = (message) => new TimeoutError(message);
+  const deadline = performance.now() + budget;
+  const timer = setTimeout(() => timeout.abort(timedOut(`${options.name} timed out after ${budget}ms`)), budget);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout.signal]) : timeout.signal;
+  let reason;
+  try {
+    for (const [index, route] of routes.entries()) {
+      if (performance.now() >= deadline)
+        timeout.abort(timedOut(`${options.name} timed out after ${budget}ms`));
+      signal.throwIfAborted();
+      const attempt = new AbortController;
+      const end = Math.min(deadline, performance.now() + options.connectTimeoutMs);
+      const expire = () => attempt.abort(timedOut(`${options.name} attempt timed out (${route.name})`));
+      const attemptTimer = setTimeout(expire, Math.max(1, Math.ceil(end - performance.now())));
+      const attemptSignal = AbortSignal.any([signal, attempt.signal]);
+      const context = {
+        signal: attemptSignal,
+        remainingMs: () => {
+          if (performance.now() >= end)
+            expire();
+          attemptSignal.throwIfAborted();
+          return Math.max(1, Math.ceil(end - performance.now()));
+        }
+      };
+      let candidate;
+      let discarded = false;
+      const discard = async () => {
+        if (!candidate || discarded)
+          return;
+        discarded = true;
+        await options.close(candidate.connection);
+      };
+      let result;
+      try {
+        const prepared = options.open(route, context).then(async (value) => {
+          candidate = value;
+          if (attemptSignal.aborted) {
+            await discard();
+            attemptSignal.throwIfAborted();
+          }
+          return value;
+        });
+        result = await awaitWithSignal(prepared, attemptSignal);
+      } catch (failure) {
+        await discard();
+        signal.throwIfAborted();
+        const error = attemptSignal.aborted ? attemptSignal.reason : failure;
+        reason = options.retryReason(error);
+        if (reason === undefined || index === routes.length - 1)
+          throw error;
+        continue;
+      } finally {
+        clearTimeout(attemptTimer);
+      }
+      try {
+        attemptSignal.throwIfAborted();
+        options.onRoute?.({ transport: result.transport, reason });
+        attemptSignal.throwIfAborted();
+        return result.connection;
+      } catch (error) {
+        await discard();
+        throw error;
+      }
+    }
+    throw new Error("Connection routes exhausted");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export { awaitWithSignal, acquireConnection };

package/dist/{chunk-shsabpc1.js → chunk-r3rnsvwv.js}

@@ -1,7 +1,7 @@
 import {
   KubernetesError,
   kubernetesHttpError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/{chunk-20kv4wc3.js → chunk-rkt41za2.js}

@@ -15,6 +15,12 @@ class KubernetesError extends ToolboxError {
 
 class FileError extends ToolboxError {
 }
+
+class TimeoutError extends ToolboxError {
+  constructor(message, options) {
+    super(message, { kind: "timeout", code: "ETIMEDOUT", cause: options?.cause });
+  }
+}
 function kubernetesHttpError(status) {
   const kind = {
     401: "authentication_failed",
@@ -41,4 +47,4 @@ function kubernetesCommandError(result) {
   return status ? kubernetesHttpError(status) : new KubernetesError("Kubernetes resource request failed", { kind: "operation_failed" });
 }
 
-export { ToolboxError, KubernetesError, FileError, kubernetesHttpError, kubernetesCommandError };
+export { ToolboxError, KubernetesError, FileError, TimeoutError, kubernetesHttpError, kubernetesCommandError };

package/dist/{chunk-8mb6natq.js → chunk-sbt20n84.js}

@@ -1,6 +1,10 @@
+import {
+  acquireConnection,
+  awaitWithSignal
+} from "./chunk-gm4swndx.js";
 import {
   ToolboxError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   isConnectionNetworkError
 } from "./chunk-h8fwx0k7.js";
@@ -68,6 +72,15 @@ class OpenSearchEngine {
     return this.client.close();
   }
 }
+function openSearchRetryReason(error) {
+  if (isConnectionNetworkError(error))
+    return String(error.code);
+  if (error instanceof errors.TimeoutError)
+    return "ETIMEDOUT";
+  if (error instanceof errors.ConnectionError)
+    return error.name;
+  return;
+}
 
 class OpenSearchClient {
   source;
@@ -86,44 +99,49 @@ class OpenSearchClient {
   initialize() {
     this.signal.throwIfAborted();
     return this.#initialization ??= (async () => {
-      const target = await this.source.resolve();
+      const target = await awaitWithSignal(this.source.resolve(), this.signal);
       this.signal.throwIfAborted();
       const original = new URL(target.node);
-      let reason;
-      for (const [index, transport] of this.source.transports.entries()) {
+      try {
+        this.#engine = await acquireConnection(this.source.transports, {
+          name: "OpenSearch connection",
+          signal: this.signal,
+          connectTimeoutMs: target.connectTimeoutMs ?? target.requestTimeoutMs ?? 1e4,
+          acquireTimeoutMs: target.acquireTimeoutMs,
+          onRoute: this.lifecycle.onRoute,
+          open: async (transport, attempt) => {
+            if (transport.kind !== "tcp")
+              throw new Error("OpenSearch requires a TCP transport");
+            const endpoint = await transport.connect({
+              host: original.hostname,
+              port: Number(original.port || (original.protocol === "https:" ? 443 : 80)),
+              servername: target.servername ?? original.hostname
+            });
+            attempt.signal.throwIfAborted();
+            const url = new URL(original);
+            url.hostname = endpoint.host;
+            url.port = String(endpoint.port);
+            const engine = new OpenSearchEngine({ ...target, node: url.toString(), servername: endpoint.servername ?? target.servername ?? original.hostname });
+            try {
+              await engine.ping(attempt.signal, attempt.remainingMs());
+              return { connection: engine, transport: transport.name };
+            } catch (error) {
+              await engine.close();
+              throw error;
+            }
+          },
+          close: (engine) => engine.close(),
+          retryReason: openSearchRetryReason
+        });
+      } catch (error) {
         this.signal.throwIfAborted();
-        if (transport.kind !== "tcp")
-          throw new Error("OpenSearch requires a TCP transport");
-        let engine;
-        try {
-          const endpoint = await transport.connect({
-            host: original.hostname,
-            port: Number(original.port || (original.protocol === "https:" ? 443 : 80)),
-            servername: target.servername ?? original.hostname
-          });
-          this.signal.throwIfAborted();
-          const url = new URL(original);
-          url.hostname = endpoint.host;
-          url.port = String(endpoint.port);
-          engine = new OpenSearchEngine({ ...target, node: url.toString(), servername: endpoint.servername ?? target.servername ?? original.hostname });
-          await engine.ping(this.signal, target.connectTimeoutMs ?? target.requestTimeoutMs ?? 1e4);
-          this.signal.throwIfAborted();
-          this.lifecycle.onRoute?.({ transport: transport.name, reason });
-          this.#engine = engine;
-          return;
-        } catch (error) {
-          await engine?.close();
-          this.signal.throwIfAborted();
-          const network = isConnectionNetworkError(error);
-          if (!network && !(error instanceof errors.ConnectionError) && !(error instanceof errors.TimeoutError))
-            throw error;
-          reason = network ? String(error.code) : error.name;
-          if (index === this.source.transports.length - 1) {
-            throw new ToolboxError(`OpenSearch connect failed (${reason})`, { kind: "connection_failed", code: reason, cause: error });
-          }
-        }
+        if (error instanceof ToolboxError && error.kind === "timeout")
+          throw error;
+        const reason = openSearchRetryReason(error);
+        if (reason === undefined)
+          throw error;
+        throw new ToolboxError(`OpenSearch connect failed (${reason})`, { kind: "connection_failed", code: reason, cause: error });
       }
-      throw new Error("OpenSearch DataSource has no transport");
     })();
   }
   #ready() {

package/dist/{chunk-h73h2b7y.js → chunk-t4hrnaj0.js}

@@ -5,13 +5,18 @@ import {
 import {
   queryReadonlySession,
   validateQueryLimits
-} from "./chunk-age65q4n.js";
+} from "./chunk-db4an9td.js";
 import {
+  connectMysql,
   destroyMysqlConnection
-} from "./chunk-136egyff.js";
+} from "./chunk-835fssgz.js";
+import {
+  acquireConnection,
+  awaitWithSignal
+} from "./chunk-gm4swndx.js";
 import {
   ToolboxError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
@@ -20,7 +25,6 @@ import {
 } from "./chunk-h8fwx0k7.js";
 
 // src/mysql/client.ts
-import { createConnection } from "mysql2/promise";
 function mysqlOperationError(error, phase) {
   if (!error || typeof error !== "object" || !("code" in error) || error.code !== "PROTOCOL_CONNECTION_LOST")
     return error;
@@ -37,7 +41,7 @@ class MysqlDatabase {
   connect;
   #queries = new ConcurrencyPool(1);
   #connections = new Map;
-  constructor(transports, options, connect = createConnection) {
+  constructor(transports, options, connect = connectMysql) {
     this.transports = transports;
     this.options = options;
     this.connect = connect;
@@ -120,39 +124,40 @@ class MysqlDatabase {
       return rows;
     });
   }
-  async#open(target) {
-    let reason;
-    for (let i = 0;i < this.transports.length; i++) {
-      const transport = this.transports[i];
-      this.options.signal?.throwIfAborted();
-      if (transport.kind === "python") {
-        this.options.onRoute?.({ transport: transport.name, reason });
-        return { kind: "python", transport };
-      }
-      try {
-        const endpoint = await transport.connect(target);
-        const connection = await this.connect({
-          host: endpoint.host,
-          port: endpoint.port,
-          user: target.user,
-          password: target.password,
-          database: target.database,
-          connectTimeout: this.options.connectTimeoutMs,
-          dateStrings: true,
-          supportBigNumbers: true,
-          bigNumberStrings: true
-        });
-        this.options.onRoute?.({ transport: endpoint.host === target.host && endpoint.port === target.port ? "direct" : transport.name, reason });
-        return { kind: "tcp", connection };
-      } catch (error) {
-        const failure = mysqlOperationError(error, "connect");
-        const connectionLost = failure instanceof ToolboxError && failure.kind === "connection_lost";
-        if (!isConnectionNetworkError(failure) && !connectionLost || i === this.transports.length - 1)
-          throw failure;
-        reason = String(failure.code);
-      }
-    }
-    throw new Error("MySQL DataSource has no transport");
+  #open(target) {
+    return acquireConnection(this.transports, {
+      name: "MySQL connection",
+      ...this.options,
+      open: async (transport, attempt) => {
+        if (transport.kind === "python")
+          return { connection: { kind: "python", transport }, transport: transport.name };
+        try {
+          const endpoint = await transport.connect(target);
+          const connection = await this.connect({
+            host: endpoint.host,
+            port: endpoint.port,
+            user: target.user,
+            password: target.password,
+            database: target.database,
+            connectTimeout: attempt.remainingMs(),
+            dateStrings: true,
+            supportBigNumbers: true,
+            bigNumberStrings: true
+          }, attempt.signal);
+          return {
+            connection: { kind: "tcp", connection },
+            transport: endpoint.host === target.host && endpoint.port === target.port ? "direct" : transport.name
+          };
+        } catch (error) {
+          throw mysqlOperationError(error, "connect");
+        }
+      },
+      close: (session) => {
+        if (session.kind === "tcp")
+          destroyMysqlConnection(session.connection);
+      },
+      retryReason: (error) => isConnectionNetworkError(error) || error instanceof ToolboxError && error.kind === "connection_lost" ? String(error.code) : undefined
+    });
   }
   async queryOne(target, sql, values) {
     return (await this.query(target, sql, values))[0];
@@ -186,7 +191,7 @@ class MysqlClient {
   initialize() {
     this.signal.throwIfAborted();
     return this.#initialization ??= (async () => {
-      this.#target = await this.source.resolve();
+      this.#target = await awaitWithSignal(this.source.resolve(), this.signal);
       this.signal.throwIfAborted();
       this.#database = new MysqlDatabase(this.source.transports, { ...this.options, signal: this.signal });
       await this.#database.initialize(this.#target);

package/dist/{chunk-kkts16w9.js → chunk-ww11q58v.js}

@@ -1,7 +1,7 @@
 import {
   FileError,
   ToolboxError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/{chunk-4ms037k2.js → chunk-x0yhfg29.js}

@@ -1,6 +1,6 @@
 import {
   resourcePath
-} from "./chunk-ftkrjqkc.js";
+} from "./chunk-dpcge1xt.js";
 import {
   clientKey
 } from "./chunk-a9htb6cr.js";
@@ -8,7 +8,7 @@ import {
   KubernetesError,
   ToolboxError,
   kubernetesHttpError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/{chunk-5zgz1z41.js → chunk-z15gwjvg.js}

@@ -1,6 +1,6 @@
 import {
   KubernetesError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 
 // src/kubernetes/compute-quantity.ts
 function object(value) {

package/dist/connection/acquire.d.ts

@@ -0,0 +1,34 @@
+import type { ClientLifecycle } from "../datasource";
+/** Stop waiting without leaving rejected preparation promises unobserved. */
+export declare function awaitWithSignal<T>(pending: Promise<T>, signal: AbortSignal, cancel?: () => void): Promise<T>;
+export interface ConnectionAttempt {
+    readonly signal: AbortSignal;
+    /** Remaining mapping + handshake budget, not a fresh timeout for each phase. */
+    remainingMs(): number;
+}
+interface Acquisition<R, C> {
+    name: string;
+    connectTimeoutMs: number;
+    acquireTimeoutMs?: number;
+    signal?: AbortSignal;
+    open(route: R, attempt: ConnectionAttempt): Promise<{
+        connection: C;
+        transport: string;
+    }>;
+    close(connection: C): void | Promise<void>;
+    /** Undefined means terminal; authentication and protocol errors must not change route. */
+    retryReason(error: unknown): string | undefined;
+    onRoute?: ClientLifecycle["onRoute"];
+}
+/**
+ * @spec One acquisition owns ordered attempts and a deadline covering mapping and handshake.
+ * @spec Cancellation keeps its original reason; a late successful connection is closed, never published.
+ * @rule Only connection preparation enters this function. Commands and queries must never be replayed.
+ * @why Protocol adapters own partial handles and error classification; all protocols share the same lifecycle.
+ * @see {@link component://docs/toolbox.md}
+ * @case id=connection_mapping_cancel,desc=`Cancel while mapping a route`,expect=`Acquisition exits without a late handshake`
+ */
+export declare function acquireConnection<R extends {
+    readonly name: string;
+}, C>(routes: readonly R[], options: Acquisition<R, C>): Promise<C>;
+export {};

package/dist/connection/acquire.js

@@ -0,0 +1,9 @@
+import {
+  acquireConnection,
+  awaitWithSignal
+} from "../chunk-gm4swndx.js";
+import"../chunk-rkt41za2.js";
+export {
+  awaitWithSignal,
+  acquireConnection
+};

package/dist/datasource.js

@@ -6,7 +6,7 @@ import {
 import {
   KubernetesError,
   ToolboxError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 export {
   clientKey,
   ToolboxError,

package/dist/errors.d.ts

@@ -13,6 +13,10 @@ export declare class KubernetesError extends ToolboxError {
 }
 export declare class FileError extends ToolboxError {
 }
+/** A local deadline expiry, distinct from a connection failure reported by a driver. */
+export declare class TimeoutError extends ToolboxError {
+    constructor(message: string, options?: ErrorOptions);
+}
 export declare function kubernetesHttpError(status: number): KubernetesError;
 /**
  * Normalize a failed kubectl resource request at the transport boundary.

package/dist/errors.js

@@ -1,14 +1,16 @@
 import {
   FileError,
   KubernetesError,
+  TimeoutError,
   ToolboxError,
   kubernetesCommandError,
   kubernetesHttpError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 export {
   kubernetesHttpError,
   kubernetesCommandError,
   ToolboxError,
+  TimeoutError,
   KubernetesError,
   FileError
 };

package/dist/file/client.js

@@ -2,8 +2,8 @@ import {
   BoundedFileClient,
   fileClientOptions,
   filePaths
-} from "../chunk-kkts16w9.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-ww11q58v.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   filePaths,

package/dist/file/index.js

@@ -1,15 +1,15 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-grpygk6f.js";
+} from "../chunk-dx6yvj81.js";
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-sqbew04a.js";
-import"../chunk-kkts16w9.js";
+} from "../chunk-f3vq900j.js";
+import"../chunk-ww11q58v.js";
 import {
   FileError
-} from "../chunk-20kv4wc3.js";
+} from "../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 
 // src/file/index.ts

package/dist/file/local.js

@@ -1,9 +1,9 @@
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-sqbew04a.js";
-import"../chunk-kkts16w9.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-f3vq900j.js";
+import"../chunk-ww11q58v.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   LocalFileDataSource,

package/dist/file/pod.js

@@ -1,9 +1,9 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-grpygk6f.js";
-import"../chunk-kkts16w9.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-dx6yvj81.js";
+import"../chunk-ww11q58v.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   PodFileDataSource,

package/dist/kubernetes/client.js

@@ -1,15 +1,15 @@
 import {
   KubernetesClient
-} from "../chunk-c2n8zvyn.js";
+} from "../chunk-g2bac2jd.js";
+import"../chunk-ae84rzq5.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-4ms037k2.js";
-import"../chunk-ftkrjqkc.js";
-import"../chunk-shsabpc1.js";
-import"../chunk-0s27bgga.js";
+import"../chunk-x0yhfg29.js";
+import"../chunk-dpcge1xt.js";
+import"../chunk-r3rnsvwv.js";
 import"../chunk-a9htb6cr.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-631vce5z.js";
 import"../chunk-hmah9t8e.js";

package/dist/kubernetes/compute-quantity.js

@@ -8,8 +8,8 @@ import {
   sum,
   summarizePods,
   zero
-} from "../chunk-5zgz1z41.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-z15gwjvg.js";
+import"../chunk-rkt41za2.js";
 export {
   zero,
   summarizePods,

package/dist/kubernetes/compute.js

@@ -6,10 +6,10 @@ import {
   requiredString,
   sum,
   summarizePods
-} from "../chunk-5zgz1z41.js";
+} from "../chunk-z15gwjvg.js";
 import {
   KubernetesError
-} from "../chunk-20kv4wc3.js";
+} from "../chunk-rkt41za2.js";
 
 // src/kubernetes/compute.ts
 function requestBudget(options) {

package/dist/kubernetes/environment.js

@@ -1,17 +1,17 @@
 import {
   KubernetesClient
-} from "../chunk-c2n8zvyn.js";
+} from "../chunk-g2bac2jd.js";
+import"../chunk-ae84rzq5.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-4ms037k2.js";
-import"../chunk-ftkrjqkc.js";
-import"../chunk-shsabpc1.js";
-import"../chunk-0s27bgga.js";
+import"../chunk-x0yhfg29.js";
+import"../chunk-dpcge1xt.js";
+import"../chunk-r3rnsvwv.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-631vce5z.js";
 import"../chunk-hmah9t8e.js";

package/dist/kubernetes/exec-transport.js

@@ -1,7 +1,7 @@
 import {
   KubernetesExecTransport
-} from "../chunk-shsabpc1.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-r3rnsvwv.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   KubernetesExecTransport

package/dist/kubernetes/pod-log-datasource.js

@@ -8,7 +8,7 @@ import"../chunk-a9htb6cr.js";
 import {
   clientKey
 } from "../chunk-z5pm2emz.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 
 // src/kubernetes/pod-log-datasource.ts

package/dist/kubernetes/resource-transport.js

@@ -1,9 +1,9 @@
 import {
   KubernetesResourceTransport
-} from "../chunk-4ms037k2.js";
-import"../chunk-ftkrjqkc.js";
+} from "../chunk-x0yhfg29.js";
+import"../chunk-dpcge1xt.js";
 import"../chunk-a9htb6cr.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 export {
   KubernetesResourceTransport

package/dist/kubernetes/resources.js

@@ -1,7 +1,7 @@
 import {
   resourcePath
-} from "../chunk-ftkrjqkc.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-dpcge1xt.js";
+import"../chunk-rkt41za2.js";
 export {
   resourcePath
 };

package/dist/kubernetes/workload.js

@@ -1,7 +1,7 @@
 import {
   resolveWorkload
-} from "../chunk-0s27bgga.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-ae84rzq5.js";
+import"../chunk-rkt41za2.js";
 export {
   resolveWorkload
 };

package/dist/mysql/client.d.ts

@@ -1,13 +1,16 @@
 import type { Client } from "../client";
-import { type Connection, type ConnectionOptions } from "mysql2/promise";
+import type { Connection, ConnectionOptions } from "mysql2/promise";
 import type { Database, DatabaseTarget, DatabaseRow, DatabaseQueryLimits, DatabaseQueryResult, SqlStatement } from "./types";
 import type { ConnectionSource, ClientLifecycle } from "../datasource";
 import { type Transport } from "../transport";
 export interface MysqlDatabaseOptions extends ClientLifecycle {
+    /** Per-route mapping and handshake budget. */
     connectTimeoutMs: number;
+    /** Total acquisition budget; defaults to connectTimeoutMs times the route count. */
+    acquireTimeoutMs?: number;
     queryTimeoutMs: number;
 }
-type ConnectionFactory = (options: ConnectionOptions) => Promise<Connection>;
+type ConnectionFactory = (options: ConnectionOptions, signal?: AbortSignal) => Promise<Connection>;
 /**
  * @spec SQL is executed once; only native connection establishment may advance to another transport.
  * @why mysql2 reports a socket closed during handshake as PROTOCOL_CONNECTION_LOST, before any SQL is sent.

package/dist/mysql/client.js

@@ -2,11 +2,12 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-h73h2b7y.js";
+} from "../chunk-t4hrnaj0.js";
 import"../chunk-m91t44jh.js";
-import"../chunk-age65q4n.js";
-import"../chunk-136egyff.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-db4an9td.js";
+import"../chunk-835fssgz.js";
+import"../chunk-gm4swndx.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";

package/dist/mysql/connection.d.ts

@@ -1,3 +1,6 @@
+import { type ConnectionOptions } from "mysql2";
 import type { Connection } from "mysql2/promise";
+/** Keep the native handle available so cancellation can destroy an unfinished handshake. */
+export declare function connectMysql(options: ConnectionOptions, signal?: AbortSignal): Promise<Connection>;
 /** @why Disposal must release the socket even when the peer never finishes its TCP half-close. */
 export declare function destroyMysqlConnection(connection: Connection): void;

package/dist/mysql/connection.js

@@ -1,6 +1,8 @@
 import {
+  connectMysql,
   destroyMysqlConnection
-} from "../chunk-136egyff.js";
+} from "../chunk-835fssgz.js";
 export {
-  destroyMysqlConnection
+  destroyMysqlConnection,
+  connectMysql
 };

package/dist/mysql/index.js

@@ -1,3 +1,4 @@
+import"../chunk-pfar9cm3.js";
 import {
   withReadScope
 } from "../chunk-4sqvppz7.js";
@@ -5,9 +6,9 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-h73h2b7y.js";
+} from "../chunk-t4hrnaj0.js";
 import"../chunk-m91t44jh.js";
-import"../chunk-age65q4n.js";
+import"../chunk-db4an9td.js";
 import {
   parseMysqlEnvTarget
 } from "../chunk-qq77x9ek.js";
@@ -16,9 +17,9 @@ import {
   limitedStatement,
   queryLimited
 } from "../chunk-1gyshqd9.js";
-import"../chunk-136egyff.js";
-import"../chunk-pfar9cm3.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-835fssgz.js";
+import"../chunk-gm4swndx.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";

package/dist/mysql/readonly.js

@@ -1,8 +1,8 @@
 import {
   queryReadonlySession,
   validateQueryLimits
-} from "../chunk-age65q4n.js";
-import"../chunk-136egyff.js";
+} from "../chunk-db4an9td.js";
+import"../chunk-835fssgz.js";
 export {
   validateQueryLimits,
   queryReadonlySession

package/dist/opensearch/client.d.ts

@@ -9,8 +9,10 @@ export interface OpenSearchOptions {
     node: string;
     auth: OpenSearchAuth;
     requestTimeoutMs?: number;
-    /** Deadline for the initialization probe; query deadlines remain independent. */
+    /** Per-route mapping and probe budget; query deadlines remain independent. */
     connectTimeoutMs?: number;
+    /** Total acquisition budget; defaults to the per-route budget times the route count. */
+    acquireTimeoutMs?: number;
     /** Original TLS identity when a transport maps the socket to localhost. */
     servername?: string;
 }

package/dist/opensearch/client.js

@@ -3,8 +3,9 @@ import {
   OpenSearchEngine,
   isOpenSearchReadApi,
   openOpenSearch
-} from "../chunk-8mb6natq.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-sbt20n84.js";
+import"../chunk-gm4swndx.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";
 import"../chunk-631vce5z.js";

package/dist/opensearch/index.js

@@ -10,8 +10,9 @@ import {
   OpenSearchEngine,
   isOpenSearchReadApi,
   openOpenSearch
-} from "../chunk-8mb6natq.js";
-import"../chunk-20kv4wc3.js";
+} from "../chunk-sbt20n84.js";
+import"../chunk-gm4swndx.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";
 import"../chunk-631vce5z.js";

package/dist/redis/client.js

@@ -4,9 +4,10 @@ import {
   RedisConnection,
   openRedis,
   parseRedisInfo
-} from "../chunk-yp6tcw22.js";
+} from "../chunk-f98qrpx1.js";
+import"../chunk-gm4swndx.js";
 import"../chunk-5tbzf9wd.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";
 import"../chunk-631vce5z.js";

package/dist/redis/index.js

@@ -1,18 +1,19 @@
-import {
-  collectRedisKeyStats,
-  redisGroupedSampleSizes
-} from "../chunk-jr9y0ghr.js";
 import {
   RedisAccess,
   RedisClient,
   RedisConnection,
   openRedis,
   parseRedisInfo
-} from "../chunk-yp6tcw22.js";
+} from "../chunk-f98qrpx1.js";
+import"../chunk-gm4swndx.js";
+import {
+  collectRedisKeyStats,
+  redisGroupedSampleSizes
+} from "../chunk-jr9y0ghr.js";
 import {
   discoverRedisTopology
 } from "../chunk-5tbzf9wd.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";
 import"../chunk-631vce5z.js";

package/dist/s3/datasource.js

@@ -2,7 +2,7 @@ import {
   S3DataSource
 } from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import"../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";

package/dist/s3/index.js

@@ -2,7 +2,7 @@ import {
   S3DataSource
 } from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
-import"../chunk-20kv4wc3.js";
+import"../chunk-rkt41za2.js";
 import {
   S3Client
 } from "../chunk-zp1s833x.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {

package/dist/chunk-136egyff.js

@@ -1,11 +0,0 @@
-// src/mysql/connection.ts
-function destroyMysqlConnection(connection) {
-  const native = connection.connection;
-  try {
-    connection.destroy();
-  } finally {
-    native.stream.destroy();
-  }
-}
-
-export { destroyMysqlConnection };