@compforge/harness-toolbox 0.3.1 → 0.3.3

package/README.md

@@ -156,3 +156,50 @@ is not an arbitrary-SQL sandbox. This API requires MySQL 5.7.8+ `max_execution_t
 fall back to Pod Python. Completion, truncation, timeout, and cancellation destroy the disposable
 session without replay or changes to ordinary borrowed sessions. Disconnect does not prove immediate
 server cancellation. The byte budget limits retained JSON rows, not individual wire packets or fields.
+
+## Shared Pod relay transport
+
+`PodRelayTransport` opens TCP routes through an existing Running/Ready Pod. It discovers an
+eligible container in the selected namespace (optionally restricted by a label selector); the
+current implementation uses Python 3.8+ standard-library asyncio. Callers supply endpoints,
+not a Pod name or interpreter. It creates no Pods and installs no packages. The selected Pod
+must be able to resolve and reach each destination.
+
+Create one transport in the root execution's ClientManager and lend it to all Service/protocol
+clients. Its key describes cluster access and relay policy, never a Service or database identity.
+Concurrent callers share Pod discovery, one relay process and one forward per host/port. Database
+credentials and connections remain owned by their protocol clients.
+
+```ts
+import { ClientManager } from '@compforge/harness-toolbox';
+import { PodRelayTransport } from '@compforge/harness-toolbox/transport';
+
+const clients = new ClientManager();
+try {
+  const relay = await clients.get({
+    clientKey: 'transport:customer-cluster:app',
+    createClient: (_clients, signal) => new PodRelayTransport({
+      kubeconfig: '/config/cluster', context: 'customer', namespace: 'app',
+      selector: 'diagnostic-relay=eligible',
+      startupTimeoutMs: 5000, connectTimeoutMs: 5000,
+      maxConnections: 16, maxTargets: 8, maxCandidatePods: 8, signal,
+    }),
+  });
+  // The same instance belongs in each protocol client's ConnectionSource.transports.
+  const address = await relay.connect({host: 'database.internal', port: 3306});
+  // Connect the native protocol client to address; do not dispose relay in a Service.
+} finally {
+  await clients.dispose();
+}
+```
+
+The host must authorize `list pods`, `create pods/exec` and `create pods/portforward`, including
+running a temporary process in the selected container. List/discovery and each readiness operation
+use startupTimeoutMs; candidate Pod count, target count and aggregate live relay connections are
+bounded separately. List pods is namespace scoped. Relay listeners bind only to Pod loopback and
+local forwards only to host loopback. Control messages contain destinations, never DB credentials.
+
+Disposal closes forwards and the exec stream; EOF closes remote listeners/connections. If an exec
+connection is lost without EOF, a 30-second heartbeat lease bounds remote process lifetime.
+A dead relay invalidates its routes and fails callers; no SQL or other protocol operation is replayed.
+The root should finish or cancel protocol work before disposing the transport.

package/dist/{chunk-0cq1gx86.js → chunk-35cjec9z.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-zp1s833x.js";
 import {
   DirectTransport
-} from "./chunk-xy4g56g4.js";
+} from "./chunk-h8fwx0k7.js";
 
 // src/s3/datasource.ts
 class S3DataSource {

package/dist/chunk-5fgbhx2r.js

@@ -0,0 +1,253 @@
+import {
+  startPortForward
+} from "./chunk-xh3zwhjh.js";
+import {
+  KubectlExecutor
+} from "./chunk-hmah9t8e.js";
+import {
+  POD_RELAY_SCRIPT
+} from "./chunk-ssj93brx.js";
+
+// src/transport/pod-relay.ts
+class PodRelayTransport {
+  options;
+  kind = "tcp";
+  name = "pod-relay";
+  #controller = new AbortController;
+  #signal;
+  #executor;
+  #startForward;
+  #targets = new Map;
+  #pending = new Map;
+  #forwards = [];
+  #startup;
+  #execution;
+  #input;
+  #heartbeat;
+  #failure;
+  #disposal;
+  #sequence = 0;
+  constructor(options, dependencies) {
+    this.options = options;
+    for (const key of ["startupTimeoutMs", "connectTimeoutMs", "maxConnections", "maxTargets", "maxCandidatePods"]) {
+      if (!Number.isSafeInteger(options[key]) || options[key] <= 0)
+        throw new Error(`${key} must be a positive integer`);
+    }
+    this.#executor = dependencies?.executor ?? new KubectlExecutor(options);
+    this.#startForward = dependencies?.startForward ?? startPortForward;
+    this.#signal = options.signal ? AbortSignal.any([options.signal, this.#controller.signal]) : this.#controller.signal;
+    this.#signal.addEventListener("abort", this.#onAbort, { once: true });
+  }
+  async initialize() {
+    this.#check();
+  }
+  #check() {
+    this.#signal.throwIfAborted();
+    if (this.#failure)
+      throw this.#failure;
+  }
+  #onAbort = () => {
+    this.#fail(new Error("Pod relay aborted"));
+  };
+  #fail(error) {
+    this.#failure ??= error;
+    if (this.#heartbeat)
+      clearInterval(this.#heartbeat);
+    if (this.#input) {
+      try {
+        this.#input.close();
+      } catch {}
+    }
+    this.#input = undefined;
+    for (const pending of this.#pending.values())
+      pending.reject(this.#failure);
+    this.#pending.clear();
+    for (const forward of this.#forwards.splice(0))
+      forward.stop();
+  }
+  async#select() {
+    const command = ["get", "pods", "--field-selector=status.phase=Running", "-o", "json"];
+    if (this.options.selector)
+      command.push("-l", this.options.selector);
+    const listed = await this.#executor.run(command, { timeoutMs: this.options.startupTimeoutMs, signal: this.#signal });
+    if (!listed.ok)
+      throw new Error("Cannot discover an existing Pod for relay");
+    const pods = JSON.parse(listed.stdout).items.filter((pod) => pod.status?.phase === "Running" && !pod.metadata?.deletionTimestamp).sort((a, b) => (a.metadata?.name ?? "").localeCompare(b.metadata?.name ?? "")).slice(0, this.options.maxCandidatePods);
+    for (const pod of pods) {
+      if (!pod.metadata?.name)
+        continue;
+      for (const container of pod.status?.containerStatuses ?? []) {
+        if (!container.ready)
+          continue;
+        const target = { pod: pod.metadata.name, container: container.name };
+        for (const executable of ["python3", "python"]) {
+          this.#check();
+          const probe = await this.#executor.exec(target, [executable, "-c", "import asyncio,sys; assert sys.version_info >= (3, 8); print('relay-ready')"], { timeoutMs: this.options.startupTimeoutMs, signal: this.#signal });
+          if (probe.ok && probe.stdout.trim() === "relay-ready")
+            return { target, executable };
+        }
+      }
+    }
+    throw new Error("No eligible existing Pod can run the TCP relay");
+  }
+  async#start() {
+    const pod = await this.#select();
+    this.#check();
+    const input = new ReadableStream({ start: (controller) => {
+      this.#input = controller;
+    } });
+    let ready;
+    let rejectReady;
+    const readiness = new Promise((resolve, reject) => {
+      ready = resolve;
+      rejectReady = reject;
+    });
+    let buffered = "";
+    const config = {
+      connectTimeoutMs: this.options.connectTimeoutMs,
+      maxConnections: this.options.maxConnections,
+      maxTargets: this.options.maxTargets,
+      leaseMs: 30000
+    };
+    this.#execution = this.#executor.exec(pod.target, [pod.executable, "-u", "-c", POD_RELAY_SCRIPT, JSON.stringify(config)], {
+      stdin: input,
+      signal: this.#signal,
+      timeoutMs: 2147483647,
+      collectStdout: false,
+      onStdout: (chunk) => {
+        buffered += chunk;
+        if (buffered.length > 65536) {
+          this.#fail(new Error("Pod relay control response exceeded limit"));
+          return;
+        }
+        while (buffered.includes(`
+`)) {
+          const end = buffered.indexOf(`
+`);
+          const line = buffered.slice(0, end);
+          buffered = buffered.slice(end + 1);
+          try {
+            const response = JSON.parse(line);
+            if (response.ready)
+              ready();
+            else if (response.id !== undefined) {
+              const pending = this.#pending.get(response.id);
+              this.#pending.delete(response.id);
+              if (Number.isInteger(response.port) && response.port > 0 && response.port <= 65535)
+                pending?.resolve(response.port);
+              else
+                pending?.reject(new Error("Pod relay listener unavailable"));
+            }
+          } catch {
+            this.#fail(new Error("Invalid Pod relay control response"));
+          }
+        }
+      }
+    }).then(() => {
+      const error = new Error("Pod relay execution ended");
+      rejectReady(error);
+      this.#fail(error);
+    }, () => {
+      const error = new Error("Pod relay execution failed");
+      rejectReady(error);
+      this.#fail(error);
+    });
+    this.#heartbeat = setInterval(() => {
+      try {
+        this.#send({ heartbeat: true });
+      } catch {
+        this.#fail(new Error("Pod relay control channel closed"));
+      }
+    }, 5000);
+    const timer = setTimeout(() => rejectReady(new Error("Pod relay startup timed out")), this.options.startupTimeoutMs);
+    try {
+      await readiness;
+      this.#check();
+      return pod;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #send(value) {
+    this.#check();
+    if (!this.#input)
+      throw new Error("Pod relay control channel unavailable");
+    this.#input.enqueue(new TextEncoder().encode(`${JSON.stringify(value)}
+`));
+  }
+  connect(endpoint) {
+    this.#check();
+    if (!endpoint.host || !Number.isInteger(endpoint.port) || endpoint.port < 1 || endpoint.port > 65535) {
+      return Promise.reject(new Error("Invalid relay endpoint"));
+    }
+    const key = JSON.stringify([endpoint.host, endpoint.port]);
+    let pending = this.#targets.get(key);
+    if (!pending) {
+      if (this.#targets.size >= this.options.maxTargets)
+        return Promise.reject(new Error("Pod relay target limit reached"));
+      this.#startup ??= this.#start().catch((error) => {
+        this.#fail(error instanceof Error ? error : new Error("Pod relay startup failed"));
+        throw error;
+      });
+      pending = this.#connect(endpoint, this.#startup);
+      this.#targets.set(key, pending);
+    }
+    return pending.then((local) => ({ ...local, servername: endpoint.servername ?? endpoint.host }));
+  }
+  async#connect(endpoint, startup) {
+    const pod = await startup;
+    this.#check();
+    const id = ++this.#sequence;
+    const remotePort = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new Error("Pod relay listener timed out"));
+      }, this.options.startupTimeoutMs);
+      this.#pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+      try {
+        this.#send({ id, host: endpoint.host, port: endpoint.port });
+      } catch (error) {
+        this.#pending.get(id)?.reject(error);
+        this.#pending.delete(id);
+      }
+    });
+    this.#check();
+    const forwarded = await this.#startForward({
+      ...this.options,
+      target: { kind: "pod", name: pod.target.pod },
+      remotePort,
+      timeoutMs: this.options.startupTimeoutMs
+    });
+    if (!forwarded.ok || !forwarded.value)
+      throw new Error("Pod relay port-forward unavailable");
+    try {
+      this.#check();
+    } catch (error) {
+      forwarded.value.stop();
+      throw error;
+    }
+    this.#forwards.push(forwarded.value);
+    return { host: "127.0.0.1", port: forwarded.value.localPort };
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("Pod relay disposed"));
+      this.#fail(new Error("Pod relay disposed"));
+      await Promise.allSettled(this.#targets.values());
+      await this.#execution;
+      this.#signal.removeEventListener("abort", this.#onAbort);
+      this.#targets.clear();
+    })();
+  }
+}
+
+export { PodRelayTransport };

package/dist/{chunk-0rs1aacd.js → chunk-hmah9t8e.js}

@@ -1,6 +1,6 @@
 import {
   spawnProcess
-} from "./chunk-ztenxgjv.js";
+} from "./chunk-mn6dwsvh.js";
 
 // src/kubernetes/executor.ts
 function buildKubectlArgs(opts, sub) {

package/dist/{chunk-jkpwa8tb.js → chunk-jx740hjh.js}

@@ -3,14 +3,15 @@ import {
   validateQueryLimits
 } from "./chunk-kbewz29a.js";
 import {
-  queryMysqlViaPod
-} from "./chunk-s06hs7a8.js";
+  queryMysqlViaPod,
+  queryMysqlViaPodBatch
+} from "./chunk-m91t44jh.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
 import {
   isConnectionNetworkError
-} from "./chunk-xy4g56g4.js";
+} from "./chunk-h8fwx0k7.js";
 
 // src/mysql/client.ts
 import { createConnection } from "mysql2/promise";
@@ -28,6 +29,22 @@ class MysqlDatabase {
   query(target, sql, values) {
     return this.#queries.run(() => this.#query(target, sql, values), this.options.signal);
   }
+  queryBatch(target, statements) {
+    return this.#queries.run(async () => {
+      if (!statements.length)
+        return [];
+      return this.#withSession(target, async (session) => {
+        if (session.kind === "python")
+          return queryMysqlViaPodBatch(session.transport, target, statements, this.options);
+        const results = [];
+        for (const { sql, values } of statements) {
+          const [rows] = await session.connection.execute({ sql, values: [...values], timeout: this.options.queryTimeoutMs });
+          results.push(rows);
+        }
+        return results;
+      });
+    }, this.options.signal);
+  }
   queryReadonly(target, sql, values, limits) {
     validateQueryLimits(limits);
     return this.#queries.run(async () => {
@@ -60,7 +77,7 @@ class MysqlDatabase {
     }
     return pending;
   }
-  async#query(target, sql, values) {
+  async#withSession(target, run) {
     this.options.signal?.throwIfAborted();
     const key = [target.host, target.port, target.database, target.user, target.password].join("\x00");
     const pending = this.#session(target);
@@ -68,10 +85,7 @@ class MysqlDatabase {
     try {
       session = await pending;
       this.options.signal?.throwIfAborted();
-      if (session.kind === "python")
-        return await queryMysqlViaPod(session.transport, target, sql, values, this.options);
-      const [rows] = await session.connection.execute({ sql, values: [...values], timeout: this.options.queryTimeoutMs });
-      return rows;
+      return await run(session);
     } catch (error) {
       if (this.#connections.get(key) === pending)
         this.#connections.delete(key);
@@ -80,6 +94,14 @@ class MysqlDatabase {
       throw error;
     }
   }
+  async#query(target, sql, values) {
+    return this.#withSession(target, async (session) => {
+      if (session.kind === "python")
+        return queryMysqlViaPod(session.transport, target, sql, values, this.options);
+      const [rows] = await session.connection.execute({ sql, values: [...values], timeout: this.options.queryTimeoutMs });
+      return rows;
+    });
+  }
   async#open(target) {
     let reason;
     for (let i = 0;i < this.transports.length; i++) {

package/dist/{chunk-s06hs7a8.js → chunk-m91t44jh.js}

@@ -50,9 +50,20 @@ try:
     )
     try:
         with connection.cursor(pymysql.cursors.DictCursor) as cursor:
-            cursor.execute(request["sql"], request["values"])
-            rows = cursor.fetchall()
-        print(json.dumps({"rows": rows}, default=encode, ensure_ascii=False))
+            statements = request.get("statements")
+            if statements is None:
+                cursor.execute(request["sql"], request["values"])
+                rows = cursor.fetchall()
+                print(json.dumps({"rows": rows}, default=encode, ensure_ascii=False))
+            else:
+                # Batch: one process and one connection for independent statements;
+                # the per-statement deadline is re-armed before each execute.
+                results = []
+                for statement in statements:
+                    signal.alarm(math.ceil(request["queryTimeoutMs"] / 1000))
+                    cursor.execute(statement["sql"], statement["values"])
+                    results.append({"rows": cursor.fetchall()})
+                print(json.dumps({"results": results}, default=encode, ensure_ascii=False))
     finally:
         connection.close()
 except Exception as error:
@@ -62,6 +73,9 @@ except Exception as error:
 finally:
     signal.alarm(0)
 `;
+function parsePodResponse(raw) {
+  return JSON.parse(raw, (_key, value) => value?.type === "Buffer" && Array.isArray(value.data) ? Buffer.from(value.data) : value);
+}
 async function queryMysqlViaPod(transport, target, sql, values, options) {
   const raw = await transport.run(POD_QUERY, {
     target,
@@ -69,11 +83,28 @@ async function queryMysqlViaPod(transport, target, sql, values, options) {
     values,
     ...options
   }, options.queryTimeoutMs + 3000);
-  const response = JSON.parse(raw, (_key, value) => value?.type === "Buffer" && Array.isArray(value.data) ? Buffer.from(value.data) : value);
+  const response = parsePodResponse(raw);
   if (response.error || !Array.isArray(response.rows)) {
     throw new Error(`MySQL via Pod failed: ${response.error ?? "invalid response"}${response.code ? ` (${response.code})` : ""}`);
   }
   return response.rows;
 }
+async function queryMysqlViaPodBatch(transport, target, statements, options) {
+  const raw = await transport.run(POD_QUERY, {
+    target,
+    statements: statements.map(({ sql, values }) => ({ sql: preparePodSql(sql, values), values })),
+    ...options
+  }, options.connectTimeoutMs + options.queryTimeoutMs * statements.length + 3000);
+  const response = parsePodResponse(raw);
+  if (response.error || !Array.isArray(response.results)) {
+    throw new Error(`MySQL via Pod batch failed: ${response.error ?? "invalid response"}${response.code ? ` (${response.code})` : ""}`);
+  }
+  return response.results.map((result, index) => {
+    if (!Array.isArray(result.rows)) {
+      throw new Error(`MySQL via Pod batch statement ${index} returned no rows`);
+    }
+    return result.rows;
+  });
+}
 
-export { preparePodSql, queryMysqlViaPod };
+export { preparePodSql, queryMysqlViaPod, queryMysqlViaPodBatch };

package/dist/{chunk-ztenxgjv.js → chunk-mn6dwsvh.js}

@@ -8,7 +8,14 @@ function spawnProcess(argv, opts) {
     stdio: "pipe",
     env: opts?.env
   });
-  child.stdin.end(opts?.stdin);
+  if (opts?.stdin instanceof ReadableStream) {
+    const input = Readable.fromWeb(opts.stdin);
+    input.on("error", () => child.stdin.destroy());
+    child.stdin.on("error", () => input.destroy());
+    child.once("close", () => input.destroy());
+    input.pipe(child.stdin);
+  } else
+    child.stdin.end(opts?.stdin);
   const exited = new Promise((resolve, reject) => {
     child.once("error", reject);
     child.once("close", (code) => resolve(code ?? 1));

package/dist/{chunk-205a4vma.js → chunk-qhpqse1y.js}

@@ -1,6 +1,3 @@
-import {
-  PortForwardScope
-} from "./chunk-hv2kx47y.js";
 import {
   findPodsForService,
   findService,
@@ -9,6 +6,9 @@ import {
 import {
   findPod
 } from "./chunk-6fnhzhdb.js";
+import {
+  PortForwardScope
+} from "./chunk-xh3zwhjh.js";
 
 // src/kubernetes/service-port-forward.ts
 class ServicePortForwarder {

package/dist/chunk-ssj93brx.js

@@ -0,0 +1,89 @@
+// src/transport/pod-relay-script.ts
+var POD_RELAY_SCRIPT = String.raw`
+import asyncio, json, sys
+
+async def main():
+    config = json.loads(sys.argv[1])
+    loop = asyncio.get_running_loop()
+    reader = asyncio.StreamReader(limit=4096)
+    await loop.connect_read_pipe(lambda: asyncio.StreamReaderProtocol(reader), sys.stdin.buffer)
+    servers = []
+    active = set()
+
+    async def pipe(source, destination):
+        while True:
+            chunk = await source.read(65536)
+            if not chunk:
+                if destination.can_write_eof():
+                    destination.write_eof()
+                return
+            destination.write(chunk)
+            await destination.drain()
+
+    async def relay(source, destination, host, port):
+        task = asyncio.current_task()
+        if len(active) >= config["maxConnections"]:
+            destination.close()
+            await destination.wait_closed()
+            return
+        active.add(task)
+        upstream = None
+        pumps = []
+        try:
+            remote, upstream = await asyncio.wait_for(
+                asyncio.open_connection(host, port), config["connectTimeoutMs"] / 1000)
+            pumps = [asyncio.create_task(pipe(source, upstream)), asyncio.create_task(pipe(remote, destination))]
+            await asyncio.gather(*pumps)
+        except (OSError, asyncio.TimeoutError):
+            pass
+        finally:
+            for pump in pumps:
+                pump.cancel()
+            await asyncio.gather(*pumps, return_exceptions=True)
+            for writer in (upstream, destination):
+                if writer:
+                    writer.close()
+            for writer in (upstream, destination):
+                if writer:
+                    try:
+                        await writer.wait_closed()
+                    except OSError:
+                        pass
+            active.discard(task)
+
+    print(json.dumps({"ready": True}), flush=True)
+    try:
+        while True:
+            # EOF cleans up normal shutdown; lease expiry bounds an orphan after lost exec transport.
+            line = await asyncio.wait_for(reader.readline(), config["leaseMs"] / 1000)
+            if not line:
+                break
+            request = json.loads(line)
+            if request.get("heartbeat"):
+                continue
+            identifier = request["id"]
+            try:
+                if len(servers) >= config["maxTargets"]:
+                    raise ValueError("target limit")
+                host, port = request["host"], request["port"]
+                server = await asyncio.start_server(
+                    lambda r, w, h=host, p=port: relay(r, w, h, p), "127.0.0.1", 0)
+                servers.append(server)
+                print(json.dumps({"id": identifier, "port": server.sockets[0].getsockname()[1]}), flush=True)
+            except (OSError, ValueError):
+                print(json.dumps({"id": identifier, "error": "relay listener unavailable"}), flush=True)
+    except asyncio.TimeoutError:
+        pass
+    finally:
+        for server in servers:
+            server.close()
+        await asyncio.gather(*(server.wait_closed() for server in servers))
+        tasks = list(active)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+asyncio.run(main())
+`;
+
+export { POD_RELAY_SCRIPT };

package/dist/{chunk-4pdwsfcx.js → chunk-td11zjfb.js}

@@ -1,18 +1,18 @@
 import {
-  ServicePortForwarder
-} from "./chunk-205a4vma.js";
+  resolveWorkload
+} from "./chunk-y3dx8jh6.js";
 import {
-  KubectlExecutor
-} from "./chunk-0rs1aacd.js";
+  ServicePortForwarder
+} from "./chunk-qhpqse1y.js";
 import {
   resourceAccess
-} from "./chunk-1kpbvat9.js";
-import {
-  resolveWorkload
-} from "./chunk-y3dx8jh6.js";
+} from "./chunk-2m0mh09h.js";
 import {
   KubernetesError
 } from "./chunk-ntfm5e85.js";
+import {
+  KubectlExecutor
+} from "./chunk-hmah9t8e.js";
 
 // src/kubernetes/client.ts
 class KubernetesClient {

package/dist/{chunk-hv2kx47y.js → chunk-xh3zwhjh.js}

@@ -1,10 +1,10 @@
 import {
   buildKubectlArgs
-} from "./chunk-0rs1aacd.js";
+} from "./chunk-hmah9t8e.js";
 import {
   sleep,
   spawnProcess
-} from "./chunk-ztenxgjv.js";
+} from "./chunk-mn6dwsvh.js";
 
 // src/kubernetes/port-forward.ts
 async function startPortForward(opts) {

package/dist/kubernetes/client.js

@@ -1,16 +1,16 @@
 import {
   KubernetesClient
-} from "../chunk-4pdwsfcx.js";
-import"../chunk-205a4vma.js";
-import"../chunk-hv2kx47y.js";
+} from "../chunk-td11zjfb.js";
+import"../chunk-y3dx8jh6.js";
+import"../chunk-qhpqse1y.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
-import"../chunk-1kpbvat9.js";
-import"../chunk-y3dx8jh6.js";
-import"../chunk-v3hxvnrc.js";
+import"../chunk-2m0mh09h.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   KubernetesClient
 };

package/dist/kubernetes/environment.js

@@ -1,19 +1,19 @@
 import {
   KubernetesClient
-} from "../chunk-4pdwsfcx.js";
-import"../chunk-205a4vma.js";
-import"../chunk-hv2kx47y.js";
+} from "../chunk-td11zjfb.js";
+import"../chunk-y3dx8jh6.js";
+import"../chunk-qhpqse1y.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
-import"../chunk-1kpbvat9.js";
-import"../chunk-y3dx8jh6.js";
+import"../chunk-2m0mh09h.js";
 import {
   clientKey
 } from "../chunk-a9htb6cr.js";
-import"../chunk-v3hxvnrc.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 
 // src/kubernetes/environment.ts
 class KubernetesEnvironment {

package/dist/kubernetes/executor.d.ts

@@ -9,7 +9,7 @@ export interface ExecTarget {
     container?: string;
 }
 export interface RunOptions {
-    stdin?: string | Uint8Array;
+    stdin?: string | Uint8Array | ReadableStream<Uint8Array>;
     timeoutMs?: number;
     signal?: AbortSignal;
     onStdout?: (chunk: string) => void;

package/dist/kubernetes/executor.js

@@ -3,8 +3,8 @@ import {
   buildExecArgs,
   buildKubectlArgs,
   runArgv
-} from "../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
+} from "../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   runArgv,
   buildKubectlArgs,

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

@@ -1,9 +1,9 @@
 import {
   PodLogClient
-} from "../chunk-mnad4zkp.js";
+} from "../chunk-010339ga.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
+import"../chunk-mp88s7r7.js";
 import"../chunk-a9htb6cr.js";
 import"../chunk-v3hxvnrc.js";
 export {

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

@@ -1,15 +1,15 @@
 import {
   PodLogClient
-} from "../chunk-mnad4zkp.js";
+} from "../chunk-010339ga.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-mp88s7r7.js";
 import"../chunk-1vfwvgkj.js";
+import"../chunk-mp88s7r7.js";
 import"../chunk-a9htb6cr.js";
 import {
   clientKey
 } from "../chunk-z5pm2emz.js";
-import"../chunk-v3hxvnrc.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
 
 // src/kubernetes/pod-log-datasource.ts
 class PodLogDataSource {

package/dist/kubernetes/port-forward.js

@@ -1,9 +1,9 @@
 import {
   PortForwardScope,
   startPortForward
-} from "../chunk-hv2kx47y.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
+} from "../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   startPortForward,
   PortForwardScope

package/dist/kubernetes/resources.js

@@ -1,8 +1,8 @@
 import {
   resourceAccess
-} from "../chunk-1kpbvat9.js";
-import"../chunk-v3hxvnrc.js";
+} from "../chunk-2m0mh09h.js";
 import"../chunk-ntfm5e85.js";
+import"../chunk-v3hxvnrc.js";
 export {
   resourceAccess
 };

package/dist/kubernetes/service-port-forward.js

@@ -1,11 +1,11 @@
 import {
   ServicePortForwarder
-} from "../chunk-205a4vma.js";
-import"../chunk-hv2kx47y.js";
+} from "../chunk-qhpqse1y.js";
 import"../chunk-j46x7j7c.js";
 import"../chunk-6fnhzhdb.js";
-import"../chunk-0rs1aacd.js";
-import"../chunk-ztenxgjv.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
 export {
   ServicePortForwarder
 };

package/dist/mysql/client.d.ts

@@ -1,6 +1,6 @@
 import type { Client } from "../client";
 import { type Connection, type ConnectionOptions } from "mysql2/promise";
-import type { Database, DatabaseTarget, DatabaseRow, DatabaseQueryLimits, DatabaseQueryResult } from "./types";
+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 {
@@ -16,6 +16,12 @@ export declare class MysqlDatabase implements Database {
     private readonly connect;
     constructor(transports: readonly Transport[], options: MysqlDatabaseOptions, connect?: ConnectionFactory);
     query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;
+    /**
+     * Independent statements in submission order, one session: a Pod transport pays the exec
+     * and connection cost once instead of per statement. Fail-fast like query(); use query()
+     * when a statement depends on an earlier result.
+     */
+    queryBatch(target: DatabaseTarget, statements: readonly SqlStatement[]): Promise<DatabaseRow[][]>;
     /** Bounded, single-statement prepared execution on an isolated READ ONLY session (native only). */
     queryReadonly(target: DatabaseTarget, sql: string, values: readonly unknown[], limits: DatabaseQueryLimits): Promise<DatabaseQueryResult>;
     initialize(target: DatabaseTarget): Promise<void>;

package/dist/mysql/client.js

@@ -2,11 +2,16 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-jkpwa8tb.js";
+} from "../chunk-jx740hjh.js";
 import"../chunk-kbewz29a.js";
-import"../chunk-s06hs7a8.js";
+import"../chunk-m91t44jh.js";
 import"../chunk-v3hxvnrc.js";
-import"../chunk-xy4g56g4.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   openMysql,
   MysqlDatabase,

package/dist/mysql/index.js

@@ -1,16 +1,21 @@
-import {
-  parseMysqlEnvTarget
-} from "../chunk-qq77x9ek.js";
-import"../chunk-pfar9cm3.js";
 import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-jkpwa8tb.js";
+} from "../chunk-jx740hjh.js";
 import"../chunk-kbewz29a.js";
-import"../chunk-s06hs7a8.js";
+import {
+  parseMysqlEnvTarget
+} from "../chunk-qq77x9ek.js";
+import"../chunk-pfar9cm3.js";
+import"../chunk-m91t44jh.js";
 import"../chunk-v3hxvnrc.js";
-import"../chunk-xy4g56g4.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   parseMysqlEnvTarget,
   openMysql,

package/dist/mysql/pod.d.ts

@@ -1,7 +1,16 @@
-import type { DatabaseRow, DatabaseTarget } from "./types";
+import type { DatabaseRow, DatabaseTarget, SqlStatement } from "./types";
 import type { PodPythonTransport } from "../transport";
 export declare function preparePodSql(sql: string, values: readonly unknown[]): string;
 export declare function queryMysqlViaPod(transport: PodPythonTransport, target: DatabaseTarget, sql: string, values: readonly unknown[], options: {
     connectTimeoutMs: number;
     queryTimeoutMs: number;
 }): Promise<DatabaseRow[]>;
+/**
+ * Independent statements over one Pod process and one MySQL connection: the per-exec cost
+ * (kubectl handshake, interpreter start, auth) is paid once. Fail-fast: a statement error
+ * aborts the batch, later statements never execute, and the whole batch throws.
+ */
+export declare function queryMysqlViaPodBatch(transport: PodPythonTransport, target: DatabaseTarget, statements: readonly SqlStatement[], options: {
+    connectTimeoutMs: number;
+    queryTimeoutMs: number;
+}): Promise<DatabaseRow[][]>;

package/dist/mysql/pod.js

@@ -1,8 +1,10 @@
 import {
   preparePodSql,
-  queryMysqlViaPod
-} from "../chunk-s06hs7a8.js";
+  queryMysqlViaPod,
+  queryMysqlViaPodBatch
+} from "../chunk-m91t44jh.js";
 export {
+  queryMysqlViaPodBatch,
   queryMysqlViaPod,
   preparePodSql
 };

package/dist/mysql/types.d.ts

@@ -8,6 +8,10 @@ export interface DatabaseTarget extends DatabaseIdentity {
     database: string;
 }
 export type DatabaseRow = Record<string, unknown>;
+export interface SqlStatement {
+    sql: string;
+    values: readonly unknown[];
+}
 export interface DatabaseQueryLimits {
     timeoutMs: number;
     maxRows: number;

package/dist/process/index.d.ts

@@ -5,7 +5,7 @@ export interface RuntimeProcess {
     kill(): void;
 }
 export interface SpawnProcessOptions {
-    stdin?: string | Uint8Array;
+    stdin?: string | Uint8Array | ReadableStream<Uint8Array>;
     env?: NodeJS.ProcessEnv;
 }
 /** 使用 Node-compatible 子进程 API，不要求调用方使用 Bun runtime。 */

package/dist/process/index.js

@@ -1,7 +1,7 @@
 import {
   sleep,
   spawnProcess
-} from "../chunk-ztenxgjv.js";
+} from "../chunk-mn6dwsvh.js";
 export {
   spawnProcess,
   sleep

package/dist/redis/index.js

@@ -1,3 +1,7 @@
+import {
+  collectRedisKeyStats,
+  redisGroupedSampleSizes
+} from "../chunk-jr9y0ghr.js";
 import {
   discoverRedisTopology
 } from "../chunk-c6z919qb.js";
@@ -8,10 +12,6 @@ import {
   openRedis,
   parseRedisInfo
 } from "../chunk-ajhdd4hp.js";
-import {
-  collectRedisKeyStats,
-  redisGroupedSampleSizes
-} from "../chunk-jr9y0ghr.js";
 export {
   redisGroupedSampleSizes,
   parseRedisInfo,

package/dist/s3/datasource.js

@@ -1,12 +1,17 @@
 import {
   S3DataSource
-} from "../chunk-0cq1gx86.js";
+} from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
+import"../chunk-ntfm5e85.js";
 import"../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";
-import"../chunk-xy4g56g4.js";
-import"../chunk-ntfm5e85.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   S3DataSource
 };

package/dist/s3/index.js

@@ -1,14 +1,19 @@
 import {
   S3DataSource
-} from "../chunk-0cq1gx86.js";
+} from "../chunk-35cjec9z.js";
 import"../chunk-z5pm2emz.js";
+import"../chunk-ntfm5e85.js";
 import {
   S3Client
 } from "../chunk-zp1s833x.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-x4ntb898.js";
-import"../chunk-xy4g56g4.js";
-import"../chunk-ntfm5e85.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   S3DataSource,
   S3Client

package/dist/transport/index.d.ts

@@ -38,3 +38,4 @@ export declare class PodPythonTransport {
 export type Transport = TcpTransport | PodPythonTransport;
 /** Only failure to establish a connection permits a route change; never replay protocol operations. */
 export declare function isConnectionNetworkError(error: unknown): boolean;
+export { PodRelayTransport, type PodRelayOptions } from "./pod-relay";

package/dist/transport/index.js

@@ -3,10 +3,18 @@ import {
   PodPythonTransport,
   PortForwardTransport,
   isConnectionNetworkError
-} from "../chunk-xy4g56g4.js";
+} from "../chunk-h8fwx0k7.js";
+import {
+  PodRelayTransport
+} from "../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   isConnectionNetworkError,
   PortForwardTransport,
+  PodRelayTransport,
   PodPythonTransport,
   DirectTransport
 };

package/dist/transport/pod-relay-script.d.ts

@@ -0,0 +1,2 @@
+/** Private wire protocol: control travels over exec stdin; database bytes only over TCP. */
+export declare const POD_RELAY_SCRIPT: string;

package/dist/transport/pod-relay-script.js

@@ -0,0 +1,6 @@
+import {
+  POD_RELAY_SCRIPT
+} from "../chunk-ssj93brx.js";
+export {
+  POD_RELAY_SCRIPT
+};

package/dist/transport/pod-relay.d.ts

@@ -0,0 +1,31 @@
+import type { Client } from "../client";
+import { type Executor, type KubectlOptions } from "../kubernetes/executor";
+import { type StartPortForward } from "../kubernetes/port-forward";
+import type { Endpoint, TcpTransport } from "./index";
+export interface PodRelayOptions extends KubectlOptions {
+    namespace: string;
+    /** Restrict eligible existing Pods without coupling callers to the relay runtime. */
+    selector?: string;
+    startupTimeoutMs: number;
+    connectTimeoutMs: number;
+    maxConnections: number;
+    maxTargets: number;
+    maxCandidatePods: number;
+    signal?: AbortSignal;
+}
+/** Execution-scoped TCP transport borrowed by all Service clients; only its root owner disposes it.
+ * Python is private. Requires list pods, pods/exec and pods/portforward, never pods/create.
+ */
+export declare class PodRelayTransport implements TcpTransport, Client {
+    #private;
+    private readonly options;
+    readonly kind = "tcp";
+    readonly name = "pod-relay";
+    constructor(options: PodRelayOptions, dependencies?: {
+        executor?: Executor;
+        startForward?: StartPortForward;
+    });
+    initialize(): Promise<void>;
+    connect(endpoint: Endpoint): Promise<Endpoint>;
+    dispose(): Promise<void>;
+}

package/dist/transport/pod-relay.js

@@ -0,0 +1,10 @@
+import {
+  PodRelayTransport
+} from "../chunk-5fgbhx2r.js";
+import"../chunk-xh3zwhjh.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
+export {
+  PodRelayTransport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -102,6 +102,9 @@
     "@types/node-fetch": "2.6.13",
     "@types/node": "^22"
   },
+  "overrides": {
+    "@compforge/harness-common": "file:../common"
+  },
   "publishConfig": {
     "access": "public"
   },

package/dist/{chunk-mnad4zkp.js → chunk-010339ga.js}

@@ -2,12 +2,12 @@ import {
   PodLogByteBudget,
   runPodLogCapturePlan
 } from "./chunk-8nm9f0hh.js";
-import {
-  logTimestampNanos
-} from "./chunk-mp88s7r7.js";
 import {
   LogCaptureFile
 } from "./chunk-1vfwvgkj.js";
+import {
+  logTimestampNanos
+} from "./chunk-mp88s7r7.js";
 import {
   clientKey
 } from "./chunk-a9htb6cr.js";

package/dist/{chunk-1kpbvat9.js → chunk-2m0mh09h.js}

@@ -1,11 +1,11 @@
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
 import {
   KubernetesError,
   ToolboxError,
   kubernetesHttpError
 } from "./chunk-ntfm5e85.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
 
 // src/kubernetes/resources.ts
 import { KubeConfig } from "@kubernetes/client-node";