@compforge/harness-toolbox 0.5.2 → 0.5.3

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.2",
+  "version": "0.5.3",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -122,6 +122,9 @@
     "@types/node": "^22",
     "@types/ws": "^8.18.1"
   },
+  "overrides": {
+    "@compforge/harness-common": "file:../common"
+  },
   "publishConfig": {
     "access": "public"
   },