@compforge/harness-toolbox 0.5.2 → 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/kubernetes/secret-datasource.d.ts

@@ -0,0 +1,44 @@
+import { type Client, type ClientManager, type ClientProvider, type DataSource } from "@compforge/harness-common";
+import { type ResourceAccess, type ResourceRequestOptions } from "./resources";
+export interface KubernetesSecretTarget {
+    readonly namespace: string;
+    readonly name: string;
+}
+export interface KubernetesSecretRead {
+    resourceVersion?: string;
+    observedAt: string;
+    values: Record<string, string>;
+    /** A successful read can establish absence without treating it as an API failure. */
+    missingKeys: string[];
+}
+export type KubernetesSecretAccess = Client & Pick<ResourceAccess, "get">;
+export declare function secretKeys(keys: readonly string[]): readonly string[];
+/**
+ * @spec Only declared UTF-8 keys enter results; Kubernetes failures retain their kind and never become missing keys.
+ * @rule The borrowed resource access owns transport capacity and byte limits; request deadlines and cancellation flow through get.
+ * @see {@link component://../../../docs/toolbox.md}
+ */
+export declare class KubernetesSecretClient implements Client {
+    #private;
+    private readonly acquire;
+    readonly keys: readonly string[];
+    constructor(keys: readonly string[], signal: AbortSignal, acquire: () => Promise<{
+        target: KubernetesSecretTarget;
+        access: Pick<ResourceAccess, "get">;
+    }>);
+    get target(): Readonly<KubernetesSecretTarget>;
+    initialize(): Promise<void>;
+    read(options?: ResourceRequestOptions): Promise<KubernetesSecretRead>;
+    private capture;
+    /** @spec Disposal cancels and drains owned reads without closing borrowed Kubernetes access. */
+    dispose(): Promise<void>;
+}
+/** Named Secret acquisition; callers own discovery, access policy and interpretation of the selected values. */
+export declare class KubernetesSecretDataSource implements DataSource<KubernetesSecretClient> {
+    private readonly kubernetes;
+    readonly clientKey: string;
+    readonly target: Readonly<KubernetesSecretTarget>;
+    readonly keys: readonly string[];
+    constructor(kubernetes: ClientProvider<KubernetesSecretAccess>, target: KubernetesSecretTarget, keys: readonly string[]);
+    createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): KubernetesSecretClient;
+}

package/dist/kubernetes/secret-datasource.js

@@ -0,0 +1,118 @@
+import {
+  resourcePath
+} from "../chunk-dpcge1xt.js";
+import {
+  KubernetesError
+} from "../chunk-rkt41za2.js";
+
+// src/kubernetes/secret-datasource.ts
+import { clientKey } from "@compforge/harness-common";
+function secretKeys(keys) {
+  if (!keys.length || keys.some((key) => !/^[A-Za-z0-9._-]+$/.test(key)) || new Set(keys).size !== keys.length) {
+    throw new KubernetesError("Secret keys must be nonempty, distinct Kubernetes data keys", { kind: "invalid_argument" });
+  }
+  return Object.freeze([...keys]);
+}
+function secretTarget(target) {
+  if (!target.namespace || !target.name)
+    throw new KubernetesError("Secret target requires namespace and name", { kind: "invalid_argument" });
+  resourcePath({ apiVersion: "v1", resource: "secrets", namespace: target.namespace }, target.name);
+  return Object.freeze({ namespace: target.namespace, name: target.name });
+}
+
+class KubernetesSecretClient {
+  acquire;
+  keys;
+  #controller = new AbortController;
+  #signal;
+  #operations = new Set;
+  #target;
+  #access;
+  #disposal;
+  constructor(keys, signal, acquire) {
+    this.acquire = acquire;
+    this.keys = secretKeys(keys);
+    this.#signal = AbortSignal.any([signal, this.#controller.signal]);
+  }
+  get target() {
+    if (!this.#target)
+      throw new KubernetesError("Secret client is not initialized", { kind: "operation_failed" });
+    return this.#target;
+  }
+  async initialize() {
+    this.#signal.throwIfAborted();
+    const { target, access } = await this.acquire();
+    this.#signal.throwIfAborted();
+    this.#target = secretTarget(target);
+    this.#access = access;
+  }
+  async read(options = {}) {
+    const signal = options.signal ? AbortSignal.any([this.#signal, options.signal]) : this.#signal;
+    signal.throwIfAborted();
+    const target = this.target;
+    const operation = this.capture(target, { ...options, signal });
+    this.#operations.add(operation);
+    try {
+      return await operation;
+    } finally {
+      this.#operations.delete(operation);
+    }
+  }
+  async capture(target, options) {
+    const secret = await this.#access.get({ apiVersion: "v1", resource: "secrets", ...target }, options);
+    options.signal.throwIfAborted();
+    const values = Object.create(null);
+    const missingKeys = [];
+    for (const key of this.keys) {
+      if (!Object.hasOwn(secret.data ?? {}, key)) {
+        missingKeys.push(key);
+        continue;
+      }
+      const encoded = secret.data[key];
+      try {
+        const bytes = Buffer.from(encoded, "base64");
+        if (bytes.toString("base64") !== encoded)
+          throw new Error("invalid base64");
+        values[key] = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      } catch {
+        throw new KubernetesError(`Secret key is not valid base64 UTF-8: ${key}`, { kind: "invalid_response" });
+      }
+    }
+    return {
+      values,
+      missingKeys,
+      observedAt: new Date().toISOString(),
+      ...typeof secret.metadata?.resourceVersion === "string" ? { resourceVersion: secret.metadata.resourceVersion } : {}
+    };
+  }
+  dispose() {
+    this.#disposal ??= (async () => {
+      this.#controller.abort(new KubernetesError("Secret client disposed", { kind: "operation_failed" }));
+      await Promise.allSettled([...this.#operations]);
+      this.#target = undefined;
+      this.#access = undefined;
+    })();
+    return this.#disposal;
+  }
+}
+
+class KubernetesSecretDataSource {
+  kubernetes;
+  clientKey;
+  target;
+  keys;
+  constructor(kubernetes, target, keys) {
+    this.kubernetes = kubernetes;
+    this.target = secretTarget(target);
+    this.keys = secretKeys(keys);
+    this.clientKey = clientKey("kubernetes-secret", { access: kubernetes.clientKey, target: this.target, keys: this.keys });
+  }
+  createClient(clients, signal) {
+    return new KubernetesSecretClient(this.keys, signal, async () => ({ target: this.target, access: await clients.get(this.kubernetes) }));
+  }
+}
+export {
+  secretKeys,
+  KubernetesSecretDataSource,
+  KubernetesSecretClient
+};

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.2",
+  "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": [