@compforge/harness-toolbox 0.3.10 → 0.4.0

package/README.md

@@ -16,6 +16,82 @@ claiming snapshot consistency; callers supply cancellation and decide how to per
 Protocol adapters have separate entry points; importing lifecycle or transport contracts does
 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.
+
+```ts
+import { ClientManager, FileDataSource } from "@compforge/harness-common";
+import { LocalFileDataSource, PodFileDataSource } from "@compforge/harness-toolbox/file";
+
+const source = new LocalFileDataSource("./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));
+  }
+} finally {
+  await clients.dispose();
+}
+
+// `environment` is a KubernetesEnvironment (or an equivalent ClientProvider).
+// Resolve Workloads first and create one source per chosen Pod/container.
+const podSource = new PodFileDataSource(environment,
+  { namespace: "app", pod: "worker-abc", container: "worker" },
+  "/etc/app/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.
+
+## Kubernetes resources
+
+Borrow a root `KubernetesClient` through `KubernetesEnvironment` and `ClientManager`. Use
+`get(ref)` and `list(query)` for resource reads; `inNamespace(namespace)` binds a borrowed view
+to a namespace without creating a second client or pool:
+
+```ts
+const kube = await clients.get(environment);
+const ns = kube.inNamespace("app");
+const service = await ns.get({ apiVersion: "v1", resource: "services", name: "api" });
+const pods = await ns.list({ apiVersion: "v1", resource: "pods", labelSelector: "app=api" },
+  { timeoutMs: 15_000, signal });
+```
+
+`resource` is the plural REST resource name, not a Kind or kubectl alias. Explicit API versions
+support built-in resources and custom resources without a discovery request or local allowlist.
+The root uses its configured namespace unless the query overrides it; namespace views enforce
+their bound namespace. Resource objects and list metadata are returned intact. List requests
+accept label/field selectors and explicit `limit`/`continue` pages; they do not silently read all pages.
+Errors are `KubernetesError` objects carrying a stable kind and the HTTP status when available.
+Callers retain the query with their evidence; resource operations do not produce shell command results.
+
+The root owns one HTTP transport with keep-alive connections shared across namespaces and resource
+kinds. Authentication refreshes on each request. TLS/proxy identity changes select a new pool and
+retire the previous one after its active reads finish. Requests have bounded bytes and a deadline
+covering queueing, authentication and body consumption. `dispose()` cancels work, waits for tracked
+operations, and closes connections. Views and injected borrowed resource readers have no ownership
+of that lifecycle. No query results are cached and failures are never replayed through another transport.
+
+Native resource access uses kubeconfig authentication, TLS and explicit `proxy-url`. It does not
+select transports based on shell proxy environment variables. `exec` and `forward` are separate
+streaming operations; their implementation does not intercept resource reads. `KubernetesClient`
+has no `run(argv)` method. Concurrency remains caller-configured rather than inferred from pool size.
+
 ## Workload discovery
 
 Borrow a KubernetesClient through KubernetesEnvironment and the shared ClientManager lifecycle, then call

package/dist/{chunk-p6k59m3q.js → chunk-0s27bgga.js}

@@ -1,6 +1,6 @@
 import {
   KubernetesError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 
 // src/kubernetes/workload.ts
 function failure(message, kind) {
@@ -48,7 +48,7 @@ async function resolveWorkload(access, workload, namespace, environment) {
     if (!Object.keys(location.labels).length)
       return failure("Pod labels must be nonempty", "invalid_argument");
     selected = selector(location.labels, true);
-    const result = await access.get(namespace, "pods", undefined, selected);
+    const result = await access.list({ namespace, apiVersion: "v1", resource: "pods", labelSelector: selected });
     if (!Array.isArray(result.items))
       return failure("Pod list lacks items", "invalid_response");
     pods = result.items;
@@ -63,12 +63,17 @@ async function resolveWorkload(access, workload, namespace, environment) {
       return failure("Unsupported workload resource", "unsupported_operation");
     if (!location.name.trim())
       return failure("Resource name is required", "invalid_argument");
-    const item = await access.get(namespace, resource, location.name);
+    const item = await access.get({
+      namespace,
+      resource,
+      name: location.name,
+      apiVersion: resource === "pods" || resource === "services" ? "v1" : "apps/v1"
+    });
     if (resource === "pods")
       pods = [item];
     else {
       selected = selector(item.spec?.selector, resource === "services");
-      const result = await access.get(namespace, "pods", undefined, selected);
+      const result = await access.list({ namespace, apiVersion: "v1", resource: "pods", labelSelector: selected });
       if (!Array.isArray(result.items))
         return failure("Pod list lacks items", "invalid_response");
       pods = result.items;

package/dist/{chunk-zhkrydeg.js → chunk-20kv4wc3.js}

@@ -12,6 +12,9 @@ class ToolboxError extends Error {
 
 class KubernetesError extends ToolboxError {
 }
+
+class FileError extends ToolboxError {
+}
 function kubernetesHttpError(status) {
   const kind = {
     401: "authentication_failed",
@@ -38,4 +41,4 @@ function kubernetesCommandError(result) {
   return status ? kubernetesHttpError(status) : new KubernetesError("Kubernetes resource request failed", { kind: "operation_failed" });
 }
 
-export { ToolboxError, KubernetesError, kubernetesHttpError, kubernetesCommandError };
+export { ToolboxError, KubernetesError, FileError, kubernetesHttpError, kubernetesCommandError };

package/dist/chunk-4ms037k2.js

@@ -0,0 +1,210 @@
+import {
+  resourcePath
+} from "./chunk-ftkrjqkc.js";
+import {
+  clientKey
+} from "./chunk-a9htb6cr.js";
+import {
+  KubernetesError,
+  ToolboxError,
+  kubernetesHttpError
+} from "./chunk-20kv4wc3.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
+
+// src/kubernetes/resource-transport.ts
+import { KubeConfig } from "@kubernetes/client-node";
+import fetch from "node-fetch/lib/index.js";
+import { Headers } from "node-fetch";
+class KubernetesResourceTransport {
+  limits;
+  #config = new KubeConfig;
+  #controller = new AbortController;
+  #pool;
+  #agents = new Set;
+  #server;
+  #signal;
+  #current;
+  constructor(options, signal, limits) {
+    this.limits = limits;
+    if (![limits.timeoutMs, limits.concurrency, limits.maxBytes].every((value) => Number.isSafeInteger(value) && value > 0)) {
+      throw new KubernetesError("Resource limits must be positive integers", { kind: "invalid_argument" });
+    }
+    try {
+      if (options.kubeconfig)
+        this.#config.loadFromFile(options.kubeconfig);
+      else
+        this.#config.loadFromDefault();
+      if (options.context)
+        this.#config.setCurrentContext(options.context);
+    } catch (cause) {
+      throw new KubernetesError("Cannot load Kubernetes access configuration", { kind: "connection_failed", cause });
+    }
+    const cluster = this.#config.getCurrentCluster();
+    if (!cluster)
+      throw new KubernetesError("Kubernetes context has no cluster", { kind: "invalid_argument" });
+    this.#server = cluster.server.replace(/\/$/, "");
+    if (new URL(cluster.server).protocol === "http:") {
+      this.#config.clusters = this.#config.clusters.map((item) => item === cluster ? { ...item, skipTLSVerify: true } : item);
+    }
+    this.#signal = AbortSignal.any([signal, this.#controller.signal]);
+    this.#pool = new ConcurrencyPool(limits.concurrency);
+  }
+  async get(ref, options) {
+    if (!ref.name)
+      throw new KubernetesError("Resource name is required", { kind: "invalid_argument" });
+    return this.#read(resourcePath(ref, ref.name), undefined, options);
+  }
+  async list(query, options) {
+    const params = new URLSearchParams;
+    if (query.labelSelector)
+      params.set("labelSelector", query.labelSelector);
+    if (query.fieldSelector)
+      params.set("fieldSelector", query.fieldSelector);
+    if (query.continue)
+      params.set("continue", query.continue);
+    if (query.limit !== undefined) {
+      if (!Number.isSafeInteger(query.limit) || query.limit <= 0) {
+        throw new KubernetesError("Resource page limit must be a positive integer", { kind: "invalid_argument" });
+      }
+      params.set("limit", String(query.limit));
+    }
+    const value = await this.#read(resourcePath(query), params, options);
+    if (!Array.isArray(value.items) || value.items.some((item) => !isObject(item))) {
+      throw new KubernetesError("Resource list lacks object items", { kind: "invalid_response" });
+    }
+    return value;
+  }
+  dispose() {
+    this.#controller.abort(new Error("Kubernetes resource transport disposed"));
+    for (const entry of this.#agents)
+      entry.agent.destroy();
+    this.#agents.clear();
+    this.#current = undefined;
+  }
+  async#read(path, params, options) {
+    const timeoutMs = options?.timeoutMs ?? this.limits.timeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+      throw new KubernetesError("Resource timeout must be a positive integer", { kind: "invalid_argument" });
+    }
+    const caller = options?.signal ? AbortSignal.any([this.#signal, options.signal]) : this.#signal;
+    const deadline = new AbortController;
+    const signal = AbortSignal.any([caller, deadline.signal]);
+    const timer = setTimeout(() => deadline.abort(), Math.min(timeoutMs, this.limits.timeoutMs));
+    try {
+      return await this.#pool.run(async () => {
+        const request = await this.#authenticate(signal);
+        if (signal.aborted) {
+          request.agent.destroy();
+          signal.throwIfAborted();
+        }
+        const entry = this.#acquireAgent(request);
+        try {
+          const url = new URL(this.#server + path);
+          if (params)
+            url.search = params.toString();
+          const headers = new Headers;
+          for (const [name, value2] of Object.entries(request.headers ?? {})) {
+            for (const entry2 of Array.isArray(value2) ? value2 : [value2]) {
+              if (entry2 !== undefined)
+                headers.append(name, String(entry2));
+            }
+          }
+          if (request.auth)
+            headers.set("Authorization", "Basic " + Buffer.from(request.auth).toString("base64"));
+          const response = await fetch(url.href, { agent: entry.agent, headers, signal, size: this.limits.maxBytes });
+          if (!response.ok) {
+            response.body.destroy();
+            const error = kubernetesHttpError(response.status);
+            throw new KubernetesError("Read Kubernetes resource " + path + " failed", { kind: error.kind, code: error.code });
+          }
+          const value = await response.json();
+          signal.throwIfAborted();
+          if (!isObject(value))
+            throw new KubernetesError("Resource response is not an object", { kind: "invalid_response" });
+          return value;
+        } finally {
+          entry.users--;
+          this.#retire(entry);
+        }
+      }, signal);
+    } catch (cause) {
+      if (caller.aborted)
+        throw caller.reason;
+      if (cause instanceof ToolboxError)
+        throw cause;
+      const type = cause && typeof cause === "object" && "type" in cause ? cause.type : undefined;
+      const code = cause && typeof cause === "object" && "code" in cause && typeof cause.code === "string" ? cause.code : undefined;
+      const tls = code !== undefined && [
+        "CERT_HAS_EXPIRED",
+        "DEPTH_ZERO_SELF_SIGNED_CERT",
+        "SELF_SIGNED_CERT_IN_CHAIN",
+        "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+        "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+        "ERR_TLS_CERT_ALTNAME_INVALID"
+      ].includes(code);
+      throw new KubernetesError("Read Kubernetes resource " + path + " failed", {
+        kind: deadline.signal.aborted ? "timeout" : type === "max-size" ? "limit_exceeded" : type === "invalid-json" ? "invalid_response" : tls ? "tls_verification_failed" : code === "ECONNRESET" ? "connection_lost" : "connection_failed",
+        cause,
+        code
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #authenticate(signal) {
+    return new Promise((resolve, reject) => {
+      if (signal.aborted) {
+        reject(signal.reason);
+        return;
+      }
+      const abort = () => reject(signal.reason);
+      signal.addEventListener("abort", abort, { once: true });
+      const options = { headers: {} };
+      this.#config.applyToHTTPSOptions(options).then(() => {
+        signal.removeEventListener("abort", abort);
+        if (signal.aborted) {
+          options.agent.destroy();
+          reject(signal.reason);
+        } else
+          resolve(options);
+      }, (error) => {
+        signal.removeEventListener("abort", abort);
+        reject(error);
+      });
+    });
+  }
+  #acquireAgent(options) {
+    const fresh = options.agent;
+    const cluster = this.#config.getCurrentCluster();
+    const tls = { ...options, agent: undefined, headers: undefined, auth: undefined };
+    const key = clientKey("kubernetes-agent", { server: this.#server, proxy: cluster?.proxyUrl, tls });
+    if (this.#current?.key === key) {
+      fresh.destroy();
+    } else {
+      fresh.keepAlive = true;
+      fresh.maxSockets = this.limits.concurrency;
+      fresh.maxTotalSockets = this.limits.concurrency;
+      fresh.maxFreeSockets = this.limits.concurrency;
+      const previous = this.#current;
+      this.#current = { key, agent: fresh, users: 0 };
+      this.#agents.add(this.#current);
+      if (previous)
+        this.#retire(previous);
+    }
+    this.#current.users++;
+    return this.#current;
+  }
+  #retire(entry) {
+    if (entry !== this.#current && entry.users === 0) {
+      entry.agent.destroy();
+      this.#agents.delete(entry);
+    }
+  }
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export { KubernetesResourceTransport };

package/dist/{chunk-b7f39m4v.js → chunk-8mb6natq.js}

@@ -1,6 +1,6 @@
 import {
   ToolboxError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 import {
   isConnectionNetworkError
 } from "./chunk-h8fwx0k7.js";

package/dist/chunk-ba883sdp.js

@@ -0,0 +1,60 @@
+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-ftkrjqkc.js

@@ -0,0 +1,15 @@
+import {
+  KubernetesError
+} from "./chunk-20kv4wc3.js";
+
+// src/kubernetes/resources.ts
+function resourcePath(query, name) {
+  const parts = query.apiVersion.split("/");
+  if (parts.length > 2 || parts.some((part) => !/^[a-z0-9][a-z0-9.-]*$/.test(part)) || !/^[a-z][a-z0-9-]*$/.test(query.resource) || query.namespace !== undefined && !/^[a-z0-9][a-z0-9-]*$/.test(query.namespace) || name !== undefined && !/^[a-z0-9][a-z0-9.-]*$/.test(name)) {
+    throw new KubernetesError("Invalid Kubernetes resource identity", { kind: "invalid_argument" });
+  }
+  const prefix = parts.length === 1 ? "/api/" : "/apis/";
+  return prefix + parts.join("/") + (query.namespace === undefined ? "" : "/namespaces/" + query.namespace) + "/" + query.resource + (name === undefined ? "" : "/" + name);
+}
+
+export { resourcePath };

package/dist/{chunk-ahc00qs5.js → chunk-h73h2b7y.js}

@@ -1,3 +1,7 @@
+import {
+  queryMysqlViaPod,
+  queryMysqlViaPodBatch
+} from "./chunk-m91t44jh.js";
 import {
   queryReadonlySession,
   validateQueryLimits
@@ -5,13 +9,9 @@ import {
 import {
   destroyMysqlConnection
 } from "./chunk-136egyff.js";
-import {
-  queryMysqlViaPod,
-  queryMysqlViaPodBatch
-} from "./chunk-m91t44jh.js";
 import {
   ToolboxError
-} from "./chunk-zhkrydeg.js";
+} from "./chunk-20kv4wc3.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/chunk-mxyvpy79.js

@@ -0,0 +1,62 @@
+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

@@ -0,0 +1,91 @@
+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 };