@bymax-one/nest-logger 1.4.1 → 1.4.3

package/CHANGELOG.md

@@ -11,6 +11,163 @@ heading here.
 
 ## [Unreleased]
 
+## [1.4.3] - 2026-10-31
+
+### Added
+
+- `LOGGER_REDACTOR_TOKEN`, `REDACT_COMMON_FIELDS` and `isValidTraceId` are exported from the package
+  root. The token is the injection point of `PinoLoggerService`'s redactor, so a consumer composing
+  its own providers can now name it. `REDACT_COMMON_FIELDS` is the name list the
+  default redactor matches, and `DEFAULT_REDACT_PATHS` is built from it, so extending the defaults no
+  longer means copying the names. `isValidTraceId` is the check the trace mixin already applies.
+  `sanitizeError` stays internal: its output shape is not a contract this release commits to.
+
+### Deprecated
+
+- `@LogContext(name)` is marked `@deprecated`. It records a label as class metadata and nothing in
+  the package reads it, so the label has never been applied. `@InjectLogger(MyClass.name)` is the
+  working equivalent. `shouldUseAsNestLogger` was already deprecated and is unchanged.
+
+### Fixed
+
+- **A custom `timestamp` can no longer break the log line or add fields to it.** Pino inserts the
+  value into the JSON line verbatim, and the library wrapped it in quotes without encoding it, so a
+  quote, a backslash or a newline in the returned string produced invalid JSON for every entry, and a
+  crafted value such as `","injected":"x` added a field. The value is now encoded as a JSON string,
+  and `time` carries exactly what the function returned.
+
+### Breaking
+
+- **`http.excludePaths` now excludes `/health/live` and `/health/ready` by default**, the probes of
+  `@bymax-one/nest-core`, so the defaults are `/health`, `/health/live`, `/health/ready` and
+  `/metrics`. A probe hit every few seconds drowned the record (8272 of 8274 entries on one
+  deployment). Each default is an exact, anchored path, so a route such as `/health/other` is still
+  logged.
+- **Options are validated more strictly at bootstrap**, each rejection naming the option and, where
+  there is a value to show, what was received. Added checks: `maxEntrySizeBytes` must be a finite number (a `NaN` or `Infinity`
+  made the size gate never trip); `isGlobal`, `shouldDisableDefaultRedact` and the `http` and `otel`
+  switches must be booleans (the string `'false'` is truthy); `redactCensor` a string; `timestamp` a
+  function; `redactPaths` an array of non-empty strings; `serializers` an object of functions;
+  `destinations` an array whose entries have a `write` method, a non-empty `name` and function hooks;
+  `http` and `otel` objects; `http.excludePaths` an array of `RegExp` (a pattern from another realm,
+  such as a `vm` context, is accepted); `http.tenantIdHeader` and the
+  three `otel.*Field` names non-empty strings; `otel.fieldFormat` `'camelCase'` or `'snake_case'`
+  (an unknown value silently behaved as `camelCase`).
+- **`PrettyDevDestination` refuses to initialize when `NODE_ENV` is `production`.** The 0.1.0 entry
+  said it was auto-disabled in production, and nothing did that: registered there it rendered ANSI
+  colour through a main-thread transform into the log stream. It now fails at `onInit()` with a
+  message naming the cause; the registry reports `LOGGER_DESTINATION_INIT_FAILED` on stderr, later
+  writes to it are dropped, and when it is the only destination entries go to stdout as raw NDJSON.
+  Only the exact value `production` refuses.
+
+#### Apply to a consumer
+
+- A deployment whose own `/health/live` or `/health/ready` route should stay in the log now sets
+  `http.excludePaths` itself. A value replaces the defaults, and `[/^\/health$/, /^\/metrics$/]`
+  restores the previous list.
+- An application that passed a value of the wrong kind, such as `http: { isEnabled: 'false' }` or a
+  destination without a `name`, now fails at bootstrap with a message naming the option, where it
+  previously booted with that value ignored or misread. Correct the value.
+- A deployment that registers `PrettyDevDestination` with `NODE_ENV=production` now gets raw JSON on
+  stdout and one stderr line instead of coloured output. Register it only outside production, for
+  example `...(process.env.NODE_ENV === 'production' ? [] : [new PrettyDevDestination()])`, and keep
+  `DefaultStdoutDestination` in the list.
+
+### Documentation
+
+- The error catalog listed codes that nothing in the library emits (for example
+  `LOGGER_INVALID_OPTIONS` and `LOGGER_OTEL_API_UNAVAILABLE`), and described them as thrown. A thrown
+  error carries a message, not a code, so the catalog now separates the message each thrown error
+  starts with from the log keys the library writes. It also gains the errors it omitted and the real
+  surface of a missing `@opentelemetry/api`, a `LOGGER_BOOTSTRAP_WARNING` with
+  `reason: 'OTEL_API_UNAVAILABLE'`.
+  `readme-error-catalog.spec.ts` scans every throw site in `src` and fails when a row and the code
+  disagree in either direction.
+- The README documents the injection tokens and the exported helpers, the `useClass` and
+  `useExisting` forms of `forRootAsync`, the rules the request-id middleware applies to an inbound
+  `x-request-id` and tenant header (a value that fails them is replaced, not cleaned), and that a
+  Fastify adapter is not supported.
+- `forRootAsync` does not register the exception filter, which `forRoot` does, and the README now
+  says so under the async example, in the options table and in the `http` option JSDoc. Measured with
+  the same failing controller on both paths: with `http.isEnabled`, `forRootAsync` emits the access
+  log (`HTTP_REQUEST_START`, `_CLIENT_ERROR`, `_SERVER_ERROR`) and the real error reaches its terminal
+  entry, but not `HTTP_EXCEPTION_HANDLED` or `HTTP_EXCEPTION_UNHANDLED`; the 500 response is
+  identical. Registering `{ provide: APP_FILTER, useClass: HttpExceptionFilter }` yields them. The
+  difference is deliberate, and a spec pins the behaviour and the remedy.
+- `ILogDestination` JSDoc: `write` no longer says a failing destination "may be temporarily
+  skipped". Nothing skips a destination that initialized: every failed entry is dropped for it and
+  reported, and it keeps receiving entries. Only one whose `onInit()` failed receives none.
+  `minLevel` says it can only narrow what the module `level` lets through.
+- The README prose and tables are corrected against the code; that correction touches no source file.
+  - The options table gave `level` a default of `'info'`. Outside `NODE_ENV=production` the default
+    is `'debug'`. It now lists the options it omitted: `isGlobal`, `serializers`, `timestamp`, the
+    deprecated `shouldUseAsNestLogger`, and `otel.traceIdField`, `otel.spanIdField` and
+    `otel.traceFlagsField`.
+  - `DefaultStdoutDestination` was called "always active". It is the default sink only while
+    `destinations` is empty, as the Destinations section already said. A destination whose
+    `onInit()` rejects was described as staying in the write fan-out. It is removed from the fan-out
+    and from shutdown.
+  - The architecture diagram showed `info(logKey, msg, context, metadata)`; the third parameter is
+    `userId`. It named a `composedMixin()` that does not exist (the function is
+    `createTraceContextMixin`) and put `userId` in the scope `RequestIdMiddleware` opens, which holds
+    `requestId` and `tenantId`.
+  - The tech stack badges now read pnpm 11 and tsup 9. The URL normalization lists name ULID and
+    nanoid segments as well as UUID and numeric ones. The `LogContextService` table lists `get()`.
+    The last two HTTP log keys sit inside their table.
+  - The Pino throughput figures are attributed to Pino's own benchmarks, the `Scope.REQUEST` cost
+    to NestJS's estimate, and the EPIPE guard note names its one exception, `pino-pretty`'s own
+    stream.
+  - The resource identity example passed `process.env.POD_UID` to `service.instanceId`, which does
+    not compile under `exactOptionalPropertyTypes` because the value can be `undefined`. It now reads
+    `process.env.POD_UID!`.
+
+### Tests
+
+- `readme-options.spec.ts` parses the three option tables in the README and checks every default
+  against the defaults the module applies, and checks that the tables list exactly the options the
+  module resolves, so a default that drifts, or an option added without a row, fails the suite.
+
+## [1.4.2] - 2026-10-30
+
+No breaking changes. Dependency and build-tooling maintenance only. No source file under `src/` changes and the
+runtime JavaScript in `dist/` is byte-identical to `1.4.1`.
+
+### Security
+
+- Raise the pnpm override floors for transitive devDependencies that resolved to versions
+  with new advisories: `body-parser` `^2.4.0` (GHSA-27r3-jxmh-p828, DoS on trailing bytes after a
+  compressed body), `multer` `^2.5.0` (GHSA-q7qp-rjg7-q26m, DoS from a pending async
+  `fileFilter`), `qs` `^6.16.1` (GHSA-6pq8-jhm2-2vcw, `qs.stringify` DoS) and `zod` `^4.6.6`
+  (GHSA-mrhx-c7xc-m3w5, memory exhaustion on oversized collections). Dev-only: the published
+  package has zero runtime dependencies.
+- Ignore GHSA-gcqx-w48m-w2h4 (`deepmerge` <= 4.3.1, prototype poisoning in `mergeObject`) in
+  `osv-scanner.toml` until 2027-01-27. No patched release exists, and `deepmerge` is reached
+  only through `jest-config`, a devDependency. Remove the entry when a fixed `deepmerge` ships
+  or jest drops it.
+
+### Changed
+
+- Build with `tsup` 9 (devDependency, was 8.5). The published `.mjs` and `.cjs` bundles are
+  byte-identical; the `.d.ts` and `.d.cts` files re-emit type exports as a separate
+  `export type { … }` statement instead of inline `type` modifiers, which declares the same
+  public surface. `attw` reports no problems and the bundle-size budgets hold.
+- Resolve `@opentelemetry/api` to 1.10.0 in the lockfile (was 1.9.1), so the test suite runs
+  against the current API release. The `^1.9.0` range in `package.json`, devDependency and peer
+  alike, is unchanged.
+- Bump `github/codeql-action/upload-sarif` to 4.39.1 in the Scorecard workflow. CI only; nothing
+  ships.
+
+### Documentation
+
+- The runtime bundles are unchanged, and the type declarations were regenerated by `tsup` 9.
+- The 1.0.1 and 1.0.8 release notes are corrected: 1.0.8 now records the id-safe charset
+  validation of inbound `x-request-id` and tenant ids that it already shipped.
+
+#### Apply to a consumer
+
+No action required. There is no new public API, no peer range changed, and the runtime JavaScript
+is byte-identical to `1.4.1`; only the grouping of type exports in the declaration files differs.
+
 ## [1.4.1] - 2026-10-23
 
 No breaking changes.
@@ -1699,8 +1856,9 @@ identical to `1.0.8`, and nothing changed but the version number.
 
 ## [1.0.8] - 2026-08-10
 
-Remediation of a local audit's redaction, attribution and correlation-id findings. No API
-changed; the fixes are in the default redact set, the acting-user resolution and the docs.
+Remediation of a local audit's redaction, attribution and correlation-id findings. The public
+API is unchanged; the fixes are in the default redact set, the acting-user resolution, the
+correlation-id validation and the docs.
 
 ### Fixed
 
@@ -1712,6 +1870,14 @@ changed; the fixes are in the default redact set, the acting-user resolution and
   exception filter now resolve the acting user as `sub ?? id`, so a JWT principal (every
   `@bymax-one/nest-auth` token) is attributed to its subject rather than an ORM `id` when a
   principal carries both.
+- **Inbound correlation and tenant ids are confined to an id-safe charset.** The inbound
+  `x-request-id` and tenant-id header values are now accepted only when they are drawn from an
+  id-safe character set and fit the length bound; anything else (control bytes, whitespace,
+  markup characters) is rejected. A rejected request id is replaced by a generated one (when
+  `shouldGenerateRequestId` is on) and a rejected tenant id is omitted. The request id is echoed
+  on the `x-request-id` response header and both ids are stored in the log context, so this keeps
+  a client from planting a control byte or markup fragment in the logs and the header of every
+  request it makes.
 
 ### Documentation
 
@@ -1956,11 +2122,11 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
   Dev-only: the published package has zero runtime dependencies.
 - Force `qs` to `^6.15.3` (via `pnpm.overrides`) to clear GHSA-q8mj-m7cp-5q26
   (`qs.stringify` DoS). `typed-rest-client`, pulled in by Stryker, pins `qs` at
-  the affected `6.15.1` exactly, so no dependency refresh could resolve it
+  the affected `6.15.1` exactly, so no dependency refresh could resolve it.
 - Pin every third-party and GitHub-owned action to a full commit SHA, with the
   release tag kept as a trailing comment so Dependabot can still bump them. The
   org's own `bymaxone/.github` reusable workflows and composite action stay on
-  the `@v1` moving tag by design, so shared-pipeline fixes keep propagating
+  the `@v1` moving tag by design, so shared-pipeline fixes keep propagating.
 
 ### Changed
 
@@ -2026,7 +2192,9 @@ published `dist/` is identical — no runtime behaviour changes for consumers.
 - Professional CI suite: `ci.yml`, `bench.yml`, `codeql.yml`, `scorecard.yml`,
   `release.yml`, Dependabot, and issue templates
 
-[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.4.1...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-logger/compare/v1.4.3...HEAD
+[1.4.3]: https://github.com/bymaxone/nest-logger/compare/v1.4.2...v1.4.3
+[1.4.2]: https://github.com/bymaxone/nest-logger/compare/v1.4.1...v1.4.2
 [1.4.1]: https://github.com/bymaxone/nest-logger/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/bymaxone/nest-logger/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/bymaxone/nest-logger/compare/v1.3.0...v1.3.1