@bymax-one/nest-logger 1.3.1 → 1.4.1

package/dist/server/index.mjs

@@ -182,6 +182,7 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED",
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
+  HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",
@@ -765,12 +766,26 @@ var HTTP_SERVER_ERROR_MIN = 500;
 var UNKNOWN_USER_AGENT = "unknown";
 var RECORDER_ACTIVE = /* @__PURE__ */ Symbol("bymax-one/nest-logger:recorder");
 var RECORDED_ERROR = /* @__PURE__ */ Symbol("bymax-one/nest-logger:error");
+var OWN_REQUEST_ID = /* @__PURE__ */ Symbol("bymax-one/nest-logger:request-id");
+var CORRELATION_OPENED = /* @__PURE__ */ Symbol("bymax-one/nest-logger:correlation");
 function markRecorderActive(req) {
   Reflect.set(req, RECORDER_ACTIVE, true);
 }
 function isRecorderActive(req) {
   return Reflect.get(req, RECORDER_ACTIVE) === true;
 }
+function markCorrelationOpened(req) {
+  Reflect.set(req, CORRELATION_OPENED, true);
+}
+function isCorrelationOpened(req) {
+  return Reflect.get(req, CORRELATION_OPENED) === true;
+}
+function markOwnRequestId(req, requestId) {
+  Reflect.set(req, OWN_REQUEST_ID, requestId);
+}
+function readOwnRequestId(req) {
+  return Reflect.get(req, OWN_REQUEST_ID);
+}
 function recordError(req, error) {
   Reflect.set(req, RECORDED_ERROR, { error });
 }
@@ -788,6 +803,16 @@ function readUserAgent(req) {
   return typeof raw === "string" ? raw : UNKNOWN_USER_AGENT;
 }
 
+// src/server/utils/matches-exclude-path.util.ts
+function matchesExcludePath(patterns, path2) {
+  return patterns.some((pattern) => {
+    if (pattern.global || pattern.sticky) {
+      pattern.lastIndex = 0;
+    }
+    return pattern.test(path2);
+  });
+}
+
 // src/server/interceptors/http-logging.interceptor.ts
 var HTTP_SUCCESS_MIN = 200;
 var HttpLoggingInterceptor = class {
@@ -809,7 +834,7 @@ var HttpLoggingInterceptor = class {
    * @returns `true` when the path matches a configured exclude pattern.
    */
   isExcluded(path2) {
-    return this.excludePaths.some((pattern) => pattern.test(path2));
+    return matchesExcludePath(this.excludePaths, path2);
   }
   /**
    * Emit the START entry, then attach success/redirect/error logging to the
@@ -2091,8 +2116,21 @@ var LogContextService = class {
    * 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
@@ -2103,6 +2141,35 @@ var LogContextService = class {
   run(context, callback) {
     return this.als.run(this.sanitizeContext(context), callback);
   }
+  /**
+   * 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(context, callback) {
+    const merged = { ...this.als.getStore(), ...this.sanitizeContext(context) };
+    return this.als.run(merged, callback);
+  }
   /**
    * Read the active context, or `undefined` when called outside any scope.
    *
@@ -2555,13 +2622,17 @@ var HttpAccessLogMiddleware = class {
    * @param next - The next handler in the chain.
    */
   use(req, res, next) {
+    if (isRecorderActive(req)) {
+      next();
+      return;
+    }
     if (!this.isEnabled) {
       next();
       return;
     }
     const target = req.originalUrl ?? req.url;
     const path2 = stripQueryString(target);
-    if (this.excludePaths.some((pattern) => pattern.test(path2))) {
+    if (matchesExcludePath(this.excludePaths, path2)) {
       next();
       return;
     }
@@ -2657,6 +2728,7 @@ HttpAccessLogMiddleware = __decorateClass([
 var REQUEST_ID_HEADER = "x-request-id";
 var MAX_CORRELATION_ID_LENGTH = 256;
 var CORRELATION_ID_CHARSET = /^[A-Za-z0-9._:/+=-]+$/;
+var INHERITABLE_CONTEXT_KEYS = ["requestId", "tenantId"];
 function isAcceptableHeaderValue(value) {
   return typeof value === "string" && value.length <= MAX_CORRELATION_ID_LENGTH && CORRELATION_ID_CHARSET.test(value);
 }
@@ -2675,27 +2747,128 @@ var RequestIdMiddleware = class {
   }
   /**
    * 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, res, next) {
-    const incoming = Reflect.get(req.headers, REQUEST_ID_HEADER);
-    const fromHeader = isAcceptableHeaderValue(incoming) ? incoming : void 0;
-    const requestId = fromHeader ?? (this.shouldGenerateRequestId ? randomUUID() : void 0);
-    const context = {};
+    if (isCorrelationOpened(req)) {
+      const ownRequestId = readOwnRequestId(req);
+      if (ownRequestId !== void 0) {
+        this.adoptExistingScope(ownRequestId, req, res);
+      }
+      next();
+      return;
+    }
+    markCorrelationOpened(req);
+    const context = this.inheritableContext();
+    const requestId = this.resolveRequestId(req);
     if (requestId !== void 0) {
       res.setHeader(REQUEST_ID_HEADER, requestId);
       context.requestId = requestId;
+      markOwnRequestId(req, requestId);
     }
-    const rawTenantId = Reflect.get(req.headers, this.tenantIdHeader);
-    if (isAcceptableHeaderValue(rawTenantId)) {
-      context.tenantId = rawTenantId;
+    if (context.tenantId === void 0) {
+      const tenantId = this.resolveTenantId(req);
+      if (tenantId !== void 0) {
+        context.tenantId = tenantId;
+      }
     }
     this.logContext.run(context, () => next());
   }
+  /**
+   * 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.
+   */
+  inheritableContext() {
+    const store = { ...this.logContext.getStore() };
+    const inherited = {};
+    for (const key of INHERITABLE_CONTEXT_KEYS) {
+      const value = Reflect.get(store, key);
+      if (value !== void 0) {
+        Reflect.set(inherited, key, value);
+      }
+    }
+    return inherited;
+  }
+  /**
+   * 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.
+   */
+  adoptExistingScope(requestId, req, res) {
+    res.setHeader(REQUEST_ID_HEADER, requestId);
+    this.logContext.set("requestId", requestId);
+    if (this.logContext.get("tenantId") === void 0) {
+      const tenantId = this.resolveTenantId(req);
+      if (tenantId !== void 0) {
+        this.logContext.set("tenantId", tenantId);
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  resolveRequestId(req) {
+    const incoming = Reflect.get(req.headers, REQUEST_ID_HEADER);
+    const fromHeader = isAcceptableHeaderValue(incoming) ? incoming : void 0;
+    return fromHeader ?? (this.shouldGenerateRequestId ? randomUUID() : void 0);
+  }
+  /**
+   * 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`.
+   */
+  resolveTenantId(req) {
+    const raw = Reflect.get(req.headers, this.tenantIdHeader);
+    return isAcceptableHeaderValue(raw) ? raw : void 0;
+  }
 };
 RequestIdMiddleware = __decorateClass([
   Injectable(),
@@ -2703,11 +2876,94 @@ RequestIdMiddleware = __decorateClass([
   __decorateParam(1, Inject(LOGGER_OPTIONS_TOKEN))
 ], RequestIdMiddleware);
 
+// src/server/middlewares/apply-access-log.ts
+function resolveDependencies(app) {
+  try {
+    return {
+      logger: app.get(PinoLoggerService),
+      logContext: app.get(LogContextService),
+      options: app.get(LOGGER_OPTIONS_TOKEN)
+    };
+  } catch (cause) {
+    throw new Error(
+      "[BymaxLoggerModule] applyAccessLog(app) called but BymaxLoggerModule was not imported",
+      { cause }
+    );
+  }
+}
+function applyAccessLog(app) {
+  const { logger, logContext, options } = resolveDependencies(app);
+  const requestId = new RequestIdMiddleware(logContext, options);
+  const accessLog = new HttpAccessLogMiddleware(logger, logContext, options);
+  app.use((req, res, next) => {
+    requestId.use(req, res, () => {
+      accessLog.use(req, res, next);
+    });
+  });
+}
+
 // src/server/middlewares/apply-request-id-middleware.ts
 var ALL_ROUTES = "/";
 function applyRequestIdMiddleware(consumer, routes = ALL_ROUTES) {
   consumer.apply(RequestIdMiddleware, HttpAccessLogMiddleware).forRoutes(routes);
 }
+var PinoUnexpectedErrorSink = class {
+  /**
+   * @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) {
+    this.logger = logger;
+  }
+  /**
+   * 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) {
+    try {
+      const metadata = { method: report.method, route: report.route };
+      if (report.correlationId !== void 0) {
+        metadata["correlationId"] = report.correlationId;
+      }
+      this.logger.errorStructured(
+        RESERVED_LOG_KEYS.HTTP_UNEXPECTED_ERROR,
+        toLoggableError(report.error),
+        void 0,
+        metadata
+      );
+    } catch {
+    }
+  }
+};
+PinoUnexpectedErrorSink = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(PinoLoggerService))
+], PinoUnexpectedErrorSink);
+function toLoggableError(value) {
+  try {
+    return isErrorLike(value) ? value : sanitizeError(value);
+  } catch {
+    return sanitizeError(value);
+  }
+}
 var INJECT_LOGGER_CONTEXT_METADATA_KEY = "bymax_logger:context";
 function InjectLogger(context) {
   return (target, propertyKey, parameterIndex) => {
@@ -2769,4 +3025,4 @@ function LogPerformance(thresholdMs = DEFAULT_THRESHOLD_MS) {
 // src/shared/constants/log-keys-convention.constants.ts
 var LOG_KEYS_CONVENTION_REGEX = /^[A-Z][A-Z0-9_]+_[A-Z][A-Z0-9_]+(_[A-Z][A-Z0-9_]+)?$/;
 
-export { BymaxLoggerModule, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpExceptionFilter, HttpLoggingInterceptor, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, LogContextService, LogPerformance, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, applyRequestIdMiddleware };
+export { BymaxLoggerModule, DEFAULT_REDACT_PATHS, DefaultStdoutDestination, HttpAccessLogMiddleware, HttpExceptionFilter, HttpLoggingInterceptor, InjectLogger, LOGGER_DESTINATIONS_TOKEN, LOGGER_OPTIONS_TOKEN, LOGGER_PINO_INSTANCE_TOKEN, LOG_CONTEXT_METADATA_KEY, LOG_CONTEXT_TOKEN, LOG_KEYS_CONVENTION_REGEX, LogContext, LogContextService, LogPerformance, PINO_LEVEL_NAMES, PINO_LEVEL_NUMBERS, PinoLoggerService, PinoUnexpectedErrorSink, PrettyDevDestination, RESERVED_LOG_KEYS, RESERVED_LOG_KEYS_NOT_EMITTED, RequestIdMiddleware, applyAccessLog, applyRequestIdMiddleware };

package/dist/shared/index.cjs

@@ -17,6 +17,7 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED",
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
+  HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",

package/dist/shared/index.d.cts

@@ -238,6 +238,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";

package/dist/shared/index.d.ts

@@ -238,6 +238,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";

package/dist/shared/index.mjs

@@ -15,6 +15,7 @@ var RESERVED_LOG_KEYS = Object.freeze({
   HTTP_REQUEST_ABORTED: "HTTP_REQUEST_ABORTED",
   HTTP_EXCEPTION_HANDLED: "HTTP_EXCEPTION_HANDLED",
   HTTP_EXCEPTION_UNHANDLED: "HTTP_EXCEPTION_UNHANDLED",
+  HTTP_UNEXPECTED_ERROR: "HTTP_UNEXPECTED_ERROR",
   METHOD_EXECUTION: "METHOD_EXECUTION",
   METHOD_SLOW_EXECUTION: "METHOD_SLOW_EXECUTION",
   LOGGER_DESTINATION_INIT_FAILED: "LOGGER_DESTINATION_INIT_FAILED",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-logger",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Structured JSON logging for NestJS based on Pino 10, with optional OpenTelemetry correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -61,8 +61,8 @@
     "check:mutants": "node scripts/check-mutation-directives.mjs",
     "check:published": "node scripts/check-published-surface.mjs",
     "clean": "rm -rf dist coverage",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "lint": "eslint src scripts test bench '*.config.ts' '*.config.mjs' '*.config.cjs'",
+    "lint:fix": "eslint src scripts test bench '*.config.ts' '*.config.mjs' '*.config.cjs' --fix",
     "mutation": "stryker run",
     "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "mutation:dry-run": "stryker run --dryRunOnly",