@compforge/harness-toolbox 0.3.8 → 0.3.10

package/README.md

@@ -250,3 +250,13 @@ Disposal closes forwards and the exec stream; EOF closes remote listeners/connec
 connection is lost without EOF, a 30-second heartbeat lease bounds remote process lifetime.
 A dead relay invalidates its routes and fails callers; no SQL or other protocol operation is replayed.
 The root should finish or cancel protocol work before disposing the transport.
+
+### OpenSearch connection preparation
+
+`openOpenSearch` probes the resolved endpoint before returning. It tries the supplied TCP transports
+in order only for connection failures; HTTP authorization/server errors stop preparation, and failed
+reads are never replayed on another route. `onRoute` reports the selected transport and safe fallback
+reason. The caller owns shared transports such as `PodRelayTransport` and their cleanup.
+
+Routed HTTPS preserves the original TLS server name. Bun disables HTTP keep-alive because its reused
+socket recovery can replay a failed request below the driver; Node retains connection pooling.

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

@@ -9,6 +9,9 @@ import {
   queryMysqlViaPod,
   queryMysqlViaPodBatch
 } from "./chunk-m91t44jh.js";
+import {
+  ToolboxError
+} from "./chunk-zhkrydeg.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";
@@ -18,6 +21,16 @@ import {
 
 // src/mysql/client.ts
 import { createConnection } from "mysql2/promise";
+function mysqlOperationError(error, phase) {
+  if (!error || typeof error !== "object" || !("code" in error) || error.code !== "PROTOCOL_CONNECTION_LOST")
+    return error;
+  return new ToolboxError(`MySQL ${phase} failed: connection lost (PROTOCOL_CONNECTION_LOST)`, {
+    kind: "connection_lost",
+    code: error.code,
+    cause: error
+  });
+}
+
 class MysqlDatabase {
   transports;
   options;
@@ -56,6 +69,8 @@ class MysqlDatabase {
         throw new Error("Bounded readonly MySQL queries require a native TCP transport");
       try {
         return await queryReadonlySession(session.connection, sql, values, limits, this.options.signal);
+      } catch (error) {
+        throw mysqlOperationError(error, "query");
       } finally {
         destroyMysqlConnection(session.connection);
       }
@@ -94,7 +109,7 @@ class MysqlDatabase {
         this.#connections.delete(key);
       if (session?.kind === "tcp")
         destroyMysqlConnection(session.connection);
-      throw error;
+      throw session ? mysqlOperationError(error, "query") : error;
     }
   }
   async#query(target, sql, values) {
@@ -130,9 +145,11 @@ class MysqlDatabase {
         this.options.onRoute?.({ transport: endpoint.host === target.host && endpoint.port === target.port ? "direct" : transport.name, reason });
         return { kind: "tcp", connection };
       } catch (error) {
-        if (!isConnectionNetworkError(error) || i === this.transports.length - 1)
-          throw error;
-        reason = String(error.code);
+        const failure = mysqlOperationError(error, "connect");
+        const connectionLost = failure instanceof ToolboxError && failure.kind === "connection_lost";
+        if (!isConnectionNetworkError(failure) && !connectionLost || i === this.transports.length - 1)
+          throw failure;
+        reason = String(failure.code);
       }
     }
     throw new Error("MySQL DataSource has no transport");

package/dist/{chunk-w3a4p6jm.js → chunk-b7f39m4v.js}

@@ -1,15 +1,30 @@
+import {
+  ToolboxError
+} from "./chunk-zhkrydeg.js";
+import {
+  isConnectionNetworkError
+} from "./chunk-h8fwx0k7.js";
+
 // src/opensearch/client.ts
-import { Client } from "@opensearch-project/opensearch";
+import { Client, Connection, errors } from "@opensearch-project/opensearch";
 function isOpenSearchReadApi(search) {
   return typeof search.request === "function";
 }
+
+class OpenSearchConnection extends Connection {
+  buildRequestObject(params) {
+    return { ...super.buildRequestObject(params), servername: this.ssl?.servername };
+  }
+}
 function createClient(options) {
   return new Client({
     node: options.node,
+    Connection: OpenSearchConnection,
     auth: options.auth.username && options.auth.password ? { username: options.auth.username, password: options.auth.password } : undefined,
-    ssl: { rejectUnauthorized: false },
+    ssl: { rejectUnauthorized: false, servername: options.servername },
     requestTimeout: options.requestTimeoutMs ?? 60000,
-    maxRetries: 0
+    maxRetries: 0,
+    agent: { keepAlive: !process.versions.bun }
   });
 }
 
@@ -36,8 +51,18 @@ class OpenSearchEngine {
     });
     return response.body;
   }
-  ping() {
-    return this.client.ping();
+  async ping(signal, timeoutMs) {
+    signal?.throwIfAborted();
+    const request = this.client.ping({}, timeoutMs === undefined ? undefined : { requestTimeout: timeoutMs });
+    const abort = () => {
+      request.abort?.();
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      return await request;
+    } finally {
+      signal?.removeEventListener("abort", abort);
+    }
   }
   close() {
     return this.client.close();
@@ -46,6 +71,7 @@ class OpenSearchEngine {
 
 class OpenSearchClient {
   source;
+  lifecycle;
   #controller = new AbortController;
   signal;
   #initialization;
@@ -54,6 +80,7 @@ class OpenSearchClient {
   #operations = new Set;
   constructor(source, lifecycle = {}) {
     this.source = source;
+    this.lifecycle = lifecycle;
     this.signal = lifecycle.signal ? AbortSignal.any([lifecycle.signal, this.#controller.signal]) : this.#controller.signal;
   }
   initialize() {
@@ -61,15 +88,42 @@ class OpenSearchClient {
     return this.#initialization ??= (async () => {
       const target = await this.source.resolve();
       this.signal.throwIfAborted();
-      const transport = this.source.transports[0];
-      if (!transport || transport.kind !== "tcp")
-        throw new Error("OpenSearch requires a TCP transport");
-      const url = new URL(target.node);
-      const endpoint = await transport.connect({ host: url.hostname, port: Number(url.port || (url.protocol === "https:" ? 443 : 80)) });
-      this.signal.throwIfAborted();
-      url.hostname = endpoint.host;
-      url.port = String(endpoint.port);
-      this.#engine = new OpenSearchEngine({ ...target, node: url.toString() });
+      const original = new URL(target.node);
+      let reason;
+      for (const [index, transport] of this.source.transports.entries()) {
+        this.signal.throwIfAborted();
+        if (transport.kind !== "tcp")
+          throw new Error("OpenSearch requires a TCP transport");
+        let engine;
+        try {
+          const endpoint = await transport.connect({
+            host: original.hostname,
+            port: Number(original.port || (original.protocol === "https:" ? 443 : 80)),
+            servername: target.servername ?? original.hostname
+          });
+          this.signal.throwIfAborted();
+          const url = new URL(original);
+          url.hostname = endpoint.host;
+          url.port = String(endpoint.port);
+          engine = new OpenSearchEngine({ ...target, node: url.toString(), servername: endpoint.servername ?? target.servername ?? original.hostname });
+          await engine.ping(this.signal, target.connectTimeoutMs ?? target.requestTimeoutMs ?? 1e4);
+          this.signal.throwIfAborted();
+          this.lifecycle.onRoute?.({ transport: transport.name, reason });
+          this.#engine = engine;
+          return;
+        } catch (error) {
+          await engine?.close();
+          this.signal.throwIfAborted();
+          const network = isConnectionNetworkError(error);
+          if (!network && !(error instanceof errors.ConnectionError) && !(error instanceof errors.TimeoutError))
+            throw error;
+          reason = network ? String(error.code) : error.name;
+          if (index === this.source.transports.length - 1) {
+            throw new ToolboxError(`OpenSearch connect failed (${reason})`, { kind: "connection_failed", code: reason, cause: error });
+          }
+        }
+      }
+      throw new Error("OpenSearch DataSource has no transport");
     })();
   }
   #ready() {

package/dist/mysql/client.d.ts

@@ -8,7 +8,11 @@ export interface MysqlDatabaseOptions extends ClientLifecycle {
     queryTimeoutMs: number;
 }
 type ConnectionFactory = (options: ConnectionOptions) => Promise<Connection>;
-/** SQL is executed once; only native connection establishment may advance to another transport. */
+/**
+ * @spec SQL is executed once; only native connection establishment may advance to another transport.
+ * @why mysql2 reports a socket closed during handshake as PROTOCOL_CONNECTION_LOST, before any SQL is sent.
+ * @case id=mysql_handshake_closed,desc=`Peer closes during handshake`,expect=`Try the next transport`,forbid=`Replay an interrupted query`
+ */
 export declare class MysqlDatabase implements Database {
     #private;
     private readonly transports;

package/dist/mysql/client.js

@@ -2,10 +2,11 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-qqntng20.js";
+} from "../chunk-ahc00qs5.js";
 import"../chunk-age65q4n.js";
 import"../chunk-136egyff.js";
 import"../chunk-m91t44jh.js";
+import"../chunk-zhkrydeg.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";

package/dist/mysql/index.js

@@ -14,10 +14,11 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-qqntng20.js";
+} from "../chunk-ahc00qs5.js";
 import"../chunk-age65q4n.js";
 import"../chunk-136egyff.js";
 import"../chunk-m91t44jh.js";
+import"../chunk-zhkrydeg.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-wv4jwhvj.js";

package/dist/opensearch/client.d.ts

@@ -9,6 +9,10 @@ export interface OpenSearchOptions {
     node: string;
     auth: OpenSearchAuth;
     requestTimeoutMs?: number;
+    /** Deadline for the initialization probe; query deadlines remain independent. */
+    connectTimeoutMs?: number;
+    /** Original TLS identity when a transport maps the socket to localhost. */
+    servername?: string;
 }
 export interface OpenSearchClientApi {
     count(params: Record<string, unknown>): Promise<{
@@ -19,7 +23,11 @@ export interface OpenSearchClientApi {
     search(params: Record<string, unknown>): Promise<{
         body: SearchResult;
     }>;
-    ping(params?: Record<string, unknown>): Promise<unknown>;
+    ping(params?: Record<string, unknown>, options?: {
+        requestTimeout?: number;
+    }): Promise<unknown> & {
+        abort?(): void;
+    };
     transport?: {
         request(params: {
             method: string;
@@ -43,12 +51,18 @@ export declare class OpenSearchEngine implements OpenSearchReadApi {
     count(index: string, query: SearchQuery): Promise<number>;
     search(index: string, body: SearchQuery): Promise<SearchResult>;
     request(path: string, query?: SearchQuery): Promise<unknown>;
-    ping(): Promise<unknown>;
+    ping(signal?: AbortSignal, timeoutMs?: number): Promise<unknown>;
     close(): Promise<void>;
 }
+/**
+ * @spec Only connection preparation may advance to another Transport; reads are never replayed.
+ * @why The official client connects lazily and wraps socket errors, so creating it does not prove reachability.
+ * @case id=opensearch_connect_fallback,desc=`Host cannot reach target`,expect=`Probe next TCP route`,forbid=`Replay a failed search`
+ */
 export declare class OpenSearchClient implements ManagedClient, OpenSearchReadApi {
     #private;
     private readonly source;
+    private readonly lifecycle;
     readonly signal: AbortSignal;
     constructor(source: ConnectionSource<OpenSearchOptions>, lifecycle?: ClientLifecycle);
     initialize(): Promise<void>;

package/dist/opensearch/client.js

@@ -3,7 +3,14 @@ import {
   OpenSearchEngine,
   isOpenSearchReadApi,
   openOpenSearch
-} from "../chunk-w3a4p6jm.js";
+} from "../chunk-b7f39m4v.js";
+import"../chunk-zhkrydeg.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-wv4jwhvj.js";
+import"../chunk-631vce5z.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   openOpenSearch,
   isOpenSearchReadApi,

package/dist/opensearch/index.js

@@ -3,7 +3,7 @@ import {
   OpenSearchEngine,
   isOpenSearchReadApi,
   openOpenSearch
-} from "../chunk-w3a4p6jm.js";
+} from "../chunk-b7f39m4v.js";
 import {
   searchAfterPages
 } from "../chunk-99p0zt4f.js";
@@ -11,6 +11,13 @@ import {
   parseOpenSearchEndpoint
 } from "../chunk-s1sjyem7.js";
 import"../chunk-djk4kmxb.js";
+import"../chunk-zhkrydeg.js";
+import"../chunk-h8fwx0k7.js";
+import"../chunk-wv4jwhvj.js";
+import"../chunk-631vce5z.js";
+import"../chunk-hmah9t8e.js";
+import"../chunk-mn6dwsvh.js";
+import"../chunk-ssj93brx.js";
 export {
   searchAfterPages,
   parseOpenSearchEndpoint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {