@terreno/api 0.20.2 → 0.21.0

package/src/expressServer.test.ts

@@ -11,10 +11,10 @@ import {
   cronjob,
   logRequests,
   setupEnvironment,
-  setupServer,
   wrapScript,
 } from "./expressServer";
 import {logger, winstonLogger} from "./logger";
+import {TerrenoApp} from "./terrenoApp";
 import {UserModel} from "./tests";
 
 describe("expressServer", () => {
@@ -75,8 +75,8 @@ describe("expressServer", () => {
         stream: logStream,
       });
 
-      const app = setupServer({
-        addRoutes: (router) => {
+      const app = new TerrenoApp({
+        configureApp: (router) => {
           router.get("/context-test", (req, res) => {
             logger.info("context route log");
             return res.json({requestId: req.requestId, sessionId: req.sessionId});
@@ -85,7 +85,7 @@ describe("expressServer", () => {
         logRequests: false,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
       winstonLogger.add(transport);
 
       const res = await supertest(app)
@@ -410,7 +410,7 @@ describe("expressServer", () => {
     });
   });
 
-  describe("setupServer", () => {
+  describe("TerrenoApp", () => {
     const originalEnv = process.env;
 
     beforeEach(() => {
@@ -429,61 +429,60 @@ describe("expressServer", () => {
     });
 
     it("creates server with skipListen option", () => {
-      const addRoutes = () => {};
+      const configureApp = (): void => {};
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       expect(app).toBeDefined();
     });
 
-    it("creates server with addMiddleware option", () => {
+    it("creates server with beforeJsonSetup option", () => {
       let middlewareCalled = false;
-      const addMiddleware = (app: any) => {
-        middlewareCalled = true;
-        app.use((_req: any, _res: any, next: any) => next());
-      };
-      const addRoutes = () => {};
+      const configureApp = (): void => {};
 
-      const app = setupServer({
-        addMiddleware,
-        addRoutes,
+      const app = new TerrenoApp({
+        beforeJsonSetup: (httpApp: any) => {
+          middlewareCalled = true;
+          httpApp.use((_req: any, _res: any, next: any) => next());
+        },
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       expect(app).toBeDefined();
       expect(middlewareCalled).toBe(true);
     });
 
     it("creates server with custom corsOrigin", () => {
-      const addRoutes = () => {};
+      const configureApp = (): void => {};
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         corsOrigin: "https://example.com",
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       expect(app).toBeDefined();
     });
 
     it("creates server with authOptions", () => {
-      const addRoutes = () => {};
+      const configureApp = (): void => {};
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
         authOptions: {
           generateJWTPayload: (user) => ({customField: "test", id: user._id}),
           generateTokenExpiration: () => "2h",
         },
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       expect(app).toBeDefined();
     });
@@ -514,7 +513,7 @@ describe("expressServer", () => {
     });
   });
 
-  describe("setupServer with full integration", () => {
+  describe("TerrenoApp with full integration", () => {
     const originalEnv = process.env;
 
     beforeEach(() => {
@@ -533,49 +532,49 @@ describe("expressServer", () => {
     });
 
     it("sets Sentry transaction ID tag from header", async () => {
-      const addRoutes = (app: any) => {
-        app.get("/test", (_req: any, res: any) => {
+      const configureApp = (httpApp: any) => {
+        httpApp.get("/test", (_req: any, res: any) => {
           res.json({ok: true});
         });
       };
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       await supertest(app).get("/test").set("X-Transaction-ID", "txn-123").expect(200);
     });
 
     it("sets Sentry session ID tag from header", async () => {
-      const addRoutes = (app: any) => {
-        app.get("/test", (_req: any, res: any) => {
+      const configureApp = (httpApp: any) => {
+        httpApp.get("/test", (_req: any, res: any) => {
           res.json({ok: true});
         });
       };
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       await supertest(app).get("/test").set("X-Session-ID", "session-456").expect(200);
     });
 
     it("sets both transaction and session ID tags", async () => {
-      const addRoutes = (app: any) => {
-        app.get("/test", (_req: any, res: any) => {
+      const configureApp = (httpApp: any) => {
+        httpApp.get("/test", (_req: any, res: any) => {
           res.json({ok: true});
         });
       };
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       await supertest(app)
         .get("/test")
@@ -585,52 +584,52 @@ describe("expressServer", () => {
     });
 
     it("handles fallthrough error handler", async () => {
-      const addRoutes = (app: any) => {
-        app.get("/error", (_req: any, _res: any) => {
+      const configureApp = (httpApp: any) => {
+        httpApp.get("/error", (_req: any, _res: any) => {
           throw new Error("Unexpected error");
         });
       };
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       await supertest(app).get("/error").expect(500);
     });
 
-    it("handles loggingOptions passed to setupServer", async () => {
-      const addRoutes = (app: any) => {
-        app.get("/test", (_req: any, res: any) => {
+    it("handles loggingOptions passed to TerrenoApp", async () => {
+      const configureApp = (httpApp: any) => {
+        httpApp.get("/test", (_req: any, res: any) => {
           res.json({ok: true});
         });
       };
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         loggingOptions: {
           logSlowRequests: true,
           logSlowRequestsReadMs: 100,
         },
         skipListen: true,
         userModel: UserModel as any,
-      });
+      }).build();
 
       await supertest(app).get("/test").expect(200);
     });
 
-    it("re-throws when addRoutes throws during route initialization", () => {
-      const addRoutes = () => {
+    it("re-throws when configureApp throws during build", () => {
+      const configureApp = () => {
         throw new Error("Route init boom");
       };
 
       expect(() =>
-        setupServer({
-          addRoutes,
+        new TerrenoApp({
+          configureApp,
           skipListen: true,
           userModel: UserModel as any,
-        })
+        }).build()
       ).toThrow("Route init boom");
     });
   });
@@ -788,7 +787,7 @@ describe("expressServer", () => {
     });
   });
 
-  describe("setupServer with listen (skipListen false)", () => {
+  describe("TerrenoApp with listen (skipListen false)", () => {
     const originalEnv = process.env;
 
     beforeEach(() => {
@@ -808,11 +807,10 @@ describe("expressServer", () => {
     });
 
     it("starts the server when skipListen is false", async () => {
-      const addRoutes = () => {};
-      // Mock app.listen on the Express prototype to avoid opening a real port
-      const express = await import("express");
-      const originalListen = express.default.application.listen;
-      express.default.application.listen = mock(function (this: unknown, ...args: unknown[]) {
+      const configureApp = (): void => {};
+      const http = await import("node:http");
+      const originalListen = http.Server.prototype.listen;
+      http.Server.prototype.listen = mock(function (this: unknown, ...args: unknown[]) {
         const cb = args.find((a: unknown) => typeof a === "function") as (() => void) | undefined;
         if (cb) {
           cb();
@@ -820,29 +818,28 @@ describe("expressServer", () => {
         return this;
       }) as unknown as typeof originalListen;
       try {
-        const app = setupServer({
-          addRoutes,
+        const app = new TerrenoApp({
+          configureApp,
           skipListen: false,
           userModel: UserModel as any,
-        });
+        }).start();
         expect(app).toBeDefined();
       } finally {
-        express.default.application.listen = originalListen;
+        http.Server.prototype.listen = originalListen;
       }
     });
 
     it("handles listen error with invalid port", () => {
       process.env.PORT = "-1";
-      const addRoutes = () => {};
-      // Using an invalid port should trigger the catch block and process.exit(1)
+      const configureApp = (): void => {};
       const originalExit = process.exit;
       process.exit = (() => {}) as unknown as typeof process.exit;
       try {
-        setupServer({
-          addRoutes,
+        new TerrenoApp({
+          configureApp,
           skipListen: false,
           userModel: UserModel as any,
-        });
+        }).start();
       } catch {
         // May throw
       }
@@ -850,7 +847,7 @@ describe("expressServer", () => {
     });
   });
 
-  describe("setupServer with listen", () => {
+  describe("TerrenoApp with listen", () => {
     const originalEnv = process.env;
     const http = require("node:http");
     let activeServer: any = null;
@@ -884,13 +881,13 @@ describe("expressServer", () => {
     });
 
     it("starts listening on a port when skipListen is false", async () => {
-      const addRoutes = () => {};
+      const configureApp = (): void => {};
 
-      const app = setupServer({
-        addRoutes,
+      const app = new TerrenoApp({
+        configureApp,
         skipListen: false,
         userModel: UserModel as any,
-      });
+      }).start();
 
       expect(app).toBeDefined();
       await new Promise((resolve) => setTimeout(resolve, 100));
@@ -947,7 +944,7 @@ describe("expressServer", () => {
     });
   });
 
-  describe("setupServer error handling", () => {
+  describe("TerrenoApp error handling", () => {
     const originalEnv = process.env;
 
     beforeEach(() => {
@@ -965,17 +962,17 @@ describe("expressServer", () => {
       process.env = originalEnv;
     });
 
-    it("catches and rethrows errors from initializeRoutes", () => {
-      const addRoutes = () => {
+    it("throws when configureApp throws during build", () => {
+      const configureApp = () => {
         throw new Error("route initialization failed");
       };
 
       expect(() =>
-        setupServer({
-          addRoutes,
+        new TerrenoApp({
+          configureApp,
           skipListen: true,
           userModel: UserModel as any,
-        })
+        }).build()
       ).toThrow("route initialization failed");
     });
   });

package/src/expressServer.ts

@@ -1,30 +1,13 @@
 import * as Sentry from "@sentry/bun";
-import cors from "cors";
 import cron from "cron";
 import express, {type Router} from "express";
 import type jwt from "jsonwebtoken";
 import cloneDeep from "lodash/cloneDeep";
 import onFinished from "on-finished";
 import passport from "passport";
-import qs from "qs";
 import type {ModelRouterOptions} from "./api";
-import {addAuthRoutes, addMeRoutes, setupAuth, type UserModel as UserMongooseModel} from "./auth";
-import {
-  apiErrorMiddleware,
-  apiFallthroughErrorMiddleware,
-  apiUnauthorizedMiddleware,
-} from "./errors";
-import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
-import {type LoggingOptions, logger, setupLogging} from "./logger";
+import {type LoggingOptions, logger} from "./logger";
 import {sendToSlack} from "./notifiers";
-import {openApiCompatMiddleware, patchAppUse} from "./openApiCompat";
-import {openApiEtagMiddleware} from "./openApiEtag";
-import {
-  getCurrentRequestContext,
-  requestContextMiddleware,
-  updateRequestContextFromRequest,
-} from "./requestContext";
-import openapi from "./vendor/wesleytodd-openapi/index";
 
 const SLOW_READ_MAX = 200;
 const SLOW_WRITE_MAX = 500;
@@ -170,201 +153,6 @@ export interface AuthOptions {
   generateRefreshTokenExpiration?: (user: any) => number | jwt.SignOptions["expiresIn"];
 }
 
-interface InitializeRoutesOptions {
-  corsOrigin?:
-    | string
-    | boolean
-    | RegExp
-    | Array<boolean | string | RegExp>
-    | ((
-        requestOrigin: string | undefined,
-        callback: (
-          err: Error | null,
-          origin?: boolean | string | RegExp | Array<boolean | string | RegExp>
-        ) => void
-      ) => void);
-  addMiddleware?: AddRoutes;
-  // The maximum number of array elements to parse in a query string. Defaults to 200.
-  arrayLimit?: number;
-  // Whether requests should be logged. In production, you may want to disable this if using another
-  // logger (e.g. Google Cloud).
-  logRequests?: boolean;
-  loggingOptions?: LoggingOptions;
-  authOptions?: AuthOptions;
-  /** GitHub OAuth configuration. When provided, enables GitHub authentication. */
-  githubAuth?: GitHubAuthOptions;
-}
-
-const initializeRoutes = (
-  UserModel: UserMongooseModel,
-  addRoutes: AddRoutes,
-  options: InitializeRoutesOptions = {}
-): express.Application => {
-  const app = express();
-
-  // Record mount paths on layers for Express 5 → OpenAPI compat
-  patchAppUse(app);
-
-  app.set("query parser", (str: string) => qs.parse(str, {arrayLimit: options.arrayLimit ?? 200}));
-
-  app.use(requestContextMiddleware);
-
-  app.use(
-    cors({
-      origin: options.corsOrigin ?? "*",
-    })
-  );
-
-  if (options.addMiddleware) {
-    options.addMiddleware(app);
-  }
-
-  app.use(express.json({limit: "50mb"}));
-
-  // Add login/signup/refresh_token before the JWT/auth middlewares
-  addAuthRoutes(app, UserModel, options?.authOptions);
-  setupAuth(app, UserModel);
-  app.use((req, res, next) => {
-    updateRequestContextFromRequest(req, res);
-    next();
-  });
-
-  if (options.logRequests !== false) {
-    app.use(logRequests);
-  }
-
-  // Store the logging options on the request so we can access them later.
-  app.use((_req, res, next) => {
-    res.locals.loggingOptions = options.loggingOptions;
-    next();
-  });
-
-  // Add Sentry scopes for session, transaction, and userId if any are set
-  app.use((req: express.Request, _res: express.Response, next: express.NextFunction) => {
-    const context = getCurrentRequestContext();
-    const transactionId = req.header("X-Transaction-ID");
-    const sessionId = context?.sessionId ?? req.header("X-Session-ID");
-    if (context?.requestId) {
-      Sentry.getCurrentScope().setTag("request_id", context.requestId);
-    }
-    if (transactionId) {
-      Sentry.getCurrentScope().setTag("transaction_id", transactionId);
-    }
-    if (sessionId) {
-      Sentry.getCurrentScope().setTag("session_id", sessionId);
-    }
-    if (req.user?._id) {
-      Sentry.getCurrentScope().setTag("user", String(req.user._id));
-    }
-    next();
-  });
-
-  // Add ETag middleware for OpenAPI JSON endpoint before the openapi middleware
-  app.use(openApiCompatMiddleware);
-  app.use(openApiEtagMiddleware);
-
-  const oapi = openapi({
-    info: {
-      description: "Generated docs from an Express api",
-      title: "Express Application",
-      version: "1.0.0",
-    },
-    openapi: "3.0.0",
-  });
-  app.use(oapi);
-
-  if (process.env.ENABLE_SWAGGER === "true") {
-    app.use("/swagger", oapi.swaggerui());
-  }
-
-  addMeRoutes(app, UserModel, options?.authOptions);
-
-  // Set up GitHub OAuth if configured (works with JWT auth)
-  if (options.githubAuth) {
-    setupGitHubAuth(app, UserModel, options.githubAuth);
-    addGitHubAuthRoutes(app, UserModel, options.githubAuth, options.authOptions);
-  }
-
-  addRoutes(app, {openApi: oapi});
-
-  Sentry.setupExpressErrorHandler(app);
-
-  // Catch any thrown APIErrors and return them in an OpenAPI compatible format
-  app.use(apiUnauthorizedMiddleware);
-  app.use(apiErrorMiddleware);
-
-  app.use(apiFallthroughErrorMiddleware);
-
-  return app;
-};
-
-export interface SetupServerOptions {
-  userModel: UserMongooseModel;
-  addRoutes: AddRoutes;
-  loggingOptions?: LoggingOptions;
-  // Whether requests should be logged. Defaults to true.
-  logRequests?: boolean;
-  authOptions?: AuthOptions;
-  /**
-   * GitHub OAuth configuration. When provided, enables GitHub authentication.
-   * Requires the user schema to have GitHub fields (use githubUserPlugin).
-   */
-  githubAuth?: GitHubAuthOptions;
-  skipListen?: boolean;
-  corsOrigin?:
-    | string
-    | boolean
-    | RegExp
-    | Array<boolean | string | RegExp>
-    | ((
-        requestOrigin: string | undefined,
-        callback: (
-          err: Error | null,
-          origin?: boolean | string | RegExp | Array<boolean | string | RegExp>
-        ) => void
-      ) => void);
-  addMiddleware?: AddRoutes;
-  ignoreTraces?: string[];
-  sentryOptions?: Sentry.BunOptions;
-}
-
-export const setupServer = (options: SetupServerOptions): express.Application => {
-  const UserModel = options.userModel;
-  const addRoutes = options.addRoutes;
-
-  setupLogging(options.loggingOptions);
-
-  let app: express.Application;
-  try {
-    app = initializeRoutes(UserModel, addRoutes, {
-      addMiddleware: options.addMiddleware,
-      authOptions: options.authOptions,
-      corsOrigin: options.corsOrigin,
-      githubAuth: options.githubAuth,
-      loggingOptions: options.loggingOptions,
-      logRequests: options.logRequests,
-    });
-  } catch (error: unknown) {
-    const stack = error instanceof Error && error.stack ? error.stack : String(error);
-    logger.error(`Error initializing routes: ${stack}`);
-    throw error;
-  }
-
-  if (!options.skipListen) {
-    const port = process.env.PORT || "9000";
-    try {
-      app.listen(port, () => {
-        logger.info(`Listening on port ${port}`);
-      });
-    } catch (error) {
-      const stack = error instanceof Error ? error.stack : String(error);
-      logger.error(`Error trying to start HTTP server: ${error}\n${stack}`);
-      process.exit(1);
-    }
-  }
-  return app;
-};
-
 export const cronjob = (
   name: string,
   schedule: "hourly" | "minutely" | string,