@terreno/api 0.13.3 → 0.14.1

package/src/errors.ts

@@ -1,7 +1,7 @@
 // https://jsonapi.org/format/#errors
 import * as Sentry from "@sentry/bun";
 import type {NextFunction, Request, Response} from "express";
-import {Schema} from "mongoose";
+import mongoose, {Schema} from "mongoose";
 
 import {logger} from "./logger";
 
@@ -42,7 +42,7 @@ export interface APIErrorConstructor {
   };
   // A meta object containing non-standard meta-information about the error.
   meta?: {[id: string]: string};
-  error?: Error;
+  error?: unknown;
   // If true, this error will not be sent to external error reporting tools like Sentry.
   disableExternalErrorTracking?: boolean;
 }
@@ -82,19 +82,17 @@ export class APIError extends Error {
       }
     | undefined;
 
-  meta: {[id: string]: any} | undefined;
+  meta: {[id: string]: unknown} | undefined;
 
-  error?: Error;
+  error?: unknown;
 
   disableExternalErrorTracking?: boolean;
 
   constructor(data: APIErrorConstructor) {
+    const errorStack =
+      data.error instanceof Error && data.error.stack ? `\n${data.error.stack}` : "";
     // Include details in when the error is printed to the console or sent to Sentry.
-    super(
-      `${data.title}${data.detail ? `: ${data.detail}` : ""}${
-        data.error ? `\n${data.error.stack}` : ""
-      }`
-    );
+    super(`${data.title}${data.detail ? `: ${data.detail}` : ""}${errorStack}`);
     this.name = "APIError";
 
     let {title, id, links, status, code, detail, source, meta, fields, error} = data;
@@ -120,9 +118,9 @@ export class APIError extends Error {
       this.meta.fields = fields;
     }
     this.error = error;
-    const logMessage = `APIError(${status}): ${title} ${detail ? detail : ""}${
-      data.error?.stack ? `\n${data.error?.stack}` : ""
-    }`;
+    const dataErrorStack =
+      data.error instanceof Error && data.error.stack ? `\n${data.error.stack}` : "";
+    const logMessage = `APIError(${status}): ${title} ${detail ? detail : ""}${dataErrorStack}`;
     if (data.disableExternalErrorTracking) {
       logger.warn(logMessage);
     } else {
@@ -138,32 +136,54 @@ export class APIError extends Error {
 // Create an errors field for storing error information in a JSONAPI compatible form directly on a
 // model.
 export const errorsPlugin = (schema: Schema): void => {
-  const errorSchema = new Schema({
-    code: {description: "Application-specific error code", type: String},
-    detail: {description: "Human-readable explanation of the error", type: String},
-    id: {description: "Unique identifier for this error occurrence", type: String},
-    links: {
-      about: {description: "Link to documentation about this error", type: String},
-      type: {description: "Link describing the error type", type: String},
-    },
-    meta: {description: "Non-standard meta information about the error", type: Schema.Types.Mixed},
-    source: {
-      header: {description: "HTTP header that caused the error", type: String},
-      parameter: {description: "Query parameter that caused the error", type: String},
-      pointer: {
-        description: "JSON pointer to the request field that caused the error",
-        type: String,
+  const errorSchema = new Schema(
+    {
+      code: {description: "Application-specific error code", type: String},
+      detail: {description: "Human-readable explanation of the error", type: String},
+      id: {description: "Unique identifier for this error occurrence", type: String},
+      links: {
+        about: {description: "Link to documentation about this error", type: String},
+        type: {description: "Link describing the error type", type: String},
+      },
+      meta: {
+        description: "Non-standard meta information about the error",
+        type: Schema.Types.Mixed,
+      },
+      source: {
+        header: {description: "HTTP header that caused the error", type: String},
+        parameter: {description: "Query parameter that caused the error", type: String},
+        pointer: {
+          description: "JSON pointer to the request field that caused the error",
+          type: String,
+        },
       },
+      status: {description: "HTTP status code for this error", type: Number},
+      title: {description: "Short summary of the error", required: true, type: String},
     },
-    status: {description: "HTTP status code for this error", type: Number},
-    title: {description: "Short summary of the error", required: true, type: String},
-  });
+    {_id: false, strict: "throw"}
+  );
 
   schema.add({apiErrors: errorSchema});
 };
 
-export const isAPIError = (error: Error): error is APIError => {
-  return error.name === "APIError";
+export const isAPIError = (error: unknown): error is APIError => {
+  return error instanceof Error && error.name === "APIError";
+};
+
+/** Extract a human-readable message from an unknown error. */
+export const errorMessage = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+};
+
+/** Extract a stack trace string from an unknown error. */
+export const errorStack = (error: unknown): string => {
+  if (error instanceof Error && error.stack) {
+    return error.stack;
+  }
+  return String(error);
 };
 
 /**
@@ -186,8 +206,9 @@ export const getDisableExternalErrorTracking = (error: unknown): boolean | undef
 // Creates an APIError body to send to clients as JSON. Errors don't have a toJSON defined,
 // and we want to strip out things like message, name, and stack for the client.
 // There is almost certainly a more elegant solution to this.
-export const getAPIErrorBody = (error: APIError): {[id: string]: any} => {
-  const errorData = {status: error.status, title: error.title};
+export const getAPIErrorBody = (error: APIError): Record<string, unknown> => {
+  const errorData: Record<string, unknown> = {status: error.status, title: error.title};
+  const indexable = error as unknown as Record<string, unknown>;
   for (const key of [
     "id",
     "links",
@@ -198,8 +219,8 @@ export const getAPIErrorBody = (error: APIError): {[id: string]: any} => {
     "meta",
     "disableExternalErrorTracking",
   ]) {
-    if (error[key]) {
-      errorData[key] = error[key];
+    if (indexable[key]) {
+      errorData[key] = indexable[key];
     }
   }
   return errorData;
@@ -219,6 +240,40 @@ export const apiUnauthorizedMiddleware = (
   }
 };
 
+/**
+ * Converts Mongoose validation/cast errors into client-friendly APIErrors.
+ */
+export const mongooseErrorToAPIError = (err: Error): APIError | null => {
+  if (err instanceof mongoose.Error.ValidationError) {
+    const fields: {[id: string]: string} = {};
+    for (const [path, subErr] of Object.entries(err.errors)) {
+      fields[path] = subErr.message;
+    }
+    return new APIError({
+      detail: err.message,
+      disableExternalErrorTracking: true,
+      fields,
+      status: 400,
+      title: "Validation failed",
+    });
+  }
+
+  if (err instanceof mongoose.Error.CastError) {
+    const path = err.path ?? "field";
+    return new APIError({
+      detail: `Invalid value for ${path}`,
+      disableExternalErrorTracking: true,
+      fields: {
+        [path]: `Expected ${err.kind ?? "a valid value"}, got ${JSON.stringify(err.value)}`,
+      },
+      status: 400,
+      title: "Validation failed",
+    });
+  }
+
+  return null;
+};
+
 export const apiErrorMiddleware = (
   err: Error,
   _req: Request,
@@ -230,7 +285,32 @@ export const apiErrorMiddleware = (
       Sentry.captureException(err);
     }
     res.status(err.status).json(getAPIErrorBody(err)).send();
-  } else {
-    next(err);
+    return;
+  }
+
+  const mongooseError = mongooseErrorToAPIError(err);
+  if (mongooseError) {
+    res.status(mongooseError.status).json(getAPIErrorBody(mongooseError)).send();
+    return;
+  }
+
+  next(err);
+};
+
+/**
+ * Final Express error handler for unexpected errors. Always returns JSON so
+ * clients (e.g. RTK Query) can parse the response.
+ */
+export const apiFallthroughErrorMiddleware = (
+  err: Error,
+  _req: Request,
+  res: Response,
+  _next: NextFunction
+): void => {
+  logger.error(`Fallthrough error: ${err}${err.stack ? `\n${err.stack}` : ""}`);
+  Sentry.captureException(err);
+  if (res.headersSent) {
+    return;
   }
+  res.status(500).json({status: 500, title: "Internal server error"}).send();
 };

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,46 @@ 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(isDeletedPlugin);
+userSchema.plugin(findOneOrNone);
+userSchema.plugin(findExactlyOne);
 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 +90,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 +114,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;
@@ -723,6 +772,103 @@ describe("expressServer", () => {
     });
   });
 
+  describe("setupServer with listen", () => {
+    const originalEnv = process.env;
+    const http = require("node:http");
+    let activeServer: any = null;
+    let originalListen: any = null;
+
+    beforeEach(() => {
+      process.env = {
+        ...originalEnv,
+        PORT: "0",
+        REFRESH_TOKEN_SECRET: "test-refresh-secret",
+        SESSION_SECRET: "test-session-secret",
+        TOKEN_EXPIRES_IN: "1h",
+        TOKEN_ISSUER: "test-issuer",
+        TOKEN_SECRET: "test-secret",
+      };
+
+      originalListen = http.Server.prototype.listen;
+      http.Server.prototype.listen = function (...args: any[]) {
+        activeServer = this;
+        return originalListen.apply(this, args);
+      };
+    });
+
+    afterEach(async () => {
+      process.env = originalEnv;
+      http.Server.prototype.listen = originalListen;
+      if (activeServer) {
+        await new Promise<void>((resolve) => activeServer.close(() => resolve()));
+        activeServer = null;
+      }
+    });
+
+    it("starts listening on a port when skipListen is false", async () => {
+      const addRoutes = () => {};
+
+      const app = setupServer({
+        addRoutes,
+        skipListen: false,
+        userModel: UserModel as any,
+      });
+
+      expect(app).toBeDefined();
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+  });
+
+  describe("wrapScript timeout callbacks", () => {
+    const originalEnv = process.env;
+    const originalExit = process.exit;
+    const originalSetTimeout = globalThis.setTimeout;
+    const timerIds: ReturnType<typeof setTimeout>[] = [];
+    const timerCallbacks: Array<{callback: () => void; delay: number}> = [];
+
+    beforeEach(() => {
+      process.env = {
+        ...process.env,
+        REFRESH_TOKEN_SECRET: "test-refresh-secret",
+        SESSION_SECRET: "test-session-secret",
+        TOKEN_EXPIRES_IN: "1h",
+        TOKEN_ISSUER: "test-issuer",
+        TOKEN_SECRET: "test-secret",
+      };
+      process.exit = mock(() => {
+        throw new Error("__EXIT__");
+      }) as unknown as typeof process.exit;
+
+      timerCallbacks.length = 0;
+      timerIds.length = 0;
+      globalThis.setTimeout = ((cb: () => void, delay: number) => {
+        timerCallbacks.push({callback: cb, delay});
+        const id = originalSetTimeout(cb, delay);
+        timerIds.push(id);
+        return id;
+      }) as typeof setTimeout;
+    });
+
+    afterEach(() => {
+      for (const id of timerIds) {
+        clearTimeout(id);
+      }
+      globalThis.setTimeout = originalSetTimeout;
+      process.exit = originalExit;
+      process.env = originalEnv;
+    });
+
+    it("registers warn and terminate timeouts with correct delays", async () => {
+      const func = async () => "ok";
+      await expect(wrapScript(func, {terminateTimeout: 100})).rejects.toThrow("__EXIT__");
+
+      const warnTimer = timerCallbacks.find((t) => t.delay === 50000);
+      const closeTimer = timerCallbacks.find((t) => t.delay === 100000);
+      expect(warnTimer).toBeDefined();
+      expect(closeTimer).toBeDefined();
+    });
+  });
+
   describe("setupServer error handling", () => {
     const originalEnv = process.env;
 
@@ -750,7 +896,6 @@ describe("expressServer", () => {
         setupServer({
           addRoutes,
           skipListen: true,
-          // biome-ignore lint/suspicious/noExplicitAny: Test mock for UserModel.
           userModel: UserModel as any,
         })
       ).toThrow("route initialization failed");