@compforge/harness-toolbox 0.4.4 → 0.4.7

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-2171tajs.js → chunk-1ts7pswj.js}

@@ -2,13 +2,13 @@ import {
   findPodsForService,
   findService,
   listServiceNetwork
-} from "./chunk-j46x7j7c.js";
+} from "./chunk-xgnz10sr.js";
 import {
   findPod
 } from "./chunk-6fnhzhdb.js";
 import {
   PortForwardScope
-} from "./chunk-631vce5z.js";
+} from "./chunk-nftzckdy.js";
 
 // src/kubernetes/service-port-forward.ts
 class ServicePortForwarder {
@@ -24,13 +24,14 @@ class ServicePortForwarder {
     this.#scope = new PortForwardScope(starter);
   }
   static async create(executor, opts, starter) {
-    const network = await listServiceNetwork(executor, opts.namespace);
+    const network = await listServiceNetwork(executor, opts.namespace, opts.signal);
     return new ServicePortForwarder(opts, network.services, network.pods, starter);
   }
   get activeForwards() {
     return this.#scope.active;
   }
   forward(endpoint) {
+    this.opts.signal?.throwIfAborted();
     const key = `${endpoint.host}:${endpoint.port}`;
     let pending = this.#cache.get(key);
     if (!pending) {

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-mn6dwsvh.js → chunk-9shz0bw1.js}

@@ -24,7 +24,9 @@ function spawnProcess(argv, opts) {
     stdout: Readable.toWeb(child.stdout),
     stderr: Readable.toWeb(child.stderr),
     exited,
-    kill: () => child.kill()
+    kill: (signal) => {
+      child.kill(signal);
+    }
   };
 }
 function sleep(ms) {

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-wv4jwhvj.js → chunk-fqrknvr8.js}

@@ -1,9 +1,9 @@
 import {
   startPortForward
-} from "./chunk-631vce5z.js";
+} from "./chunk-nftzckdy.js";
 import {
   KubectlExecutor
-} from "./chunk-hmah9t8e.js";
+} from "./chunk-rq5fc007.js";
 import {
   POD_RELAY_SCRIPT
 } from "./chunk-ssj93brx.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-c2n8zvyn.js → chunk-m391jmpw.js}

@@ -1,21 +1,21 @@
+import {
+  resolveWorkload
+} from "./chunk-ae84rzq5.js";
 import {
   ServicePortForwarder
-} from "./chunk-2171tajs.js";
+} from "./chunk-1ts7pswj.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";
+} from "./chunk-rq5fc007.js";
 
 // src/kubernetes/client.ts
 class KubernetesClient {