@checkstack/secrets-backend 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @checkstack/secrets-backend
 
+## 0.3.4
+
+### Patch Changes
+
+- 43e4484: Kill the redundant active-backend-id read N+1 in secret run resolution.
+  Behavior unchanged; performance-only: the same env vars and masking context are
+  produced for a run, only the number of active-backend-id config reads drops from
+  N (one per distinct secret name) to 1.
+
+  - The internal `SecretStore` interface gains an optional
+    `resolveMany(names: string[]): Promise<Map<string, string>>` batch path
+    (the single `resolve` stays for back-compat and single-secret callers).
+  - The active-backend store (`createActiveBackendStore`) implements
+    `resolveMany`: it resolves the active backend id ONCE for the whole batch and
+    then fetches each distinct name through that single backend, de-duping names
+    and throwing the same `Secret not found: NAME` on any absent value. The
+    per-name backend fetch is inherent; the removed redundancy is the per-name
+    active-backend-id config read.
+  - `SecretResolverService.resolveForRun` now collects the distinct secret names
+    (as before) and resolves them via one `resolveMany` call instead of a per-name
+    `resolve` loop. Stores without a batch path fall back to looping `resolve`,
+    so behavior is identical for every caller.
+
+  State & scale: the active backend id still resolves from the shared config
+  store, so every pod returns the same answer; no process-local or duplicated
+  state is introduced.
+
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+  - @checkstack/backend-api@0.31.1
+  - @checkstack/command-backend@0.2.22
+
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [f93ee7a]
+- Updated dependencies [f93ee7a]
+- Updated dependencies [d0eddc9]
+- Updated dependencies [d0eddc9]
+- Updated dependencies [d0eddc9]
+- Updated dependencies [f93ee7a]
+  - @checkstack/common@0.22.0
+  - @checkstack/backend-api@0.31.0
+  - @checkstack/command-backend@0.2.21
+  - @checkstack/secrets-common@0.3.2
+
 ## 0.3.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/secrets-backend",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Secrets platform backend: resolver service, masking, backend extension point, RPC router",
   "author": "Checkstack contributors",
   "license": "Elastic-2.0",
@@ -25,22 +25,22 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.30.0",
-    "@checkstack/command-backend": "0.2.20",
-    "@checkstack/common": "0.21.0",
-    "@checkstack/secrets-common": "0.3.1",
+    "@checkstack/backend-api": "0.31.1",
+    "@checkstack/command-backend": "0.2.22",
+    "@checkstack/common": "0.22.0",
+    "@checkstack/secrets-common": "0.3.2",
     "@orpc/server": "^1.14.4",
     "drizzle-orm": "^0.45.0",
     "uuid": "^14.0.0",
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@checkstack/scripts": "0.7.2",
-    "@checkstack/dev-server": "2.2.7",
-    "@checkstack/backend": "0.23.5",
+    "@checkstack/scripts": "0.7.3",
+    "@checkstack/dev-server": "2.2.8",
+    "@checkstack/backend": "0.24.1",
     "@checkstack/tsconfig": "0.0.7",
     "@checkstack/drizzle-helper": "0.0.6",
-    "@checkstack/test-utils-backend": "0.1.54",
+    "@checkstack/test-utils-backend": "0.1.56",
     "@types/bun": "^1.3.5",
     "@types/node": "^20.0.0",
     "drizzle-kit": "^0.31.10",

package/src/active-backend.test.ts

@@ -43,4 +43,94 @@ describe("createActiveBackendStore", () => {
       "Secret not found: absent",
     );
   });
+
+  describe("resolveMany", () => {
+    it("resolves the active backend id exactly once for the whole batch", async () => {
+      const registry = createSecretBackendRegistry();
+      registry.register(
+        fakeBackend("local", { A: "a-val", B: "b-val", C: "c-val" }),
+      );
+
+      let idReads = 0;
+      const store = createActiveBackendStore({
+        backends: registry,
+        getActiveBackendId: async () => {
+          idReads++;
+          return "local";
+        },
+      });
+
+      const resolved = await store.resolveMany!(["A", "B", "C"]);
+      expect(idReads).toBe(1);
+      expect(resolved).toEqual(
+        new Map([
+          ["A", "a-val"],
+          ["B", "b-val"],
+          ["C", "c-val"],
+        ]),
+      );
+    });
+
+    it("de-dupes names and reads the active backend id once", async () => {
+      const registry = createSecretBackendRegistry();
+      let gets = 0;
+      registry.register({
+        id: "local",
+        get: async ({ name }) => {
+          gets++;
+          return `val-${name}`;
+        },
+        list: async () => [],
+      });
+
+      let idReads = 0;
+      const store = createActiveBackendStore({
+        backends: registry,
+        getActiveBackendId: async () => {
+          idReads++;
+          return "local";
+        },
+      });
+
+      const resolved = await store.resolveMany!(["dup", "dup", "other"]);
+      expect(idReads).toBe(1);
+      expect(gets).toBe(2); // distinct names only
+      expect(resolved).toEqual(
+        new Map([
+          ["dup", "val-dup"],
+          ["other", "val-other"],
+        ]),
+      );
+    });
+
+    it("returns an empty map (and reads no backend id) for empty input", async () => {
+      const registry = createSecretBackendRegistry();
+      registry.register(fakeBackend("local", {}));
+
+      let idReads = 0;
+      const store = createActiveBackendStore({
+        backends: registry,
+        getActiveBackendId: async () => {
+          idReads++;
+          return "local";
+        },
+      });
+
+      const resolved = await store.resolveMany!([]);
+      expect(resolved.size).toBe(0);
+      expect(idReads).toBe(0);
+    });
+
+    it("throws Secret not found on any absent name", async () => {
+      const registry = createSecretBackendRegistry();
+      registry.register(fakeBackend("local", { A: "a-val" }));
+      const store = createActiveBackendStore({
+        backends: registry,
+        getActiveBackendId: async () => "local",
+      });
+      await expect(store.resolveMany!(["A", "missing"])).rejects.toThrow(
+        "Secret not found: missing",
+      );
+    });
+  });
 });

package/src/active-backend.ts

@@ -24,5 +24,26 @@ export function createActiveBackendStore({
       }
       return value;
     },
+
+    resolveMany: async (names: string[]): Promise<Map<string, string>> => {
+      const distinct = [...new Set(names)];
+      const resolved = new Map<string, string>();
+      if (distinct.length === 0) {
+        return resolved;
+      }
+      // Resolve the active backend id ONCE for the whole batch. The id
+      // read goes through the config store (a DB read), so doing it per
+      // name — as a `resolve` loop would — is the redundant N+1 this path
+      // removes. The per-name `backend.get` fetch is inherent.
+      const backend = backends.get(await getActiveBackendId());
+      for (const name of distinct) {
+        const value = await backend.get({ name });
+        if (value === undefined) {
+          throw new Error(`Secret not found: ${name}`);
+        }
+        resolved.set(name, value);
+      }
+      return resolved;
+    },
   };
 }

package/src/resolver-service.test.ts

@@ -65,7 +65,7 @@ describe("SecretResolverService.resolveForRun", () => {
     ).rejects.toThrow("Secret not found: absent");
   });
 
-  it("resolves each distinct secret once even when reused", async () => {
+  it("resolves each distinct secret once even when reused (resolve fallback)", async () => {
     let calls = 0;
     const counting: SecretStore = {
       resolve: async (name) => {
@@ -84,4 +84,35 @@ describe("SecretResolverService.resolveForRun", () => {
     // "same" + "other" → 2 distinct resolutions despite 3 references.
     expect(calls).toBe(2);
   });
+
+  it("uses resolveMany once for the whole batch when the store provides it", async () => {
+    let manyCalls = 0;
+    let singleCalls = 0;
+    const batching: SecretStore = {
+      resolve: async (name) => {
+        singleCalls++;
+        return `val-${name}`;
+      },
+      resolveMany: async (names) => {
+        manyCalls++;
+        return new Map(names.map((name) => [name, `val-${name}`]));
+      },
+    };
+    const service = createSecretResolverService({ secretStore: batching });
+    const { env } = await service.resolveForRun({
+      secretEnv: {
+        A: "${{ secrets.same }}",
+        B: "${{ secrets.same }}",
+        C: "${{ secrets.other }}",
+      },
+    });
+    // One batch call, never the per-name single resolve.
+    expect(manyCalls).toBe(1);
+    expect(singleCalls).toBe(0);
+    expect(env).toEqual({
+      A: "val-same",
+      B: "val-same",
+      C: "val-other",
+    });
+  });
 });

package/src/resolver-service.ts

@@ -85,10 +85,15 @@ export function createSecretResolverService({
         collectSecretNames({ value: Object.values(normalized) }),
       );
 
-      const resolved = new Map<string, string>();
-      for (const name of names) {
-        resolved.set(name, await secretStore.resolve(name));
-      }
+      // Resolve the whole batch in one shot. `resolveMany` (active-backend
+      // store) resolves the active backend id ONCE for every name instead
+      // of the per-name config read the old `resolve` loop incurred. Stores
+      // without a batch path (e.g. a plain `resolve`-only literal) fall back
+      // to looping `resolve` — same result, no batch optimization.
+      const nameList = [...names];
+      const resolved = secretStore.resolveMany
+        ? await secretStore.resolveMany(nameList)
+        : await resolveEach({ secretStore, names: nameList });
 
       // Build the env by substituting templates in each mapping value.
       const env: Record<string, string> = {};
@@ -102,6 +107,24 @@ export function createSecretResolverService({
   };
 }
 
+/**
+ * Fallback batch resolution for a {@link SecretStore} without a native
+ * `resolveMany`: resolve each distinct name via the single `resolve`.
+ */
+async function resolveEach({
+  secretStore,
+  names,
+}: {
+  secretStore: SecretStore;
+  names: string[];
+}): Promise<Map<string, string>> {
+  const resolved = new Map<string, string>();
+  for (const name of names) {
+    resolved.set(name, await secretStore.resolve(name));
+  }
+  return resolved;
+}
+
 const TEMPLATE_RE = /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g;
 
 function substituteTemplate({

package/src/secret-resolver.ts

@@ -8,6 +8,16 @@ import { isSecretSchema } from "@checkstack/backend-api";
  */
 export interface SecretStore {
   resolve: (name: string) => Promise<string>;
+  /**
+   * Resolve many secret names in one batch. Optional — implementations
+   * backed by the active backend override this to resolve the active
+   * backend id ONCE for the whole batch (instead of the per-name config
+   * read `resolve` incurs), returning a `name → value` map keyed by the
+   * distinct input names. Throws `Secret not found: NAME` on any absent
+   * name, matching `resolve`. Callers that need a batch but face a store
+   * without this method fall back to looping `resolve`.
+   */
+  resolveMany?: (names: string[]) => Promise<Map<string, string>>;
 }
 
 /**