@bymax-one/nest-logger 1.3.1 → 1.4.1

package/dist/server/index.cjs

@@ -185,6 +185,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",
@@ -768,12 +769,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 });
 }
@@ -791,6 +806,16 @@ function readUserAgent(req) {
   return typeof raw === "string" ? raw : UNKNOWN_USER_AGENT;
 }
 
+// src/server/utils/matches-exclude-path.util.ts
+function matchesExcludePath(patterns, path) {
+  return patterns.some((pattern) => {
+    if (pattern.global || pattern.sticky) {
+      pattern.lastIndex = 0;
+    }
+    return pattern.test(path);
+  });
+}
+
 // src/server/interceptors/http-logging.interceptor.ts
 var HTTP_SUCCESS_MIN = 200;
 exports.HttpLoggingInterceptor = class HttpLoggingInterceptor {
@@ -812,7 +837,7 @@ exports.HttpLoggingInterceptor = class HttpLoggingInterceptor {
    * @returns `true` when the path matches a configured exclude pattern.
    */
   isExcluded(path) {
-    return this.excludePaths.some((pattern) => pattern.test(path));
+    return matchesExcludePath(this.excludePaths, path);
   }
   /**
    * Emit the START entry, then attach success/redirect/error logging to the
@@ -2094,8 +2119,21 @@ exports.LogContextService = 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
@@ -2106,6 +2144,35 @@ exports.LogContextService = class LogContextService {
   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.
    *
@@ -2537,7 +2604,7 @@ var PrettyDevDestination = class {
     });
   }
 };
-var HttpAccessLogMiddleware = class {
+exports.HttpAccessLogMiddleware = class HttpAccessLogMiddleware {
   /**
    * @param logger - The structured logger the access entries are written to.
    *   Injected by token explicitly: the package is bundled without
@@ -2558,13 +2625,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 path = stripQueryString(target);
-    if (this.excludePaths.some((pattern) => pattern.test(path))) {
+    if (matchesExcludePath(this.excludePaths, path)) {
       next();
       return;
     }
@@ -2651,15 +2722,16 @@ var HttpAccessLogMiddleware = class {
     );
   }
 };
-HttpAccessLogMiddleware = __decorateClass([
+exports.HttpAccessLogMiddleware = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(exports.PinoLoggerService)),
   __decorateParam(1, common.Inject(exports.LogContextService)),
   __decorateParam(2, common.Inject(LOGGER_OPTIONS_TOKEN))
-], HttpAccessLogMiddleware);
+], exports.HttpAccessLogMiddleware);
 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);
 }
@@ -2678,27 +2750,128 @@ exports.RequestIdMiddleware = class RequestIdMiddleware {
   }
   /**
    * 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 ? crypto.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 ? crypto.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;
+  }
 };
 exports.RequestIdMiddleware = __decorateClass([
   common.Injectable(),
@@ -2706,10 +2879,93 @@ exports.RequestIdMiddleware = __decorateClass([
   __decorateParam(1, common.Inject(LOGGER_OPTIONS_TOKEN))
 ], exports.RequestIdMiddleware);
 
+// src/server/middlewares/apply-access-log.ts
+function resolveDependencies(app) {
+  try {
+    return {
+      logger: app.get(exports.PinoLoggerService),
+      logContext: app.get(exports.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 exports.RequestIdMiddleware(logContext, options);
+  const accessLog = new exports.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(exports.RequestIdMiddleware, HttpAccessLogMiddleware).forRoutes(routes);
+  consumer.apply(exports.RequestIdMiddleware, exports.HttpAccessLogMiddleware).forRoutes(routes);
+}
+exports.PinoUnexpectedErrorSink = class PinoUnexpectedErrorSink {
+  /**
+   * @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 {
+    }
+  }
+};
+exports.PinoUnexpectedErrorSink = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(exports.PinoLoggerService))
+], exports.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) {
@@ -2787,4 +3043,5 @@ exports.PINO_LEVEL_NUMBERS = PINO_LEVEL_NUMBERS;
 exports.PrettyDevDestination = PrettyDevDestination;
 exports.RESERVED_LOG_KEYS = RESERVED_LOG_KEYS;
 exports.RESERVED_LOG_KEYS_NOT_EMITTED = RESERVED_LOG_KEYS_NOT_EMITTED;
+exports.applyAccessLog = applyAccessLog;
 exports.applyRequestIdMiddleware = applyRequestIdMiddleware;