@compforge/harness-toolbox 0.4.7 → 0.5.0

package/dist/transport/index.d.ts

@@ -1,3 +1,7 @@
+import { Transport } from "./lifecycle";
+import type { ConnectionAttempt } from "../connection/acquire";
+export { Transport } from "./lifecycle";
+/** Dial address only. Protocol identity remains with the client, never inferred from a forwarded address. */
 export interface Endpoint {
     host: string;
     port: number;
@@ -6,20 +10,24 @@ export interface Endpoint {
 export interface TcpTransport {
     readonly kind: "tcp";
     readonly name: string;
-    connect(endpoint: Endpoint): Promise<Endpoint>;
+    connect(endpoint: Endpoint, attempt?: ConnectionAttempt): Promise<Endpoint>;
 }
-export declare class DirectTransport implements TcpTransport {
+export declare class DirectTransport extends Transport implements TcpTransport {
     readonly kind = "tcp";
     readonly name = "direct";
-    connect(endpoint: Endpoint): Promise<Endpoint>;
+    protected paths(): readonly TransportPath[];
+    connect(endpoint: Endpoint, attempt?: ConnectionAttempt): Promise<Endpoint>;
 }
 /** The supplied forwarder owns port allocation and cleanup; external endpoints may stay direct. */
-export declare class PortForwardTransport implements TcpTransport {
+export declare class PortForwardTransport extends Transport implements TcpTransport {
     private readonly forward;
+    private readonly release?;
     readonly kind = "tcp";
     readonly name = "port-forward";
-    constructor(forward: (endpoint: Endpoint) => Promise<Endpoint>);
-    connect(endpoint: Endpoint): Promise<Endpoint>;
+    constructor(forward: (endpoint: Endpoint, attempt?: ConnectionAttempt) => Promise<Endpoint>, release?: (() => void | Promise<void>) | undefined, signal?: AbortSignal);
+    protected paths(): readonly TransportPath[];
+    connect(endpoint: Endpoint, attempt?: ConnectionAttempt): Promise<Endpoint>;
+    protected close(): Promise<void>;
 }
 export interface PodRunOptions {
     stdin: string;
@@ -27,15 +35,17 @@ export interface PodRunOptions {
 }
 export type PodRunner = (command: readonly string[], options: PodRunOptions) => Promise<string>;
 /** A Python-capable Pod path. Protocol code supplies the script; the host enforces access. */
-export declare class PodPythonTransport {
+export declare class PodPythonTransport extends Transport {
     private readonly exec;
     private readonly python;
     readonly kind = "python";
     readonly name = "pod-python";
     constructor(exec: PodRunner, python?: string);
+    protected paths(): readonly TransportPath[];
     run(script: string, input: unknown, timeoutMs: number): Promise<string>;
 }
-export type Transport = TcpTransport | PodPythonTransport;
+export type TransportPath = TcpTransport | PodPythonTransport;
 /** Only failure to establish a connection permits a route change; never replay protocol operations. */
 export declare function isConnectionNetworkError(error: unknown): boolean;
 export { PodRelayTransport, type PodRelayOptions } from "./pod-relay";
+export { ServicePortForwardTransport } from "./service-port-forward";

package/dist/transport/index.js

@@ -3,16 +3,29 @@ import {
   PodPythonTransport,
   PortForwardTransport,
   isConnectionNetworkError
-} from "../chunk-h8fwx0k7.js";
+} from "../chunk-18gcp0ck.js";
 import {
   PodRelayTransport
-} from "../chunk-fqrknvr8.js";
-import"../chunk-nftzckdy.js";
+} from "../chunk-kap6ka3n.js";
+import"../chunk-ssj93brx.js";
+import {
+  ServicePortForwardTransport
+} from "../chunk-ehmx0yhp.js";
+import"../chunk-0d8vs5q8.js";
+import"../chunk-xgnz10sr.js";
+import"../chunk-6fnhzhdb.js";
+import"../chunk-mvkxs8d0.js";
 import"../chunk-rq5fc007.js";
 import"../chunk-9shz0bw1.js";
-import"../chunk-ssj93brx.js";
+import {
+  Transport
+} from "../chunk-sb5qzv37.js";
+import"../chunk-43mcyrh4.js";
+import"../chunk-rkt41za2.js";
 export {
   isConnectionNetworkError,
+  Transport,
+  ServicePortForwardTransport,
   PortForwardTransport,
   PodRelayTransport,
   PodPythonTransport,

package/dist/transport/lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { Client } from "../client";
+import { type Acquisition } from "../connection/acquire";
+import type { TransportPath } from "./index";
+/**
+ * @spec A transport selects and prepares access paths; protocol establishment is supplied by the client.
+ * @rule Borrowed routes are never disposed by their consumers. Register resource-owning routes with ClientManager.
+ * @see {@link component://docs/toolbox.md}
+ */
+export declare class Transport implements Client {
+    #private;
+    private readonly candidates;
+    /** Root cancellation stops borrowers; only this transport's disposal tears down shared resources. */
+    protected readonly resourceSignal: AbortSignal;
+    readonly signal: AbortSignal;
+    constructor(candidates?: readonly TransportPath[], signal?: AbortSignal);
+    protected paths(): readonly TransportPath[];
+    initialize(): Promise<void>;
+    /** Internal handshake collaboration: only establishment errors can select another path. */
+    acquire<C>(options: Acquisition<TransportPath, C>): Promise<C>;
+    protected close(): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/transport/lifecycle.js

@@ -0,0 +1,8 @@
+import {
+  Transport
+} from "../chunk-sb5qzv37.js";
+import"../chunk-43mcyrh4.js";
+import"../chunk-rkt41za2.js";
+export {
+  Transport
+};

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

@@ -1,7 +1,9 @@
 import type { Client } from "../client";
 import { type Executor, type KubectlOptions } from "../kubernetes/executor";
 import { type StartPortForward } from "../kubernetes/port-forward";
-import type { Endpoint, TcpTransport } from "./index";
+import { Transport } from "./lifecycle";
+import type { Endpoint, TcpTransport, TransportPath } from "./index";
+import type { ConnectionAttempt } from "../connection/acquire";
 export interface PodRelayOptions extends KubectlOptions {
     namespace: string;
     /** Restrict eligible existing Pods without coupling callers to the relay runtime. */
@@ -16,7 +18,7 @@ export interface PodRelayOptions extends KubectlOptions {
 /** Execution-scoped TCP transport borrowed by all Service clients; only its root owner disposes it.
  * Python is private. Requires list pods, pods/exec and pods/portforward, never pods/create.
  */
-export declare class PodRelayTransport implements TcpTransport, Client {
+export declare class PodRelayTransport extends Transport implements TcpTransport, Client {
     #private;
     private readonly options;
     readonly kind = "tcp";
@@ -25,7 +27,8 @@ export declare class PodRelayTransport implements TcpTransport, Client {
         executor?: Executor;
         startForward?: StartPortForward;
     });
+    protected paths(): readonly TransportPath[];
     initialize(): Promise<void>;
-    connect(endpoint: Endpoint): Promise<Endpoint>;
-    dispose(): Promise<void>;
+    connect(endpoint: Endpoint, attempt?: ConnectionAttempt): Promise<Endpoint>;
+    protected close(): Promise<void>;
 }

package/dist/transport/pod-relay.js

@@ -1,10 +1,13 @@
 import {
   PodRelayTransport
-} from "../chunk-fqrknvr8.js";
-import"../chunk-nftzckdy.js";
+} from "../chunk-kap6ka3n.js";
+import"../chunk-ssj93brx.js";
+import"../chunk-mvkxs8d0.js";
 import"../chunk-rq5fc007.js";
 import"../chunk-9shz0bw1.js";
-import"../chunk-ssj93brx.js";
+import"../chunk-sb5qzv37.js";
+import"../chunk-43mcyrh4.js";
+import"../chunk-rkt41za2.js";
 export {
   PodRelayTransport
 };

package/dist/transport/service-port-forward.d.ts

@@ -0,0 +1,30 @@
+import { Transport } from "./lifecycle";
+import type { Endpoint, TcpTransport, TransportPath } from "./index";
+import type { ConnectionAttempt } from "../connection/acquire";
+import { type Executor, type KubectlOptions } from "../kubernetes/executor";
+import type { StartPortForward } from "../kubernetes/port-forward";
+/**
+ * @spec One manager-owned transport shares forwards across protocol clients in the same namespace.
+ * @rule Cancelling a borrower does not stop a shared forward; root disposal releases it.
+ * @see {@link component://docs/toolbox.md}
+ */
+export declare class ServicePortForwardTransport extends Transport implements TcpTransport {
+    #private;
+    private readonly options;
+    private readonly dependencies?;
+    readonly kind = "tcp";
+    readonly name = "port-forward";
+    constructor(options: KubectlOptions & {
+        namespace: string;
+        signal?: AbortSignal;
+        onDiagnostic?: (line: string) => void;
+    }, dependencies?: {
+        executor?: Executor;
+        startForward?: StartPortForward;
+    } | undefined);
+    protected paths(): readonly TransportPath[];
+    initialize(): Promise<void>;
+    get activeForwards(): readonly import("../kubernetes/port-forward").PortForward[];
+    connect(endpoint: Endpoint, attempt?: ConnectionAttempt): Promise<Endpoint>;
+    protected close(): Promise<void>;
+}

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

@@ -0,0 +1,15 @@
+import {
+  ServicePortForwardTransport
+} from "../chunk-ehmx0yhp.js";
+import"../chunk-0d8vs5q8.js";
+import"../chunk-xgnz10sr.js";
+import"../chunk-6fnhzhdb.js";
+import"../chunk-mvkxs8d0.js";
+import"../chunk-rq5fc007.js";
+import"../chunk-9shz0bw1.js";
+import"../chunk-sb5qzv37.js";
+import"../chunk-43mcyrh4.js";
+import"../chunk-rkt41za2.js";
+export {
+  ServicePortForwardTransport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -99,14 +99,15 @@
     "README.md"
   ],
   "dependencies": {
-    "@compforge/harness-common": "0.5.4",
     "@aws-sdk/client-s3": "3.1133.0",
+    "@compforge/harness-common": "0.5.10",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",
     "@redis/client": "6.1.0",
     "@smithy/node-http-handler": "4.12.1",
     "mysql2": "3.23.1",
     "node-fetch": "2.7.0",
+    "race-signal": "2.0.2",
     "ws": "8.21.3"
   },
   "devDependencies": {

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

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

package/dist/{chunk-x0yhfg29.js → chunk-5w85c7cs.js}

@@ -4,14 +4,14 @@ import {
 import {
   clientKey
 } from "./chunk-a9htb6cr.js";
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
 import {
   KubernetesError,
   ToolboxError,
   kubernetesHttpError
 } from "./chunk-rkt41za2.js";
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
 
 // src/kubernetes/resource-transport.ts
 import { KubeConfig } from "@kubernetes/client-node";

package/dist/{chunk-ww11q58v.js → chunk-rncagjbc.js}

@@ -1,10 +1,10 @@
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
 import {
   FileError,
   ToolboxError
 } from "./chunk-rkt41za2.js";
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
 
 // src/file/client.ts
 function fileClientOptions(options) {

package/dist/{chunk-r3rnsvwv.js → chunk-xeft7af0.js}

@@ -1,10 +1,10 @@
+import {
+  ConcurrencyPool
+} from "./chunk-v3hxvnrc.js";
 import {
   KubernetesError,
   kubernetesHttpError
 } from "./chunk-rkt41za2.js";
-import {
-  ConcurrencyPool
-} from "./chunk-v3hxvnrc.js";
 
 // src/kubernetes/exec-transport.ts
 import { KubeConfig } from "@kubernetes/client-node";