@terreno/api 0.20.1 → 0.21.0

package/dist/githubAuth.test.js

@@ -79,10 +79,10 @@ var passport_1 = __importDefault(require("passport"));
 var passport_local_mongoose_1 = __importDefault(require("passport-local-mongoose"));
 var supertest_1 = __importDefault(require("supertest"));
 var auth_1 = require("./auth");
-var expressServer_1 = require("./expressServer");
 var githubAuth_1 = require("./githubAuth");
 var logger_1 = require("./logger");
 var plugins_1 = require("./plugins");
+var terrenoApp_1 = require("./terrenoApp");
 var fakeGithubOutcome = { type: "redirect", url: "http://github.com/mock" };
 var installFakeGithubStrategy = function () {
     var strategy = {
@@ -190,8 +190,8 @@ var connectDb = function () { return __awaiter(void 0, void 0, void 0, function
                     return [4 /*yield*/, testUser.save()];
                 case 5:
                     _a.sent();
-                    app = (0, expressServer_1.setupServer)({
-                        addRoutes: addRoutes,
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: addRoutes,
                         githubAuth: {
                             allowAccountLinking: true,
                             callbackURL: "http://localhost:9000/auth/github/callback",
@@ -200,7 +200,7 @@ var connectDb = function () { return __awaiter(void 0, void 0, void 0, function
                         },
                         skipListen: true,
                         userModel: GitHubTestUserModel,
-                    });
+                    }).build();
                     agent = supertest_1.default.agent(app);
                     return [2 /*return*/];
             }
@@ -338,11 +338,11 @@ var connectDb = function () { return __awaiter(void 0, void 0, void 0, function
                 case 2:
                     _a.sent();
                     // Setup server WITHOUT GitHub auth
-                    app = (0, expressServer_1.setupServer)({
-                        addRoutes: addRoutes,
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: addRoutes,
                         skipListen: true,
                         userModel: GitHubTestUserModel,
-                    });
+                    }).build();
                     agent = supertest_1.default.agent(app);
                     return [2 /*return*/];
             }
@@ -665,8 +665,8 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                     return [4 /*yield*/, GitHubTestUserModel.deleteMany({})];
                 case 2:
                     _a.sent();
-                    app = (0, expressServer_1.setupServer)({
-                        addRoutes: addRoutes,
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: addRoutes,
                         githubAuth: {
                             allowAccountLinking: true,
                             callbackURL: "http://localhost:9000/auth/github/callback",
@@ -675,7 +675,7 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                         },
                         skipListen: true,
                         userModel: GitHubTestUserModel,
-                    });
+                    }).build();
                     agent = supertest_1.default.agent(app);
                     return [2 /*return*/];
             }
@@ -767,10 +767,10 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                     return [4 /*yield*/, GitHubTestUserModel.deleteMany({})];
                 case 2:
                     _a.sent();
-                    app = (0, expressServer_1.setupServer)({
-                        addMiddleware: function (a) {
+                    app = new terrenoApp_1.TerrenoApp({
+                        beforeJsonSetup: function (a) {
                             // The handler reads (req as unknown as {session?: {returnTo?: string}}).session?.returnTo.
-                            // setupServer does not install express-session, so prime a fake session from a request
+                            // TerrenoApp does not install express-session, so prime a fake session from a request
                             // header for tests.
                             a.use(function (req, _res, next) {
                                 var headerReturnTo = req.headers["x-mock-return-to"];
@@ -780,7 +780,7 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                                 next();
                             });
                         },
-                        addRoutes: addRoutes,
+                        configureApp: addRoutes,
                         githubAuth: {
                             allowAccountLinking: true,
                             callbackURL: "http://localhost:9000/auth/github/callback",
@@ -789,8 +789,8 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                         },
                         skipListen: true,
                         userModel: GitHubTestUserModel,
-                    });
-                    // Swap the github strategy with our fake after setupServer registered it.
+                    }).build();
+                    // Swap the github strategy with our fake after TerrenoApp registered it.
                     installFakeGithubStrategy();
                     agent = supertest_1.default.agent(app);
                     return [2 /*return*/];
@@ -910,8 +910,8 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                     return [4 /*yield*/, GitHubTestUserModel.deleteMany({})];
                 case 2:
                     _a.sent();
-                    app = (0, expressServer_1.setupServer)({
-                        addRoutes: addRoutes,
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: addRoutes,
                         githubAuth: {
                             allowAccountLinking: true,
                             callbackURL: "http://localhost:9000/auth/github/callback",
@@ -920,7 +920,7 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                         },
                         skipListen: true,
                         userModel: GitHubTestUserModel,
-                    });
+                    }).build();
                     installFakeGithubStrategy();
                     agent = supertest_1.default.agent(app);
                     return [2 /*return*/];
@@ -983,8 +983,8 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                     return [4 /*yield*/, GitHubTestUserModel.deleteMany({})];
                 case 2:
                     _a.sent();
-                    app = (0, expressServer_1.setupServer)({
-                        addRoutes: addRoutes,
+                    app = new terrenoApp_1.TerrenoApp({
+                        configureApp: addRoutes,
                         githubAuth: {
                             allowAccountLinking: true,
                             callbackURL: "http://localhost:9000/auth/github/callback",
@@ -993,7 +993,7 @@ var invokeGitHubVerify = function (req, accessToken, refreshToken, profile) {
                         },
                         skipListen: true,
                         userModel: GitHubTestUserModel,
-                    });
+                    }).build();
                     installFakeGithubStrategy();
                     agent = supertest_1.default.agent(app);
                     return [2 /*return*/];

package/dist/logger.d.ts

@@ -1,5 +1,47 @@
 import winston from "winston";
+/** Always attached to Winston metadata while a request/job ALS scope is active. */
+export interface TerrenoRequestLogEntry {
+    requestId: string;
+    userId: string | null;
+}
+export interface LogContextFields {
+    jobId?: string;
+    requestId?: string;
+    sessionId?: string;
+    terrenoLabels?: Record<string, string>;
+    terrenoLogPrefix?: string;
+    traceId?: string;
+    userId?: string;
+}
+/**
+ * Builds the ` key=value ...` suffix appended to console/file log lines after the message.
+ * Request-scoped fields come from AsyncLocalStorage via Winston metadata; `terrenoLabels` and
+ * `terrenoLogPrefix` come from {@link createScopedLogger}. Nested `terrenoRequestLog`
+ * (`requestId` + `userId` including `null` when anonymous) is attached on the Winston info
+ * object for structured transports only, not repeated in this suffix.
+ */
+export declare const formatLogContextSuffix: (fields: LogContextFields) => string;
 export declare const winstonLogger: winston.Logger;
+/**
+ * Global application logger. Each method writes through Winston (console/file transports) and, when
+ * `USE_SENTRY_LOGGING=true`, mirrors the line to Sentry with the active request context attached.
+ *
+ * Prefer {@link createScopedLogger} when a workflow spans multiple log lines that should share a
+ * prefix or labels.
+ *
+ * @example
+ * ```typescript
+ * import {logger} from "@terreno/api";
+ *
+ * logger.info("Server started", {port: 4000});
+ * logger.warn("Slow query", {ms: 500});
+ * logger.error("Failed to process", {error});
+ * logger.debug("Request details", {body: req.body});
+ *
+ * // Convenient `.catch` handler for promises – logs and captures the exception.
+ * await chargeCard(id).catch(logger.catch);
+ * ```
+ */
 export declare const logger: {
     catch: (e: unknown) => void;
     debug: (msg: string, ...args: unknown[]) => void;
@@ -7,6 +49,116 @@ export declare const logger: {
     info: (msg: string, ...args: unknown[]) => void;
     warn: (msg: string, ...args: unknown[]) => void;
 };
+/**
+ * Logger-shaped object returned by {@link createScopedLogger} and {@link createFeatureFlaggedLogger}.
+ * Method signatures match the global {@link logger} so the three are interchangeable at call sites.
+ */
+export interface ScopedLogger {
+    /** Log a caught exception. Suitable as a promise handler: `promise.catch(log.catch)`. */
+    catch: (e: unknown) => void;
+    debug: (msg: string, ...args: unknown[]) => void;
+    error: (msg: string, ...args: unknown[]) => void;
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+}
+export interface CreateScopedLoggerOptions {
+    /** Short, stable token prepended to every message (for grep and log Explorer text search). */
+    prefix?: string;
+    /**
+     * Workflow-specific dimensions merged into Winston metadata as `terrenoLabels` (plain-text
+     * suffix and structured jsonPayload on cloud transports). Avoid keys that collide with
+     * request context or scoped metadata: requestId, jobId, sessionId, userId, traceId, spanId,
+     * terrenoLogPrefix, terrenoRequestLog, terrenoLabels.
+     */
+    labels?: Record<string, string | number | boolean | undefined>;
+}
+/**
+ * Creates a {@link ScopedLogger} that prefixes every message and/or attaches stable `labels` to
+ * every line, so multi-step workflows are easy to group and search.
+ *
+ * - `prefix` is prepended to the human-readable message (easy grep / Log Explorer text search) and
+ *   also stored as the Winston metadata field `terrenoLogPrefix`.
+ * - `labels` are normalized to strings and stored as the Winston metadata field `terrenoLabels`.
+ *   They appear in the plain-text ` key=value` suffix (see {@link formatLogContextSuffix}) and as
+ *   discrete fields on structured transports such as `@google-cloud/logging-winston`.
+ *
+ * Both ride on a Winston **child logger**, so they merge with — and never overwrite — the
+ * request/job correlation fields that AsyncLocalStorage injects (`requestId`, `userId`,
+ * `terrenoRequestLog`, etc.). Avoid label keys that collide with those framework fields:
+ * `requestId`, `jobId`, `sessionId`, `userId`, `traceId`, `spanId`, `terrenoLogPrefix`,
+ * `terrenoRequestLog`, `terrenoLabels`.
+ *
+ * If both `prefix` and `labels` are empty, the global {@link logger} is returned unchanged.
+ *
+ * @param options - Optional `prefix` token and/or `labels` dimensions for this scope.
+ * @returns A scoped logger sharing the same methods as the global {@link logger}.
+ * @see {@link createFeatureFlaggedLogger} to gate a scoped logger behind a feature flag.
+ *
+ * @example Reuse one instance for a whole workflow so every line shares identifiers
+ * ```typescript
+ * import {createScopedLogger} from "@terreno/api";
+ *
+ * const log = createScopedLogger({
+ *   prefix: "[InvoicePay]",
+ *   labels: {invoiceId: invoice._id.toString(), attempt: String(attemptNumber)},
+ * });
+ *
+ * log.info("Starting capture");        // -> "[InvoicePay] Starting capture invoiceId=... attempt=1 requestId=..."
+ * log.warn("Stripe rate limited, backing off");
+ * await capture(invoice).catch(log.catch);
+ * ```
+ */
+export declare const createScopedLogger: (options?: CreateScopedLoggerOptions) => ScopedLogger;
+export interface CreateFeatureFlaggedLoggerOptions {
+    /**
+     * When this returns true, log calls are forwarded to `target`. Invoked on every call so flags
+     * can flip without process restart (env, database-backed flags, `@terreno/feature-flags`, etc.).
+     */
+    isEnabled: () => boolean;
+    /** Defaults to global `logger`; pass `createScopedLogger({...})` for gated diagnostic blocks. */
+    target?: ScopedLogger;
+    /**
+     * When false (default), `catch` always forwards to `target` so `promise.catch(log.catch)` still
+     * records errors when the flag is off. Set true to gate `catch` the same as other levels.
+     */
+    gateCatch?: boolean;
+}
+/**
+ * Wraps a {@link ScopedLogger} so all `debug` / `info` / `warn` / `error` traffic is dropped while
+ * `isEnabled()` returns false. Use it to keep verbose diagnostics in the code but silent until a
+ * flag turns them on — no redeploy required.
+ *
+ * `isEnabled` is evaluated on **every** call, so it can read any feature-flag source: an
+ * environment variable, a cached/remote flag map, or a call into `@terreno/feature-flags` from your
+ * app. (`@terreno/api` deliberately does not import `@terreno/feature-flags` to avoid a package
+ * cycle — you supply the predicate.)
+ *
+ * @param options - The `isEnabled` predicate plus an optional `target` logger and `gateCatch`.
+ * @returns A scoped logger that forwards to `target` only while the flag is enabled.
+ * @see {@link createScopedLogger} for the usual `target`.
+ *
+ * @example Gate a scoped logger behind an env var (flips live, no restart)
+ * ```typescript
+ * import {createFeatureFlaggedLogger, createScopedLogger} from "@terreno/api";
+ *
+ * const jobLog = createFeatureFlaggedLogger({
+ *   isEnabled: () => process.env.JOB_TRACE_LOGS === "true",
+ *   target: createScopedLogger({prefix: "[Job]", labels: {jobName: "nightly-sync"}}),
+ * });
+ *
+ * jobLog.info("step 1"); // silent unless JOB_TRACE_LOGS=true
+ * ```
+ *
+ * @example Drive it from `@terreno/feature-flags` in app code
+ * ```typescript
+ * const debugLog = createFeatureFlaggedLogger({
+ *   isEnabled: () => flags.isEnabled("debug.billing"),
+ *   target: createScopedLogger({prefix: "[Billing]"}),
+ *   gateCatch: true, // also silence `catch` while the flag is off (default: false)
+ * });
+ * ```
+ */
+export declare const createFeatureFlaggedLogger: (options: CreateFeatureFlaggedLoggerOptions) => ScopedLogger;
 export interface LoggingOptions {
     level?: "debug" | "info" | "warn" | "error";
     transports?: winston.transport[];
@@ -19,5 +171,7 @@ export interface LoggingOptions {
     logSlowRequests?: boolean;
     logSlowRequestsReadMs?: number;
     logSlowRequestsWriteMs?: number;
+    /** When true, skips the dev JSONL file under `.terreno/logs/app.log`. */
+    disableTerrenoDevJsonlLog?: boolean;
 }
 export declare const setupLogging: (options?: LoggingOptions) => void;