@compforge/harness-toolbox 0.5.3 → 0.5.4

package/README.md

@@ -430,3 +430,14 @@ timeouts remain separate, and failed operations are never replayed on another tr
 DataLoader accepts an optional `logger.debug(message)` and a non-sensitive `label`.
 Diagnostics distinguish miss, wait, hit, bypass, not-retained and close using scope/read
 identifiers, never keys, values or errors. Logging does not change retention or retry policy.
+
+### Network connectivity
+
+`@compforge/harness-toolbox/network` exports `probeConnectivity({host, port, tls?}, execute, {timeoutMs, signal?})`.
+The caller supplies an executor in the consumer environment (host, Pod or sandbox),
+which runs Python 3 with the supplied argv and stdin and enforces timeout/cancellation.
+DNS, TCP and optional verified TLS have separate results and timings. Domain names,
+IP literals and Kubernetes `service.namespace` names use the same API. There is no
+implicit execution on the caller host or ICMP requirement. Network failure returns
+evidence; missing Python, execution failure and incomplete output throw. TLS success
+does not establish HTTP authorization, object access or application download policy.

package/dist/mysql/index.js

@@ -1,3 +1,6 @@
+import {
+  withReadScope
+} from "../chunk-4sqvppz7.js";
 import {
   MysqlClient,
   MysqlDatabase,
@@ -15,9 +18,6 @@ import {
 } from "../chunk-1gyshqd9.js";
 import"../chunk-835fssgz.js";
 import"../chunk-pfar9cm3.js";
-import {
-  withReadScope
-} from "../chunk-4sqvppz7.js";
 import"../chunk-18gcp0ck.js";
 import"../chunk-kap6ka3n.js";
 import"../chunk-v3hxvnrc.js";

package/dist/network/connectivity.d.ts

@@ -0,0 +1,35 @@
+/** A probe runs in the caller-selected environment; it never falls back to the Doctor/CLI host. */
+export interface ConnectivityTarget {
+    host: string;
+    port: number;
+    tls?: boolean;
+}
+export interface ConnectivityStage {
+    stage: "dns" | "tcp" | "tls";
+    status: "passed" | "failed";
+    elapsedMs: number;
+    addresses?: string[];
+    address?: string;
+    error?: string;
+}
+export interface ConnectivityResult {
+    target: ConnectivityTarget;
+    stages: ConnectivityStage[];
+    status: "passed" | "failed";
+}
+export interface ConnectivityExecutor {
+    (command: readonly string[], options: {
+        stdin: string;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+/**
+ * @spec DNS, TCP and optional verified TLS are observed from the supplied executor's network context.
+ * @rule A hostname (including service.namespace) and an IP use the same path; connectivity requires an explicit port.
+ * @rule Tool failure/timeout throws; it is not evidence that the target is unhealthy. No ICMP, credentials or HTTP policy is implied.
+ */
+export declare function probeConnectivity(target: ConnectivityTarget, execute: ConnectivityExecutor, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<ConnectivityResult>;

package/dist/network/connectivity.js

@@ -0,0 +1,63 @@
+// src/network/connectivity.ts
+var SCRIPT = `import json,socket,ssl,sys,time
+q=json.load(sys.stdin)
+start=time.monotonic()
+deadline=start+q["timeoutMs"]/1000
+stages=[]
+def remaining():
+    t=deadline-time.monotonic()
+    if t<=0: raise TimeoutError()
+    return t
+def add(stage,t,**values):
+    stages.append(dict(stage=stage,elapsedMs=round((time.monotonic()-t)*1000,3),**values))
+phase="dns"
+t=time.monotonic()
+sock=None
+try:
+    addresses=socket.getaddrinfo(q["host"],q["port"],type=socket.SOCK_STREAM)
+    if not addresses: raise socket.gaierror()
+    add(phase,t,status="passed",addresses=list(dict.fromkeys(a[4][0] for a in addresses))[:8])
+    phase="tcp"
+    t=time.monotonic()
+    failure=None
+    for family,kind,proto,_,address in addresses[:8]:
+        candidate=socket.socket(family,kind,proto)
+        try:
+            candidate.settimeout(remaining())
+            candidate.connect(address)
+            sock=candidate
+            break
+        except OSError as e:
+            failure=e
+            candidate.close()
+    if sock is None: raise failure or OSError()
+    add(phase,t,status="passed",address=sock.getpeername()[0])
+    if q.get("tls"):
+        phase="tls"
+        t=time.monotonic()
+        sock.settimeout(remaining())
+        sock=ssl.create_default_context().wrap_socket(sock,server_hostname=q["host"])
+        add(phase,t,status="passed")
+except (OSError,ValueError) as e:
+    add(phase,t,status="failed",error=type(e).__name__)
+finally:
+    if sock is not None: sock.close()
+print(json.dumps(dict(stages=stages,status="failed" if any(s["status"]=="failed" for s in stages) else "passed")))`;
+async function probeConnectivity(target, execute, options) {
+  if (!target.host.trim() || /[\s/\\?#@]/.test(target.host) || !Number.isInteger(target.port) || target.port < 1 || target.port > 65535) {
+    throw new Error("Connectivity requires a hostname/IP and a port between 1 and 65535");
+  }
+  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)
+    throw new Error("Connectivity timeout must be positive");
+  options.signal?.throwIfAborted();
+  const raw = await execute(["python3", "-c", SCRIPT], { ...options, stdin: JSON.stringify({ ...target, timeoutMs: options.timeoutMs }) });
+  options.signal?.throwIfAborted();
+  const value = JSON.parse(raw);
+  const expected = ["dns", "tcp", ...target.tls ? ["tls"] : []];
+  if (!value || !Array.isArray(value.stages) || !value.stages.length || value.stages.length > expected.length || !["passed", "failed"].includes(value.status) || value.stages.some((stage, index) => !stage || stage.stage !== expected[index] || !["passed", "failed"].includes(stage.status) || !Number.isFinite(stage.elapsedMs) || stage.elapsedMs < 0 || index < value.stages.length - 1 && stage.status !== "passed") || (value.status === "passed" ? value.stages.length !== expected.length || value.stages.some((stage) => stage.status !== "passed") : value.stages.at(-1)?.status !== "failed"))
+    throw new Error("Invalid connectivity probe result");
+  return { target: { ...target }, stages: value.stages, status: value.status };
+}
+export {
+  probeConnectivity
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -96,6 +96,10 @@
     "./http": {
       "types": "./dist/http/index.d.ts",
       "import": "./dist/http/index.js"
+    },
+    "./network": {
+      "types": "./dist/network/connectivity.d.ts",
+      "import": "./dist/network/connectivity.js"
     }
   },
   "files": [
@@ -122,9 +126,6 @@
     "@types/node": "^22",
     "@types/ws": "^8.18.1"
   },
-  "overrides": {
-    "@compforge/harness-common": "file:../common"
-  },
   "publishConfig": {
     "access": "public"
   },