@compforge/harness-toolbox 0.5.1 → 0.5.3

package/README.md

@@ -426,3 +426,7 @@ MySQL, OpenSearch and Redis use the same acquisition lifecycle. `connectTimeoutM
 and handshake/probe; optional `acquireTimeoutMs` bounds all routes together (default: per-route budget × route count).
 Cancellation preserves the caller reason and prevents late mappings from starting a handshake. Query and command
 timeouts remain separate, and failed operations are never replayed on another transport.
+
+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.

package/dist/data-loader.d.ts

@@ -3,6 +3,11 @@ export interface DataLoaderOptions {
     /** Serialized result bytes retained, excluding keys/errors and active operation memory. */
     maxBytes: number;
     signal: AbortSignal;
+    /** Non-sensitive label supplied by the adapter; keys and values never enter diagnostics. */
+    label?: string;
+    logger?: {
+        debug(message: string): void;
+    };
 }
 /** A scoped async loading cache, similar to Guava's LoadingCache.
  * Shares results, failures and in-flight reads until close; consumers must not mutate results.

package/dist/data-loader.js

@@ -1,8 +1,12 @@
 // src/data-loader.ts
 import { serialize } from "node:v8";
+var nextScopeId = 0;
 
 class DataLoader {
   options;
+  #scopeId = ++nextScopeId;
+  #readIds = new WeakMap;
+  #nextReadId = 0;
   #entries = new Map;
   #pending = new Set;
   #controller = new AbortController;
@@ -20,30 +24,46 @@ class DataLoader {
   #abort = () => {
     this.close(this.options.signal.reason);
   };
+  #debug(event, readId, reason) {
+    if (!this.options.logger)
+      return;
+    try {
+      this.options.logger.debug(`[data-loader] scope=${this.#scopeId}` + (this.options.label ? ` label=${this.options.label}` : "") + (readId === undefined ? "" : ` read=${readId}`) + ` event=${event}` + (reason ? ` reason=${reason}` : ""));
+    } catch {}
+  }
   async read(key, operation, signal) {
     this.#controller.signal.throwIfAborted();
     signal?.throwIfAborted();
     let pending = key === undefined ? undefined : this.#entries.get(key);
-    if (!pending) {
+    if (pending) {
+      this.#debug(this.#pending.has(pending) ? "wait" : "hit", this.#readIds.get(pending));
+    } else {
+      const readId = ++this.#nextReadId;
       const retain = key !== undefined && this.#entries.size < this.options.maxEntries;
+      this.#debug(retain ? "miss" : "bypass", readId, retain ? undefined : key === undefined ? "no-key" : "entry-limit");
       pending = Promise.resolve().then(async () => {
         this.#controller.signal.throwIfAborted();
         const value = await operation(this.#controller.signal);
         this.#controller.signal.throwIfAborted();
         if (retain) {
           let bytes;
+          let reason = "byte-limit";
           try {
             bytes = serialize(value).byteLength;
           } catch {
             bytes = Infinity;
+            reason = "not-serializable";
           }
           if (this.#bytes + bytes <= this.options.maxBytes)
             this.#bytes += bytes;
-          else
+          else {
             this.#entries.delete(key);
+            this.#debug("not-retained", readId, reason);
+          }
         }
         return value;
       });
+      this.#readIds.set(pending, readId);
       if (retain)
         this.#entries.set(key, pending);
       this.#pending.add(pending);
@@ -74,6 +94,7 @@ class DataLoader {
   }
   close(reason = new Error("DataLoader scope is closed")) {
     if (!this.#closing) {
+      this.#debug("close");
       this.#closing = Promise.resolve().then(async () => {
         await Promise.allSettled([...this.#pending]);
         this.#entries.clear();

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -104,7 +104,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "3.1133.0",
-    "@compforge/harness-common": "0.5.10",
+    "@compforge/harness-common": "0.5.11",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",
     "@redis/client": "6.1.0",
@@ -122,6 +122,9 @@
     "@types/node": "^22",
     "@types/ws": "^8.18.1"
   },
+  "overrides": {
+    "@compforge/harness-common": "file:../common"
+  },
   "publishConfig": {
     "access": "public"
   },