@bymax-one/nest-core 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -11,6 +11,254 @@ heading here.
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-08-13
+
+HTTP metrics were blind to every request that did not reach a handler. Nest runs
+**middleware → guards → interceptors → pipes → handler**, and the recorder was an
+interceptor, so authentication failures, authorization failures, throttled
+requests and unknown paths were never counted. Measured on a running
+application, three requests — a handler success, a guard rejection, an unknown
+path — produced **one** sample. A deployment could be under a credential-stuffing
+run, a privilege probe or route enumeration with a flat error graph, which makes
+this a security fix rather than an observability improvement.
+
+**Apply to a derived backend:** bump the dependency. No code change is needed.
+Expect new `401`/`403`/`429` series on routes that already existed, a new
+`route="<unmatched>"` series for `404`s, and a **lower success rate** — the
+denominator finally includes the rejections. Existing `status_code="200"` series
+keep their values.
+
+### Security
+
+- **Requests rejected before a handler are now counted.** The recorder moved
+  from `APP_INTERCEPTOR` to middleware (`BymaxTimingMiddleware`), applied to
+  every route when `timing.enabled` is `true`. Nest runs middleware, then
+  guards, then interceptors: a request a guard rejects never reached
+  `intercept()`, and a request matching no route never reached a controller.
+  Measured on a real application, three requests — a handler success, a guard
+  rejection and an unknown path — produced exactly **one** sample. `401`, `403`,
+  `429` and `404` were all invisible, which is to say a deployment could be under
+  a credential-stuffing run, a privilege probe or route enumeration with a flat
+  error graph. All six cases are now counted, and the sample is emitted on the
+  response's `'close'` event rather than `'finish'`, so a client that hangs up
+  mid-request — what a scanner does — is counted too.
+- **The root path is recorded.** On Express the middleware is mounted at `'/'`
+  rather than through a wildcard pattern. The unbraced `'*splat'` skips the root outright,
+  and the braced `'{*splat}'` that Nest 11's migration guide prescribes stops
+  matching the _prefixed_ root once an application calls `setGlobalPrefix` —
+  which production applications almost always do. That was reported as
+  nest#14520 and fixed by nest#14522, whose regression test covers Fastify;
+  measured on `@nestjs/core` 11.1.28 with the Express adapter, the prefixed root
+  still reaches no middleware while the route itself answers `200`. Both
+  patterns were measured against the mount, which matched every path in both
+  configurations. Fastify needs the opposite choice — see the next entry. One
+  limit remains and is documented: module middleware is scoped to the global
+  prefix, so a request outside it entirely reaches no middleware.
+- **Fastify records the same labels as Express**, which the documented support
+  for both platforms had been promising without any test behind it. Nest runs
+  middleware on Fastify through `@fastify/middie`, whose `runMiddie` calls
+  `run(req.raw, reply.raw, next)` and copies only `id`, `hostname`, `protocol`,
+  `ip`, `ips`, `log`, `query` and `body` onto that raw request — never
+  `routeOptions`. The recorder therefore saw no route metadata at all and would
+  have labelled every Fastify request `<unmatched>`, destroying the per-route
+  breakdown and making a scan indistinguishable from ordinary traffic. Worse,
+  `forRoutes('/')` is a mount on Express but an **exact match** on Fastify, so
+  most requests produced no sample whatsoever. The module now selects the mount
+  per adapter and registers an `onRequest` hook on Fastify that carries the
+  resolved template to the recorder. Covered by a new Fastify end-to-end suite.
+- **Unmatched requests record a bounded label.** A request that matched no route
+  is recorded as `<unmatched>` (exported as `UNMATCHED_ROUTE`), never the
+  requested path. The previous raw-URL fallback would have let anyone mint one
+  Prometheus time series per probe, so counting scanner traffic under it would
+  have turned this fix into a memory-exhaustion vector.
+
+### Changed
+
+- **`ITimingSink` implementations now receive more samples**, including requests
+  that never reached a handler. Sinks that assumed "one sample per completed
+  request" should expect "one sample per closed request". The built-in metrics
+  bridge needs no change; a dashboard filtering on `2xx` sees its numbers
+  unchanged and its error rates become correct.
+- **No status is relabelled**, and that is deliberate. A client that hangs up
+  mid-handler was already counted — destroying the socket does not cancel the
+  JavaScript already running, so the handler finished and the interceptor
+  recorded an ordinary `200` — and it still is, once, under the same `200`.
+  Introducing a sentinel status for aborts would rewrite the value of
+  `status_code="200"` series that already exist in every deployment, moving
+  error-rate panels with no change in traffic. Whether an abort deserves its own
+  status is a separate decision from whether the request is counted at all, and
+  this release makes only the second one.
+- **The timing recorder is registered once, not twice.** The middleware
+  **replaced** the interceptor rather than joining it — two recorders would
+  double every rate an alert threshold is tuned against, which is a quieter
+  failure than the one being fixed.
+
+### Deprecated
+
+- **`TimingInterceptor`** is superseded by `BymaxTimingMiddleware` and is no
+  longer registered by `BymaxCoreModule`. It stays exported so an application
+  that wired it by hand keeps compiling; registering it alongside the middleware
+  records a second sample for every request that reaches a handler.
+
+### Added
+
+- **`BymaxTimingMiddleware` and `UNMATCHED_ROUTE`** are exported from the package
+  root.
+- **A library can describe its own routes in a consumer's document.** A provider
+  marked `@BymaxOpenApiContributor()` returns OpenAPI fragments keyed by handler
+  identity — `'AuthController.login'` — and they are merged onto the operations
+  those handlers produced. It exists because the two obvious alternatives do
+  not work: decorating a library's controllers with `@nestjs/swagger` would load
+  that peer in every application importing the library, and a consumer-side map
+  keyed by path cannot be written by a library mounted through
+  `RouterModule.register`, which does not know its own final paths.
+- **`openapi.operationIdFactory`**, plus the exported `OpenApiOperationIdFactory`
+  type. This package now always installs a factory so it can learn which handler
+  produced which operation, and **delegates the id string** — to this option when
+  set, to the format `@nestjs/swagger` itself produces otherwise. Choosing the id
+  instead would have renamed every operation in every published document and
+  broken any client generated from one; a test compares both documents to keep
+  that true if the peer's format ever changes.
+- **The contract types** `IOpenApiContributor`, `OpenApiFragment`,
+  `OpenApiFragmentObject` and `OpenApiHandlerKey`, exported from `./openapi` so a
+  sibling library can target them at its own compile time.
+- **`BYMAX_OPENAPI_CONTRACT_VERSION`**, and a required `contractVersion` on every
+  fragment. A fragment crosses a boundary between independently released
+  packages, and on that boundary compile-time types protect nothing: each side
+  type-checks against its own installed copy, so only the value travelling at
+  runtime can say which shape it is. A revision this package does not speak fails
+  the build naming both. Required rather than inferred from absence, following
+  the pattern Kubernetes objects use for `apiVersion` — an optional discriminator
+  is unambiguous only while exactly one revision exists, which is precisely when
+  nobody checks it.
+
+### Fixed
+
+- **`DiscoveryModule` is imported when only the document is enabled.** It was
+  imported on the synchronous registration path only when readiness discovery or
+  metrics could scan, so an application enabling nothing but OpenAPI had no
+  scanner — and a library's description of its own routes would have been
+  silently dropped.
+
+### Notes
+
+- Deriving fragments from validation decorators is deliberately **not** in this
+  package: it takes no dependency on any validation library. A library that
+  wants its schemas to track its own decorators generates them in its own build,
+  where that dependency already exists, and commits the result with a test
+  asserting generated matches committed — so drift fails in the repository that
+  caused it. An application's own DTOs need none of this; `@nestjs/swagger`'s CLI
+  plugin already derives them, which is the route a precompiled library lacks.
+
+## [1.3.2] - 2026-08-12
+
+A consumer audit of the served document found that it described the library's
+promises rather than the deployment: routes of features that were switched off
+were still listed, the contributed schemas were never referenced by any
+operation, and nothing said which operations needed authentication. Everything
+below is additive — no option changes meaning, no existing document loses an
+entry it had.
+
+**Apply to a derived backend:** bump the dependency. The document improves with
+no code change; the two new options are opt-in.
+
+### Added
+
+- **`openapi.security` and `openapi.operationSecurity`.** A document-level
+  default requirement, plus per-operation overrides keyed `"<METHOD> <path>"`.
+  An empty array marks an operation public, which is the specification's own way
+  of overriding the default — and it matters for generated clients, since an
+  operation with _absent_ security inherits the document default and a client
+  would attach credentials to a public registration endpoint.
+- **The operation key is a documented contract**, with `OpenApiOperationKey` and
+  `OperationSecurityMap` exported as types so a sibling library can ship a
+  plain-data map of its own operations and have it checked at its own compile
+  time, with no runtime coupling. The path is written exactly as documented,
+  **including any global prefix** — `@nestjs/swagger` puts `setGlobalPrefix` into
+  the documented paths, so a library shipping such a map should expose a function
+  taking the prefix rather than a frozen constant.
+- **A key addressing no operation fails the document build**, listing both the
+  keys that missed and the operations that exist. A stale key would otherwise
+  leave a route silently documented as authenticated when it is not, or the
+  reverse. Failing is safe here: the document is only ever built outside
+  production.
+- **A requirement naming an undeclared security scheme fails the same way.** A
+  requirement is a reference, and a reference to nothing produces a document
+  whose security cannot be resolved — a client generator looks the name up in
+  `components.securitySchemes`, finds nothing, and either fails or emits an
+  unauthenticated client. Configuring the requirement and forgetting the scheme
+  is one edit apart. A scheme the document itself declares counts as declared,
+  and marking an operation public names no scheme, so it needs none.
+
+### Fixed
+
+- **A disabled feature's routes are no longer documented.** With
+  `metrics: { enabled: false }` the runtime answers `GET /metrics` with a 404
+  envelope — on `forRootAsync` the controller is mounted unconditionally and
+  guards each request, because route metadata is fixed before the async options
+  resolve — while the document still advertised it. The filter reads the same
+  resolved snapshot the guard reads, so the two cannot drift. `@nestjs/swagger`
+  documents paths as the application serves them — the global prefix, and under
+  `enableVersioning({ type: URI })` the version segment that follows it, so
+  `/api/v1/metrics` — and both are **read from the application** rather than
+  inferred from the document. Versioning matters as much as the prefix: without
+  it, every versioned application kept advertising the routes of a feature it
+  had switched off, and its health probes lost the payload schema and the public
+  marking this package contributes. Inference is the trap: an application whose routes all sit under one
+  controller prefix would have that treated as the global one, and a consumer
+  route ending in `/health/live` deleted as though this package owned it. What
+  leaves is also the **operation**, not the path item — a method the consumer
+  mounted on the same path survives, and the path disappears only once nothing
+  is left under it.
+- **The automatic security policy is stated for `GET` alone.** These controllers
+  expose no other method, so a consumer's `POST` on the same path is theirs and
+  no longer inherits a requirement written for ours.
+- **The envelope response follows the envelope feature.** With
+  `envelope.enabled` off, errors are shaped by Nest or by the consumer's own
+  handler, so documenting this package's envelope described a body the
+  deployment never sends. The health response is a separate feature and is
+  unaffected.
+- **A response written as a bare `$ref` is a declaration.** It carries no
+  `content`, so the placeholder rule would have overwritten it — discarding the
+  reference and leaving `$ref` beside sibling keys, which is not a valid
+  response object.
+- **`BymaxMetricsAuth` is reserved while a scrape token is configured.** The
+  name was silently overwritten or silently lost depending on where the other
+  definition came from, and the losing case left the scrape operation pointing
+  at a scheme that is not the bearer token the runtime checks. It now fails the
+  document build with the collision named.
+- **The contributed schemas are referenced by the operations that return them.**
+  They shipped orphaned: `components.schemas` carried the envelope, the health
+  response and the pagination shapes while no operation pointed at any of them,
+  so a generated client had no error type at all. Every operation now carries a
+  `default` response referencing `BymaxErrorEnvelope`, and the health endpoints
+  an explicit `200` referencing `BymaxHealthResponse`. Gated by
+  `includeCoreSchemas`, because referencing a schema that was not contributed
+  would leave a dangling `$ref`.
+- **A response is judged by whether it declares a shape.** `@nestjs/swagger`
+  emits a placeholder `200` with a description and no content for every handler,
+  so a plain "existing always wins" rule would never have written a contributed
+  schema. A response carrying `content` is a real declaration and is untouched;
+  one without it is filled in, keeping any description already written.
+- **The library documents the security of its own three routes.** The health
+  probes are marked public — an orchestrator polls them holding no credential —
+  and the scrape endpoint carries a bearer requirement, with its scheme, exactly
+  when `metrics.authToken` is set. The library owns both the routes and the
+  option, so no consumer should have to restate either.
+
+### Documentation
+
+- The metrics naming rules are framed as an adoption guideline for sibling
+  libraries, with the reason the rules live here: a Prometheus registry is a flat
+  namespace, so two libraries picking the same metric name collide at the
+  _consumer's_ boot, in an application neither library's CI ever assembles. A
+  contributing library is asked to publish its own metric list; this package
+  deliberately keeps no central catalogue.
+- `applyBymaxOpenApi` documents that testing its enabled path under Jest needs
+  `NODE_OPTIONS=--experimental-vm-modules`, because the optional peer is reached
+  through a dynamic `import()`. Only the enabled case fails without it, which is
+  what makes the omission confusing.
+
 ## [1.3.1] - 2026-08-11
 
 A patch fixing a defect that existed only in the published artifact: `applyBymaxOpenApi` threw on
@@ -394,9 +642,11 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.0.1]: https://github.com/bymaxone/nest-core/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/bymaxone/nest-core/releases/tag/v1.0.0
 [1.1.1]: https://github.com/bymaxone/nest-core/compare/v1.1.0...v1.1.1
+[1.3.2]: https://github.com/bymaxone/nest-core/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/bymaxone/nest-core/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/bymaxone/nest-core/compare/v1.2.2...v1.3.0
 [1.2.2]: https://github.com/bymaxone/nest-core/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/bymaxone/nest-core/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/bymaxone/nest-core/compare/v1.1.1...v1.2.0
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.3.1...HEAD
+[1.4.0]: https://github.com/bymaxone/nest-core/compare/v1.3.2...v1.4.0
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.4.0...HEAD