@compforge/harness-toolbox 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# Harness Toolbox
+
+Shared infrastructure for diagnostic tools, test runners and business adapters. Use the same
+clients to access Kubernetes, MySQL, Redis and OpenSearch without depending on a particular
+command, plugin protocol, test model or verdict.
+
+The package supports Node.js 22+ and Bun. Install with `npm install @compforge/harness-toolbox`.
+Protocol adapters have separate entry points; importing lifecycle or transport contracts does
+not load database or Kubernetes drivers.
+
+A `DataSource` identifies a reusable client and constructs it. The `Client` owns initialization
+and idempotent disposal; a `ClientManager` joins concurrent initialization for the same key and
+closes owned clients when the caller finishes. A `ConnectionSource` resolves connection settings
+and available `Transport` paths. Clients execute protocol operations through those paths.
+
+```ts
+import { ClientManager, dataSourceKey, type DataSource } from "@compforge/harness-toolbox";
+import { MysqlClient } from "@compforge/harness-toolbox/mysql";
+import { DirectTransport } from "@compforge/harness-toolbox/transport";
+
+const target = { host: "localhost", port: 3306, database: "app", user: "reader", password: "..." };
+const source: DataSource<MysqlClient> = {
+  key: dataSourceKey("mysql", target),
+  createClient: signal => new MysqlClient({
+    resolve: async () => target,
+    transports: [new DirectTransport()],
+  }, { signal, connectTimeoutMs: 5_000, queryTimeoutMs: 10_000 }),
+};
+const clients = new ClientManager();
+try {
+  const db = await clients.get(source);
+  const rows = await db.database.query(db.target, "SELECT 1 AS value", []);
+} finally {
+  await clients.dispose();
+}
+```
+
+Callers own credentials, authorization, query semantics, capacity and timeouts. MySQL can use
+TCP or a Python-capable Pod; the latter needs PyMySQL. Transport fallback occurs only when
+establishing a connection, never by replaying a failed SQL operation. Pod inputs use stdin.
+
+Pod log capture shares an identical Pod/container instance and absolute time window once per
+client, while consumers filter independently and retain their own raw copies. Supply an explicit
+capture policy, shared concurrency pool and byte budget; the package does not choose product
+limits. Temporary capture files live until client disposal.
+
+See [toolbox contracts](../../../docs/toolbox.md) for ownership and cross-language semantics.

package/dist/chunk-0rs1aacd.js

@@ -0,0 +1,127 @@
+import {
+  spawnProcess
+} from "./chunk-ztenxgjv.js";
+
+// src/kubernetes/executor.ts
+function buildKubectlArgs(opts, sub) {
+  const args = ["kubectl"];
+  if (opts.kubeconfig)
+    args.push("--kubeconfig", opts.kubeconfig);
+  if (opts.context)
+    args.push("--context", opts.context);
+  if (opts.namespace)
+    args.push("-n", opts.namespace);
+  return [...args, ...sub];
+}
+function buildExecArgs(opts, target, cmd, interactive) {
+  const sub = ["exec"];
+  if (interactive)
+    sub.push("-i");
+  sub.push(target.pod);
+  if (target.container)
+    sub.push("-c", target.container);
+  sub.push("--", ...cmd);
+  return buildKubectlArgs(opts, sub);
+}
+var DEFAULT_TIMEOUT_MS = 30000;
+async function readOutput(stream, onChunk, onBytes, collect = true) {
+  const reader = stream.getReader();
+  const decoder = collect || onChunk ? new TextDecoder : undefined;
+  let output = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done)
+      break;
+    onBytes?.(value);
+    if (decoder) {
+      const chunk = decoder.decode(value, { stream: true });
+      if (collect)
+        output += chunk;
+      onChunk?.(chunk);
+    }
+  }
+  const tail = decoder?.decode() ?? "";
+  if (collect)
+    output += tail;
+  if (tail)
+    onChunk?.(tail);
+  return output;
+}
+async function runArgv(argv, opts) {
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const started = Date.now();
+  let proc;
+  try {
+    proc = spawnProcess(argv, { stdin: opts?.stdin });
+  } catch (err) {
+    return {
+      ok: false,
+      exitCode: null,
+      stdout: "",
+      stderr: err instanceof Error ? err.message : String(err),
+      durationMs: Date.now() - started,
+      timedOut: false,
+      command: argv
+    };
+  }
+  let timedOut = false;
+  let aborted = false;
+  const abort = () => {
+    aborted = true;
+    proc.kill();
+  };
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill();
+  }, timeoutMs);
+  if (opts?.signal?.aborted)
+    abort();
+  else
+    opts?.signal?.addEventListener("abort", abort, { once: true });
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      readOutput(proc.stdout, opts?.onStdout, opts?.onStdoutBytes, opts?.collectStdout ?? true),
+      readOutput(proc.stderr, opts?.onStderr),
+      proc.exited
+    ]);
+    return {
+      ok: exitCode === 0 && !timedOut,
+      exitCode,
+      stdout,
+      stderr: timedOut ? `${stderr}
+[timeout after ${timeoutMs}ms]`.trim() : aborted ? `${stderr}
+[aborted]`.trim() : stderr,
+      durationMs: Date.now() - started,
+      timedOut,
+      command: argv
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      exitCode: null,
+      stdout: "",
+      stderr: err instanceof Error ? err.message : String(err),
+      durationMs: Date.now() - started,
+      timedOut,
+      command: argv
+    };
+  } finally {
+    clearTimeout(timer);
+    opts?.signal?.removeEventListener("abort", abort);
+  }
+}
+
+class KubectlExecutor {
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  run(sub, opts) {
+    return runArgv(buildKubectlArgs(this.opts, sub), opts);
+  }
+  exec(target, cmd, opts) {
+    return runArgv(buildExecArgs(this.opts, target, cmd, opts?.stdin !== undefined), opts);
+  }
+}
+
+export { buildKubectlArgs, buildExecArgs, runArgv, KubectlExecutor };

package/dist/chunk-1at7zs0z.js

@@ -0,0 +1,104 @@
+import {
+  PodLogByteBudget,
+  runPodLogCapturePlan
+} from "./chunk-8nm9f0hh.js";
+import {
+  logTimestampNanos
+} from "./chunk-mp88s7r7.js";
+import {
+  LogCaptureFile
+} from "./chunk-1vfwvgkj.js";
+import {
+  dataSourceKey
+} from "./chunk-hqx7j9xe.js";
+
+// src/kubernetes/pod-log-client.ts
+import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+class PodLogClient {
+  pool;
+  signal;
+  policy;
+  #sources = new Map;
+  #consumers = new Set;
+  #budget;
+  #directory;
+  #disposal;
+  constructor(pool, signal, policy, budget = new PodLogByteBudget(policy.maxTotalBytes)) {
+    this.pool = pool;
+    this.signal = signal;
+    this.policy = policy;
+    this.#budget = budget;
+  }
+  async initialize() {
+    this.signal.throwIfAborted();
+    this.#directory ??= mkdtempSync(join(tmpdir(), "harness-log-sources-"));
+  }
+  capture(access, scope, request, onReuse) {
+    this.signal.throwIfAborted();
+    if (!this.#directory || this.#disposal)
+      throw new Error("Log capture session is not active");
+    const key = scope.instance && request.sinceTime ? dataSourceKey("pod-log", {
+      scope,
+      pod: request.pod,
+      container: request.container,
+      previous: !!request.previous,
+      allContainers: !!request.allContainers,
+      prefix: !!request.prefix,
+      tail: request.tail,
+      sinceTime: logTimestampNanos(request.sinceTime)?.toString(),
+      untilTime: request.untilTime ? logTimestampNanos(request.untilTime)?.toString() : undefined,
+      limitBytes: request.limitBytes
+    }) : randomUUID();
+    let source = this.#sources.get(key);
+    const reused = source !== undefined;
+    if (!source) {
+      const file = new LogCaptureFile(join(this.#directory, `${randomUUID()}.log`));
+      const result = Promise.resolve().then(async () => {
+        try {
+          const captures = await runPodLogCapturePlan(access, [{ target: undefined, request: {
+            ...request,
+            rawFilePath: undefined,
+            collectStdout: false,
+            onLine: (line) => file.append(line)
+          } }], this.policy, this.pool, this.signal, this.#budget);
+          const capture = captures[0]?.capture;
+          return capture;
+        } finally {
+          file.finish();
+        }
+      });
+      result.catch(() => {});
+      source = { file, result };
+      this.#sources.set(key, source);
+    } else
+      onReuse?.();
+    const pending = this.#consume(source, request, reused);
+    this.#consumers.add(pending);
+    pending.then(() => this.#consumers.delete(pending), () => this.#consumers.delete(pending));
+    return pending;
+  }
+  async#consume(source, request, reused) {
+    const started = Date.now();
+    await source.file.follow(request.onLine ?? (() => {}));
+    if (request.rawFilePath)
+      copyFileSync(source.file.path, request.rawFilePath);
+    const result = await source.result;
+    return result && { ...result, durationMs: Date.now() - started, bytesRead: reused ? 0 : result.bytesRead, reused };
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      await Promise.allSettled([...this.#sources.values()].map((source) => source.result));
+      await Promise.allSettled(this.#consumers);
+      for (const source of this.#sources.values())
+        source.file.close();
+      this.#sources.clear();
+      if (this.#directory)
+        rmSync(this.#directory, { recursive: true, force: true });
+    })();
+  }
+}
+
+export { PodLogClient };

package/dist/chunk-1vfwvgkj.js

@@ -0,0 +1,104 @@
+// src/kubernetes/log-capture-file.ts
+import { closeSync, openSync, readSync, writeSync } from "node:fs";
+import { setImmediate } from "node:timers/promises";
+var BLOCK_BYTES = 64 * 1024;
+
+class LogCaptureFile {
+  path;
+  #fd;
+  #pending = [];
+  #pendingBytes = 0;
+  #flushed = 0;
+  #finished = false;
+  #waiters = new Set;
+  constructor(path) {
+    this.path = path;
+  }
+  get size() {
+    return this.#flushed + this.#pendingBytes;
+  }
+  append(line) {
+    const chunk = Buffer.from(`${line}
+`);
+    this.#pending.push(chunk);
+    this.#pendingBytes += chunk.length;
+    if (this.#pendingBytes >= BLOCK_BYTES)
+      this.#flush();
+    this.#wake();
+  }
+  #flush() {
+    if (!this.#pendingBytes)
+      return;
+    this.#fd ??= openSync(this.path, "w+", 384);
+    const bytes = Buffer.concat(this.#pending, this.#pendingBytes);
+    let offset = 0;
+    while (offset < bytes.length)
+      offset += writeSync(this.#fd, bytes, offset, bytes.length - offset);
+    this.#flushed += bytes.length;
+    this.#pending = [];
+    this.#pendingBytes = 0;
+  }
+  #wake() {
+    for (const resolve of this.#waiters)
+      resolve();
+    this.#waiters.clear();
+  }
+  finish() {
+    try {
+      this.#flush();
+      if (this.#flushed === 0)
+        this.#fd ??= openSync(this.path, "w+", 384);
+    } finally {
+      this.close();
+      this.#finished = true;
+      this.#wake();
+    }
+  }
+  async follow(onLine) {
+    let cursor = 0;
+    let pending = "";
+    const decoder = new TextDecoder;
+    const consume = (text) => {
+      const lines = (pending + text).split(`
+`);
+      pending = lines.pop();
+      for (const line of lines)
+        onLine(line);
+    };
+    while (true) {
+      if (cursor < this.#flushed) {
+        const buffer = Buffer.allocUnsafe(Math.min(BLOCK_BYTES, this.#flushed - cursor));
+        const fd = this.#fd ?? openSync(this.path, "r");
+        let count;
+        try {
+          count = readSync(fd, buffer, 0, buffer.length, cursor);
+        } finally {
+          if (this.#fd === undefined)
+            closeSync(fd);
+        }
+        cursor += count;
+        consume(decoder.decode(buffer.subarray(0, count), { stream: true }));
+        await setImmediate();
+      } else if (cursor < this.size) {
+        const buffer = Buffer.concat(this.#pending, this.#pendingBytes).subarray(cursor - this.#flushed);
+        cursor += buffer.length;
+        consume(decoder.decode(buffer, { stream: true }));
+      } else if (this.#finished) {
+        consume(decoder.decode());
+        if (pending)
+          onLine(pending);
+        return;
+      } else {
+        await new Promise((resolve) => this.#waiters.add(resolve));
+      }
+    }
+  }
+  close() {
+    if (this.#fd !== undefined) {
+      closeSync(this.#fd);
+      this.#fd = undefined;
+    }
+  }
+}
+
+export { LogCaptureFile };

package/dist/chunk-205a4vma.js

@@ -0,0 +1,85 @@
+import {
+  PortForwardScope
+} from "./chunk-hv2kx47y.js";
+import {
+  findPodsForService,
+  findService,
+  listServiceNetwork
+} from "./chunk-j46x7j7c.js";
+import {
+  findPod
+} from "./chunk-6fnhzhdb.js";
+
+// src/kubernetes/service-port-forward.ts
+class ServicePortForwarder {
+  opts;
+  services;
+  pods;
+  #cache = new Map;
+  #scope;
+  constructor(opts, services, pods, starter) {
+    this.opts = opts;
+    this.services = services;
+    this.pods = pods;
+    this.#scope = new PortForwardScope(starter);
+  }
+  static async create(executor, opts, starter) {
+    const network = await listServiceNetwork(executor, opts.namespace);
+    return new ServicePortForwarder(opts, network.services, network.pods, starter);
+  }
+  get activeForwards() {
+    return this.#scope.active;
+  }
+  forward(endpoint) {
+    const key = `${endpoint.host}:${endpoint.port}`;
+    let pending = this.#cache.get(key);
+    if (!pending) {
+      pending = this.#forward(endpoint);
+      this.#cache.set(key, pending);
+    }
+    return pending;
+  }
+  async forwardServiceTargets(endpoint) {
+    const service = findService(this.services, endpoint, this.opts.namespace);
+    if (!service)
+      return [await this.forward(endpoint)];
+    const pods = findPodsForService(this.services, this.pods, service.name, service.namespace);
+    if (!pods.length)
+      return [await this.forward(endpoint)];
+    const servicePort = service.ports.find((port) => port.port === endpoint.port);
+    if (typeof servicePort?.targetPort === "string")
+      return [await this.forward(endpoint)];
+    const remotePort = servicePort?.targetPort ?? endpoint.port;
+    const results = await Promise.allSettled(pods.map(async (pod) => ({
+      ...await this.forward({ host: pod.name, port: remotePort }),
+      pod: pod.name
+    })));
+    const targets = results.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
+    if (targets.length)
+      return targets;
+    throw results.find((result) => result.status === "rejected")?.reason;
+  }
+  async#forward(endpoint) {
+    const service = findService(this.services, endpoint, this.opts.namespace);
+    const pod = service ? undefined : findPod(this.pods, endpoint, this.opts.namespace);
+    const target = service ? { kind: "service", name: service.name, namespace: service.namespace } : pod ? { kind: "pod", name: pod.name, namespace: pod.namespace } : undefined;
+    if (!target)
+      return endpoint;
+    const result = await this.#scope.start({
+      ...this.opts,
+      namespace: target.namespace,
+      target: { kind: target.kind, name: target.name },
+      remotePort: endpoint.port
+    });
+    if (!result.value) {
+      throw new Error(`为 ${target.kind}/${target.name} 建立 port-forward 失败：${result.reason ?? "unknown error"}`);
+    }
+    return { host: "127.0.0.1", port: result.value.localPort, servername: endpoint.host };
+  }
+  stop() {
+    this.#scope.stop();
+    this.#cache.clear();
+  }
+}
+
+export { ServicePortForwarder };

package/dist/chunk-3dt25p98.js

@@ -0,0 +1,59 @@
+// src/client-manager.ts
+class ClientManager {
+  #controller = new AbortController;
+  signal;
+  #clients = new Map;
+  #ready = [];
+  #disposal;
+  constructor(signal) {
+    this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
+  }
+  get(source) {
+    this.signal.throwIfAborted();
+    const existing = this.#clients.get(source.key);
+    if (existing)
+      return existing;
+    const pending = Promise.resolve().then(async () => {
+      this.signal.throwIfAborted();
+      const client = source.createClient(this.signal);
+      try {
+        await client.initialize();
+        this.signal.throwIfAborted();
+        this.#ready.push(client);
+        return client;
+      } catch (error) {
+        try {
+          await client.dispose();
+        } catch (cleanup) {
+          throw new AggregateError([error, cleanup], "Client initialization and cleanup failed");
+        }
+        throw error;
+      }
+    });
+    this.#clients.set(source.key, pending);
+    pending.catch(() => {
+      if (this.#clients.get(source.key) === pending)
+        this.#clients.delete(source.key);
+    });
+    return pending;
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("Client manager disposed"));
+      const settled = await Promise.allSettled(this.#clients.values());
+      this.#clients.clear();
+      const errors = settled.flatMap((result) => result.status === "rejected" && result.reason instanceof AggregateError ? [result.reason] : []);
+      for (const client of this.#ready.splice(0).reverse()) {
+        try {
+          await client.dispose();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      if (errors.length)
+        throw new AggregateError(errors, "Client cleanup failed");
+    })();
+  }
+}
+
+export { ClientManager };

package/dist/chunk-6fnhzhdb.js

@@ -0,0 +1,103 @@
+// src/kubernetes/pod.ts
+function termination(raw) {
+  if (!raw)
+    return;
+  return {
+    exitCode: raw.exitCode,
+    signal: raw.signal,
+    reason: raw.reason,
+    message: raw.message,
+    startedAt: raw.startedAt,
+    finishedAt: raw.finishedAt,
+    containerId: raw.containerID
+  };
+}
+function containerState(raw) {
+  if (raw?.waiting) {
+    return { kind: "waiting", reason: raw.waiting.reason, message: raw.waiting.message };
+  }
+  if (raw?.running)
+    return { kind: "running", startedAt: raw.running.startedAt };
+  const terminated = termination(raw?.terminated);
+  return terminated ? { kind: "terminated", ...terminated } : undefined;
+}
+function parsePods(raw, defaultNamespace) {
+  const value = JSON.parse(raw);
+  return (value.items ?? []).flatMap((item) => {
+    const name = item.metadata?.name;
+    if (!name)
+      return [];
+    const statusByName = new Map((item.status?.containerStatuses ?? []).flatMap((container) => {
+      const containerName = container.name?.trim();
+      return containerName ? [[containerName, container]] : [];
+    }));
+    const declaredContainers = (item.spec?.containers ?? []).flatMap((container) => {
+      const containerName = container.name?.trim();
+      if (!containerName)
+        return [];
+      const status = statusByName.get(containerName);
+      const ports = (container.ports ?? []).flatMap((port) => Number.isInteger(port.containerPort) ? [{ name: port.name, containerPort: port.containerPort }] : []);
+      return [{
+        name: containerName,
+        image: container.image?.trim() ?? "",
+        imageId: status?.imageID?.trim() || undefined,
+        ...status?.containerID ? { containerId: status.containerID } : {},
+        ...ports.length ? { ports } : {},
+        requests: container.resources?.requests ?? {},
+        limits: container.resources?.limits ?? {},
+        ready: status?.ready,
+        started: status?.started,
+        restartCount: status?.restartCount ?? 0,
+        state: containerState(status?.state),
+        lastTermination: termination(status?.lastState?.terminated),
+        hasPreviousTerminated: !!status?.lastState?.terminated?.containerID
+      }];
+    });
+    return [{
+      kind: "pod",
+      namespace: item.metadata?.namespace ?? defaultNamespace,
+      name,
+      ...item.metadata?.uid ? { uid: item.metadata.uid } : {},
+      serviceAccountName: item.spec?.serviceAccountName?.trim() || item.spec?.serviceAccount?.trim() || "default",
+      ip: item.status?.podIP,
+      phase: item.status?.phase ?? "Unknown",
+      reason: item.status?.reason,
+      message: item.status?.message,
+      conditions: (item.status?.conditions ?? []).flatMap((condition) => condition.type && condition.status ? [{
+        type: condition.type,
+        status: condition.status,
+        reason: condition.reason,
+        message: condition.message,
+        lastTransitionTime: condition.lastTransitionTime
+      }] : []),
+      labels: item.metadata?.labels ?? {},
+      containers: declaredContainers.length > 0 ? declaredContainers : (item.status?.containerStatuses ?? []).flatMap((container) => {
+        const containerName = container.name?.trim();
+        if (!containerName)
+          return [];
+        return [{
+          name: containerName,
+          image: "",
+          imageId: container.imageID?.trim() || undefined,
+          ...container.containerID ? { containerId: container.containerID } : {},
+          requests: {},
+          limits: {},
+          ready: container.ready,
+          started: container.started,
+          restartCount: container.restartCount ?? 0,
+          state: containerState(container.state),
+          lastTermination: termination(container.lastState?.terminated),
+          hasPreviousTerminated: !!container.lastState?.terminated?.containerID
+        }];
+      })
+    }];
+  });
+}
+function findPod(pods, endpoint, defaultNamespace) {
+  const host = endpoint.host.replace(/\.$/, "");
+  const labels = host.split(".");
+  const dnsNamespace = labels.length >= 4 && labels[3] === "svc" ? labels[2] : undefined;
+  return pods.find((pod) => pod.namespace === (dnsNamespace ?? defaultNamespace) && (pod.ip === host || pod.name === host || host.startsWith(`${pod.name}.`)));
+}
+
+export { parsePods, findPod };