@terreno/api 0.20.2 → 0.22.0

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

@@ -1,241 +1,27 @@
-// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
-import {afterAll, afterEach, beforeAll, beforeEach, mock} from "bun:test";
-import {Writable} from "node:stream";
-import mongoose from "mongoose";
-import winston from "winston";
+import {registerBackendPreload, registerSimpleMongoPreload} from "@terreno/test";
 
-import {setupEnvironment} from "../expressServer";
-import {logger, winstonLogger} from "../logger";
+const useFixtureCache = process.env.TERRENO_TEST_USE_FIXTURE_CACHE === "true";
 
-const shouldConnectToTestDb = process.env.BUN_TEST_DISABLE_DB !== "true";
-
-// 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);
+if (useFixtureCache) {
+  registerBackendPreload({
+    connectMongoInBeforeAll: true,
+    loadTestDataFromCache: async () => {
+      const {loadTestDataFromCache} = await import("./mongoTestSetup");
+      await loadTestDataFromCache();
+    },
+    mongo: {
+      baseDatabaseName: "terrenoTest_base",
+      useReplSet: true,
+    },
+    testEnv: {
+      tokenIssuer: "terreno-api.test",
+    },
+    useTransactions: true,
   });
-}
-
-// Close MongoDB connection after all tests
-if (shouldConnectToTestDb) {
-  afterAll(async () => {
-    await mongoose.connection.close();
+} else {
+  registerSimpleMongoPreload({
+    testEnv: {
+      tokenIssuer: "terreno-api.test",
+    },
   });
 }
-
-let logs: string[] = [];
-
-const SHOW_ALL_LOGS = process.env.SHOW_ALL_TEST_LOGS === "true";
-
-// Create a custom stream that captures logs
-const logStream = new Writable({
-  write(chunk: any, _encoding: any, callback: any) {
-    logs.push(chunk.toString());
-    if (SHOW_ALL_LOGS) {
-      process.stdout.write(chunk);
-    }
-    callback();
-  },
-});
-
-// Silence both winston loggers by replacing all transports with our capturing stream
-const silentTransport = new winston.transports.Stream({
-  format: winston.format.simple(),
-  stream: logStream,
-});
-
-// Clear and silence the default winston logger
-winston.clear();
-winston.add(silentTransport);
-
-// Clear and silence the custom winstonLogger
-winstonLogger.clear();
-winstonLogger.add(silentTransport);
-
-// Capture and silence console methods
-const originalConsole = {
-  debug: console.debug,
-  error: console.error,
-  info: console.info,
-  // biome-ignore lint/suspicious/noConsole: We keep the original reference.
-  log: console.log,
-  warn: console.warn,
-};
-
-const captureConsoleMethod = (method: keyof typeof originalConsole): void => {
-  (console as any)[method] = (...args: any[]) => {
-    const logMessage = `[console.${method}] ${args.map((arg) => (typeof arg === "object" ? JSON.stringify(arg) : String(arg))).join(" ")}`;
-    logs.push(logMessage);
-    if (SHOW_ALL_LOGS) {
-      originalConsole[method](...args);
-    }
-  };
-};
-
-captureConsoleMethod("log");
-captureConsoleMethod("info");
-captureConsoleMethod("warn");
-captureConsoleMethod("error");
-captureConsoleMethod("debug");
-
-// Setup before each test
-beforeEach(() => {
-  process.env.TOKEN_SECRET = "secret";
-  process.env.TOKEN_ISSUER = "terreno-api.test";
-  process.env.SESSION_SECRET = "sessionSecret";
-  process.env.REFRESH_TOKEN_SECRET = "refreshTokenSecret";
-  setupEnvironment();
-  // Re-silence loggers after setupEnvironment which may reconfigure them
-  winston.clear();
-  winston.add(silentTransport);
-  winstonLogger.clear();
-  winstonLogger.add(silentTransport);
-  logs = [];
-});
-
-// Clear logs after each test
-afterEach(() => {
-  logs = [];
-});
-
-// Mock @sentry/bun module
-mock.module("@sentry/bun", () => {
-  const mockFn = (): ReturnType<typeof mock> => mock(() => {});
-
-  // Mock Scope
-  const mockScope = {
-    addBreadcrumb: mockFn(),
-    clear: mockFn(),
-    getSpan: mockFn(),
-    setContext: mockFn(),
-    setFingerprint: mockFn(),
-    setLevel: mockFn(),
-    setSpan: mockFn(),
-    setTag: mockFn(),
-    setTags: mockFn(),
-    setTransactionName: mockFn(),
-    setUser: mockFn(),
-  };
-
-  // Mock Hub
-  const mockClient = {
-    captureException: mockFn(),
-    captureMessage: mockFn(),
-    close: mock(() => Promise.resolve(true)),
-    flush: mock(() => Promise.resolve(true)),
-    getOptions: mock(() => ({})),
-  };
-
-  const mockHub = {
-    addBreadcrumb: mockFn(),
-    captureException: mockFn(),
-    captureMessage: mockFn(),
-    configureScope: mockFn(),
-    getClient: mock(() => mockClient),
-    getScope: mock(() => mockScope),
-    popScope: mockFn(),
-    pushScope: mockFn(),
-    setContext: mockFn(),
-    setTag: mockFn(),
-    setTags: mockFn(),
-    setUser: mockFn(),
-    withScope: mockFn(),
-  };
-
-  const mockSpan: any = {
-    finish: mockFn(),
-    setData: mockFn(),
-    setStatus: mockFn(),
-    setTag: mockFn(),
-    startChild: mockFn(),
-    toTraceparent: mock(() => "mock-trace-parent"),
-  };
-  mockSpan.startChild = mock(() => mockSpan);
-
-  const mockTransaction = {
-    finish: mockFn(),
-    setData: mockFn(),
-    setName: mockFn(),
-    setStatus: mockFn(),
-    setTag: mockFn(),
-    startChild: mock(() => mockSpan),
-    toTraceparent: mock(() => "mock-trace-parent"),
-  };
-
-  return {
-    addBreadcrumb: mockFn(),
-    captureException: mockFn(),
-    captureMessage: mockFn(),
-    clearScope: mockFn(),
-    close: mock(() => Promise.resolve(true)),
-    configureScope: mockFn(),
-    default: {
-      addBreadcrumb: mockFn(),
-      captureException: mockFn(),
-      captureMessage: mockFn(),
-      clearScope: mockFn(),
-      close: mock(() => Promise.resolve(true)),
-      configureScope: mockFn(),
-      flush: mock(() => Promise.resolve(true)),
-      getClient: mock(() => mockClient),
-      getCurrentHub: mock(() => mockHub),
-      getCurrentScope: mock(() => mockScope),
-      Handlers: {
-        errorHandler: mock(() => (err: any, _req: any, _res: any, next: any) => next(err)),
-        requestHandler: mock(() => (_req: any, _res: any, next: any) => next()),
-        tracingHandler: mock(() => (_req: any, _res: any, next: any) => next()),
-      },
-      init: mockFn(),
-      isInitialized: mock(() => true),
-      popScope: mockFn(),
-      pushScope: mockFn(),
-      Severity: {
-        Debug: "debug",
-        Error: "error",
-        Fatal: "fatal",
-        Info: "info",
-        Warning: "warning",
-      } as const,
-      setContext: mockFn(),
-      setFingerprint: mockFn(),
-      setLevel: mockFn(),
-      setTag: mockFn(),
-      setTags: mockFn(),
-      setUser: mockFn(),
-      setupExpressErrorHandler: mockFn(),
-      startTransaction: mock(() => mockTransaction),
-      withScope: mock((callback: any) => callback(mockScope)),
-    },
-    flush: mock(() => Promise.resolve(true)),
-    getClient: mock(() => mockClient),
-    getCurrentHub: mock(() => mockHub),
-    getCurrentScope: mock(() => mockScope),
-    Handlers: {
-      errorHandler: mock(() => (err: any, _req: any, _res: any, next: any) => next(err)),
-      requestHandler: mock(() => (_req: any, _res: any, next: any) => next()),
-      tracingHandler: mock(() => (_req: any, _res: any, next: any) => next()),
-    },
-    init: mockFn(),
-    isInitialized: mock(() => true),
-    popScope: mockFn(),
-    pushScope: mockFn(),
-    Severity: {
-      Debug: "debug",
-      Error: "error",
-      Fatal: "fatal",
-      Info: "info",
-      Warning: "warning",
-    } as const,
-    setContext: mockFn(),
-    setFingerprint: mockFn(),
-    setLevel: mockFn(),
-    setTag: mockFn(),
-    setTags: mockFn(),
-    setUser: mockFn(),
-    setupExpressErrorHandler: mockFn(),
-    startTransaction: mock(() => mockTransaction),
-    withScope: mock((callback: any) => callback(mockScope)),
-  };
-});

package/src/tests/createTestData.ts

@@ -0,0 +1,176 @@
+import type {HydratedDocument} from "mongoose";
+import type {PassportLocalMongooseDocument} from "passport-local-mongoose";
+
+import {logger} from "../logger";
+import {FoodModel, RequiredModel, type User, UserModel} from "./models";
+import type {CachedTestData, TestData, TestFoods, TestRequired, TestUsers} from "./types";
+
+const setPassword = async (user: HydratedDocument<User>, password: string): Promise<void> => {
+  await (user as unknown as PassportLocalMongooseDocument).setPassword(password);
+  await user.save();
+};
+
+export const clearTestCollections = async (): Promise<void> => {
+  await Promise.all([
+    UserModel.deleteMany({}),
+    FoodModel.deleteMany({}),
+    RequiredModel.deleteMany({}),
+  ]).catch(logger.catch);
+};
+
+export const createTestUsers = async (): Promise<TestUsers> => {
+  const [notAdmin, admin, adminOther] = await Promise.all([
+    UserModel.create({email: "notAdmin@example.com", name: "Not Admin"}),
+    UserModel.create({admin: true, email: "admin@example.com", name: "Admin"}),
+    UserModel.create({admin: true, email: "admin+other@example.com", name: "Admin Other"}),
+  ]);
+
+  await Promise.all([
+    setPassword(notAdmin, "password"),
+    setPassword(admin, "securePassword"),
+    setPassword(adminOther, "otherPassword"),
+  ]);
+
+  return {admin, adminOther, notAdmin};
+};
+
+export const createStandardFoods = async (users: TestUsers): Promise<TestFoods> => {
+  const {admin, adminOther, notAdmin} = users;
+
+  const [spinach, apple, carrots, pizza] = await Promise.all([
+    FoodModel.create({
+      calories: 1,
+      categories: [{name: "Vegetables", show: true}],
+      created: new Date("2021-12-03T00:00:20.000Z"),
+      eatenBy: [admin._id],
+      expiration: "2026-12-31",
+      hidden: false,
+      lastEatenWith: {
+        dressing: new Date("2021-12-03T19:00:30.000Z"),
+      },
+      likesIds: [
+        {likes: true, userId: admin._id},
+        {likes: false, userId: notAdmin._id},
+      ],
+      name: "Spinach",
+      ownerId: notAdmin._id,
+      source: {
+        dateAdded: "2023-12-13T12:30:00.000Z",
+        href: "https://www.example.com/spinach",
+        name: "Brand",
+      },
+      tags: ["healthy"],
+    }),
+    FoodModel.create({
+      calories: 100,
+      created: new Date("2021-12-03T00:00:30.000Z"),
+      expiration: "2026-12-31",
+      hidden: true,
+      likesIds: [{likes: true, userId: admin._id}],
+      name: "Apple",
+      ownerId: admin._id,
+      source: {name: "Orchard"},
+      tags: ["healthy"],
+    }),
+    FoodModel.create({
+      calories: 100,
+      created: new Date("2021-12-03T00:00:00.000Z"),
+      eatenBy: [admin._id, notAdmin._id],
+      expiration: "2026-12-31",
+      hidden: false,
+      likesIds: [{likes: false, userId: notAdmin._id}],
+      name: "Carrots",
+      ownerId: admin._id,
+      source: {name: "Farm"},
+      tags: ["vegetable"],
+    }),
+    FoodModel.create({
+      calories: 800,
+      created: new Date("2022-01-01T00:00:00.000Z"),
+      expiration: "2026-12-31",
+      hidden: false,
+      likesIds: [{likes: true, userId: adminOther._id}],
+      name: "Pizza",
+      ownerId: adminOther._id,
+      source: {name: "Pizzeria"},
+      tags: ["comfort"],
+    }),
+  ]);
+
+  return {apple, carrots, pizza, spinach};
+};
+
+export const createRequiredFixtures = async (): Promise<TestRequired> => {
+  const [sample, withAbout] = await Promise.all([
+    RequiredModel.create({name: "Sample Required"}),
+    RequiredModel.create({about: "Optional about text", name: "Required With About"}),
+  ]);
+
+  return {sample, withAbout};
+};
+
+/** Builds the standard Terreno API test database (users, foods, required docs). */
+export const createTestData = async (): Promise<TestData> => {
+  await clearTestCollections();
+
+  const users = await createTestUsers();
+  const [foods, required] = await Promise.all([
+    createStandardFoods(users),
+    createRequiredFixtures(),
+  ]);
+
+  return {foods, required, users};
+};
+
+export const toCachedTestData = (testData: TestData): CachedTestData => ({
+  foods: {
+    apple: testData.foods.apple.id,
+    carrots: testData.foods.carrots.id,
+    pizza: testData.foods.pizza.id,
+    spinach: testData.foods.spinach.id,
+  },
+  required: {
+    sample: testData.required.sample.id,
+    withAbout: testData.required.withAbout.id,
+  },
+  users: {
+    admin: testData.users.admin.id,
+    adminOther: testData.users.adminOther.id,
+    notAdmin: testData.users.notAdmin.id,
+  },
+});
+
+export const loadTestDataFromDocuments = async (cached: CachedTestData): Promise<TestData> => {
+  const [admin, notAdmin, adminOther, spinach, apple, carrots, pizza, sample, withAbout] =
+    await Promise.all([
+      UserModel.findById(cached.users.admin),
+      UserModel.findById(cached.users.notAdmin),
+      UserModel.findById(cached.users.adminOther),
+      FoodModel.findById(cached.foods.spinach),
+      FoodModel.findById(cached.foods.apple),
+      FoodModel.findById(cached.foods.carrots),
+      FoodModel.findById(cached.foods.pizza),
+      RequiredModel.findById(cached.required.sample),
+      RequiredModel.findById(cached.required.withAbout),
+    ]);
+
+  if (
+    !admin ||
+    !notAdmin ||
+    !adminOther ||
+    !spinach ||
+    !apple ||
+    !carrots ||
+    !pizza ||
+    !sample ||
+    !withAbout
+  ) {
+    throw new Error("[createTestData] Cached test data references missing documents");
+  }
+
+  return {
+    foods: {apple, carrots, pizza, spinach},
+    required: {sample, withAbout},
+    users: {admin, adminOther, notAdmin},
+  };
+};