@terreno/api 0.13.2 → 0.14.0

package/src/example.ts

@@ -3,11 +3,17 @@ import mongoose, {model, Schema} from "mongoose";
 import passportLocalMongoose from "passport-local-mongoose";
 
 import {type ModelRouterOptions, modelRouter} from "./api";
-import {addAuthRoutes, setupAuth} from "./auth";
+import {addAuthRoutes, setupAuth, type UserModel as UserMongooseModel} from "./auth";
 import {setupServer} from "./expressServer";
 import {logger} from "./logger";
 import {Permissions} from "./permissions";
-import {baseUserPlugin, createdUpdatedPlugin} from "./plugins";
+import {
+  baseUserPlugin,
+  createdUpdatedPlugin,
+  findExactlyOne,
+  findOneOrNone,
+  isDeletedPlugin,
+} from "./plugins";
 
 mongoose
   .connect("mongodb://localhost:27017/example")
@@ -31,27 +37,43 @@ interface Food {
   hidden?: boolean;
 }
 
-const userSchema = new Schema<User>({
-  admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
-  username: {description: "The user's username", type: String},
-});
+const userSchema = new Schema<User>(
+  {
+    admin: {default: false, description: "Whether the user has admin privileges", type: Boolean},
+    username: {description: "The user's username", type: String},
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
 
+// biome-ignore lint/suspicious/noExplicitAny: passport-local-mongoose's plugin type is incompatible with mongoose Schema generics
 userSchema.plugin(passportLocalMongoose as any, {usernameField: "email"});
 userSchema.plugin(createdUpdatedPlugin);
 userSchema.plugin(baseUserPlugin);
 const UserModel = model<User>("User", userSchema);
 
-const schema = new Schema<Food>({
-  calories: {description: "Number of calories in the food", type: Number},
-  created: {description: "When this food was created", type: Date},
-  hidden: {default: false, description: "Whether this food is hidden from listings", type: Boolean},
-  name: {description: "The name of the food", type: String},
-  ownerId: {description: "The user who owns this food entry", ref: "User", type: "ObjectId"},
-});
+const schema = new Schema<Food>(
+  {
+    calories: {description: "Number of calories in the food", type: Number},
+    created: {description: "When this food was created", type: Date},
+    hidden: {
+      default: false,
+      description: "Whether this food is hidden from listings",
+      type: Boolean,
+    },
+    name: {description: "The name of the food", type: String},
+    ownerId: {description: "The user who owns this food entry", ref: "User", type: "ObjectId"},
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+schema.plugin(createdUpdatedPlugin);
+schema.plugin(isDeletedPlugin);
+schema.plugin(findOneOrNone);
+schema.plugin(findExactlyOne);
 
 const FoodModel = model<Food>("Food", schema);
 
-function getBaseServer() {
+const getBaseServer = () => {
   const app = express();
 
   app.use((req, res, next) => {
@@ -65,14 +87,17 @@ function getBaseServer() {
     }
   });
   app.use(express.json());
-  setupAuth(app, UserModel as any);
-  addAuthRoutes(app, UserModel as any);
+  setupAuth(app, UserModel as unknown as UserMongooseModel);
+  addAuthRoutes(app, UserModel as unknown as UserMongooseModel);
 
-  function addRoutes(router: express.Router, options?: Partial<ModelRouterOptions<any>>): void {
+  const addRoutes = (
+    router: express.Router,
+    options?: Partial<ModelRouterOptions<unknown>>
+  ): void => {
     router.use(
       "/food",
       modelRouter(FoodModel, {
-        ...options,
+        ...(options as Partial<ModelRouterOptions<Food>>),
         openApiOverwrite: {
           get: {responses: {200: {description: "Get all the food"}}},
         },
@@ -86,14 +111,14 @@ function getBaseServer() {
         queryFields: ["name", "calories", "created", "ownerId", "hidden"],
       })
     );
-  }
+  };
 
   return setupServer({
     addRoutes,
     loggingOptions: {
       level: "debug",
     },
-    userModel: UserModel as any,
+    userModel: UserModel as unknown as UserMongooseModel,
   });
-}
+};
 getBaseServer();

package/src/express.d.ts

@@ -1,5 +1,22 @@
 declare namespace Express {
   export interface Request {
-    user?: {_id: string | ObjectId; id: string; admin: boolean};
+    authTokenPayload?: {
+      sid?: string;
+      sessionId?: string;
+      [key: string]: unknown;
+    };
+    jobId?: string;
+    requestId?: string;
+    sessionId?: string;
+    user?: {
+      _id: string | ObjectId;
+      id: string;
+      admin: boolean;
+      disabled?: boolean;
+      type?: string;
+      testUser?: boolean;
+      email?: string;
+      [key: string]: unknown;
+    };
   }
 }

package/src/expressServer.test.ts

@@ -1,6 +1,9 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
+import {Writable} from "node:stream";
 import express from "express";
 import supertest from "supertest";
+import winston from "winston";
 
 import {
   createRouter,
@@ -11,6 +14,7 @@ import {
   setupServer,
   wrapScript,
 } from "./expressServer";
+import {logger, winstonLogger} from "./logger";
 import {UserModel} from "./tests";
 
 describe("expressServer", () => {
@@ -58,6 +62,52 @@ describe("expressServer", () => {
   });
 
   describe("logRequests", () => {
+    it("attaches request and session context to route logs", async () => {
+      const logs: string[] = [];
+      const logStream = new Writable({
+        write(chunk, _encoding, callback) {
+          logs.push(chunk.toString());
+          callback();
+        },
+      });
+      const transport = new winston.transports.Stream({
+        format: winston.format.json(),
+        stream: logStream,
+      });
+
+      const app = setupServer({
+        addRoutes: (router) => {
+          router.get("/context-test", (req, res) => {
+            logger.info("context route log");
+            return res.json({requestId: req.requestId, sessionId: req.sessionId});
+          });
+        },
+        logRequests: false,
+        skipListen: true,
+        userModel: UserModel as any,
+      });
+      winstonLogger.add(transport);
+
+      const res = await supertest(app)
+        .get("/context-test")
+        .set("X-Request-ID", "req-123")
+        .set("X-Session-ID", "session-123")
+        .expect(200);
+
+      expect(res.headers["x-request-id"]).toBe("req-123");
+      expect(res.headers["x-session-id"]).toBe("session-123");
+      expect(res.body).toEqual({requestId: "req-123", sessionId: "session-123"});
+
+      const parsedLog = logs
+        .map((entry) => JSON.parse(entry))
+        .find((entry) => entry.message === "context route log");
+      expect(parsedLog).toBeDefined();
+      expect(parsedLog.requestId).toBe("req-123");
+      expect(parsedLog.sessionId).toBe("session-123");
+
+      winstonLogger.remove(transport);
+    });
+
     it("logs request with admin user type", () => {
       const req = {
         body: {},
@@ -653,7 +703,6 @@ describe("expressServer", () => {
     const timerIds: ReturnType<typeof setTimeout>[] = [];
 
     beforeEach(() => {
-      // biome-ignore lint/suspicious/noExplicitAny: Mock requires type override for process.exit.
       process.exit = mock(() => {
         throw new Error("process.exit called");
       }) as unknown as typeof process.exit;
@@ -750,7 +799,6 @@ describe("expressServer", () => {
         setupServer({
           addRoutes,
           skipListen: true,
-          // biome-ignore lint/suspicious/noExplicitAny: Test mock for UserModel.
           userModel: UserModel as any,
         })
       ).toThrow("route initialization failed");

package/src/expressServer.ts

@@ -9,19 +9,28 @@ 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, apiUnauthorizedMiddleware} from "./errors";
+import {
+  apiErrorMiddleware,
+  apiFallthroughErrorMiddleware,
+  apiUnauthorizedMiddleware,
+} from "./errors";
 import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
 import {type LoggingOptions, logger, setupLogging} 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;
 const IS_JEST = process.env.JEST_WORKER_ID !== undefined;
 
-export function setupEnvironment(): void {
+export const setupEnvironment = (): void => {
   if (!process.env.TOKEN_ISSUER) {
     throw new Error("TOKEN_ISSUER must be set in env.");
   }
@@ -40,12 +49,13 @@ export function setupEnvironment(): void {
   if (!process.env.REFRESH_TOKEN_EXPIRES_IN && !IS_JEST) {
     logger.warn("REFRESH_TOKEN_EXPIRES_IN not set so using default.");
   }
-}
+};
 
 export type AddRoutes = (router: Router, options?: Partial<ModelRouterOptions<unknown>>) => void;
 
+// biome-ignore lint/suspicious/noExplicitAny: also called from tests with mock request/response objects
 const logRequestsFinished = (req: any, res: any, startTime: bigint) => {
-  const options = (res.locals.loggingOptions ?? {}) as LoggingOptions;
+  const options = (res.locals?.loggingOptions ?? {}) as LoggingOptions;
 
   const slowReadMs = options.logSlowRequestsReadMs ?? SLOW_READ_MAX;
   const slowWriteMs = options.logSlowRequestsWriteMs ?? SLOW_WRITE_MAX;
@@ -84,7 +94,8 @@ const logRequestsFinished = (req: any, res: any, startTime: bigint) => {
   }
 };
 
-export function logRequests(req: any, res: any, next: any) {
+// biome-ignore lint/suspicious/noExplicitAny: also called from tests with mock request/response objects
+export const logRequests = (req: any, res: any, next: express.NextFunction): void => {
   const startTime = process.hrtime.bigint();
 
   let userString = "";
@@ -114,37 +125,48 @@ export function logRequests(req: any, res: any, next: any) {
   }
   onFinished(res, () => logRequestsFinished(req, res, startTime));
   next();
-}
+};
 
-export function createRouter(rootPath: string, addRoutes: AddRoutes, middleware: any[] = []) {
-  function routePathMiddleware(req: any, _res: any, next: any) {
+export const createRouter = (
+  rootPath: string,
+  addRoutes: AddRoutes,
+  middleware: express.RequestHandler[] = []
+): Array<string | express.RequestHandler | Router> => {
+  const routePathMiddleware = (
+    req: express.Request & {routeMount?: string[]},
+    _res: express.Response,
+    next: express.NextFunction
+  ): void => {
     if (!req.routeMount) {
       req.routeMount = [];
     }
     req.routeMount.push(rootPath);
     next();
-  }
+  };
 
   const router = express.Router();
   router.use(routePathMiddleware);
   addRoutes(router);
   return [rootPath, ...middleware, router];
-}
+};
 
-export function createRouterWithAuth(
+export const createRouterWithAuth = (
   rootPath: string,
   addRoutes: (router: Router) => void,
-  middleware: any[] = []
-) {
+  middleware: express.RequestHandler[] = []
+): Array<string | express.RequestHandler | Router> => {
   return createRouter(rootPath, addRoutes, [
     passport.authenticate("firebase-jwt", {session: false}),
     ...middleware,
   ]);
-}
+};
 
 export interface AuthOptions {
-  generateJWTPayload?: (user: any) => Record<string, any>;
+  // biome-ignore lint/suspicious/noExplicitAny: user shape is provided by the consumer's User model — any preserves the loose-binding contract
+  generateJWTPayload?: (user: any) => Record<string, unknown>;
+  // biome-ignore lint/suspicious/noExplicitAny: see above
   generateTokenExpiration?: (user: any) => number | jwt.SignOptions["expiresIn"];
+  // biome-ignore lint/suspicious/noExplicitAny: see above
   generateRefreshTokenExpiration?: (user: any) => number | jwt.SignOptions["expiresIn"];
 }
 
@@ -173,19 +195,20 @@ interface InitializeRoutesOptions {
   githubAuth?: GitHubAuthOptions;
 }
 
-function initializeRoutes(
+const initializeRoutes = (
   UserModel: UserMongooseModel,
   addRoutes: AddRoutes,
   options: InitializeRoutesOptions = {}
-): express.Application {
+): express.Application => {
   const app = express();
 
   // Record mount paths on layers for Express 5 → OpenAPI compat
   patchAppUse(app);
 
-  // TODO: Log a warning when we hit the array limit.
   app.set("query parser", (str: string) => qs.parse(str, {arrayLimit: options.arrayLimit ?? 200}));
 
+  app.use(requestContextMiddleware);
+
   app.use(
     cors({
       origin: options.corsOrigin ?? "*",
@@ -199,8 +222,12 @@ function initializeRoutes(
   app.use(express.json({limit: "50mb"}));
 
   // Add login/signup/refresh_token before the JWT/auth middlewares
-  addAuthRoutes(app, UserModel as any, options?.authOptions);
-  setupAuth(app as any, UserModel as any);
+  addAuthRoutes(app, UserModel, options?.authOptions);
+  setupAuth(app, UserModel);
+  app.use((req, res, next) => {
+    updateRequestContextFromRequest(req, res);
+    next();
+  });
 
   if (options.logRequests !== false) {
     app.use(logRequests);
@@ -213,9 +240,13 @@ function initializeRoutes(
   });
 
   // Add Sentry scopes for session, transaction, and userId if any are set
-  app.use((req: any, _res: any, next: any) => {
+  app.use((req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    const context = getCurrentRequestContext();
     const transactionId = req.header("X-Transaction-ID");
-    const sessionId = req.header("X-Session-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);
     }
@@ -223,7 +254,7 @@ function initializeRoutes(
       Sentry.getCurrentScope().setTag("session_id", sessionId);
     }
     if (req.user?._id) {
-      Sentry.getCurrentScope().setTag("user", req.user._id);
+      Sentry.getCurrentScope().setTag("user", String(req.user._id));
     }
     next();
   });
@@ -246,12 +277,12 @@ function initializeRoutes(
     app.use("/swagger", oapi.swaggerui());
   }
 
-  addMeRoutes(app, UserModel as any, options?.authOptions);
+  addMeRoutes(app, UserModel, options?.authOptions);
 
   // Set up GitHub OAuth if configured (works with JWT auth)
   if (options.githubAuth) {
-    setupGitHubAuth(app, UserModel as any, options.githubAuth);
-    addGitHubAuthRoutes(app, UserModel as any, options.githubAuth, options.authOptions);
+    setupGitHubAuth(app, UserModel, options.githubAuth);
+    addGitHubAuthRoutes(app, UserModel, options.githubAuth, options.authOptions);
   }
 
   addRoutes(app, {openApi: oapi});
@@ -262,20 +293,17 @@ function initializeRoutes(
   app.use(apiUnauthorizedMiddleware);
   app.use(apiErrorMiddleware);
 
-  app.use(function onError(err: any, _req: any, res: any, _next: any) {
-    logger.error(`Fallthrough error: ${err}${err?.stack ? `\n${err.stack}` : ""}}`);
-    Sentry.captureException(err);
-    res.statusCode = 500;
-    res.end(`${res.sentry}\n`);
-  });
+  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.
@@ -300,8 +328,7 @@ export interface SetupServerOptions {
   sentryOptions?: Sentry.BunOptions;
 }
 
-// Sets up the routes and returns the app.
-export function setupServer(options: SetupServerOptions): express.Application {
+export const setupServer = (options: SetupServerOptions): express.Application => {
   const UserModel = options.userModel;
   const addRoutes = options.addRoutes;
 
@@ -314,9 +341,12 @@ export function setupServer(options: SetupServerOptions): express.Application {
       authOptions: options.authOptions,
       corsOrigin: options.corsOrigin,
       githubAuth: options.githubAuth,
+      loggingOptions: options.loggingOptions,
+      logRequests: options.logRequests,
     });
-  } catch (error: any) {
-    logger.error(`Error initializing routes: ${error.stack}`);
+  } catch (error: unknown) {
+    const stack = error instanceof Error && error.stack ? error.stack : String(error);
+    logger.error(`Error initializing routes: ${stack}`);
     throw error;
   }
 
@@ -327,19 +357,19 @@ export function setupServer(options: SetupServerOptions): express.Application {
         logger.info(`Listening on port ${port}`);
       });
     } catch (error) {
-      logger.error(`Error trying to start HTTP server: ${error}\n${(error as any).stack}`);
+      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;
-}
+};
 
-// Convenience method to execute cronjobs with an always-running server.
-export function cronjob(
+export const cronjob = (
   name: string,
   schedule: "hourly" | "minutely" | string,
   callback: () => void
-) {
+): void => {
   const cronSchedule =
     schedule === "hourly" ? "0 * * * *" : schedule === "minutely" ? "* * * * *" : schedule;
   logger.info(`Adding cronjob ${name}, running at: ${cronSchedule}`);
@@ -348,16 +378,17 @@ export function cronjob(
   } catch (error) {
     throw new Error(`Failed to create cronjob: ${error}`);
   }
-}
+};
 
 export interface WrapScriptOptions {
-  onFinish?: (result?: any) => void | Promise<void>;
+  onFinish?: (result?: unknown) => void | Promise<void>;
   terminateTimeout?: number; // in seconds, defaults to 300. Set to 0 to have no termination timeout.
   slackChannel?: string;
 }
-// Wrap up a script with some helpers, such as catching errors, reporting them to sentry, notifying
-// Slack of runs, etc. Also supports timeouts.
-export async function wrapScript(func: () => Promise<any>, options: WrapScriptOptions = {}) {
+export const wrapScript = async (
+  func: () => Promise<unknown>,
+  options: WrapScriptOptions = {}
+): Promise<void> => {
   const name = require.main?.filename.split("/").slice(-1)[0].replace(".ts", "");
   logger.info(`Running script ${name}`);
   await sendToSlack(`Running script ${name}`, {
@@ -383,7 +414,7 @@ export async function wrapScript(func: () => Promise<any>, options: WrapScriptOp
     }, closeTime);
   }
 
-  let result: any;
+  let result: unknown;
   try {
     result = await func();
     if (options.onFinish) {
@@ -397,6 +428,5 @@ export async function wrapScript(func: () => Promise<any>, options: WrapScriptOp
     process.exit(1);
   }
   await sendToSlack(`Success running script ${name}: ${result}`);
-  // Unclear why we have to exit here to prevent the script for continuing to run.
   process.exit(0);
-}
+};

package/src/githubAuth.test.ts

@@ -1,3 +1,4 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 import {afterEach, beforeEach, describe, expect, it, setSystemTime} from "bun:test";
 import type express from "express";
 import mongoose, {model, Schema} from "mongoose";