@compforge/harness-toolbox 0.4.1 → 0.4.2

package/README.md

@@ -18,45 +18,49 @@ not load database or Kubernetes drivers.
 
 ## File sources
 
-Use `LocalFileDataSource` for a local file or `PodFileDataSource` for a file in an explicit
-namespace/Pod/container. Both extend Common's `FileDataSource`, so a Service can store them directly
-as DataSources and consumers can recognize files with `instanceof FileDataSource`. No additional
-`id` or `kind` wrapper is required; consumer-owned selection names remain separate from client identity.
+A FileDataSource is a caller-declared acquisition group. Use `LocalFileDataSource` for local paths
+or `PodFileDataSource` for paths in one explicit namespace/Pod/container. Both extend Common's
+`FileDataSource`; no additional id/kind wrapper is required.
 
 ```ts
-import { ClientManager, FileDataSource } from "@compforge/harness-common";
+import { ClientManager } from "@compforge/harness-common";
 import { LocalFileDataSource, PodFileDataSource } from "@compforge/harness-toolbox/file";
 
-const source = new LocalFileDataSource("./config.yaml", { concurrency: 2 });
+const source = new LocalFileDataSource(["./config.yaml", "./secret/config.yaml"], { concurrency: 2 });
 const clients = new ClientManager();
 try {
-  if (source instanceof FileDataSource) {
-    const file = await clients.get(source);
-    const bytes = await file.read({ maxBytes: 1024 * 1024, timeoutMs: 15_000 });
-    console.log(source.path, new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  const file = await clients.get(source);
+  const results = await file.read({ maxBytes: 1024 * 1024, maxTotalBytes: 2 * 1024 * 1024, timeoutMs: 15_000 });
+  for (const result of results) {
+    if (result.status === "error") console.error(result.path, result.error.message);
+    else console.log(result.path, new TextDecoder("utf-8", { fatal: true }).decode(result.bytes));
   }
-} finally {
-  await clients.dispose();
-}
+} finally { await clients.dispose(); }
 
-// `environment` is a KubernetesEnvironment (or an equivalent ClientProvider).
-// Resolve Workloads first and create one source per chosen Pod/container.
+// Resolve Workloads first. This entire group is fetched through one exec session.
 const podSource = new PodFileDataSource(environment,
   { namespace: "app", pod: "worker-abc", container: "worker" },
-  "/etc/app/config.yaml", { concurrency: 2 });
+  ["/etc/app/config.yaml", "/etc/app/secret/config.yaml"], { concurrency: 2 });
 ```
 
-Each read reopens the file; the manager shares clients, not previous file contents. The byte limit
-rejects oversized reads, including a zero-byte limit on a nonempty file. Timeouts include queue time;
-caller cancellation and disposal cancel active reads. Keep the source path and Pod target with any
-persisted evidence. A successful read describes bytes at that location, not the application's parsed
-or effective configuration and not an atomic filesystem snapshot.
-
-Local files may be symlinks to regular files. Pod reads require `pods/exec` access and `head -c` in the
-selected container; paths are passed as argv without a shell. A Pod name is an access location, not
-a UID fence; callers needing incarnation guarantees must verify discovery around collection. Pod
-sources borrow Kubernetes access from the root manager and never close it themselves. Unsupported
-commands, missing paths and denied reads fail explicitly; they are not empty file results.
+Every read reopens all declared paths and returns one ordered result per path. Empty files succeed;
+missing, denied, nonregular and oversized files return individual errors with no partial bytes.
+An error in one file does not discard sibling results. Per-file limits reset for each path; the total
+budget bounds retained decoded bytes, including incomplete files. Queueing and the whole group
+share one deadline. Cancellation, total-budget exhaustion, deadline and transport/protocol failure
+reject the operation. Sources share clients, never previous file contents.
+
+Pod groups use one exec and require `sh`, `head -c`, `base64` and `tr`. Paths remain positional
+arguments even when they contain shell syntax or newlines. Indexed base64 records carry raw binary
+bytes plus each file's exit status; truncated or malformed records reject without replay. No remote
+temporary files are written. Local reads allow symlinks to regular files and reject nonregular files.
+Keep the path and Pod target on evidence; grouping guarantees neither an atomic filesystem snapshot
+nor application configuration precedence. A Pod name is not a UID fence; callers needing incarnation
+guarantees must check discovery around collection. File clients borrow root Kubernetes access and
+never close it themselves.
+
+Version 0.4.2 requires Common 0.5.4. Replace single path arguments with arrays, supply `maxTotalBytes`,
+and handle per-file results. Publish Common before Toolbox; this change has no single-file legacy adapter.
 
 ## Kubernetes resources
 

package/dist/chunk-grpygk6f.js

@@ -0,0 +1,157 @@
+import {
+  BoundedFileClient,
+  fileClientOptions,
+  filePaths
+} from "./chunk-kkts16w9.js";
+import {
+  FileError
+} from "./chunk-20kv4wc3.js";
+
+// src/file/pod.ts
+import { posix } from "node:path";
+import { clientKey, FileDataSource } from "@compforge/harness-common";
+var READ_FILES = String.raw`limit=$1
+shift
+index=0
+for path do
+  printf '%s ' "$index"
+  { if [ -f "$path" ]; then head -c "$limit" "$path" 2>/dev/null; status=$?; else status=1; fi
+    printf '\000%03d' "$status"
+  } | base64 | tr -d '\r\n'
+  printf '\n'
+  index=$((index + 1))
+done`;
+function fileRecords(paths, maxBytes, target, sink) {
+  let index = 0, header = "", started = false, carry = "", encodedSize = 0, padded = false;
+  let trailer = Buffer.alloc(0);
+  const maximumEncoded = Math.ceil((maxBytes + 5) / 3) * 4;
+  const invalid = () => new FileError("Invalid Pod file group response", { kind: "invalid_response" });
+  const body = (part) => {
+    if (padded && part)
+      throw invalid();
+    encodedSize += part.length;
+    if (encodedSize > maximumEncoded)
+      throw invalid();
+    const text = carry + part, end = text.length - text.length % 4;
+    carry = text.slice(end);
+    if (!end)
+      return;
+    const encoded = text.slice(0, end), decoded = Buffer.from(encoded, "base64");
+    if (decoded.toString("base64") !== encoded)
+      throw invalid();
+    padded = encoded.endsWith("=");
+    if (padded && carry)
+      throw invalid();
+    const bytes = Buffer.concat([trailer, decoded]);
+    if (bytes.length > 4)
+      sink.receive(index, bytes.subarray(0, -4));
+    trailer = Buffer.from(bytes.subarray(Math.max(0, bytes.length - 4)));
+  };
+  return {
+    receive(bytes) {
+      if (bytes.some((byte) => byte > 127))
+        throw invalid();
+      const text = Buffer.from(bytes).toString("ascii");
+      for (let offset = 0;offset < text.length; ) {
+        if (!started) {
+          const char = text[offset++];
+          if (char !== " ") {
+            if (!/\d/.test(char) || header.length >= String(paths.length).length)
+              throw invalid();
+            header += char;
+            continue;
+          }
+          if (index >= paths.length || header !== String(index))
+            throw invalid();
+          started = true;
+        }
+        const newline = text.indexOf(`
+`, offset);
+        body(text.slice(offset, newline < 0 ? text.length : newline));
+        if (newline < 0)
+          return;
+        if (carry || trailer.length !== 4 || trailer[0] !== 0)
+          throw invalid();
+        const status = trailer.subarray(1).toString("ascii");
+        if (!/^\d{3}$/.test(status) || Number(status) > 255)
+          throw invalid();
+        sink.complete(index, Number(status) === 0 ? undefined : new FileError(`Cannot read Pod file: ${target.namespace}/${target.pod}/${target.container} ${paths[index]}`, { kind: "operation_failed", code: Number(status) }));
+        index++;
+        header = "";
+        started = false;
+        encodedSize = 0;
+        padded = false;
+        trailer = Buffer.alloc(0);
+        offset = newline + 1;
+      }
+    },
+    finish() {
+      if (started || header || index !== paths.length)
+        throw invalid();
+    }
+  };
+}
+
+class PodFileClient extends BoundedFileClient {
+  target;
+  acquire;
+  #kubernetes;
+  constructor(paths, target, options, signal, acquire) {
+    super(paths, options, signal);
+    this.target = target;
+    this.acquire = acquire;
+  }
+  async initializeAccess() {
+    this.#kubernetes = await this.acquire();
+  }
+  async capture(signal, limits, sink) {
+    const abort = new AbortController;
+    const combined = AbortSignal.any([signal, abort.signal]);
+    const records = fileRecords(this.paths, limits.maxBytes, this.target, sink);
+    const result = await this.#kubernetes.exec(this.target.namespace, this.target, ["sh", "-c", READ_FILES, "file-source", String(limits.maxBytes + 1), ...this.paths], {
+      signal: combined,
+      timeoutMs: limits.timeoutMs,
+      collectStdout: false,
+      onStdoutBytes: (bytes) => {
+        if (combined.aborted)
+          return;
+        try {
+          records.receive(bytes);
+          combined.throwIfAborted();
+        } catch (error) {
+          abort.abort(error);
+        }
+      }
+    });
+    combined.throwIfAborted();
+    if (!result.ok)
+      throw new FileError(`Cannot acquire Pod file group: ${this.target.namespace}/${this.target.pod}/${this.target.container}`, { kind: result.timedOut ? "timeout" : "operation_failed", code: result.exitCode ?? undefined });
+    records.finish();
+  }
+}
+
+class PodFileDataSource extends FileDataSource {
+  kubernetes;
+  paths;
+  target;
+  clientKey;
+  #options;
+  constructor(kubernetes, target, paths, options) {
+    super();
+    this.kubernetes = kubernetes;
+    this.paths = filePaths(paths);
+    if (this.paths.some((path) => !posix.isAbsolute(path)))
+      throw new FileError("Pod file paths must be absolute", { kind: "invalid_argument" });
+    if ([target.namespace, target.pod, target.container].some((value) => !value.trim())) {
+      throw new FileError("Pod file namespace, Pod and Container are required", { kind: "invalid_argument" });
+    }
+    this.target = Object.freeze({ namespace: target.namespace, pod: target.pod, container: target.container });
+    this.#options = fileClientOptions(options);
+    this.clientKey = clientKey("pod-file", { access: kubernetes.clientKey, target: this.target, paths: this.paths, options: this.#options });
+  }
+  createClient(clients, signal) {
+    return new PodFileClient(this.paths, this.target, this.#options, signal, () => clients.get(this.kubernetes));
+  }
+}
+
+export { PodFileClient, PodFileDataSource };

package/dist/chunk-kkts16w9.js

@@ -0,0 +1,131 @@
+import {
+  FileError,
+  ToolboxError
+} from "./chunk-20kv4wc3.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+
+// src/file/client.ts
+function fileClientOptions(options) {
+  if (!Number.isSafeInteger(options.concurrency) || options.concurrency < 1) {
+    throw new FileError("File concurrency must be a positive integer", { kind: "invalid_argument" });
+  }
+  return Object.freeze({ concurrency: options.concurrency });
+}
+function filePaths(paths) {
+  if (!paths.length || paths.some((path) => typeof path !== "string" || !path || path.includes("\x00")) || new Set(paths).size !== paths.length) {
+    throw new FileError("File paths must be nonempty, distinct and contain no NUL", { kind: "invalid_argument" });
+  }
+  return Object.freeze([...paths]);
+}
+
+class BoundedFileClient {
+  paths;
+  #controller = new AbortController;
+  #signal;
+  #pool;
+  #operations = new Set;
+  #ready = false;
+  #disposal;
+  constructor(paths, options, signal) {
+    this.paths = filePaths(paths);
+    this.#pool = new ConcurrencyPool(fileClientOptions(options).concurrency);
+    this.#signal = AbortSignal.any([signal, this.#controller.signal]);
+  }
+  async initialize() {
+    this.#signal.throwIfAborted();
+    await this.initializeAccess();
+    this.#signal.throwIfAborted();
+    this.#ready = true;
+  }
+  async initializeAccess() {}
+  async read(options) {
+    this.#signal.throwIfAborted();
+    if (!this.#ready)
+      throw new FileError("File client is not initialized", { kind: "operation_failed" });
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0 || options.maxBytes >= Number.MAX_SAFE_INTEGER - 5 || !Number.isSafeInteger(options.maxTotalBytes) || options.maxTotalBytes < 0 || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2147483647) {
+      throw new FileError("Invalid file group read limits", { kind: "invalid_argument" });
+    }
+    const controller = new AbortController;
+    const signal = AbortSignal.any([this.#signal, controller.signal, ...options.signal ? [options.signal] : []]);
+    const timer = setTimeout(() => controller.abort(new FileError("File group read timed out", { kind: "timeout" })), options.timeoutMs);
+    const operation = this.#pool.run(async () => {
+      const files = this.paths.map((path) => ({ path, chunks: [], size: 0, done: false, error: undefined }));
+      let retained = 0;
+      const discard = (file, error) => {
+        retained -= file.size;
+        file.size = 0;
+        file.chunks = [];
+        file.error ??= error;
+      };
+      const entry = (index) => {
+        const file = files[index];
+        if (!file || file.done)
+          throw new FileError("Invalid file group response", { kind: "invalid_response" });
+        return file;
+      };
+      const sink = {
+        receive: (index, bytes) => {
+          if (signal.aborted)
+            return;
+          const file = entry(index);
+          if (file.error)
+            return;
+          if (bytes.byteLength > options.maxBytes - file.size) {
+            discard(file, new FileError(`File exceeds ${options.maxBytes} bytes: ${file.path}`, { kind: "limit_exceeded" }));
+          } else if (bytes.byteLength > options.maxTotalBytes - retained) {
+            controller.abort(new FileError(`File group exceeds ${options.maxTotalBytes} bytes`, { kind: "limit_exceeded" }));
+          } else {
+            file.chunks.push(Uint8Array.from(bytes));
+            file.size += bytes.byteLength;
+            retained += bytes.byteLength;
+          }
+        },
+        complete: (index, error) => {
+          if (signal.aborted)
+            return;
+          const file = entry(index);
+          if (error)
+            discard(file, error);
+          file.done = true;
+        }
+      };
+      await this.capture(signal, options, sink);
+      signal.throwIfAborted();
+      if (files.some((file) => !file.done))
+        throw new FileError("Incomplete file group response", { kind: "invalid_response" });
+      return files.map((file) => {
+        if (file.error)
+          return { path: file.path, status: "error", error: file.error };
+        const bytes = new Uint8Array(file.size);
+        let offset = 0;
+        for (const chunk of file.chunks) {
+          bytes.set(chunk, offset);
+          offset += chunk.byteLength;
+        }
+        return { path: file.path, status: "ok", bytes };
+      });
+    }, signal);
+    this.#operations.add(operation);
+    try {
+      return await operation;
+    } catch (cause) {
+      signal.throwIfAborted();
+      if (cause instanceof ToolboxError)
+        throw cause;
+      throw new FileError("Cannot acquire file group", { kind: "operation_failed", cause });
+    } finally {
+      clearTimeout(timer);
+      this.#operations.delete(operation);
+    }
+  }
+  dispose() {
+    return this.#disposal ??= (async () => {
+      this.#controller.abort(new Error("File client disposed"));
+      await Promise.allSettled(this.#operations);
+    })();
+  }
+}
+
+export { fileClientOptions, filePaths, BoundedFileClient };

package/dist/chunk-sqbew04a.js

@@ -0,0 +1,65 @@
+import {
+  BoundedFileClient,
+  fileClientOptions,
+  filePaths
+} from "./chunk-kkts16w9.js";
+import {
+  FileError
+} from "./chunk-20kv4wc3.js";
+
+// src/file/local.ts
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+import { clientKey, FileDataSource } from "@compforge/harness-common";
+class LocalFileClient extends BoundedFileClient {
+  async capture(signal, limits, sink) {
+    for (const [index, path] of this.paths.entries()) {
+      try {
+        signal.throwIfAborted();
+        const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        try {
+          signal.throwIfAborted();
+          if (!(await file.stat()).isFile())
+            throw new FileError(`Not a regular file: ${path}`, { kind: "unsupported_operation" });
+          const stream = file.createReadStream({
+            autoClose: false,
+            signal,
+            end: limits.maxBytes,
+            highWaterMark: Math.min(limits.maxBytes + 1, 64 * 1024)
+          });
+          for await (const bytes of stream)
+            sink.receive(index, bytes);
+        } finally {
+          await file.close();
+        }
+        sink.complete(index);
+      } catch (cause) {
+        signal.throwIfAborted();
+        const code = cause?.code;
+        sink.complete(index, cause instanceof FileError ? cause : new FileError(`Cannot read local file: ${path}`, {
+          kind: code === "ENOENT" || code === "ENOTDIR" ? "resource_not_found" : code === "EACCES" || code === "EPERM" ? "permission_denied" : "operation_failed",
+          code,
+          cause
+        }));
+      }
+    }
+  }
+}
+
+class LocalFileDataSource extends FileDataSource {
+  paths;
+  clientKey;
+  #options;
+  constructor(paths, options) {
+    super();
+    this.paths = filePaths(filePaths(paths).map((path) => resolve(path)));
+    this.#options = fileClientOptions(options);
+    this.clientKey = clientKey("local-file", { paths: this.paths, options: this.#options });
+  }
+  createClient(_clients, signal) {
+    return new LocalFileClient(this.paths, this.#options, signal);
+  }
+}
+
+export { LocalFileClient, LocalFileDataSource };

package/dist/file/client.d.ts

@@ -1,17 +1,22 @@
-import type { FileClient, FileReadOptions } from "@compforge/harness-common";
+import type { FileClient, FileReadOptions, FileReadResult } from "@compforge/harness-common";
 export interface FileClientOptions {
     concurrency: number;
 }
+export interface FileCaptureSink {
+    receive(index: number, bytes: Uint8Array): void;
+    complete(index: number, error?: Error): void;
+}
 export declare function fileClientOptions(options: FileClientOptions): Readonly<FileClientOptions>;
-/** Shared limits and lifecycle; transports stream bytes and own per-read resource cleanup. */
+export declare function filePaths(paths: readonly string[]): readonly string[];
+/** Group lifecycle and budgets; a per-file failure releases its partial bytes and preserves sibling results. */
 export declare abstract class BoundedFileClient implements FileClient {
     #private;
-    readonly path: string;
-    constructor(path: string, options: FileClientOptions, signal: AbortSignal);
+    readonly paths: readonly string[];
+    constructor(paths: readonly string[], options: FileClientOptions, signal: AbortSignal);
     initialize(): Promise<void>;
     protected initializeAccess(): Promise<void>;
-    protected abstract capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
-    /** @spec Limits apply while streaming; a failed read never publishes partial bytes. */
-    read(options: FileReadOptions): Promise<Uint8Array>;
+    protected abstract capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
+    /** @spec Enforce budgets while streaming; file failures discard only that file, never publish partial bytes. */
+    read(options: FileReadOptions): Promise<readonly FileReadResult[]>;
     dispose(): Promise<void>;
 }

package/dist/file/client.js

@@ -1,10 +1,12 @@
 import {
   BoundedFileClient,
-  fileClientOptions
-} from "../chunk-mzdz6wwc.js";
+  fileClientOptions,
+  filePaths
+} from "../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {
+  filePaths,
   fileClientOptions,
   BoundedFileClient
 };

package/dist/file/index.d.ts

@@ -1,4 +1,4 @@
-export { FileDataSource, type FileClient, type FileReadOptions } from "@compforge/harness-common";
+export { FileDataSource, type FileClient, type FileReadOptions, type FileReadResult } from "@compforge/harness-common";
 export { FileError } from "../errors";
 export type { FileClientOptions } from "./client";
 export { LocalFileDataSource, LocalFileClient } from "./local";

package/dist/file/index.js

@@ -1,12 +1,12 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-mxyvpy79.js";
+} from "../chunk-grpygk6f.js";
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-ba883sdp.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-sqbew04a.js";
+import"../chunk-kkts16w9.js";
 import {
   FileError
 } from "../chunk-20kv4wc3.js";

package/dist/file/local.d.ts

@@ -1,13 +1,13 @@
 import { FileDataSource, type ClientManager, type FileReadOptions } from "@compforge/harness-common";
-import { BoundedFileClient, type FileClientOptions } from "./client";
+import { BoundedFileClient, type FileClientOptions, type FileCaptureSink } from "./client";
 export declare class LocalFileClient extends BoundedFileClient {
-    protected capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
+    protected capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
 }
-/** @spec Resolve relative paths once at declaration; reads reopen the path to observe replaced mounted files. */
+/** @spec Resolve paths once at declaration; each group read reopens them to observe replaced mounted files. */
 export declare class LocalFileDataSource extends FileDataSource<LocalFileClient> {
     #private;
-    readonly path: string;
+    readonly paths: readonly string[];
     readonly clientKey: string;
-    constructor(path: string, options: FileClientOptions);
+    constructor(paths: readonly string[], options: FileClientOptions);
     createClient(_clients: Pick<ClientManager, "get">, signal: AbortSignal): LocalFileClient;
 }

package/dist/file/local.js

@@ -1,8 +1,8 @@
 import {
   LocalFileClient,
   LocalFileDataSource
-} from "../chunk-ba883sdp.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-sqbew04a.js";
+import"../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/dist/file/pod.d.ts

@@ -1,6 +1,6 @@
 import { FileDataSource, type ClientManager, type ClientProvider, type FileReadOptions } from "@compforge/harness-common";
 import type { KubernetesClient } from "../kubernetes/client";
-import { BoundedFileClient, type FileClientOptions } from "./client";
+import { BoundedFileClient, type FileClientOptions, type FileCaptureSink } from "./client";
 export interface PodFileTarget {
     namespace: string;
     pod: string;
@@ -11,21 +11,22 @@ export declare class PodFileClient extends BoundedFileClient {
     #private;
     readonly target: Readonly<PodFileTarget>;
     private readonly acquire;
-    constructor(path: string, target: Readonly<PodFileTarget>, options: FileClientOptions, signal: AbortSignal, acquire: () => Promise<PodFileAccess>);
+    constructor(paths: readonly string[], target: Readonly<PodFileTarget>, options: FileClientOptions, signal: AbortSignal, acquire: () => Promise<PodFileAccess>);
     protected initializeAccess(): Promise<void>;
-    protected capture(signal: AbortSignal, limits: Pick<FileReadOptions, "maxBytes" | "timeoutMs">, receive: (bytes: Uint8Array) => void): Promise<void>;
+    /** @spec The whole declared group uses exactly one exec; file failures are records, never implicit retries. */
+    protected capture(signal: AbortSignal, limits: FileReadOptions, sink: FileCaptureSink): Promise<void>;
 }
 /**
- * @spec One explicit Pod/container/path per source; workload discovery and replica traversal belong to callers.
+ * @spec One explicit Pod/container and one caller-declared acquisition group; discovery belongs to consumers.
  * @rule Borrow Kubernetes access from the root manager; file clients never dispose that shared dependency.
  * @see {@link component://../../../docs/toolbox.md}
  */
 export declare class PodFileDataSource extends FileDataSource<PodFileClient> {
     #private;
     private readonly kubernetes;
-    readonly path: string;
+    readonly paths: readonly string[];
     readonly target: Readonly<PodFileTarget>;
     readonly clientKey: string;
-    constructor(kubernetes: ClientProvider<PodFileAccess>, target: PodFileTarget, path: string, options: FileClientOptions);
+    constructor(kubernetes: ClientProvider<PodFileAccess>, target: PodFileTarget, paths: readonly string[], options: FileClientOptions);
     createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): PodFileClient;
 }

package/dist/file/pod.js

@@ -1,8 +1,8 @@
 import {
   PodFileClient,
   PodFileDataSource
-} from "../chunk-mxyvpy79.js";
-import"../chunk-mzdz6wwc.js";
+} from "../chunk-grpygk6f.js";
+import"../chunk-kkts16w9.js";
 import"../chunk-20kv4wc3.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -99,7 +99,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@compforge/harness-common": "0.5.3",
+    "@compforge/harness-common": "0.5.4",
     "@aws-sdk/client-s3": "3.1133.0",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",

package/dist/chunk-ba883sdp.js

@@ -1,60 +0,0 @@
-import {
-  BoundedFileClient,
-  fileClientOptions
-} from "./chunk-mzdz6wwc.js";
-import {
-  FileError
-} from "./chunk-20kv4wc3.js";
-
-// src/file/local.ts
-import { constants } from "node:fs";
-import { open } from "node:fs/promises";
-import { resolve } from "node:path";
-import { clientKey, FileDataSource } from "@compforge/harness-common";
-class LocalFileClient extends BoundedFileClient {
-  async capture(signal, limits, receive) {
-    try {
-      const file = await open(this.path, constants.O_RDONLY | constants.O_NONBLOCK);
-      try {
-        signal.throwIfAborted();
-        if (!(await file.stat()).isFile()) {
-          throw new FileError(`Not a regular file: ${this.path}`, { kind: "unsupported_operation" });
-        }
-        const stream = file.createReadStream({ autoClose: false, signal, highWaterMark: Math.min(limits.maxBytes + 1, 64 * 1024) });
-        for await (const bytes of stream)
-          receive(bytes);
-      } finally {
-        await file.close();
-      }
-    } catch (cause) {
-      signal.throwIfAborted();
-      if (cause instanceof FileError)
-        throw cause;
-      const code = cause?.code;
-      throw new FileError(`Cannot read local file: ${this.path}`, {
-        kind: code === "ENOENT" || code === "ENOTDIR" ? "resource_not_found" : code === "EACCES" || code === "EPERM" ? "permission_denied" : "operation_failed",
-        code,
-        cause
-      });
-    }
-  }
-}
-
-class LocalFileDataSource extends FileDataSource {
-  path;
-  clientKey;
-  #options;
-  constructor(path, options) {
-    super();
-    if (!path || path.includes("\x00"))
-      throw new FileError("File path must be nonempty and contain no NUL", { kind: "invalid_argument" });
-    this.path = resolve(path);
-    this.#options = fileClientOptions(options);
-    this.clientKey = clientKey("local-file", { path: this.path, options: this.#options });
-  }
-  createClient(_clients, signal) {
-    return new LocalFileClient(this.path, this.#options, signal);
-  }
-}
-
-export { LocalFileClient, LocalFileDataSource };

package/dist/chunk-mxyvpy79.js

@@ -1,62 +0,0 @@
-import {
-  BoundedFileClient,
-  fileClientOptions
-} from "./chunk-mzdz6wwc.js";
-import {
-  FileError
-} from "./chunk-20kv4wc3.js";
-
-// src/file/pod.ts
-import { posix } from "node:path";
-import { clientKey, FileDataSource } from "@compforge/harness-common";
-class PodFileClient extends BoundedFileClient {
-  target;
-  acquire;
-  #kubernetes;
-  constructor(path, target, options, signal, acquire) {
-    super(path, options, signal);
-    this.target = target;
-    this.acquire = acquire;
-  }
-  async initializeAccess() {
-    this.#kubernetes = await this.acquire();
-  }
-  async capture(signal, limits, receive) {
-    const result = await this.#kubernetes.exec(this.target.namespace, this.target, ["head", "-c", String(limits.maxBytes + 1), this.path], { signal, timeoutMs: limits.timeoutMs, collectStdout: false, onStdoutBytes: receive });
-    signal.throwIfAborted();
-    if (!result.ok)
-      throw new FileError(`Cannot read Pod file: ${this.target.namespace}/${this.target.pod}/${this.target.container} ${this.path}`, { kind: result.timedOut ? "timeout" : "operation_failed", code: result.exitCode ?? undefined });
-  }
-}
-
-class PodFileDataSource extends FileDataSource {
-  kubernetes;
-  path;
-  target;
-  clientKey;
-  #options;
-  constructor(kubernetes, target, path, options) {
-    super();
-    this.kubernetes = kubernetes;
-    if (!posix.isAbsolute(path) || path.includes("\x00")) {
-      throw new FileError("Pod file path must be absolute and contain no NUL", { kind: "invalid_argument" });
-    }
-    if ([target.namespace, target.pod, target.container].some((value) => !value.trim())) {
-      throw new FileError("Pod file namespace, Pod and Container are required", { kind: "invalid_argument" });
-    }
-    this.path = path;
-    this.target = Object.freeze({ namespace: target.namespace, pod: target.pod, container: target.container });
-    this.#options = fileClientOptions(options);
-    this.clientKey = clientKey("pod-file", {
-      access: kubernetes.clientKey,
-      target: this.target,
-      path: this.path,
-      options: this.#options
-    });
-  }
-  createClient(clients, signal) {
-    return new PodFileClient(this.path, this.target, this.#options, signal, () => clients.get(this.kubernetes));
-  }
-}
-
-export { PodFileClient, PodFileDataSource };

package/dist/chunk-mzdz6wwc.js

@@ -1,91 +0,0 @@
-import {
-  FileError,
-  ToolboxError
-} from "./chunk-20kv4wc3.js";
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
-
-// src/file/client.ts
-function fileClientOptions(options) {
-  if (!Number.isSafeInteger(options.concurrency) || options.concurrency < 1) {
-    throw new FileError("File concurrency must be a positive integer", { kind: "invalid_argument" });
-  }
-  return Object.freeze({ concurrency: options.concurrency });
-}
-
-class BoundedFileClient {
-  path;
-  #controller = new AbortController;
-  #signal;
-  #pool;
-  #operations = new Set;
-  #ready = false;
-  #disposal;
-  constructor(path, options, signal) {
-    this.path = path;
-    this.#pool = new ConcurrencyPool(fileClientOptions(options).concurrency);
-    this.#signal = AbortSignal.any([signal, this.#controller.signal]);
-  }
-  async initialize() {
-    this.#signal.throwIfAborted();
-    await this.initializeAccess();
-    this.#signal.throwIfAborted();
-    this.#ready = true;
-  }
-  async initializeAccess() {}
-  async read(options) {
-    this.#signal.throwIfAborted();
-    if (!this.#ready)
-      throw new FileError(`File client is not initialized: ${this.path}`, { kind: "operation_failed" });
-    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0 || options.maxBytes === Number.MAX_SAFE_INTEGER || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs <= 0 || options.timeoutMs > 2147483647) {
-      throw new FileError(`Invalid file read limits: ${this.path}`, { kind: "invalid_argument" });
-    }
-    const { maxBytes, timeoutMs } = options;
-    const controller = new AbortController;
-    const signal = AbortSignal.any([this.#signal, controller.signal, ...options.signal ? [options.signal] : []]);
-    const timer = setTimeout(() => controller.abort(new FileError(`File read timed out: ${this.path}`, { kind: "timeout" })), timeoutMs);
-    const operation = this.#pool.run(async () => {
-      const chunks = [];
-      let size = 0;
-      await this.capture(signal, { maxBytes, timeoutMs }, (bytes) => {
-        if (signal.aborted)
-          return;
-        if (bytes.byteLength > maxBytes - size) {
-          controller.abort(new FileError(`File exceeds ${maxBytes} bytes: ${this.path}`, { kind: "limit_exceeded" }));
-          return;
-        }
-        chunks.push(Uint8Array.from(bytes));
-        size += bytes.byteLength;
-      });
-      signal.throwIfAborted();
-      const result = new Uint8Array(size);
-      let offset = 0;
-      for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.byteLength;
-      }
-      return result;
-    }, signal);
-    this.#operations.add(operation);
-    try {
-      return await operation;
-    } catch (cause) {
-      signal.throwIfAborted();
-      if (cause instanceof ToolboxError)
-        throw cause;
-      throw new FileError(`Cannot read file: ${this.path}`, { kind: "operation_failed", cause });
-    } finally {
-      clearTimeout(timer);
-      this.#operations.delete(operation);
-    }
-  }
-  dispose() {
-    return this.#disposal ??= (async () => {
-      this.#controller.abort(new Error(`File client disposed: ${this.path}`));
-      await Promise.allSettled(this.#operations);
-    })();
-  }
-}
-
-export { fileClientOptions, BoundedFileClient };