@bymax-one/nest-logger 1.3.0 → 1.4.0

package/dist/server/index.d.cts

@@ -260,6 +260,21 @@ interface HttpOptions {
      * Paths that bypass HTTP logging (health checks, metrics). Defaults:
      * `/health`, `/metrics`.
      *
+     * The defaults do NOT cover `@bymax-one/nest-core`, and that is the common case
+     * worth knowing before you rely on them. It serves liveness and readiness at
+     * `/health/live` and `/health/ready`, and no bare `/health` at all, so
+     * `/^\/health$/` excludes a route that does not exist while both probes are
+     * logged. Measured on one deployment: 8272 of 8274 HTTP entries were the
+     * liveness probe. Set `excludePaths` yourself when wiring the two together —
+     * `[/^\/health\/(live|ready)$/, /^\/metrics$/]` matches the stock layout.
+     *
+     * The defaults are not widened to include those subpaths because both prefixes
+     * are CONFIGURABLE there (`DEFAULT_HEALTH_PATH`, `DEFAULT_METRICS_PATH`): any
+     * default naming specific subpaths would be less wrong rather than correct, and
+     * a prefix pattern would silently swallow a consumer's own `/health/*` route
+     * that they did want logged. Excluding a path is a decision about which requests
+     * disappear from the record, so it stays explicit.
+     *
      * SECURITY: each pattern is `.test()`-ed against the (attacker-controllable)
      * request path on every request. Supply only anchored, linear-time regexes
      * (e.g. `/^\/health$/`); a pattern with catastrophic backtracking would turn a
@@ -863,8 +878,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
@@ -873,6 +901,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.
      *
@@ -1279,6 +1333,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.
  *
@@ -1404,6 +1528,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.
@@ -1432,13 +1597,78 @@ 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;
 }
 
 /**
@@ -1635,4 +1865,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 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, applyAccessLog, applyRequestIdMiddleware };

package/dist/server/index.d.ts

@@ -260,6 +260,21 @@ interface HttpOptions {
      * Paths that bypass HTTP logging (health checks, metrics). Defaults:
      * `/health`, `/metrics`.
      *
+     * The defaults do NOT cover `@bymax-one/nest-core`, and that is the common case
+     * worth knowing before you rely on them. It serves liveness and readiness at
+     * `/health/live` and `/health/ready`, and no bare `/health` at all, so
+     * `/^\/health$/` excludes a route that does not exist while both probes are
+     * logged. Measured on one deployment: 8272 of 8274 HTTP entries were the
+     * liveness probe. Set `excludePaths` yourself when wiring the two together —
+     * `[/^\/health\/(live|ready)$/, /^\/metrics$/]` matches the stock layout.
+     *
+     * The defaults are not widened to include those subpaths because both prefixes
+     * are CONFIGURABLE there (`DEFAULT_HEALTH_PATH`, `DEFAULT_METRICS_PATH`): any
+     * default naming specific subpaths would be less wrong rather than correct, and
+     * a prefix pattern would silently swallow a consumer's own `/health/*` route
+     * that they did want logged. Excluding a path is a decision about which requests
+     * disappear from the record, so it stays explicit.
+     *
      * SECURITY: each pattern is `.test()`-ed against the (attacker-controllable)
      * request path on every request. Supply only anchored, linear-time regexes
      * (e.g. `/^\/health$/`); a pattern with catastrophic backtracking would turn a
@@ -863,8 +878,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
@@ -873,6 +901,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.
      *
@@ -1279,6 +1333,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.
  *
@@ -1404,6 +1528,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.
@@ -1432,13 +1597,78 @@ 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;
 }
 
 /**
@@ -1635,4 +1865,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 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, applyAccessLog, applyRequestIdMiddleware };