@compforge/harness-toolbox 0.4.3 → 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:
 
@@ -376,3 +379,18 @@ reason. The caller owns shared transports such as `PodRelayTransport` and their
 
 Routed HTTPS preserves the original TLS server name. Bun disables HTTP keep-alive because its reused
 socket recovery can replay a failed request below the driver; Node retains connection pooling.
+
+## Kubernetes compute evidence
+
+`kubernetes/compute` exports `collectClusterCompute` and `collectWorkloadCompute`. They borrow
+ResourceAccess, use explicit deadlines/item/page budgets, and retain read coverage independently.
+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-8kts470p.js → chunk-g2bac2jd.js}

@@ -1,18 +1,18 @@
-import {
-  KubernetesResourceTransport
-} from "./chunk-4ms037k2.js";
 import {
   resolveWorkload
-} from "./chunk-0s27bgga.js";
+} from "./chunk-ae84rzq5.js";
 import {
   ServicePortForwarder
 } from "./chunk-2171tajs.js";
+import {
+  KubernetesResourceTransport
+} from "./chunk-x0yhfg29.js";
 import {
   KubernetesExecTransport
-} from "./chunk-shsabpc1.js";
+} from "./chunk-r3rnsvwv.js";
 import {
   KubernetesError
-} from "./chunk-20kv4wc3.js";
+} from "./chunk-rkt41za2.js";
 import {
   KubectlExecutor
 } from "./chunk-hmah9t8e.js";
@@ -83,6 +83,12 @@ class KubernetesClient {
   list(query, options) {
     return this.#track(() => this.#resourceAccess().list({ ...query, namespace: query.namespace ?? this.kube.namespace }, this.#options(options)));
   }
+  clusterResources() {
+    return {
+      get: (ref, options) => this.#track(() => this.#resourceAccess().get(ref, this.#options(options))),
+      list: (query, options) => this.#track(() => this.#resourceAccess().list(query, this.#options(options)))
+    };
+  }
   inNamespace(namespace) {
     if (!namespace.trim())
       throw new KubernetesError("Namespace is required", { kind: "invalid_argument" });

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() {