@compforge/harness-toolbox 0.4.0 → 0.4.1

package/README.md

@@ -103,7 +103,23 @@ selectorless Services and failed access raise KubernetesError.
 
 The resource path uses client-node kubeconfig authentication/TLS and bounded native JSON reads,
 not kubectl error text. Configure request timeout, concurrency and response bytes with the
-client's ResourceLimits constructor argument. Existing exec/port-forward operations remain unchanged.
+client's ResourceLimits constructor argument. Native exec uses the same root capacity/byte policy
+with a separate slot pool; its per-call timeout defaults to that policy and covers queueing,
+authentication, upgrade and execution. Explicit per-call timeouts support longer commands.
+
+Exec requires `get pods/exec` permission for the WebSocket upgrade (kubectl/SPDY paths may use
+`create pods/exec`). It connects directly to the Pod exec WebSocket endpoint without a preliminary Pod GET or
+kubectl subprocess. Each command owns a stream session; failures are never retried or replayed.
+Kubeconfig controls authentication, TLS and proxy access. stdout/stderr and remote exit status
+remain separate; retained output and individual messages are bounded. Streaming callers may
+set `collectStdout: false` and enforce their own total byte budget. Root disposal cancels active
+and queued sessions. Protocol v4 is accepted for output-only commands; stdin requires v5 to
+close input without losing remaining output/status. Bun does not expose HTTP upgrade rejection
+status, so those failures retain an unknown connection error. Native exec with a kubeconfig
+proxy requires Node: Bun cannot reliably release proxy sockets or preserve TLS name overrides.
+It fails before opening a session on Bun; use Node or explicitly provide an Executor adapter.
+The transport never bypasses the proxy or TLS checks.
+Port-forward still uses kubectl.
 See [the shared Workload model](../../../docs/workload.md).
 
 ```ts

package/dist/{chunk-y529s0mz.js → chunk-8kts470p.js}

@@ -7,6 +7,9 @@ import {
 import {
   ServicePortForwarder
 } from "./chunk-2171tajs.js";
+import {
+  KubernetesExecTransport
+} from "./chunk-shsabpc1.js";
 import {
   KubernetesError
 } from "./chunk-20kv4wc3.js";
@@ -24,11 +27,14 @@ class KubernetesClient {
   #forwarders = new Map;
   #operations = new Set;
   #disposal;
+  #exec;
+  #injectedExecutor;
   #resources;
   #transport;
   constructor(kube, signal, executor, resourceLimits = { timeoutMs: 30000, concurrency: 4, maxBytes: 8 * 1024 * 1024 }, resources) {
     this.kube = kube;
     this.resourceLimits = resourceLimits;
+    this.#injectedExecutor = executor;
     this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
     if (executor)
       this.#executors.set(kube.namespace, executor);
@@ -86,7 +92,7 @@ class KubernetesClient {
     };
   }
   exec(namespace, target, command, options) {
-    return this.#track(() => this.#executor(namespace).exec(target, command, this.#options(options)));
+    return this.#track(() => this.#injectedExecutor && namespace === this.kube.namespace ? this.#injectedExecutor.exec(target, command, this.#options(options)) : (this.#exec ??= new KubernetesExecTransport(this.kube, this.signal, this.resourceLimits)).exec(namespace, target, command, this.#options(options)));
   }
   forward(namespace, target) {
     return this.#track(async () => {

package/dist/chunk-shsabpc1.js

@@ -0,0 +1,267 @@
+import {
+  KubernetesError,
+  kubernetesHttpError
+} from "./chunk-20kv4wc3.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+
+// src/kubernetes/exec-transport.ts
+import { KubeConfig } from "@kubernetes/client-node";
+import WebSocket from "ws";
+class KubernetesExecTransport {
+  signal;
+  limits;
+  #config = new KubeConfig;
+  #capacity;
+  #server;
+  constructor(options, signal, limits) {
+    this.signal = signal;
+    this.limits = limits;
+    if (!Object.values(limits).every((value) => Number.isSafeInteger(value) && value > 0)) {
+      throw new KubernetesError("Exec limits must be positive integers", { kind: "invalid_argument" });
+    }
+    if (options.kubeconfig)
+      this.#config.loadFromFile(options.kubeconfig);
+    else
+      this.#config.loadFromDefault();
+    if (options.context)
+      this.#config.setCurrentContext(options.context);
+    const cluster = this.#config.getCurrentCluster();
+    if (!cluster)
+      throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
+    if (process.versions.bun && cluster.proxyUrl) {
+      throw new KubernetesError("Native exec through a kubeconfig proxy requires a Node host", { kind: "unsupported_operation" });
+    }
+    this.#server = cluster.server.replace(/\/$/, "");
+    if (new URL(cluster.server).protocol === "http:")
+      this.#config.clusters = this.#config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
+    this.#capacity = new ConcurrencyPool(limits.concurrency);
+  }
+  async exec(namespace, target, command, options = {}) {
+    const started = performance.now();
+    const timeoutMs = options.timeoutMs ?? this.limits.timeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || !namespace || !target.pod || !command.length) {
+      throw new KubernetesError("Exec requires a namespace, Pod, command and positive timeout", { kind: "invalid_argument" });
+    }
+    const caller = options.signal ? AbortSignal.any([this.signal, options.signal]) : this.signal;
+    const deadline = new AbortController;
+    const signal = AbortSignal.any([caller, deadline.signal]);
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    try {
+      return await this.#capacity.run(() => this.#session(namespace, target, command, options, signal, started, deadline.signal), signal);
+    } catch (error) {
+      if (caller.aborted)
+        throw caller.reason;
+      if (deadline.signal.aborted)
+        return this.#result(namespace, target, command, started, null, "", "Exec deadline exceeded", true);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #result(namespace, target, command, started, exitCode, stdout, stderr, timedOut = false) {
+    return {
+      ok: exitCode === 0 && !timedOut,
+      exitCode,
+      stdout,
+      stderr,
+      timedOut,
+      durationMs: performance.now() - started,
+      command: [
+        "kubernetes-api",
+        "exec",
+        "-n",
+        namespace,
+        target.pod,
+        ...target.container ? ["-c", target.container] : [],
+        "--",
+        ...command
+      ]
+    };
+  }
+  #session(namespace, target, command, options, signal, started, deadline) {
+    return new Promise((resolve, reject) => {
+      let socket;
+      let agent;
+      let input;
+      let settled = false;
+      let stdout = "", stderr = "", retained = 0;
+      const outDecoder = new TextDecoder, errDecoder = new TextDecoder;
+      const finish = (exitCode, error) => {
+        if (settled)
+          return;
+        settled = true;
+        signal.removeEventListener("abort", abort);
+        socket?.terminate();
+        agent?.destroy();
+        input?.cancel().catch(() => {});
+        const tail = outDecoder.decode(), errTail = errDecoder.decode();
+        if (options.collectStdout !== false)
+          stdout += tail;
+        stderr += errTail;
+        try {
+          if (tail)
+            options.onStdout?.(tail);
+          if (errTail)
+            options.onStderr?.(errTail);
+        } catch (cause) {
+          error ??= cause instanceof Error ? cause : new Error("Exec output callback failed");
+        }
+        if (error)
+          reject(error);
+        else
+          resolve(this.#result(namespace, target, command, started, exitCode, stdout, stderr, deadline.aborted));
+      };
+      const abort = () => {
+        if (deadline.aborted) {
+          stderr += `
+Exec deadline exceeded`;
+          finish(null);
+        } else
+          finish(null, signal.reason instanceof Error ? signal.reason : new Error("Exec aborted"));
+      };
+      const fail = (kind, cause) => finish(null, new KubernetesError(`Kubernetes exec ${namespace}/${target.pod} failed`, { kind, cause }));
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      signal.addEventListener("abort", abort, { once: true });
+      const request = { headers: {} };
+      this.#config.applyToHTTPSOptions(request).then(() => {
+        agent = request.agent;
+        if (settled || signal.aborted) {
+          agent?.destroy();
+          return;
+        }
+        const url = new URL(`${this.#server}/api/v1/namespaces/${encodeURIComponent(namespace)}/pods/${encodeURIComponent(target.pod)}/exec`);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        for (const arg of command)
+          url.searchParams.append("command", arg);
+        url.searchParams.set("stdout", "true");
+        url.searchParams.set("stderr", "true");
+        url.searchParams.set("stdin", String(options.stdin !== undefined));
+        url.searchParams.set("tty", "false");
+        if (target.container)
+          url.searchParams.set("container", target.container);
+        socket = new WebSocket(url, options.stdin === undefined ? ["v5.channel.k8s.io", "v4.channel.k8s.io"] : ["v5.channel.k8s.io"], { ...request, ...process.versions.bun ? { tls: {
+          ca: request.ca,
+          cert: request.cert,
+          key: request.key,
+          pfx: request.pfx,
+          passphrase: request.passphrase,
+          rejectUnauthorized: request.rejectUnauthorized,
+          serverName: request.servername
+        } } : {}, maxPayload: this.limits.maxBytes, handshakeTimeout: this.limits.timeoutMs });
+        if (!process.versions.bun)
+          socket.on("unexpected-response", (request2, response) => {
+            const status = response.statusCode ?? 500;
+            response.destroy();
+            request2.destroy();
+            const failure = kubernetesHttpError(status);
+            finish(null, new KubernetesError(`Kubernetes exec ${namespace}/${target.pod} HTTP ${status}`, {
+              kind: failure.kind,
+              code: status
+            }));
+          });
+        socket.on("error", (error) => fail("connection_failed", error));
+        socket.on("close", () => {
+          if (!settled)
+            fail("connection_lost");
+        });
+        socket.on("message", (data, binary) => {
+          if (settled)
+            return;
+          try {
+            if (!binary)
+              throw new Error("Exec frame must be binary");
+            const frame = Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+            if (!frame.length)
+              throw new Error("Empty exec frame");
+            if (frame.length > this.limits.maxBytes) {
+              fail("limit_exceeded");
+              return;
+            }
+            const channel = frame[0], payload = frame.subarray(1);
+            if (channel === 255) {
+              if (payload.length !== 1 || ![0, 1, 2].includes(payload[0]))
+                throw new Error("Invalid channel close");
+              return;
+            }
+            if (channel === 3) {
+              const status = JSON.parse(payload.toString("utf8"));
+              if (status.status === "Success") {
+                finish(0);
+                return;
+              }
+              const code = status.details?.causes?.find((cause) => cause.reason === "ExitCode")?.message;
+              if (status.status !== "Failure" || !/^\d+$/.test(code ?? ""))
+                throw new Error("Exec status lacks exit code");
+              if (!Number.isSafeInteger(Number(code)))
+                throw new Error("Invalid exit code");
+              finish(Number(code));
+              return;
+            }
+            if (channel !== 1 && channel !== 2)
+              throw new Error("Invalid exec channel");
+            if (channel === 2 || options.collectStdout !== false)
+              retained += payload.length;
+            if (retained > this.limits.maxBytes) {
+              fail("limit_exceeded");
+              return;
+            }
+            if (channel === 1) {
+              options.onStdoutBytes?.(payload);
+              const text = outDecoder.decode(payload, { stream: true });
+              if (options.collectStdout !== false)
+                stdout += text;
+              options.onStdout?.(text);
+            } else {
+              const text = errDecoder.decode(payload, { stream: true });
+              stderr += text;
+              options.onStderr?.(text);
+            }
+          } catch (error) {
+            fail("invalid_response", error);
+          }
+        });
+        socket.on("open", () => {
+          if (options.stdin === undefined || settled)
+            return;
+          const send = (bytes) => new Promise((done, failed) => {
+            if (settled) {
+              failed(new Error("Exec closed"));
+              return;
+            }
+            socket.send(Buffer.concat([Buffer.from([0]), bytes]), (error) => error ? failed(error) : done());
+          });
+          (async () => {
+            const stdin = options.stdin;
+            if (typeof stdin === "string" || stdin instanceof Uint8Array)
+              await send(typeof stdin === "string" ? new TextEncoder().encode(stdin) : stdin);
+            else {
+              const reader = stdin.getReader();
+              input = reader;
+              while (!settled) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                  break;
+                await send(chunk.value);
+              }
+            }
+            if (!settled)
+              socket.send(Buffer.from([255, 0]));
+          })().catch((error) => {
+            if (!settled)
+              fail("connection_failed", error);
+          });
+        });
+      }).catch((error) => {
+        if (!settled)
+          fail("connection_failed", error);
+      });
+    });
+  }
+}
+
+export { KubernetesExecTransport };

package/dist/kubernetes/client.js

@@ -1,12 +1,13 @@
 import {
   KubernetesClient
-} from "../chunk-y529s0mz.js";
+} from "../chunk-8kts470p.js";
 import"../chunk-4ms037k2.js";
 import"../chunk-0s27bgga.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
 import"../chunk-ftkrjqkc.js";
+import"../chunk-shsabpc1.js";
 import"../chunk-a9htb6cr.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";

package/dist/kubernetes/environment.js

@@ -1,12 +1,13 @@
 import {
   KubernetesClient
-} from "../chunk-y529s0mz.js";
+} from "../chunk-8kts470p.js";
 import"../chunk-4ms037k2.js";
 import"../chunk-0s27bgga.js";
 import"../chunk-2171tajs.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
 import"../chunk-ftkrjqkc.js";
+import"../chunk-shsabpc1.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";

package/dist/kubernetes/exec-transport.d.ts

@@ -0,0 +1,19 @@
+import type { ExecTarget, ExecResult, RunOptions } from "./executor";
+import type { KubernetesConnectionOptions } from "./resource-transport";
+export interface KubernetesExecLimits {
+    timeoutMs: number;
+    concurrency: number;
+    maxBytes: number;
+}
+/**
+ * @spec Each exec owns one channel session; it is never retried or replayed.
+ * @rule The root owns configuration and capacity. Deadlines cover queueing, auth, upgrade and execution.
+ * @why A WebSocket upgrade cannot reuse an ordinary HTTP request connection as another exec session.
+ */
+export declare class KubernetesExecTransport {
+    #private;
+    private readonly signal;
+    private readonly limits;
+    constructor(options: KubernetesConnectionOptions, signal: AbortSignal, limits: KubernetesExecLimits);
+    exec(namespace: string, target: ExecTarget, command: string[], options?: RunOptions): Promise<ExecResult>;
+}

package/dist/kubernetes/exec-transport.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -106,16 +106,15 @@
     "@redis/client": "6.1.0",
     "@smithy/node-http-handler": "4.12.1",
     "mysql2": "3.23.1",
-    "node-fetch": "2.7.0"
+    "node-fetch": "2.7.0",
+    "ws": "8.21.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.6.0",
     "@types/node-fetch": "2.6.13",
-    "@types/node": "^22"
-  },
-  "overrides": {
-    "@compforge/harness-common": "file:../common"
+    "@types/node": "^22",
+    "@types/ws": "^8.18.1"
   },
   "publishConfig": {
     "access": "public"