@terreno/api 0.18.0 → 0.20.0

package/src/realtime/realtime.test.ts

@@ -1776,6 +1776,17 @@ describe("startChangeStreamWatcher", () => {
     };
   };
 
+  const invokeRegisteredChangeHandler = async (
+    mockStream: ReturnType<typeof createMockChangeStream>,
+    event: Record<string, unknown>
+  ): Promise<void> => {
+    const changeHandler = mockStream.listeners.get("change");
+    if (!changeHandler) {
+      throw new Error("expected change handler");
+    }
+    await changeHandler(event);
+  };
+
   const createMockIo = () => {
     const rooms = new Map<string, Set<string>>();
     const sockets = new Map<string, any>();
@@ -1864,9 +1875,7 @@ describe("startChangeStreamWatcher", () => {
     startChangeStreamWatcher(io, {}, true);
 
     // Trigger an insert change event
-    const changeHandler = mockStream.listeners.get("change");
-    expect(changeHandler).toBeDefined();
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       fullDocument: {_id: "doc-1", name: "Test Todo"},
       ns: {coll: "todos"},
@@ -1886,9 +1895,8 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // Trigger for an unregistered collection — should not throw
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       fullDocument: {_id: "doc-1"},
       ns: {coll: "unknown_collection"},
@@ -1927,9 +1935,8 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // Update event should be skipped because "update" not in methods
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       fullDocument: {_id: "doc-1", name: "Updated"},
       ns: {coll: "todos"},
@@ -1969,9 +1976,8 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // Hard delete (no fullDocument)
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       ns: {coll: "todos"},
       operationType: "delete",
@@ -2009,9 +2015,8 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // Hard delete for broadcast strategy
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       ns: {coll: "broadcasts"},
       operationType: "delete",
@@ -2049,8 +2054,7 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       fullDocument: {_id: "doc-1", name: "Updated", status: "done"},
       ns: {coll: "todos"},
@@ -2110,9 +2114,8 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {ignoredOperations: ["insert"]}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // This insert should be skipped because "insert" is ignored
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       fullDocument: {_id: "doc-1"},
       ns: {coll: "todos"},
@@ -2132,15 +2135,14 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // Missing ns.coll
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       ns: {},
       operationType: "insert",
     });
     // Missing documentKey
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {},
       ns: {coll: "todos"},
       operationType: "insert",
@@ -2159,9 +2161,8 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // "drop" is not in our pipeline filter, should be skipped
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       operationType: "drop",
     });
   });
@@ -2257,9 +2258,8 @@ describe("startChangeStreamWatcher", () => {
 
     startChangeStreamWatcher(io, {}, true);
 
-    const changeHandler = mockStream.listeners.get("change");
     // Should not throw even though permission check throws
-    await changeHandler!({
+    await invokeRegisteredChangeHandler(mockStream, {
       documentKey: {_id: "doc-1"},
       fullDocument: {_id: "doc-1", name: "Test"},
       ns: {coll: "todos"},
@@ -2317,7 +2317,7 @@ describe("RealtimeApp.onServerCreated", () => {
   });
 
   const makeServer = (): import("http").Server => {
-    const http = require("http");
+    const http = require("node:http");
     const server = http.createServer();
     servers.push(server);
     return server;
@@ -2366,7 +2366,7 @@ describe("RealtimeApp.setupAdapter (private, via onServerCreated config)", () =>
   });
 
   const makeServer = (): import("http").Server => {
-    const http = require("http");
+    const http = require("node:http");
     const server = http.createServer();
     servers.push(server);
     return server;

package/src/realtime/realtimeApp.ts

@@ -60,7 +60,6 @@ export interface RealtimeSocketLike extends SocketWithDecodedToken {
   join: (room: string) => Promise<void> | void;
   leave: (room: string) => Promise<void> | void;
   emit: (event: string, payload: unknown) => void;
-  // biome-ignore lint/suspicious/noExplicitAny: Socket.io event handlers accept arbitrary argument shapes per event name
   on: (event: string, handler: (...args: any[]) => any) => void;
 }
 

package/src/realtime/registry.ts

@@ -17,7 +17,6 @@ export interface RealtimeRegistryEntry {
   /**
    * Full modelRouter options (for responseHandler, permissions, etc.).
    */
-  // biome-ignore lint/suspicious/noExplicitAny: registry stores heterogeneous models — narrowing the generic is not useful at the registry level
   options: ModelRouterOptions<any>;
 }
 

package/src/realtime/types.ts

@@ -19,10 +19,8 @@ export interface RealtimeConfig {
     | "owner"
     | "model"
     | "broadcast"
-    // biome-ignore lint/suspicious/noExplicitAny: doc is an arbitrary Mongoose document; consumers cast to their model type
     | ((doc: any, method: string, req: express.Request) => string[]);
   /** Custom serializer for real-time events. Falls back to the modelRouter responseHandler. */
-  // biome-ignore lint/suspicious/noExplicitAny: doc shape and return value are consumer-defined per model
   realtimeResponseHandler?: (doc: any, method: string) => any;
 }
 
@@ -39,7 +37,6 @@ export interface RealtimeEvent {
   /** Document ID */
   id: string;
   /** Serialized document data (omitted for hard deletes) */
-  // biome-ignore lint/suspicious/noExplicitAny: emitted document shape varies by model and serializer
   data?: any;
   /** Fields that were updated (for update events from change streams) */
   updatedFields?: string[];
@@ -105,7 +102,6 @@ export interface QuerySubscription {
   /** Collection tag (e.g. "todos") */
   collection: string;
   /** MongoDB-style query filter (e.g. {completed: false}) */
-  // biome-ignore lint/suspicious/noExplicitAny: MongoDB query filter values are arbitrary user-supplied JSON
   query: Record<string, any>;
   /** Client-provided queryId (ignored — server computes a canonical ID) */
   queryId?: string;

package/src/secretProviders.test.ts

@@ -0,0 +1,186 @@
+import {beforeEach, describe, expect, it} from "bun:test";
+
+import type {SecretProvider} from "./configurationPlugin";
+import {CachingSecretProvider, CompositeSecretProvider, EnvSecretProvider} from "./secretProviders";
+
+describe("EnvSecretProvider", () => {
+  beforeEach(() => {
+    delete process.env.MY_SECRET_KEY;
+  });
+
+  it("resolves from a SCREAMING_SNAKE_CASE env var", async () => {
+    process.env.MY_SECRET_KEY = "from-env";
+    const provider = new EnvSecretProvider();
+    expect(await provider.getSecret("my-secret-key")).toBe("from-env");
+  });
+
+  it("returns null when the env var is missing", async () => {
+    const provider = new EnvSecretProvider();
+    expect(await provider.getSecret("my-secret-key")).toBeNull();
+  });
+
+  it("ignores the version parameter", async () => {
+    process.env.MY_SECRET_KEY = "value";
+    const provider = new EnvSecretProvider();
+    expect(await provider.getSecret("my-secret-key", "5")).toBe("value");
+  });
+});
+
+describe("CompositeSecretProvider", () => {
+  it("throws when constructed with no providers", () => {
+    expect(() => new CompositeSecretProvider([])).toThrow();
+  });
+
+  it("returns the first non-null result", async () => {
+    const a: SecretProvider = {getSecret: async () => null, name: "a"};
+    const b: SecretProvider = {getSecret: async () => "from-b", name: "b"};
+    const c: SecretProvider = {getSecret: async () => "from-c", name: "c"};
+    const provider = new CompositeSecretProvider([a, b, c]);
+    expect(await provider.getSecret("x")).toBe("from-b");
+  });
+
+  it("falls through to the next provider when one throws", async () => {
+    const failing: SecretProvider = {
+      getSecret: async () => {
+        throw new Error("provider down");
+      },
+      name: "failing",
+    };
+    const fallback: SecretProvider = {getSecret: async () => "from-fallback", name: "fallback"};
+    const provider = new CompositeSecretProvider([failing, fallback]);
+    expect(await provider.getSecret("x")).toBe("from-fallback");
+  });
+
+  it("returns null when every provider yields null", async () => {
+    const a: SecretProvider = {getSecret: async () => null, name: "a"};
+    const b: SecretProvider = {getSecret: async () => null, name: "b"};
+    const provider = new CompositeSecretProvider([a, b]);
+    expect(await provider.getSecret("x")).toBeNull();
+  });
+
+  it("forwards the version parameter to each provider", async () => {
+    const seen: Array<string | undefined> = [];
+    const a: SecretProvider = {
+      getSecret: async (_name, version) => {
+        seen.push(version);
+        return null;
+      },
+      name: "a",
+    };
+    const b: SecretProvider = {
+      getSecret: async (_name, version) => {
+        seen.push(version);
+        return "value";
+      },
+      name: "b",
+    };
+    const provider = new CompositeSecretProvider([a, b]);
+    await provider.getSecret("x", "7");
+    expect(seen).toEqual(["7", "7"]);
+  });
+
+  it("builds a composite name from the underlying providers", () => {
+    const provider = new CompositeSecretProvider([
+      {getSecret: async () => null, name: "gcp"},
+      {getSecret: async () => null, name: "env"},
+    ]);
+    expect(provider.name).toBe("composite(gcp,env)");
+  });
+});
+
+describe("CachingSecretProvider", () => {
+  it("memoizes a value within the TTL (single underlying call)", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return "value";
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("x")).toBe("value");
+    expect(await provider.getSecret("x")).toBe("value");
+    expect(calls).toBe(1);
+  });
+
+  it("re-fetches after clear()", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return `value-${calls}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("x")).toBe("value-1");
+    provider.clear();
+    expect(await provider.getSecret("x")).toBe("value-2");
+    expect(calls).toBe(2);
+  });
+
+  it("re-fetches after the TTL expires", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return `value-${calls}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 1});
+    expect(await provider.getSecret("x")).toBe("value-1");
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(await provider.getSecret("x")).toBe("value-2");
+    expect(calls).toBe(2);
+  });
+
+  it("caches different versions independently", async () => {
+    const seen: Array<string | undefined> = [];
+    const underlying: SecretProvider = {
+      getSecret: async (_name, version) => {
+        seen.push(version);
+        return `v-${version ?? "latest"}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("x", "1")).toBe("v-1");
+    expect(await provider.getSecret("x", "2")).toBe("v-2");
+    // Cached hits, no additional underlying calls.
+    expect(await provider.getSecret("x", "1")).toBe("v-1");
+    expect(seen).toEqual(["1", "2"]);
+  });
+
+  it("clearKey invalidates a single secret", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return `value-${calls}`;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    await provider.getSecret("x");
+    provider.clearKey("x");
+    await provider.getSecret("x");
+    expect(calls).toBe(2);
+  });
+
+  it("caches null results", async () => {
+    let calls = 0;
+    const underlying: SecretProvider = {
+      getSecret: async () => {
+        calls++;
+        return null;
+      },
+      name: "underlying",
+    };
+    const provider = new CachingSecretProvider(underlying, {ttlMs: 10_000});
+    expect(await provider.getSecret("missing")).toBeNull();
+    expect(await provider.getSecret("missing")).toBeNull();
+    expect(calls).toBe(1);
+  });
+});

package/src/secretProviders.ts

@@ -28,7 +28,11 @@ interface SecretManagerModule {
 export class EnvSecretProvider implements SecretProvider {
   name = "env";
 
-  async getSecret(secretName: string): Promise<string | null> {
+  /**
+   * Resolve a secret from an environment variable. Environment variables have no
+   * versions, so the optional `version` parameter is ignored.
+   */
+  async getSecret(secretName: string, _version?: string): Promise<string | null> {
     // Convert secret name to env var format: "openai-api-key" → "OPENAI_API_KEY"
     const envKey = secretName.replace(/[-.]/g, "_").toUpperCase();
     const value = process.env[envKey] ?? null;
@@ -96,16 +100,28 @@ export class GcpSecretProvider implements SecretProvider {
     return this.client;
   }
 
-  async getSecret(secretName: string): Promise<string | null> {
+  /**
+   * Resolve a secret from Google Cloud Secret Manager.
+   *
+   * @param secretName - A short secret id (e.g. "openai-api-key") or a full
+   *   resource path (e.g. "projects/p/secrets/s" or
+   *   "projects/p/secrets/s/versions/3").
+   * @param version - Optional version to resolve when `secretName` is a short id
+   *   (e.g. "3"). Defaults to "latest". Ignored when `secretName` already
+   *   contains an explicit `/versions/...` suffix.
+   */
+  async getSecret(secretName: string, version?: string): Promise<string | null> {
     const client = await this.getClient();
 
+    const resolvedVersion = version ?? "latest";
     let resourceName: string;
     if (secretName.startsWith("projects/")) {
-      resourceName = secretName.endsWith("/versions/latest")
+      // Honor a full resource path. Only append a version when one is not present.
+      resourceName = secretName.includes("/versions/")
         ? secretName
-        : `${secretName}/versions/latest`;
+        : `${secretName}/versions/${resolvedVersion}`;
     } else {
-      resourceName = `projects/${this.projectId}/secrets/${secretName}/versions/latest`;
+      resourceName = `projects/${this.projectId}/secrets/${secretName}/versions/${resolvedVersion}`;
     }
 
     try {
@@ -126,3 +142,127 @@ export class GcpSecretProvider implements SecretProvider {
     }
   }
 }
+
+/**
+ * Secret provider that delegates to an ordered list of providers, returning the
+ * first non-null result.
+ *
+ * A provider that throws is warn-logged (secret name only — never the value) and
+ * resolution falls through to the next provider. This makes it easy to compose a
+ * primary provider with a fallback, e.g. GCP with an environment-variable
+ * fallback:
+ *
+ * @example
+ * ```typescript
+ * const provider = new CompositeSecretProvider([
+ *   new GcpSecretProvider({projectId: "my-project"}),
+ *   new EnvSecretProvider(),
+ * ]);
+ * const key = await provider.getSecret("openai-api-key");
+ * ```
+ */
+export class CompositeSecretProvider implements SecretProvider {
+  name: string;
+  private providers: SecretProvider[];
+
+  constructor(providers: SecretProvider[]) {
+    if (!providers || providers.length === 0) {
+      throw new APIError({
+        status: 500,
+        title: "CompositeSecretProvider requires at least one provider",
+      });
+    }
+    this.providers = providers;
+    this.name = `composite(${providers.map((p) => p.name).join(",")})`;
+  }
+
+  async getSecret(secretName: string, version?: string): Promise<string | null> {
+    for (const provider of this.providers) {
+      try {
+        const value = await provider.getSecret(secretName, version);
+        if (value !== null) {
+          return value;
+        }
+      } catch (error: unknown) {
+        // Never log the secret value — only the name and which provider failed.
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(
+          `CompositeSecretProvider: provider ${provider.name} failed for secret ${secretName}: ${message}`
+        );
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Options for CachingSecretProvider.
+ */
+export interface CachingSecretProviderOptions {
+  /** Time-to-live for cached values, in milliseconds. Defaults to 60_000 (1 minute). */
+  ttlMs?: number;
+}
+
+interface CacheEntry {
+  value: string | null;
+  expiresAt: number;
+}
+
+/**
+ * Secret provider that wraps any provider with an in-memory TTL cache.
+ *
+ * Cache entries are keyed by `secretName@version` so that pinned versions are
+ * cached independently. `null` results (secret not found) are cached too, to
+ * avoid hammering the underlying provider for missing secrets. Secret values are
+ * never logged.
+ *
+ * Use `clear()` to drop the entire cache (e.g. on rotation) or `clearKey()` to
+ * invalidate a single secret.
+ *
+ * @example
+ * ```typescript
+ * const provider = new CachingSecretProvider(
+ *   new CompositeSecretProvider([gcp, env]),
+ *   {ttlMs: 30_000}
+ * );
+ * ```
+ */
+export class CachingSecretProvider implements SecretProvider {
+  name: string;
+  private provider: SecretProvider;
+  private ttlMs: number;
+  private cache = new Map<string, CacheEntry>();
+
+  constructor(provider: SecretProvider, options?: CachingSecretProviderOptions) {
+    this.provider = provider;
+    this.ttlMs = options?.ttlMs ?? 60_000;
+    this.name = `caching(${provider.name})`;
+  }
+
+  private cacheKey(secretName: string, version?: string): string {
+    return `${secretName}@${version ?? "latest"}`;
+  }
+
+  async getSecret(secretName: string, version?: string): Promise<string | null> {
+    const key = this.cacheKey(secretName, version);
+    const now = Date.now();
+    const cached = this.cache.get(key);
+    if (cached && cached.expiresAt > now) {
+      return cached.value;
+    }
+
+    const value = await this.provider.getSecret(secretName, version);
+    this.cache.set(key, {expiresAt: now + this.ttlMs, value});
+    return value;
+  }
+
+  /** Clears the entire cache. Useful on secret rotation and in tests. */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /** Invalidates a single cached secret by name (and optional version). */
+  clearKey(secretName: string, version?: string): void {
+    this.cache.delete(this.cacheKey(secretName, version));
+  }
+}