@terreno/api 0.20.2 → 0.21.0

package/src/secretProviders.test.ts

@@ -1,7 +1,13 @@
 import {beforeEach, describe, expect, it} from "bun:test";
 
 import type {SecretProvider} from "./configurationPlugin";
-import {CachingSecretProvider, CompositeSecretProvider, EnvSecretProvider} from "./secretProviders";
+import {APIError} from "./errors";
+import {
+  CachingSecretProvider,
+  CompositeSecretProvider,
+  EnvSecretProvider,
+  GcpSecretProvider,
+} from "./secretProviders";
 
 describe("EnvSecretProvider", () => {
   beforeEach(() => {
@@ -184,3 +190,215 @@ describe("CachingSecretProvider", () => {
     expect(calls).toBe(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// GcpSecretProvider
+// ---------------------------------------------------------------------------
+
+interface MockSecretManagerClient {
+  accessSecretVersion: (request: {
+    name: string;
+  }) => Promise<[{payload?: {data?: string | Uint8Array}}]>;
+}
+
+/** Inject a pre-built mock client into a GcpSecretProvider, bypassing getClient(). */
+const injectClient = (provider: GcpSecretProvider, client: MockSecretManagerClient): void => {
+  // Bypass the private `client` field for testing — avoids the dynamic import of
+  // @google-cloud/secret-manager which is an optional peer dependency.
+  Object.defineProperty(provider, "client", {configurable: true, value: client, writable: true});
+};
+
+describe("GcpSecretProvider", () => {
+  it("has the name 'gcp'", () => {
+    const provider = new GcpSecretProvider({projectId: "my-project"});
+    expect(provider.name).toBe("gcp");
+  });
+
+  it("throws APIError when @google-cloud/secret-manager is not installed", async () => {
+    const provider = new GcpSecretProvider({projectId: "my-project"});
+    try {
+      await provider.getSecret("some-secret");
+      expect.unreachable("should have thrown");
+    } catch (error) {
+      expect(error).toBeInstanceOf(APIError);
+      expect((error as APIError).title).toContain(
+        "GcpSecretProvider requires @google-cloud/secret-manager"
+      );
+    }
+  });
+
+  it("resolves a short secret name to the full resource path with default version", async () => {
+    const calls: string[] = [];
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async (req) => {
+        calls.push(req.name);
+        return [{payload: {data: "secret-value"}}];
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "my-project"});
+    injectClient(provider, mockClient);
+
+    const result = await provider.getSecret("openai-api-key");
+    expect(result).toBe("secret-value");
+    expect(calls).toEqual(["projects/my-project/secrets/openai-api-key/versions/latest"]);
+  });
+
+  it("resolves a short secret name with an explicit version", async () => {
+    const calls: string[] = [];
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async (req) => {
+        calls.push(req.name);
+        return [{payload: {data: "v3-value"}}];
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    const result = await provider.getSecret("my-key", "3");
+    expect(result).toBe("v3-value");
+    expect(calls).toEqual(["projects/p/secrets/my-key/versions/3"]);
+  });
+
+  it("honors a full resource path that already contains /versions/", async () => {
+    const calls: string[] = [];
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async (req) => {
+        calls.push(req.name);
+        return [{payload: {data: "pinned"}}];
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "ignored"});
+    injectClient(provider, mockClient);
+
+    const result = await provider.getSecret("projects/p/secrets/s/versions/7");
+    expect(result).toBe("pinned");
+    expect(calls).toEqual(["projects/p/secrets/s/versions/7"]);
+  });
+
+  it("appends /versions/latest to a full resource path without a version suffix", async () => {
+    const calls: string[] = [];
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async (req) => {
+        calls.push(req.name);
+        return [{payload: {data: "latest-value"}}];
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "ignored"});
+    injectClient(provider, mockClient);
+
+    const result = await provider.getSecret("projects/p/secrets/s");
+    expect(result).toBe("latest-value");
+    expect(calls).toEqual(["projects/p/secrets/s/versions/latest"]);
+  });
+
+  it("appends the explicit version when full path lacks /versions/", async () => {
+    const calls: string[] = [];
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async (req) => {
+        calls.push(req.name);
+        return [{payload: {data: "v5"}}];
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "ignored"});
+    injectClient(provider, mockClient);
+
+    const result = await provider.getSecret("projects/p/secrets/s", "5");
+    expect(result).toBe("v5");
+    expect(calls).toEqual(["projects/p/secrets/s/versions/5"]);
+  });
+
+  it("decodes a Uint8Array payload", async () => {
+    const encoded = new TextEncoder().encode("binary-secret");
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async () => [{payload: {data: encoded}}],
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    expect(await provider.getSecret("bin-key")).toBe("binary-secret");
+  });
+
+  it("returns null when the payload is empty", async () => {
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async () => [{payload: {}}],
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    expect(await provider.getSecret("empty-payload")).toBeNull();
+  });
+
+  it("returns null when the payload field is missing entirely", async () => {
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async () => [{}],
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    expect(await provider.getSecret("no-payload")).toBeNull();
+  });
+
+  it("returns null on NOT_FOUND (gRPC code 5)", async () => {
+    const notFound = Object.assign(new Error("NOT_FOUND"), {code: 5});
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async () => {
+        throw notFound;
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    expect(await provider.getSecret("missing-secret")).toBeNull();
+  });
+
+  it("re-throws non-NOT_FOUND errors", async () => {
+    const permissionDenied = Object.assign(new Error("PERMISSION_DENIED"), {code: 7});
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async () => {
+        throw permissionDenied;
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    try {
+      await provider.getSecret("forbidden-secret");
+      expect.unreachable("should have thrown");
+    } catch (error) {
+      expect(error).toBe(permissionDenied);
+    }
+  });
+
+  it("re-throws non-Error throwables", async () => {
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async () => {
+        throw "string-error";
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    try {
+      await provider.getSecret("x");
+      expect.unreachable("should have thrown");
+    } catch (error) {
+      expect(error).toBe("string-error");
+    }
+  });
+
+  it("caches the client across multiple getSecret calls", async () => {
+    let callCount = 0;
+    const mockClient: MockSecretManagerClient = {
+      accessSecretVersion: async () => {
+        callCount++;
+        return [{payload: {data: `call-${callCount}`}}];
+      },
+    };
+    const provider = new GcpSecretProvider({projectId: "p"});
+    injectClient(provider, mockClient);
+
+    expect(await provider.getSecret("a")).toBe("call-1");
+    expect(await provider.getSecret("b")).toBe("call-2");
+    expect(callCount).toBe(2);
+  });
+});

package/src/terrenoApp.test.ts

@@ -6,6 +6,7 @@ import supertest from "supertest";
 import {modelRouter} from "./api";
 import type {UserModel as UserModelType} from "./auth";
 import {configurationPlugin} from "./configurationPlugin";
+import {APIError} from "./errors";
 import {Permissions} from "./permissions";
 import {createdUpdatedPlugin} from "./plugins";
 import {TerrenoApp} from "./terrenoApp";
@@ -42,6 +43,17 @@ describe("TerrenoApp", () => {
       expect(app).toBeDefined();
     });
 
+    it("does not add requestId to GET /openapi.json document bodies", async () => {
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: typedUserModel,
+      }).build();
+
+      const res = await supertest(app).get("/openapi.json").expect(200);
+      expect(res.body.openapi).toBe("3.0.0");
+      expect(res.body.requestId).toBeUndefined();
+    });
+
     it("creates server with custom corsOrigin", () => {
       const app = new TerrenoApp({
         corsOrigin: "https://example.com",
@@ -105,6 +117,7 @@ describe("TerrenoApp", () => {
       const res = await agent.get("/food").expect(200);
       expect(res.body.data).toHaveLength(1);
       expect(res.body.data[0].name).toBe("Apple");
+      expect(res.body.requestId).toBe(res.headers["x-request-id"]);
     });
 
     it("supports chaining multiple registrations", async () => {
@@ -196,6 +209,7 @@ describe("TerrenoApp", () => {
       const agent = await authAsUser(app, "admin");
       const res = await agent.get("/configuration/meta");
       expect(res.status).toBe(200);
+      expect(res.body.requestId).toBe(res.headers["x-request-id"]);
     });
 
     it("supports custom basePath via configure options", async () => {
@@ -240,6 +254,30 @@ describe("TerrenoApp", () => {
 
       const res = await supertest(app).get("/trigger-fallthrough");
       expect(res.status).toBe(500);
+      expect(res.body.requestId).toBe(res.headers["x-request-id"]);
+      expect(res.body.status).toBe(500);
+      expect(res.body.title).toBe("Internal server error");
+    });
+
+    it("adds requestId to APIError JSON responses", async () => {
+      const plugin: TerrenoPlugin = {
+        register: (pluginApp) => {
+          pluginApp.get("/api-error-route", () => {
+            throw new APIError({status: 400, title: "Bad request test"});
+          });
+        },
+      };
+      const app = new TerrenoApp({
+        skipListen: true,
+        userModel: typedUserModel,
+      })
+        .register(plugin)
+        .build();
+
+      const res = await supertest(app).get("/api-error-route").set("X-Request-ID", "api-err-rid");
+      expect(res.status).toBe(400);
+      expect(res.body.requestId).toBe("api-err-rid");
+      expect(res.body.title).toBe("Bad request test");
     });
   });
 

package/src/terrenoApp.ts

@@ -11,9 +11,10 @@ import {
   apiFallthroughErrorMiddleware,
   apiUnauthorizedMiddleware,
 } from "./errors";
-import {type AuthOptions, logRequests} from "./expressServer";
+import {type AddRoutes, type AuthOptions, logRequests} from "./expressServer";
 import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
 import {type LoggingOptions, logger, setupLogging} from "./logger";
+import {jsonResponseRequestIdMiddleware} from "./middleware";
 import {openApiCompatMiddleware, patchAppUse} from "./openApiCompat";
 import {openApiEtagMiddleware} from "./openApiEtag";
 import {RealtimeApp} from "./realtime/realtimeApp";
@@ -68,28 +69,41 @@ export interface TerrenoAppOptions {
    * Set to `true` for defaults, or pass a RealtimeAppOptions object for full control.
    */
   realtime?: boolean | RealtimeAppOptions;
+  /**
+   * Runs after CORS and before the `addMiddleware` chain and JSON body parsing.
+   * Use to attach early middleware via `app.use(...)` before JSON parsing.
+   */
+  beforeJsonSetup?: (app: express.Application) => void;
+  /**
+   * Invoked after registered plugins/model routers and before `/auth/me`.
+   * Receives the Express app and OpenAPI bundle for `modelRouter` / `createOpenApiBuilder` wiring.
+   */
+  configureApp?: AddRoutes;
 }
 
 /**
  * Fluent API for building Express applications with Terreno framework.
  *
- * TerrenoApp provides an alternative to `setupServer` using a registration
- * pattern instead of callbacks. Build applications by registering model
- * routers and plugins, then calling `start()` to begin listening.
+ * TerrenoApp is the supported way to assemble the Terreno Express stack.
+ * Build applications by registering model routers and plugins (and/or
+ * `configureApp`), then calling `start()` to listen.
  *
  * The middleware stack is configured in this order:
  * 1. CORS
- * 2. Custom middleware (via addMiddleware)
- * 3. JSON body parser
- * 4. Auth routes (/auth/login, /auth/signup, etc.)
- * 5. JWT authentication setup
- * 6. Request logging
- * 7. Sentry scopes
- * 8. OpenAPI middleware
- * 9. /auth/me routes
+ * 2. Optional `beforeJsonSetup` (configure the app before JSON parsing)
+ * 3. Custom middleware (via addMiddleware)
+ * 4. JSON body parser
+ * 5. Auth routes (/auth/login, /auth/signup, etc.)
+ * 6. JWT authentication setup
+ * 7. Request logging
+ * 8. Sentry scopes
+ * 9. OpenAPI middleware (including JSON `requestId` on object responses)
  * 10. GitHub OAuth routes (if enabled)
- * 11. Registered model routers and plugins
- * 12. Error handling middleware
+ * 11. Configuration app (if any)
+ * 12. Registered model routers and plugins
+ * 13. Optional `configureApp` callback
+ * 14. /auth/me routes
+ * 15. Error handling middleware
  *
  * @example
  * ```typescript
@@ -126,7 +140,6 @@ export interface TerrenoAppOptions {
  *   .start();
  * ```
  *
- * @see setupServer for the callback-based alternative
  * @see TerrenoPlugin for creating reusable plugins
  * @see modelRouter for creating CRUD route registrations
  */
@@ -263,6 +276,10 @@ export class TerrenoApp {
 
     app.use(cors({credentials: true, origin: options.corsOrigin ?? "*"}));
 
+    if (options.beforeJsonSetup) {
+      options.beforeJsonSetup(app);
+    }
+
     // Apply custom middleware before JSON parsing
     for (const fn of this.middlewareFns) {
       if (fn.length <= 3) {
@@ -317,6 +334,7 @@ export class TerrenoApp {
     // OpenAPI
     app.use(openApiCompatMiddleware);
     app.use(openApiEtagMiddleware);
+    app.use(jsonResponseRequestIdMiddleware);
     const oapi = openapi({
       info: {
         description: "Generated docs from an Express api",
@@ -352,6 +370,10 @@ export class TerrenoApp {
       }
     }
 
+    if (options.configureApp) {
+      options.configureApp(app, {openApi: oapi});
+    }
+
     // /auth/me must be registered after plugins so that session middleware
     // (e.g. Better Auth) has a chance to populate req.user first.
     addMeRoutes(app, options.userModel, options.authOptions);

package/src/tests/bunSetup.ts

@@ -9,12 +9,22 @@ import {logger, winstonLogger} from "../logger";
 
 const shouldConnectToTestDb = process.env.BUN_TEST_DISABLE_DB !== "true";
 
+const defaultLocalMongoUri = "mongodb://127.0.0.1/terreno?&connectTimeoutMS=360000";
+
+/** When set by {@link TERRENO_TEST_USE_MEMORY_MONGO}, holds the server to stop in afterAll. */
+let memoryMongo: {getUri: () => string; stop: () => Promise<boolean>} | undefined;
+
 // Connect to MongoDB once for all tests
 if (shouldConnectToTestDb) {
   beforeAll(async () => {
-    await mongoose
-      .connect("mongodb://127.0.0.1/terreno?&connectTimeoutMS=360000")
-      .catch(logger.catch);
+    let uri = process.env.TERRENO_TEST_MONGODB_URI?.trim();
+    if (!uri && process.env.TERRENO_TEST_USE_MEMORY_MONGO === "true") {
+      const {MongoMemoryServer} = await import("mongodb-memory-server");
+      memoryMongo = await MongoMemoryServer.create();
+      uri = memoryMongo.getUri();
+    }
+    const connectUri = uri ?? defaultLocalMongoUri;
+    await mongoose.connect(connectUri).catch(logger.catch);
   });
 }
 
@@ -22,6 +32,9 @@ if (shouldConnectToTestDb) {
 if (shouldConnectToTestDb) {
   afterAll(async () => {
     await mongoose.connection.close();
+    if (memoryMongo) {
+      await memoryMongo.stop();
+    }
   });
 }
 

package/src/tests.ts

@@ -177,7 +177,7 @@ export const getBaseServer = (): Express => {
 
   // Express 5 defaults to 'simple' query parser (Node querystring) which doesn't
   // support nested bracket notation like name[$regex]=Green. Use qs to match
-  // what setupServer() configures.
+  // what TerrenoApp.build() configures.
   app.set("query parser", (str: string) => qs.parse(str, {arrayLimit: 200}));
 
   // Record mount paths on layers for Express 5 → OpenAPI compat
@@ -210,10 +210,23 @@ export const authAsUser = async (
   return agent;
 };
 
+const defaultTestMongoUri = "mongodb://127.0.0.1/terreno?&connectTimeoutMS=360000";
+
+/** Ensures Mongoose is connected without replacing an existing test connection (e.g. MongoMemoryServer from bunSetup). */
+const ensureTestMongooseConnected = async (): Promise<void> => {
+  if (mongoose.connection.readyState === 1) {
+    return;
+  }
+  if (mongoose.connection.readyState === 2) {
+    await mongoose.connection.asPromise();
+    return;
+  }
+  const uri = process.env.TERRENO_TEST_MONGODB_URI?.trim() || defaultTestMongoUri;
+  await mongoose.connect(uri).catch(logger.catch);
+};
+
 export const setupDb = async () => {
-  await mongoose
-    .connect("mongodb://127.0.0.1/terreno?&connectTimeoutMS=360000")
-    .catch(logger.catch);
+  await ensureTestMongooseConnected();
 
   process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
   process.env.TOKEN_SECRET = "secret";