@bymax-one/nest-logger 1.3.1 → 1.4.1

package/dist/server/index.d.cts

@@ -572,6 +572,7 @@ declare const RESERVED_LOG_KEYS: Readonly<{
     readonly HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED";
     readonly HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED";
     readonly HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED";
+    readonly HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR";
     readonly METHOD_EXECUTION: "METHOD_EXECUTION";
     readonly METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION";
     readonly LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED";
@@ -878,8 +879,21 @@ declare class LogContextService {
      * Run `callback` inside a fresh context scope. Every log emitted
      * synchronously or asynchronously within the callback inherits `context`.
      *
+     * **A nested `run()` REPLACES the enclosing context, it does not extend it.**
+     * The scope starts from `context` alone, so a field an outer scope had set —
+     * a `tenantId` resolved at the edge, say — is absent for the whole inner
+     * scope: nothing throws, `get()` simply returns `undefined`, and the field is
+     * missing from every entry the callback emits. Reach for {@link runMerged}
+     * when the inner scope should extend the outer one.
+     *
+     * Replacement is the deliberate default because the opposite leaks: a
+     * background job started inside a request scope would silently inherit the
+     * caller's `userId` and attribute its entries to a user who never triggered
+     * it. A missing field is visibly missing; an inherited one is wrong while
+     * looking right.
+     *
      * @typeParam T - Return type of the callback.
-     * @param context - Initial context bag for the scope.
+     * @param context - Initial context bag for the scope. Becomes the WHOLE scope.
      * @param callback - Function executed within the scope.
      * @returns Whatever `callback` returns.
      * @example
@@ -888,6 +902,32 @@ declare class LogContextService {
      *   })
      */
     run<T>(context: LogContext$1, callback: () => T): T;
+    /**
+     * Run `callback` inside a scope that EXTENDS the enclosing one: the active
+     * context's fields are carried in, and `context` overrides them key by key.
+     *
+     * The explicit counterpart to {@link run}'s replacement semantics, for the
+     * case where an inner scope is genuinely a refinement of the outer — adding a
+     * `userId` once authentication resolved it, without having to restate the
+     * `requestId` the middleware already set.
+     *
+     * Outside any scope there is nothing to merge and this behaves exactly like
+     * {@link run}. Writes inside the new scope never reach the enclosing one: the
+     * merge produces a fresh object, so the outer context is intact after the
+     * callback returns.
+     *
+     * @typeParam T - Return type of the callback.
+     * @param context - Fields to add or override on top of the active context.
+     * @param callback - Function executed within the merged scope.
+     * @returns Whatever `callback` returns.
+     * @example
+     *   logContext.run({ requestId: 'r_1' }, () => {
+     *     logContext.runMerged({ userId: 'u_1' }, () => {
+     *       logContext.get('requestId') // 'r_1' — carried in from the outer scope
+     *     })
+     *   })
+     */
+    runMerged<T>(context: LogContext$1, callback: () => T): T;
     /**
      * Read the active context, or `undefined` when called outside any scope.
      *
@@ -1294,6 +1334,76 @@ declare class HttpLoggingInterceptor implements NestInterceptor {
     private logError;
 }
 
+/**
+ * `applyAccessLog` consumer helper — the access log mounted AHEAD of the body
+ * parser, from `main.ts`.
+ *
+ * Layer: server/middlewares — the bootstrap-time counterpart to
+ * {@link applyRequestIdMiddleware}. Both mount the same two middlewares in the
+ * same order; they differ only in WHERE the mount lands in the Express stack,
+ * and that difference decides an entire class of requests.
+ *
+ * NestJS registers the body parser one line before it registers module
+ * middleware (`@nestjs/core/nest-application.js`: `registerParserMiddleware()`
+ * then `registerModules()`), and Express dispatches in registration order. So
+ * anything wired through `configure(consumer)` sits downstream of the parser,
+ * and a body the parser rejects — `next(err)` skips every remaining non-error
+ * handler — reaches no module middleware, no guard, no interceptor and no
+ * handler. Measured: a `POST` with truncated JSON produced no access log at all.
+ *
+ * `INestApplication.use()` delegates straight to the HTTP adapter, so a handler
+ * mounted here lands in the Express stack at call time — the same reason `helmet`
+ * and `cookie-parser` are mounted this way.
+ *
+ * The boundary is **`init()`**, not `listen()`. `listen()` merely triggers `init()`
+ * when it has not run yet, so "before `listen()`" is true only for the usual
+ * bootstrap that never calls `init()` itself. A serverless handler or a test that
+ * does `await app.init()` and mounts afterwards is already behind the parser.
+ *
+ * {@link HttpAccessLogMiddleware} needed no new logic to work there: it emits
+ * from the response's `'close'` event, so it never depends on a route matching,
+ * a handler running or a filter catching anything.
+ *
+ * Full rationale, and the table of what each wiring emits today, is in the
+ * README under "Requests rejected before routing".
+ */
+
+/**
+ * Mount the correlation scope and the HTTP access log ahead of the body parser.
+ *
+ * Call AFTER `NestFactory.create()` and BEFORE the application initializes —
+ * that is, before `app.init()`, or before `app.listen()` in the usual bootstrap
+ * that never calls `init()` directly.
+ *
+ * **`init()` is the real deadline, and `listen()` is only where most bootstraps
+ * meet it.** A serverless entry point or an integration test typically does
+ * `await app.init()` and then wires things up; mounting there still mounts, but
+ * BEHIND the parser, which forfeits the entire reason to use this helper — the
+ * parser-rejected request goes unlogged exactly as before, with no error to say
+ * so. The mount is not rejected when it is late because NestJS exposes no
+ * supported signal for "already initialized" — `isInitialized` is private, and
+ * reaching into the adapter's router to guess would break on a NestJS patch
+ * release while claiming to be a safety net.
+ *
+ * The ordering is the one thing to get right here, so it is worth a glance at
+ * the call site rather than trust: mount it immediately after `NestFactory.create()`.
+ *
+ * Requires `http.isEnabled` for the access log itself; with HTTP logging off the
+ * correlation scope is still opened (matching `applyRequestIdMiddleware`) and no
+ * access entries are written.
+ *
+ * @param app - The Nest application returned by `NestFactory.create()`.
+ * @throws Error When `BymaxLoggerModule` was not imported.
+ * @example
+ *   import { BymaxLoggerModule, applyAccessLog } from '@bymax-one/nest-logger'
+ *
+ *   const app = await NestFactory.create(AppModule, { bufferLogs: true })
+ *   BymaxLoggerModule.useNestLogger(app)
+ *   applyAccessLog(app) // before init(): listen() triggers it if you have not
+ *   await app.listen(3000)
+ */
+declare function applyAccessLog(app: INestApplication): void;
+
 /**
  * `applyRequestIdMiddleware` consumer helper.
  *
@@ -1419,6 +1529,47 @@ interface LoggableResponse {
 /** Continuation passed to a middleware; invoked with no arguments here. */
 type NextHandler = () => void;
 
+/**
+ * Records the HTTP access log for every request, including the ones no
+ * interceptor can observe.
+ */
+declare class HttpAccessLogMiddleware implements NestMiddleware {
+    private readonly logger;
+    private readonly logContext;
+    /** Whether HTTP logging is on at all (`http.isEnabled`). */
+    private readonly isEnabled;
+    /** Path patterns that bypass HTTP logging entirely (health checks, metrics). */
+    private readonly excludePaths;
+    /**
+     * @param logger - The structured logger the access entries are written to.
+     *   Injected by token explicitly: the package is bundled without
+     *   `emitDecoratorMetadata`, so implicit class-type injection would not resolve.
+     * @param options - Resolved module options (read for `http.excludePaths`).
+     */
+    constructor(logger: PinoLoggerService, logContext: LogContextService, options: ResolvedBymaxLoggerModuleOptions);
+    /**
+     * Emit START, arm the terminal entry on `'close'`, and continue the chain.
+     *
+     * @param req - The incoming request (Express satisfies the contract).
+     * @param res - The outgoing response (Express satisfies the contract).
+     * @param next - The next handler in the chain.
+     */
+    use(req: LoggableRequest, res: LoggableResponse, next: NextHandler): void;
+    /**
+     * Emit the terminal entry for a closed request.
+     *
+     * `userId` is read HERE rather than at START because authentication runs in a
+     * guard, downstream of this middleware — at START there is no principal yet.
+     *
+     * @param req - The request, carrying any error the interceptor recorded.
+     * @param res - The closed response.
+     * @param method - The HTTP method.
+     * @param url - The normalized request URL.
+     * @param duration - Elapsed milliseconds.
+     */
+    private logTerminal;
+}
+
 /**
  * Reads (or generates) the correlation id and starts the per-request log
  * context scope.
@@ -1447,13 +1598,156 @@ declare class RequestIdMiddleware implements NestMiddleware {
     constructor(logContext: LogContextService, options: ResolvedBymaxLoggerModuleOptions);
     /**
      * Echo or mint the `x-request-id`, expose it on the response, and run the
-     * remainder of the request inside a fresh log-context scope.
+     * remainder of the request inside its own log-context scope.
+     *
+     * Idempotent: mounting this middleware twice on the same request mints one id,
+     * not two. The request gets its OWN store, started from the enclosing scope's
+     * correlation fields — see {@link INHERITABLE_CONTEXT_KEYS} — and nothing
+     * else, because no other field can be known to belong to this request.
+     *
+     * An enclosing scope's `requestId` is never adopted and never echoed: adoption
+     * reads a value this middleware recorded on the REQUEST, which a scope opened
+     * elsewhere does not have. What the two generation modes do with one, measured
+     * on two requests sharing a long-lived enclosing scope:
+     *
+     *   - `shouldGenerateRequestId: true` (default) — each request mints its own
+     *     id, the two requests differ, and the enclosing value reaches neither the
+     *     header nor the entries.
+     *   - `shouldGenerateRequestId: false` with no inbound header — nothing is
+     *     minted, so the request scope inherits the enclosing `requestId` and every
+     *     request inside that scope logs under it. No header is exposed. That is
+     *     the consumer's own scope being inherited, not correlation being reused,
+     *     and it is the configuration that says the gateway owns the id.
      *
      * @param req - The incoming request (Express satisfies the contract).
      * @param res - The outgoing response (Express satisfies the contract).
      * @param next - The next handler in the chain.
      */
     use(req: LoggableRequest, res: LoggableResponse, next: NextHandler): void;
+    /**
+     * The enclosing scope's fields that a request scope may start from.
+     *
+     * Plain `run()` would discard everything the caller had set and a plain merge
+     * would carry identity across requests; {@link INHERITABLE_CONTEXT_KEYS} is
+     * the middle a request scope actually needs.
+     *
+     * @returns A fresh bag, never the enclosing store itself, so writes inside the
+     *   request never reach the scope that opened it.
+     */
+    private inheritableContext;
+    /**
+     * Second mount on a request that already carries a correlation id: echo the id
+     * onto the response and fill in a tenant the scope does not have yet, without
+     * opening another scope.
+     *
+     * Nothing is minted and nothing already set is overwritten, so a third mount —
+     * or a thirtieth — changes nothing. The response header is written on every
+     * pass because the enclosing scope may have been opened by consumer code that
+     * never exposed it.
+     *
+     * @param requestId - The id already in scope, which wins.
+     * @param req - The incoming request, read for the tenant header.
+     * @param res - The outgoing response, where the effective id is exposed.
+     */
+    private adoptExistingScope;
+    /**
+     * The correlation id for this request: the inbound header when acceptable,
+     * otherwise a fresh UUID — or nothing at all when `shouldGenerateRequestId` is
+     * off and the caller sent none, which leaves correlation to the upstream
+     * gateway.
+     *
+     * @param req - The incoming request.
+     * @returns The id, or `undefined` when none is available and none is minted.
+     */
+    private resolveRequestId;
+    /**
+     * The tenant id carried by the configured header, when it is acceptable.
+     *
+     * Never minted: a tenant is an assertion about who the request belongs to, and
+     * inventing one would be a fabricated claim rather than a correlation aid.
+     *
+     * @param req - The incoming request.
+     * @returns The tenant id, or `undefined`.
+     */
+    private resolveTenantId;
+}
+
+/**
+ * Structural mirror of `@bymax-one/nest-core`'s unexpected-error sink contract.
+ *
+ * Layer: server/interfaces — the shapes `PinoUnexpectedErrorSink` implements.
+ * Declared here, not imported: this package has no dependency on nest-core and
+ * does not take one. TypeScript compares the two contracts by shape, so
+ * `PinoUnexpectedErrorSink` binds to nest-core's `BYMAX_UNEXPECTED_ERROR_SINK`
+ * token as long as these shapes stay compatible with nest-core's.
+ */
+/**
+ * What nest-core hands the sink for one unexpected (non-`HttpException`) error.
+ *
+ * It never carries the request body, headers, query string or raw URL.
+ */
+interface UnexpectedErrorReport {
+    /** The original thrown value, by identity — not necessarily an `Error`. */
+    readonly error: unknown;
+    /** HTTP method, e.g. `'GET'`. */
+    readonly method: string;
+    /**
+     * The matched route template, e.g. `'/invoices/:id'`, or `'<unmatched>'` when
+     * the error was raised before routing. Never the raw URL.
+     */
+    readonly route: string;
+    /** The request's correlation id. The key is absent when none resolved. */
+    readonly correlationId?: string;
+    /** The active OpenTelemetry trace id. The key is absent when nothing is recording. */
+    readonly traceId?: string;
+}
+/**
+ * A receiver for unexpected errors, called synchronously by nest-core's
+ * exception filter before the response is written.
+ */
+interface IUnexpectedErrorSink {
+    /**
+     * Record one unexpected error. Must be cheap: it runs on the response path.
+     *
+     * @param report - The error and its request coordinates.
+     */
+    record(report: UnexpectedErrorReport): void;
+}
+
+/**
+ * Writes each unexpected error nest-core reports as one `HTTP_UNEXPECTED_ERROR`
+ * entry at `error` level.
+ */
+declare class PinoUnexpectedErrorSink implements IUnexpectedErrorSink {
+    private readonly logger;
+    /**
+     * @param logger - The structured logger the entry is written to. Injected by
+     *   token explicitly: the package is bundled without `emitDecoratorMetadata`,
+     *   so implicit class-type injection would not resolve.
+     */
+    constructor(logger: PinoLoggerService);
+    /**
+     * Write one `error` entry for an unexpected error. Never throws.
+     *
+     * The entry carries `err` (name, message, scrubbed stack, cause chain and own
+     * fields, through the configured `err` serializer), `method`, `route` and,
+     * when present, `correlationId`. It deliberately carries nothing else from
+     * the request: the report has no body, headers or query to leak, and this
+     * method adds none.
+     *
+     * `report.traceId` is not written. The trace mixin already stamps the active
+     * span's trace id under the configured `otel.traceIdField` — the same span
+     * nest-core read it from — and writing it here would override that field and
+     * ignore `otel.shouldAutoInjectTraceContext: false`.
+     *
+     * @param report - The error and its request coordinates, from nest-core.
+     * @example
+     *   sink.record({ error: new TypeError('x is undefined'), method: 'GET', route: '/invoices/:id', correlationId: 'req-1' })
+     *   // → { level: 'error', logKey: 'HTTP_UNEXPECTED_ERROR', msg: 'x is undefined',
+     *   //     err: { type: 'TypeError', message: 'x is undefined', stack: '…' },
+     *   //     method: 'GET', route: '/invoices/:id', correlationId: 'req-1' }
+     */
+    record(report: UnexpectedErrorReport): void;
 }
 
 /**
@@ -1650,4 +1944,4 @@ interface LogEntry {
  */
 declare const LOG_KEYS_CONVENTION_REGEX: RegExp;
 
-export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, type PrettyViewOptions, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, applyRequestIdMiddleware };
+export { BymaxLoggerModule, type BymaxLoggerModuleAsyncOptions, type BymaxLoggerModuleOptions, type BymaxLoggerModuleOptionsFactory, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, type EmittedDeploymentResource, type EmittedServiceResource, HttpAccessLogMiddleware, HttpExceptionFilter, HttpLoggingInterceptor, type HttpOptions, type ILogDestination, type IUnexpectedErrorSink, type IncomingHeaders, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, type LogContext$1 as LogContextBag, LogContextService, type LogEntry, type LogLevel, LogPerformance, type LoggableRequest, type LoggableResponse, type NextHandler, type OtelOptions, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PinoUnexpectedErrorSink, PrettyDevDestination, type PrettyViewOptions, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, type ReservedLogKey, type ResolvedBymaxLoggerModuleOptions, type ResolvedServiceMetadata, type ServiceMetadata, type UnexpectedErrorReport, applyAccessLog, applyRequestIdMiddleware };