@compforge/harness-toolbox 0.4.7 → 0.5.0

package/README.md

@@ -69,7 +69,7 @@ select `single`, `cluster` or `sentinel`; `endpoints` contains that mode's seed
 configuration additionally provides `sentinelMasterName` and optional Sentinel credentials,
 separate from data-node credentials. Cluster connections require database zero.
 
-Supply ordered TCP transports through `ConnectionSource`. Only mapping or handshake network
+Supply one `Transport`, with ordered TCP paths where needed. Only mapping or handshake network
 failures advance to the next transport; authentication and TLS verification failures stop immediately.
 `connectTimeoutMs` bounds each route (mapping and handshake); it defaults to the command
 `timeoutMs`. `acquireTimeoutMs` bounds all candidates together and defaults to the per-route budget
@@ -194,8 +194,17 @@ The Makefile builds common before typechecking or building toolbox.
 A `ClientProvider` identifies a reusable client and constructs it; `DataSource` adds data-access semantics.
 Accessible environments implement ClientProvider directly without becoming data sources. 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.
+closes owned clients when the caller finishes. Protocol clients take configuration (or an async resolver)
+and one `Transport`; the transport selects and prepares access paths. `clients.create(factory)` creates
+a fresh client that its caller may close early; transports acquired with `get` stay alive until root disposal.
+
+For shared port-forwarding, register a `ServicePortForwardTransport` once per cluster/namespace, then pass the
+borrowed transport to each protocol client. Closing an OpenSearch client leaves the forward available to the next
+OpenSearch, MySQL, Redis or S3 client; root disposal closes the clients before stopping the forward processes.
+Borrower cancellation only stops that borrower's wait. Exited forwards are recreated on the next acquisition.
+Transport mapping changes the dial address, while protocol clients retain the original Host, TLS and signing identity.
+In 0.5, replace `new Client({ resolve, transports }, options)` with
+`new Client(resolve, transport, options)` (S3 retains its explicit limits argument).
 
 ```ts
 import { ClientManager, clientKey, type DataSource } from "@compforge/harness-toolbox";
@@ -205,10 +214,8 @@ import { DirectTransport } from "@compforge/harness-toolbox/transport";
 const target = { host: "localhost", port: 3306, database: "app", user: "reader", password: "..." };
 const source: DataSource<MysqlClient> = {
   clientKey: clientKey("mysql", target),
-  createClient: (_clients, signal) => new MysqlClient({
-    resolve: async () => target,
-    transports: [new DirectTransport()],
-  }, { signal, connectTimeoutMs: 5_000, queryTimeoutMs: 10_000 }),
+  createClient: (_clients, signal) => new MysqlClient(target, new DirectTransport(),
+    { signal, connectTimeoutMs: 5_000, queryTimeoutMs: 10_000 }),
 };
 const clients = new ClientManager();
 try {
@@ -351,7 +358,7 @@ try {
       maxConnections: 16, maxTargets: 8, maxCandidatePods: 8, signal,
     }),
   });
-  // The same instance belongs in each protocol client's ConnectionSource.transports.
+  // Pass this same transport instance to each protocol client; clients never dispose it.
   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 {

package/dist/{chunk-1ts7pswj.js → chunk-0d8vs5q8.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-6fnhzhdb.js";
 import {
   PortForwardScope
-} from "./chunk-nftzckdy.js";
+} from "./chunk-mvkxs8d0.js";
 
 // src/kubernetes/service-port-forward.ts
 class ServicePortForwarder {
@@ -17,6 +17,8 @@ class ServicePortForwarder {
   pods;
   #cache = new Map;
   #scope;
+  #handles = new Map;
+  #closed = false;
   constructor(opts, services, pods, starter) {
     this.opts = opts;
     this.services = services;
@@ -31,14 +33,28 @@ class ServicePortForwarder {
     return this.#scope.active;
   }
   forward(endpoint) {
+    if (this.#closed)
+      throw new Error("Port-forward transport is closed");
     this.opts.signal?.throwIfAborted();
     const key = `${endpoint.host}:${endpoint.port}`;
     let pending = this.#cache.get(key);
     if (!pending) {
       pending = this.#forward(endpoint);
       this.#cache.set(key, pending);
+      pending.catch(() => {
+        if (this.#cache.get(key) === pending)
+          this.#cache.delete(key);
+      });
     }
-    return pending;
+    return pending.then((mapped) => {
+      const handle = this.#handles.get(key);
+      if (handle?.isAlive && !handle.isAlive()) {
+        if (this.#cache.get(key) === pending)
+          this.#cache.delete(key);
+        return this.forward(endpoint);
+      }
+      return mapped;
+    });
   }
   async forwardServiceTargets(endpoint) {
     const service = findService(this.services, endpoint, this.opts.namespace);
@@ -75,11 +91,26 @@ class ServicePortForwarder {
     if (!result.value) {
       throw new Error(`为 ${target.kind}/${target.name} 建立 port-forward 失败：${result.reason ?? "unknown error"}`);
     }
+    if (this.#closed || this.opts.signal?.aborted) {
+      result.value.stop();
+      this.opts.signal?.throwIfAborted();
+      throw new Error("Port-forward transport is closed");
+    }
+    this.#handles.set(`${endpoint.host}:${endpoint.port}`, result.value);
     return { host: "127.0.0.1", port: result.value.localPort, servername: endpoint.host };
   }
   stop() {
+    this.#closed = true;
     this.#scope.stop();
     this.#cache.clear();
+    this.#handles.clear();
+  }
+  async dispose() {
+    this.#closed = true;
+    await Promise.allSettled(this.#cache.values());
+    await this.#scope.dispose();
+    this.#cache.clear();
+    this.#handles.clear();
   }
 }
 

package/dist/{chunk-h8fwx0k7.js → chunk-18gcp0ck.js}

@@ -1,34 +1,59 @@
+import {
+  Transport
+} from "./chunk-sb5qzv37.js";
+
 // src/transport/index.ts
-class DirectTransport {
+class DirectTransport extends Transport {
   kind = "tcp";
   name = "direct";
-  async connect(endpoint) {
+  paths() {
+    return [this];
+  }
+  async connect(endpoint, attempt) {
+    this.signal.throwIfAborted();
+    attempt?.signal.throwIfAborted();
     return endpoint;
   }
 }
 
-class PortForwardTransport {
+class PortForwardTransport extends Transport {
   forward;
+  release;
   kind = "tcp";
   name = "port-forward";
-  constructor(forward) {
+  constructor(forward, release, signal) {
+    super([], signal);
     this.forward = forward;
+    this.release = release;
+  }
+  paths() {
+    return [this];
   }
-  connect(endpoint) {
-    return this.forward(endpoint);
+  connect(endpoint, attempt) {
+    this.signal.throwIfAborted();
+    attempt?.signal.throwIfAborted();
+    return this.forward(endpoint, attempt);
+  }
+  async close() {
+    await this.release?.();
   }
 }
 
-class PodPythonTransport {
+class PodPythonTransport extends Transport {
   exec;
   python;
   kind = "python";
   name = "pod-python";
   constructor(exec, python = "python") {
+    super();
     this.exec = exec;
     this.python = python;
   }
+  paths() {
+    return [this];
+  }
   run(script, input, timeoutMs) {
+    this.signal.throwIfAborted();
     return this.exec([this.python, "-c", script], { stdin: JSON.stringify(input), timeoutMs });
   }
 }

package/dist/{chunk-gm4swndx.js → chunk-43mcyrh4.js}

@@ -4,26 +4,7 @@ import {
 } from "./chunk-rkt41za2.js";
 
 // src/connection/acquire.ts
-async function awaitWithSignal(pending, signal, cancel) {
-  if (signal.aborted) {
-    cancel?.();
-    pending.catch(() => {});
-    signal.throwIfAborted();
-  }
-  let abort;
-  const cancelled = new Promise((_, reject) => {
-    abort = () => {
-      cancel?.();
-      reject(signal.reason);
-    };
-    signal.addEventListener("abort", abort, { once: true });
-  });
-  try {
-    return await Promise.race([pending, cancelled]);
-  } finally {
-    signal.removeEventListener("abort", abort);
-  }
-}
+import { raceSignal } from "race-signal";
 async function acquireConnection(routes, options) {
   const budget = options.acquireTimeoutMs ?? options.connectTimeoutMs * routes.length;
   if (!routes.length)
@@ -75,9 +56,14 @@ async function acquireConnection(routes, options) {
           }
           return value;
         });
-        result = await awaitWithSignal(prepared, attemptSignal);
+        options.onPending?.(prepared);
+        result = await raceSignal(prepared, attemptSignal);
       } catch (failure) {
-        await discard();
+        try {
+          await discard();
+        } catch (cleanup) {
+          throw new AggregateError([failure, cleanup], "Connection acquisition and cleanup failed", { cause: failure });
+        }
         signal.throwIfAborted();
         const error = attemptSignal.aborted ? attemptSignal.reason : failure;
         reason = options.retryReason(error);
@@ -93,7 +79,11 @@ async function acquireConnection(routes, options) {
         attemptSignal.throwIfAborted();
         return result.connection;
       } catch (error) {
-        await discard();
+        try {
+          await discard();
+        } catch (cleanup) {
+          throw new AggregateError([error, cleanup], "Connection publication and cleanup failed", { cause: error });
+        }
         throw error;
       }
     }
@@ -103,4 +93,4 @@ async function acquireConnection(routes, options) {
   }
 }
 
-export { awaitWithSignal, acquireConnection };
+export { acquireConnection };

package/dist/{chunk-zp1s833x.js → chunk-7hbvjzb9.js}

@@ -1,3 +1,6 @@
+import {
+  isConnectionNetworkError
+} from "./chunk-18gcp0ck.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
@@ -33,7 +36,8 @@ function metadata(value) {
 }
 
 class S3Client {
-  source;
+  configuration;
+  transport;
   limits;
   lifecycle;
   #controller = new AbortController;
@@ -44,8 +48,9 @@ class S3Client {
   #disposal;
   #sdk;
   #http;
-  constructor(source, limits, lifecycle = {}) {
-    this.source = source;
+  constructor(configuration, transport, limits, lifecycle = {}) {
+    this.configuration = configuration;
+    this.transport = transport;
     this.limits = limits;
     this.lifecycle = lifecycle;
     positive(limits.concurrency, "concurrency");
@@ -59,19 +64,28 @@ class S3Client {
     return this.#initialization ??= this.#initialize();
   }
   async#initialize() {
-    const target = await this.source.resolve();
+    const target = await (typeof this.configuration === "function" ? this.configuration() : Promise.resolve(this.configuration));
     this.signal.throwIfAborted();
     const url = new URL(target.endpoint);
     if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
       throw new Error("S3 endpoint must be an HTTP(S) URL without embedded credentials, query or fragment");
     }
-    const transport = this.source.transports[0];
-    if (!transport || transport.kind !== "tcp")
-      throw new Error("S3 requires a TCP transport");
-    const route = await transport.connect({
-      host: url.hostname,
-      port: Number(url.port || (url.protocol === "https:" ? 443 : 80)),
-      servername: url.hostname
+    const route = await this.transport.acquire({
+      name: "S3 route",
+      signal: this.signal,
+      connectTimeoutMs: this.limits.connectTimeoutMs,
+      onRoute: this.lifecycle.onRoute,
+      open: async (path, attempt) => {
+        if (path.kind !== "tcp")
+          throw new Error("S3 requires a TCP transport");
+        const connection = await path.connect({
+          host: url.hostname,
+          port: Number(url.port || (url.protocol === "https:" ? 443 : 80))
+        }, attempt);
+        return { connection, transport: path.name };
+      },
+      close: () => {},
+      retryReason: (error) => isConnectionNetworkError(error) ? String(error.code) : undefined
     });
     this.signal.throwIfAborted();
     this.#http = s3Handler(target, route, this.limits);
@@ -85,7 +99,6 @@ class S3Client {
       followRegionRedirects: false,
       responseChecksumValidation: "WHEN_REQUIRED"
     });
-    this.lifecycle.onRoute?.({ transport: transport.name });
   }
   #run(options, operation) {
     this.signal.throwIfAborted();

package/dist/{chunk-f3vq900j.js → chunk-92aacbwh.js}

@@ -2,7 +2,7 @@ import {
   BoundedFileClient,
   fileClientOptions,
   filePaths
-} from "./chunk-ww11q58v.js";
+} from "./chunk-rncagjbc.js";
 import {
   FileError
 } from "./chunk-rkt41za2.js";

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

@@ -3,10 +3,13 @@ import {
 } from "./chunk-z5pm2emz.js";
 import {
   S3Client
-} from "./chunk-zp1s833x.js";
+} from "./chunk-7hbvjzb9.js";
 import {
   DirectTransport
-} from "./chunk-h8fwx0k7.js";
+} from "./chunk-18gcp0ck.js";
+import {
+  Transport
+} from "./chunk-sb5qzv37.js";
 
 // src/s3/datasource.ts
 class S3DataSource {
@@ -25,10 +28,7 @@ class S3DataSource {
     });
   }
   createClient(_clients, signal) {
-    return new S3Client({
-      resolve: async () => this.#target,
-      transports: [this.#transport]
-    }, this.#limits, { signal });
+    return new S3Client(this.#target, this.#transport instanceof Transport ? this.#transport : new Transport([this.#transport]), this.#limits, { signal });
   }
 }
 

package/dist/chunk-ehmx0yhp.js

@@ -0,0 +1,52 @@
+import {
+  ServicePortForwarder
+} from "./chunk-0d8vs5q8.js";
+import {
+  KubectlExecutor
+} from "./chunk-rq5fc007.js";
+import {
+  Transport
+} from "./chunk-sb5qzv37.js";
+
+// src/transport/service-port-forward.ts
+import { raceSignal } from "race-signal";
+class ServicePortForwardTransport extends Transport {
+  options;
+  dependencies;
+  kind = "tcp";
+  name = "port-forward";
+  #initialization;
+  #forwarder;
+  constructor(options, dependencies) {
+    super([], options.signal);
+    this.options = options;
+    this.dependencies = dependencies;
+  }
+  paths() {
+    return [this];
+  }
+  initialize() {
+    this.signal.throwIfAborted();
+    const pending = this.#initialization ??= (async () => {
+      this.#forwarder = await ServicePortForwarder.create(this.dependencies?.executor ?? new KubectlExecutor(this.options), { ...this.options, signal: this.resourceSignal }, this.dependencies?.startForward);
+      this.signal.throwIfAborted();
+    })();
+    return raceSignal(pending, this.signal);
+  }
+  get activeForwards() {
+    return this.#forwarder?.activeForwards ?? [];
+  }
+  async connect(endpoint, attempt) {
+    this.signal.throwIfAborted();
+    const signal = attempt ? AbortSignal.any([this.signal, attempt.signal]) : this.signal;
+    await raceSignal(this.initialize(), signal);
+    const mapped = await raceSignal(this.#forwarder.forward(endpoint), signal);
+    return { host: mapped.host, port: mapped.port };
+  }
+  async close() {
+    await this.#initialization?.catch(() => {});
+    await this.#forwarder?.dispose();
+  }
+}
+
+export { ServicePortForwardTransport };

package/dist/{chunk-t4hrnaj0.js → chunk-ex429qjt.js}

@@ -11,20 +11,20 @@ import {
   destroyMysqlConnection
 } from "./chunk-835fssgz.js";
 import {
-  acquireConnection,
-  awaitWithSignal
-} from "./chunk-gm4swndx.js";
-import {
-  ToolboxError
-} from "./chunk-rkt41za2.js";
+  isConnectionNetworkError
+} from "./chunk-18gcp0ck.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
 import {
-  isConnectionNetworkError
-} from "./chunk-h8fwx0k7.js";
+  Transport
+} from "./chunk-sb5qzv37.js";
+import {
+  ToolboxError
+} from "./chunk-rkt41za2.js";
 
 // src/mysql/client.ts
+import { raceSignal } from "race-signal";
 function mysqlOperationError(error, phase) {
   if (!error || typeof error !== "object" || !("code" in error) || error.code !== "PROTOCOL_CONNECTION_LOST")
     return error;
@@ -36,15 +36,15 @@ function mysqlOperationError(error, phase) {
 }
 
 class MysqlDatabase {
-  transports;
   options;
   connect;
   #queries = new ConcurrencyPool(1);
   #connections = new Map;
-  constructor(transports, options, connect = connectMysql) {
-    this.transports = transports;
+  #transport;
+  constructor(transport, options, connect = connectMysql) {
     this.options = options;
     this.connect = connect;
+    this.#transport = transport instanceof Transport ? transport : new Transport(transport);
   }
   query(target, sql, values) {
     return this.#queries.run(() => this.#query(target, sql, values), this.options.signal);
@@ -125,14 +125,14 @@ class MysqlDatabase {
     });
   }
   #open(target) {
-    return acquireConnection(this.transports, {
+    return this.#transport.acquire({
       name: "MySQL connection",
       ...this.options,
       open: async (transport, attempt) => {
         if (transport.kind === "python")
           return { connection: { kind: "python", transport }, transport: transport.name };
         try {
-          const endpoint = await transport.connect(target);
+          const endpoint = await transport.connect(target, attempt);
           const connection = await this.connect({
             host: endpoint.host,
             port: endpoint.port,
@@ -175,7 +175,8 @@ class MysqlDatabase {
 }
 
 class MysqlClient {
-  source;
+  configuration;
+  transport;
   options;
   #controller = new AbortController;
   signal;
@@ -183,17 +184,18 @@ class MysqlClient {
   #disposal;
   #database;
   #target;
-  constructor(source, options) {
-    this.source = source;
+  constructor(configuration, transport, options) {
+    this.configuration = configuration;
+    this.transport = transport;
     this.options = options;
     this.signal = options.signal ? AbortSignal.any([options.signal, this.#controller.signal]) : this.#controller.signal;
   }
   initialize() {
     this.signal.throwIfAborted();
     return this.#initialization ??= (async () => {
-      this.#target = await awaitWithSignal(this.source.resolve(), this.signal);
+      this.#target = await raceSignal(typeof this.configuration === "function" ? this.configuration() : Promise.resolve(this.configuration), this.signal);
       this.signal.throwIfAborted();
-      this.#database = new MysqlDatabase(this.source.transports, { ...this.options, signal: this.signal });
+      this.#database = new MysqlDatabase(this.transport, { ...this.options, signal: this.signal });
       await this.#database.initialize(this.#target);
     })();
   }
@@ -215,8 +217,8 @@ class MysqlClient {
     })();
   }
 }
-async function openMysql(source, options) {
-  const client = new MysqlClient(source, options);
+async function openMysql(configuration, transport, options) {
+  const client = new MysqlClient(configuration, transport, options);
   try {
     await client.initialize();
   } catch (error) {

package/dist/{chunk-fqrknvr8.js → chunk-kap6ka3n.js}

@@ -1,25 +1,29 @@
+import {
+  POD_RELAY_SCRIPT
+} from "./chunk-ssj93brx.js";
 import {
   startPortForward
-} from "./chunk-nftzckdy.js";
+} from "./chunk-mvkxs8d0.js";
 import {
   KubectlExecutor
 } from "./chunk-rq5fc007.js";
 import {
-  POD_RELAY_SCRIPT
-} from "./chunk-ssj93brx.js";
+  Transport
+} from "./chunk-sb5qzv37.js";
 
 // src/transport/pod-relay.ts
-class PodRelayTransport {
+import { raceSignal } from "race-signal";
+class PodRelayTransport extends Transport {
   options;
   kind = "tcp";
   name = "pod-relay";
-  #controller = new AbortController;
   #signal;
   #executor;
   #startForward;
   #targets = new Map;
   #pending = new Map;
   #forwards = [];
+  #exits = [];
   #startup;
   #execution;
   #input;
@@ -28,6 +32,7 @@ class PodRelayTransport {
   #disposal;
   #sequence = 0;
   constructor(options, dependencies) {
+    super([], options.signal);
     this.options = options;
     for (const key of ["startupTimeoutMs", "connectTimeoutMs", "maxConnections", "maxTargets", "maxCandidatePods"]) {
       if (!Number.isSafeInteger(options[key]) || options[key] <= 0)
@@ -35,10 +40,14 @@ class PodRelayTransport {
     }
     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 = this.resourceSignal;
     this.#signal.addEventListener("abort", this.#onAbort, { once: true });
   }
+  paths() {
+    return [this];
+  }
   async initialize() {
+    this.signal.throwIfAborted();
     this.#check();
   }
   #check() {
@@ -175,7 +184,8 @@ class PodRelayTransport {
     this.#input.enqueue(new TextEncoder().encode(`${JSON.stringify(value)}
 `));
   }
-  connect(endpoint) {
+  connect(endpoint, attempt) {
+    this.signal.throwIfAborted();
     this.#check();
     if (!endpoint.host || !Number.isInteger(endpoint.port) || endpoint.port < 1 || endpoint.port > 65535) {
       return Promise.reject(new Error("Invalid relay endpoint"));
@@ -192,7 +202,7 @@ class PodRelayTransport {
       pending = this.#connect(endpoint, this.#startup);
       this.#targets.set(key, pending);
     }
-    return pending.then((local) => ({ ...local, servername: endpoint.servername ?? endpoint.host }));
+    return raceSignal(pending, attempt ? AbortSignal.any([this.signal, attempt.signal]) : this.signal);
   }
   async#connect(endpoint, startup) {
     const pod = await startup;
@@ -225,10 +235,13 @@ class PodRelayTransport {
       ...this.options,
       target: { kind: "pod", name: pod.target.pod },
       remotePort,
-      timeoutMs: this.options.startupTimeoutMs
+      timeoutMs: this.options.startupTimeoutMs,
+      signal: this.#signal
     });
     if (!forwarded.ok || !forwarded.value)
       throw new Error("Pod relay port-forward unavailable");
+    if (forwarded.value.exited)
+      this.#exits.push(forwarded.value.exited);
     try {
       this.#check();
     } catch (error) {
@@ -238,14 +251,16 @@ class PodRelayTransport {
     this.#forwards.push(forwarded.value);
     return { host: "127.0.0.1", port: forwarded.value.localPort };
   }
-  dispose() {
+  close() {
     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;
+      const completed = await Promise.allSettled([this.#execution, ...this.#exits]);
       this.#signal.removeEventListener("abort", this.#onAbort);
       this.#targets.clear();
+      const errors = completed.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+      if (errors.length)
+        throw new AggregateError(errors, "Pod relay cleanup failed");
     })();
   }
 }