@terreno/api 0.14.0 → 0.14.2

package/dist/requestContext.test.js

@@ -212,6 +212,149 @@ var requestContext_1 = require("./requestContext");
             }
         });
     }); });
+    (0, bun_test_1.it)("parses Google Cloud trace context header in middleware", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = (0, express_1.default)();
+                    app.use(requestContext_1.requestContextMiddleware);
+                    app.get("/trace-gcloud", function (_req, res) {
+                        var ctx = (0, requestContext_1.getCurrentRequestContext)();
+                        res.json({
+                            spanId: ctx === null || ctx === void 0 ? void 0 : ctx.spanId,
+                            traceId: ctx === null || ctx === void 0 ? void 0 : ctx.traceId,
+                            traceSampled: ctx === null || ctx === void 0 ? void 0 : ctx.traceSampled,
+                        });
+                    });
+                    return [4 /*yield*/, (0, supertest_1.default)(app)
+                            .get("/trace-gcloud")
+                            .set("X-Cloud-Trace-Context", "105445aa7843bc8bf206b12000100000/1;o=1")
+                            .expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.traceId).toBe("105445aa7843bc8bf206b12000100000");
+                    (0, bun_test_1.expect)(res.body.spanId).toBe("1");
+                    (0, bun_test_1.expect)(res.body.traceSampled).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("parses Google Cloud trace context without trace sampling", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = (0, express_1.default)();
+                    app.use(requestContext_1.requestContextMiddleware);
+                    app.get("/trace-gcloud-nosample", function (_req, res) {
+                        var ctx = (0, requestContext_1.getCurrentRequestContext)();
+                        res.json({
+                            spanId: ctx === null || ctx === void 0 ? void 0 : ctx.spanId,
+                            traceId: ctx === null || ctx === void 0 ? void 0 : ctx.traceId,
+                            traceSampled: ctx === null || ctx === void 0 ? void 0 : ctx.traceSampled,
+                        });
+                    });
+                    return [4 /*yield*/, (0, supertest_1.default)(app)
+                            .get("/trace-gcloud-nosample")
+                            .set("X-Cloud-Trace-Context", "abc123/42;o=0")
+                            .expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.traceId).toBe("abc123");
+                    (0, bun_test_1.expect)(res.body.spanId).toBe("42");
+                    (0, bun_test_1.expect)(res.body.traceSampled).toBe(false);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("falls back to traceparent when cloud trace context is absent", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = (0, express_1.default)();
+                    app.use(requestContext_1.requestContextMiddleware);
+                    app.get("/trace-parent", function (_req, res) {
+                        var ctx = (0, requestContext_1.getCurrentRequestContext)();
+                        res.json({
+                            spanId: ctx === null || ctx === void 0 ? void 0 : ctx.spanId,
+                            traceId: ctx === null || ctx === void 0 ? void 0 : ctx.traceId,
+                            traceSampled: ctx === null || ctx === void 0 ? void 0 : ctx.traceSampled,
+                        });
+                    });
+                    return [4 /*yield*/, (0, supertest_1.default)(app)
+                            .get("/trace-parent")
+                            .set("traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
+                            .expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.traceId).toBe("4bf92f3577b34da6a3ce929d0e0e4736");
+                    (0, bun_test_1.expect)(res.body.spanId).toBe("00f067aa0ba902b7");
+                    (0, bun_test_1.expect)(res.body.traceSampled).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("uses trace id as request id when no explicit request id header is set", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var app, res;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    app = (0, express_1.default)();
+                    app.use(requestContext_1.requestContextMiddleware);
+                    app.get("/trace-request-id", function (_req, res) {
+                        var ctx = (0, requestContext_1.getCurrentRequestContext)();
+                        res.json({ requestId: ctx === null || ctx === void 0 ? void 0 : ctx.requestId });
+                    });
+                    return [4 /*yield*/, (0, supertest_1.default)(app)
+                            .get("/trace-request-id")
+                            .set("X-Cloud-Trace-Context", "trace-as-rid/99;o=1")
+                            .expect(200)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.body.requestId).toBe("trace-as-rid");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("handles traceSampled attribute values 'true', '1', 'false', '0'", function () {
+        var ctxTrue = (0, requestContext_1.getRequestContextFromAttributes)({
+            "x-request-id": "r1",
+            "x-trace-sampled": "true",
+        });
+        (0, bun_test_1.expect)(ctxTrue.traceSampled).toBe(true);
+        var ctx1 = (0, requestContext_1.getRequestContextFromAttributes)({
+            "x-request-id": "r2",
+            "x-trace-sampled": "1",
+        });
+        (0, bun_test_1.expect)(ctx1.traceSampled).toBe(true);
+        var ctxFalse = (0, requestContext_1.getRequestContextFromAttributes)({
+            "x-request-id": "r3",
+            "x-trace-sampled": "false",
+        });
+        (0, bun_test_1.expect)(ctxFalse.traceSampled).toBe(false);
+        var ctx0 = (0, requestContext_1.getRequestContextFromAttributes)({
+            "x-request-id": "r4",
+            "x-trace-sampled": "0",
+        });
+        (0, bun_test_1.expect)(ctx0.traceSampled).toBe(false);
+    });
+    (0, bun_test_1.it)("parses Google Cloud trace context with missing span id", function () {
+        var ctx = (0, requestContext_1.getRequestContextFromAttributes)({
+            "x-cloud-trace-context": "only-trace-id",
+            "x-request-id": "r5",
+        });
+        (0, bun_test_1.expect)(ctx.traceId).toBe("only-trace-id");
+        (0, bun_test_1.expect)(ctx.spanId).toBeUndefined();
+    });
+    (0, bun_test_1.it)("returns undefined trace when traceparent has empty trace id", function () {
+        var ctx = (0, requestContext_1.getRequestContextFromAttributes)({
+            traceparent: "00--span-01",
+            "x-request-id": "r6",
+        });
+        (0, bun_test_1.expect)(ctx.traceId).toBeUndefined();
+    });
     (0, bun_test_1.it)("adds job id to logger context", function () {
         var output = "";
         var stream = new node_stream_1.Writable({

package/package.json

@@ -106,5 +106,5 @@
     "updateSnapshot": "bun test --update-snapshots"
   },
   "types": "dist/index.d.ts",
-  "version": "0.14.0"
+  "version": "0.14.2"
 }

package/src/__tests__/versionCheckPlugin.test.ts

@@ -153,6 +153,45 @@ describe("VersionCheckPlugin", () => {
     expect(res.body.pollingIntervalMs).toBe(86400000);
   });
 
+  it("handles numeric version parameter directly", async () => {
+    await VersionConfig.create({
+      webRequiredVersion: 100,
+      webWarningVersion: 150,
+    });
+
+    const res = await app.get("/version-check?version=50&platform=web");
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe("required");
+  });
+
+  it("returns default warning message when warningMessage not set", async () => {
+    await VersionConfig.create({
+      webRequiredVersion: 0,
+      webWarningVersion: 100,
+    });
+
+    const res = await app.get("/version-check").query({platform: "web", version: 50});
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe("warning");
+    expect(res.body.message).toBe(
+      "A new version is available. Please update for the best experience."
+    );
+  });
+
+  it("returns default required message when requiredMessage not set", async () => {
+    await VersionConfig.create({
+      webRequiredVersion: 100,
+      webWarningVersion: 150,
+    });
+
+    const res = await app.get("/version-check").query({platform: "web", version: 50});
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe("required");
+    expect(res.body.message).toBe(
+      "This version is no longer supported. Please update to continue."
+    );
+  });
+
   it("version equal to required returns warning not required", async () => {
     await VersionConfig.create({
       webRequiredVersion: 100,
@@ -163,4 +202,46 @@ describe("VersionCheckPlugin", () => {
     expect(res.status).toBe(200);
     expect(res.body.status).toBe("warning");
   });
+
+  it("uses default messages when warningMessage/requiredMessage are not set", async () => {
+    await VersionConfig.create({
+      webRequiredVersion: 100,
+      webWarningVersion: 200,
+    });
+
+    const warningRes = await app.get("/version-check").query({platform: "web", version: 150});
+    expect(warningRes.body.status).toBe("warning");
+    expect(warningRes.body.message).toBe(
+      "A new version is available. Please update for the best experience."
+    );
+
+    const requiredRes = await app.get("/version-check").query({platform: "web", version: 50});
+    expect(requiredRes.body.status).toBe("required");
+    expect(requiredRes.body.message).toBe(
+      "This version is no longer supported. Please update to continue."
+    );
+  });
+
+  it("handles numeric version parameter", async () => {
+    const res = await app.get("/version-check?version=50&platform=web");
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("VersionCheckPlugin direct usage", () => {
+  it("can be instantiated and register called directly on an express app", async () => {
+    const express = require("express");
+    const plugin = new VersionCheckPlugin();
+    expect(plugin).toBeDefined();
+    expect(plugin).toBeInstanceOf(VersionCheckPlugin);
+    expect(typeof plugin.register).toBe("function");
+
+    const expressApp = express();
+    plugin.register(expressApp);
+
+    const testApp = supertest(expressApp);
+    const res = await testApp.get("/version-check");
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe("ok");
+  });
 });

package/src/betterAuthSetup.ts

@@ -12,6 +12,7 @@ import type {Application, NextFunction, Request, Response} from "express";
 import mongoose from "mongoose";
 import type {UserModel} from "./auth";
 import type {BetterAuthConfig, BetterAuthSessionData, BetterAuthUser} from "./betterAuth";
+import {APIError} from "./errors";
 import {logger} from "./logger";
 import {findOneOrNoneFor} from "./plugins";
 import {updateRequestContextFromRequest} from "./requestContext";
@@ -44,12 +45,18 @@ export const createBetterAuth = (options: CreateBetterAuthOptions): BetterAuthIn
 
   const secret = config.secret || process.env.BETTER_AUTH_SECRET;
   if (!secret) {
-    throw new Error("BETTER_AUTH_SECRET must be set in env or config.secret must be provided.");
+    throw new APIError({
+      status: 500,
+      title: "BETTER_AUTH_SECRET must be set in env or config.secret must be provided.",
+    });
   }
 
   const baseURL = config.baseURL || process.env.BETTER_AUTH_URL;
   if (!baseURL) {
-    throw new Error("BETTER_AUTH_URL must be set in env or config.baseURL must be provided.");
+    throw new APIError({
+      status: 500,
+      title: "BETTER_AUTH_URL must be set in env or config.baseURL must be provided.",
+    });
   }
 
   const basePath = config.basePath ?? "/api/auth";
@@ -253,7 +260,10 @@ export const getMongoClientFromMongoose = (): MongoClientLike => {
   const connection = mongoose.connection;
   const client = (connection as unknown as {client?: MongoClientLike}).client;
   if (!client) {
-    throw new Error("Mongoose is not connected. Ensure MongoDB connection is established first.");
+    throw new APIError({
+      status: 500,
+      title: "Mongoose is not connected. Ensure MongoDB connection is established first.",
+    });
   }
   return client;
 };

package/src/config.ts

@@ -21,6 +21,8 @@
  * `envConfigurationPlugin` provides a drop-in Mongoose schema integration.
  */
 
+import {APIError} from "./errors";
+
 const overrides = new Map<string, string | undefined>();
 
 let cachedEnv: Record<string, string> | null = null;
@@ -46,7 +48,7 @@ const REGISTRY: Record<string, ConfigRegistration> = Object.create(null);
  */
 const register = (key: string, registration: ConfigRegistration = {}): void => {
   if (REGISTRY[key]) {
-    throw new Error(`Config key "${key}" registered more than once`);
+    throw new APIError({status: 500, title: `Config key "${key}" registered more than once`});
   }
   REGISTRY[key] = registration;
 };
@@ -88,7 +90,11 @@ const getNumber = (key: string): number | undefined => {
   // whereas parseFloat would silently truncate to 5000.
   const parsed = Number(raw);
   if (!Number.isFinite(parsed)) {
-    throw new Error(`Config key "${key}" is not a valid number: ${JSON.stringify(raw)}`);
+    throw new APIError({
+      error: new Error(`Config key "${key}" is not a valid number: ${JSON.stringify(raw)}`),
+      status: 500,
+      title: `Config key "${key}" is not a valid number`,
+    });
   }
   return parsed;
 };
@@ -115,7 +121,11 @@ const getJSON = <T = unknown>(key: string): T | undefined => {
   try {
     return JSON.parse(raw) as T;
   } catch (error) {
-    throw new Error(`Config key "${key}" is not valid JSON: ${(error as Error).message}`);
+    throw new APIError({
+      error: new Error(`Config key "${key}" is not valid JSON: ${(error as Error).message}`),
+      status: 500,
+      title: `Config key "${key}" is not valid JSON`,
+    });
   }
 };
 

package/src/errors.ts

@@ -136,26 +136,32 @@ 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});
 };

package/src/example.ts

@@ -48,6 +48,9 @@ const userSchema = new Schema<User>(
 // 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);
 

package/src/expressServer.test.ts

@@ -770,6 +770,182 @@ describe("expressServer", () => {
 
       expect(func).toHaveBeenCalled();
     });
+
+    it("fires warning timeout callback when script is slow", async () => {
+      // terminateTimeout = 0.3s → warnTime = 150ms, closeTime = 300ms
+      // The func takes 200ms, so the warn callback fires at 150ms,
+      // but func completes at 200ms before the terminate callback at 300ms.
+      // afterEach clears the terminate timer.
+      const func = mock(
+        () => new Promise<string>((resolve) => originalSetTimeout(() => resolve("done"), 200))
+      );
+      try {
+        await wrapScript(func, {terminateTimeout: 0.3});
+      } catch {
+        // process.exit(0) throws
+      }
+      expect(process.exit).toHaveBeenCalledWith(0);
+    });
+  });
+
+  describe("setupServer with listen (skipListen false)", () => {
+    const originalEnv = process.env;
+
+    beforeEach(() => {
+      process.env = {
+        ...originalEnv,
+        PORT: "0", // Use port 0 to let OS assign a random free port
+        REFRESH_TOKEN_SECRET: "test-refresh-secret",
+        SESSION_SECRET: "test-session-secret",
+        TOKEN_EXPIRES_IN: "1h",
+        TOKEN_ISSUER: "test-issuer",
+        TOKEN_SECRET: "test-secret",
+      };
+    });
+
+    afterEach(() => {
+      process.env = originalEnv;
+    });
+
+    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;
+      // biome-ignore lint/suspicious/noExplicitAny: mocking Express internals requires type escape
+      express.default.application.listen = mock(function (this: unknown, ...args: unknown[]) {
+        const cb = args.find((a: unknown) => typeof a === "function") as (() => void) | undefined;
+        if (cb) {
+          cb();
+        }
+        return this;
+      }) as unknown as typeof originalListen;
+      try {
+        const app = setupServer({
+          addRoutes,
+          skipListen: false,
+          userModel: UserModel as any,
+        });
+        expect(app).toBeDefined();
+      } finally {
+        express.default.application.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 originalExit = process.exit;
+      process.exit = (() => {}) as unknown as typeof process.exit;
+      try {
+        setupServer({
+          addRoutes,
+          skipListen: false,
+          userModel: UserModel as any,
+        });
+      } catch {
+        // May throw
+      }
+      process.exit = originalExit;
+    });
+  });
+
+  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", () => {

package/src/realtime/changeStreamWatcher.ts

@@ -20,6 +20,7 @@ type WatchedChange = Extract<
 >;
 
 import type {User} from "../auth";
+import {APIError} from "../errors";
 import {logger} from "../logger";
 import {checkPermissions} from "../permissions";
 import {matchesQuery} from "./queryMatcher";
@@ -402,7 +403,10 @@ export const startChangeStreamWatcher = (
 
     const nativeDb = mongoose.connection.db;
     if (!nativeDb) {
-      throw new Error("MongoDB connection not available for change stream");
+      throw new APIError({
+        status: 500,
+        title: "MongoDB connection not available for change stream",
+      });
     }
 
     const options: ChangeStreamOptions = {
@@ -417,7 +421,7 @@ export const startChangeStreamWatcher = (
     changeWatcher = nativeDb.watch(pipeline, options);
 
     if (!changeWatcher) {
-      throw new Error("Failed to create change stream watcher");
+      throw new APIError({status: 500, title: "Failed to create change stream watcher"});
     }
 
     changeWatcher.on("change", async (rawChange: ChangeStreamDocument) => {