@bymax-one/nest-core 1.3.1 → 1.4.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _nestjs_common from '@nestjs/common';
-import { DynamicModule, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { NestModule, MiddlewareConsumer, DynamicModule, ExceptionFilter, ArgumentsHost, NestInterceptor, ExecutionContext, CallHandler, NestMiddleware } from '@nestjs/common';
 import { HttpAdapterHost } from '@nestjs/core';
 import { Observable } from 'rxjs';
 
@@ -68,6 +68,59 @@ interface OpenApiServerDescriptor {
  * so the consumer's declaration reaches the UI unchanged.
  */
 type OpenApiSecurityScheme = Readonly<Record<string, unknown>>;
+/**
+ * One security requirement: scheme name to the scopes it needs, empty for a
+ * scheme that takes none. An operation's requirements are alternatives — any
+ * one of them satisfies it — so an empty *array* of requirements means the
+ * operation needs no authentication at all, which is how the specification
+ * expresses a public route that overrides a document-level default.
+ */
+type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
+/** The HTTP methods an OpenAPI path item can carry an operation under. */
+type OpenApiHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
+/**
+ * Addresses one operation in the generated document, as `"<METHOD> <path>"`.
+ *
+ * This format is a documented contract, not an implementation detail: a sibling
+ * library may ship a plain-data map of its own operations keyed this way, so a
+ * consumer spreads it into {@link OpenApiOptions.operationSecurity} instead of
+ * restating which of that library's routes are public. Import the type to get
+ * that map checked at the library's own compile time.
+ *
+ * The method is uppercase, one space separates the two parts, and the path is
+ * written **exactly as it appears in the generated document**: leading slash,
+ * OpenAPI template braces (`/users/{id}`), no trailing slash, and including any
+ * global prefix the application sets. That last part is the one that surprises:
+ * `@nestjs/swagger` includes `app.setGlobalPrefix('api')` in the documented
+ * paths, so the key is `'POST /api/auth/login'` in an application that sets one.
+ * A library shipping such a map should therefore expose a *function* taking the
+ * prefix rather than a frozen constant — the call site is the only place that
+ * knows it.
+ *
+ * @example 'GET /users/{id}'
+ * @example 'POST /api/auth/login'
+ */
+type OpenApiOperationKey = `${OpenApiHttpMethod} /${string}`;
+/**
+ * Per-operation security requirements, keyed by {@link OpenApiOperationKey}.
+ * An empty array marks the operation public, overriding any document default.
+ */
+type OperationSecurityMap = Readonly<Record<OpenApiOperationKey, readonly OpenApiSecurityRequirement[]>>;
+/**
+ * Names the operation a route handler produced, in the generated document.
+ *
+ * Matches `@nestjs/swagger`'s own factory signature so a consumer's existing one
+ * can be handed over unchanged. This package installs a factory of its own to
+ * learn which handler produced which operation — a contract a library keys its
+ * contributed fragments against — and delegates the id string to this one when
+ * it is set, so nothing an application already generates is renamed.
+ *
+ * @param controllerKey - The controller class name.
+ * @param methodKey - The handler method name.
+ * @param version - The route's version, when the application versions routes.
+ * @returns The operation id to publish.
+ */
+type OpenApiOperationIdFactory = (controllerKey: string, methodKey: string, version?: string) => string;
 /**
  * OpenAPI document configuration.
  *
@@ -96,10 +149,63 @@ interface OpenApiOptions {
     servers?: readonly OpenApiServerDescriptor[];
     /** Security schemes added to the document's components. Default: `{}`. */
     securitySchemes?: Readonly<Record<string, OpenApiSecurityScheme>>;
+    /**
+     * The requirement every operation carries unless it says otherwise, naming
+     * schemes declared in {@link OpenApiOptions.securitySchemes}. Default: `[]`,
+     * which documents nothing and leaves every operation as it was generated.
+     *
+     * Set this when most of the API is authenticated, and mark the exceptions
+     * public through {@link OpenApiOptions.operationSecurity}. An operation that
+     * already declares its own requirement is never overwritten.
+     *
+     * @example [{ cookieAuth: [] }]
+     */
+    security?: readonly OpenApiSecurityRequirement[];
+    /**
+     * Per-operation overrides of {@link OpenApiOptions.security}, keyed by
+     * {@link OpenApiOperationKey}. An empty array marks that operation public.
+     * Default: `{}`.
+     *
+     * A key matching no operation in the generated document is a configuration
+     * error and fails the document build, naming the keys that do exist. Silence
+     * would be worse: a route renamed out from under a stale key would quietly
+     * inherit the document default and be documented as authenticated when it is
+     * not, or the reverse.
+     *
+     * That check runs only when the document is built. With
+     * {@link OpenApiOptions.enabled} false, or in a production runtime where the
+     * feature is forced off, a stale key is not reported — refusing to boot a
+     * service over a documentation setting it never serves would be the wrong
+     * trade. The cost is that the error waits for an environment that has the
+     * document switched on.
+     *
+     * @example
+     *   {
+     *     'POST /auth/login': [],
+     *     'POST /auth/refresh': [{ refreshCookie: [] }]
+     *   }
+     */
+    operationSecurity?: OperationSecurityMap;
+    /**
+     * Name the operations in the generated document. Default: the format
+     * `@nestjs/swagger` itself produces, `<ControllerKey>_<methodKey>`.
+     *
+     * Set it to control the ids a client generator will use. This package always
+     * installs a factory of its own so it can learn which handler produced which
+     * operation, and delegates to this one when it is set — so supplying it
+     * changes the published ids, and leaving it unset changes nothing.
+     */
+    operationIdFactory?: OpenApiOperationIdFactory;
     /**
      * Contribute the schemas this package owns — the error envelope, the health
-     * response, and the pagination shapes — to the document's components.
-     * Default: `true`.
+     * response, and the pagination shapes — to the document's components, and
+     * reference them from the operations that return them: the error envelope as
+     * every operation's `default` response, and the health response on the health
+     * endpoints this package registers. Default: `true`.
+     *
+     * The two halves are one switch because they are one decision. Referencing a
+     * schema this package did not contribute would leave a dangling `$ref`, and a
+     * document that resolves nowhere is worse than one that says less.
      */
     includeCoreSchemas?: boolean;
 }
@@ -221,6 +327,9 @@ interface ResolvedOpenApiOptions {
     version: string;
     servers: readonly OpenApiServerDescriptor[];
     securitySchemes: Readonly<Record<string, OpenApiSecurityScheme>>;
+    security: readonly OpenApiSecurityRequirement[];
+    operationSecurity: OperationSecurityMap;
+    operationIdFactory?: OpenApiOperationIdFactory;
     includeCoreSchemas: boolean;
 }
 /**
@@ -255,7 +364,69 @@ declare const ASYNC_OPTIONS_TYPE: _nestjs_common.ConfigurableModuleAsyncOptions<
 /**
  * `BymaxCoreModule`, the application foundation module for NestJS 11.
  */
-declare class BymaxCoreModule extends BymaxCoreModuleBase {
+declare class BymaxCoreModule extends BymaxCoreModuleBase implements NestModule {
+    private readonly resolved;
+    private readonly adapterHost?;
+    /**
+     * @param options - The resolved snapshot, read to decide whether the timing
+     *   middleware is applied at all.
+     */
+    constructor(resolved: ResolvedCoreOptions, adapterHost?: HttpAdapterHost | undefined);
+    /**
+     * Apply the request-timing middleware to every route.
+     *
+     * Middleware rather than the interceptor this replaced, because guards run
+     * before interceptors: a request rejected by an authentication, authorization
+     * or throttling guard never reached the interceptor, and one matching no
+     * route never reached a controller at all. A deployment could therefore be
+     * under a credential-stuffing run — a flood of 401s — with a flat error
+     * graph, which is why this is a security fix rather than a metrics
+     * improvement.
+     *
+     * Applied on both registration paths, and only when timing is enabled: the
+     * middleware is the sole recorder now, since a second one would count every
+     * matched request twice.
+     *
+     * There is no single pattern that covers both adapters, which is the whole
+     * reason this reads the adapter first. Measured, requesting the root, a
+     * parameterised route, a nested path and an unmatched path, with and without
+     * `setGlobalPrefix('api')`:
+     *
+     * | `forRoutes(...)` | Express          | Fastify              |
+     * | ---------------- | ---------------- | -------------------- |
+     * | `'*splat'`       | skips the root   | —                    |
+     * | `'{*splat}'`     | skips `/api`     | every path           |
+     * | `'/'`            | every path       | matches `/` only     |
+     *
+     * On Express `'/'` is a mount and matches everything beneath whatever prefix
+     * it is scoped to, while `'{*splat}'` — the form Nest 11's migration guide
+     * prescribes for "all routes" — stops matching the prefixed root once an
+     * application calls `setGlobalPrefix`. That was reported as nest#14520 and
+     * fixed by nest#14522, whose regression test covers Fastify; on
+     * `@nestjs/core` 11.1.28 with the Express adapter the prefixed root still
+     * reaches no middleware while resolving to `200`.
+     *
+     * On Fastify the same `'/'` is an exact match rather than a mount — one of
+     * three requests reached the middleware — so the wildcard is the only form
+     * that works there.
+     *
+     * A recorder that quietly omits one route is the same class of defect this
+     * middleware exists to fix, so each adapter gets the form that omits none.
+     *
+     * Fastify also needs {@link bridgeFastifyRouteMetadata}, because middie hands
+     * middleware the raw request, which carries no route metadata at all; see
+     * that file for why the label would otherwise be `<unmatched>` for every
+     * request.
+     *
+     * One limit stays and is documented in the README: Nest scopes module
+     * middleware to the global prefix, so with `setGlobalPrefix('api')` a request
+     * to `/nope` — outside the prefix entirely — reaches no middleware and is not
+     * recorded, while `/api/nope` is. No `forRoutes` argument changes that, and
+     * nothing this module can register reaches outside its own scope.
+     *
+     * @param consumer - Nest's middleware consumer.
+     */
+    configure(consumer: MiddlewareConsumer): void;
     /**
      * Register the module synchronously. Options are known now, so disabled
      * features are omitted from the providers and controllers arrays and the
@@ -345,7 +516,7 @@ declare const BYMAX_CORE_OPTIONS: unique symbol;
  */
 declare const BYMAX_CORRELATION_PROVIDER: unique symbol;
 /**
- * Provide the `ITimingSink` that receives one sample per completed request.
+ * Provide the `ITimingSink` that receives one sample per closed request.
  * Defaults to a no-op sink.
  */
 declare const BYMAX_TIMING_SINK: unique symbol;
@@ -662,9 +833,11 @@ interface MonotonicClock {
 }
 
 /**
- * @fileoverview Request-timing contracts. The timing interceptor emits one
- * {@link RequestTimingSample} per completed request to the bound
- * {@link ITimingSink}. The default sink is a no-op; consumers plug in a logger
+ * @fileoverview Request-timing contracts. `BymaxTimingMiddleware` emits one
+ * {@link RequestTimingSample} per **closed** request to the bound
+ * {@link ITimingSink} — every request the server finished with, including the
+ * ones a guard rejected, the ones that matched no route, and the ones a client
+ * abandoned mid-flight. The default sink is a no-op; consumers plug in a logger
  * bridge or the metrics bridge through the `BYMAX_TIMING_SINK` token.
  * @layer Contract
  */
@@ -694,12 +867,16 @@ interface RequestTimingSample {
 }
 /**
  * Receive request-timing samples. Implementations must never throw: a sink
- * failure is caught and silenced by the interceptor so timing never breaks a
+ * failure is caught and silenced by the recorder so timing never breaks a
  * request.
  */
 interface ITimingSink {
     /**
-     * Record one sample for a completed request.
+     * Record one sample for a closed request, however it ended.
+     *
+     * Called once per request the server closed — not only the ones a handler
+     * answered. A rejection issued by a guard, a request matching no route, and a
+     * client that hung up mid-response all arrive here.
      *
      * @param sample - The timing sample to record.
      */
@@ -707,10 +884,15 @@ interface ITimingSink {
 }
 
 /**
- * Request-timing interceptor. Registered as the `APP_INTERCEPTOR` when the
- * timing feature is enabled, on both the sync and async registration paths.
- * Non-HTTP execution contexts (GraphQL, RPC) pass through untouched: this
- * feature is HTTP-first, matching the exception filter's documented scope.
+ * Request-timing interceptor. No longer registered by `BymaxCoreModule`, which
+ * records through {@link BymaxTimingMiddleware} instead so that requests ended
+ * by a guard or by no route matching are counted too. Non-HTTP execution
+ * contexts (GraphQL, RPC) pass through untouched: this feature is HTTP-first,
+ * matching the exception filter's documented scope.
+ *
+ * @deprecated Since 1.4.0, superseded by `BymaxTimingMiddleware`, which the
+ *   module registers automatically. Registering this interceptor as well
+ *   records a second sample for every request that reaches a handler.
  */
 declare class TimingInterceptor implements NestInterceptor {
     private readonly options;
@@ -759,9 +941,9 @@ declare class TimingInterceptor implements NestInterceptor {
      */
     private readErrorStatus;
     /**
-     * Build the sample, compute the slow flag, and deliver it to the sink inside
-     * a try/catch that silences any failure: a throwing sink must never affect
-     * the request it is observing.
+     * Build the sample and deliver it to the sink inside a try/catch that
+     * silences any failure: a throwing sink must never affect the request it is
+     * observing.
      *
      * @param method - HTTP method of the request.
      * @param route - Route template of the request.
@@ -771,6 +953,133 @@ declare class TimingInterceptor implements NestInterceptor {
     private recordSample;
 }
 
+/**
+ * @fileoverview Neutral request-info accessor for request timing. Reads the
+ * HTTP method and the route template off a request without assuming Express or
+ * Fastify, so `RequestTimingSample.route` always carries a bounded-cardinality
+ * label instead of the raw URL.
+ *
+ * The bound is a security property, not a tidiness one. Requests that match no
+ * route are exactly the ones a scanner produces, each at a different path, so a
+ * label taken from the URL would mint one time series per probe — turning the
+ * scrape endpoint into the most expensive route in the service and the metric
+ * into the outage. Every unmatched request therefore shares one label.
+ *
+ * Dropping the raw-URL fallback bought a **second** guarantee that is worth
+ * stating because it was a side effect rather than the intent, and anyone
+ * weighing the fallback again would otherwise only re-weigh the cardinality
+ * argument. The recorder is middleware mounted at `'/'`, and Express gives
+ * mounted middleware a `req.url` relative to its mount point: under
+ * `setGlobalPrefix('api')` a request to `/api` arrives as `/`, so a path read
+ * there reports somewhere the caller never asked for. Nothing in this file
+ * reads `req.url` any more — the only `.url` left is Fastify's
+ * `routeOptions.url`, which is a template, not a path — so that class of bug
+ * has nowhere to land. Reintroducing a path-derived label brings both problems
+ * back, not just the cardinality one. If a raw path is ever genuinely needed,
+ * the correct read is `req.originalUrl ?? req.url`: `originalUrl` is Express's
+ * and carries the mount prefix, and the `??` covers an adapter that supplies
+ * only `url`, where no mount trimmed it in the first place.
+ * @layer Utility
+ */
+
+/**
+ * The route label carried by every request that matched no route.
+ *
+ * A single constant rather than the request's own path, and exported rather
+ * than inlined: it is the value an alert rule matches on to see a scan, so it
+ * belongs to the contract and must not drift from what this package writes.
+ * Reading `route="<unmatched>"` in a dashboard says what happened; an empty
+ * label — which Prometheus treats as equivalent to no label at all — reads as
+ * missing data and gets scrolled past, which for a signal whose purpose is to
+ * be noticed is the same as not emitting it.
+ */
+declare const UNMATCHED_ROUTE = "<unmatched>";
+/** Structural shape of an Express request's route metadata. */
+interface ExpressRouteShape {
+    route?: {
+        path?: string;
+    };
+    baseUrl?: string;
+}
+/** Structural shape of a Fastify request's route metadata. */
+interface FastifyRouteShape {
+    routeOptions?: {
+        url?: string;
+    };
+}
+/** Structural shape shared by both frameworks for the method. */
+interface RawRequestShape {
+    method?: string;
+}
+/** The combined structural shape read off the request object. */
+type RequestShape = ExpressRouteShape & FastifyRouteShape & RawRequestShape;
+
+/** The part of a response this middleware reads and listens on. */
+interface ResponseShape {
+    /** Node's event emitter, used for the single `'close'` subscription. */
+    on(event: 'close', listener: () => void): unknown;
+    /**
+     * Final status code. Optional and explicitly nullable: a connection can close
+     * before anything settled one, and that case has to be expressible rather
+     * than assumed away.
+     */
+    statusCode?: number | undefined;
+}
+/**
+ * Records one timing sample per request, whatever ended it.
+ *
+ * Registered by `BymaxCoreModule` for every route when the timing feature is
+ * enabled. It replaces the interceptor as the recorder rather than joining it:
+ * two recorders would count every matched request twice, which is a worse
+ * defect than the one being fixed because it is silent and plausible.
+ */
+declare class BymaxTimingMiddleware implements NestMiddleware {
+    private readonly options;
+    private readonly clock;
+    /** The bound sink, or an in-code no-op when nothing is bound. */
+    private readonly sink;
+    /** The bound trace reader, or an in-code no-op when nothing is bound. */
+    private readonly traceContext;
+    /**
+     * @param options - The resolved options, read for the slow-request threshold.
+     * @param sink - The bound timing sink; its failures are swallowed, because a
+     *   throwing sink must never affect the request it is observing.
+     * @param clock - Monotonic clock seam, so a test advances time by controlled
+     *   amounts instead of sleeping.
+     * @param traceContext - Reads the active span's identifiers. Optional: the
+     *   middleware stays constructible on its own, and a no-op resolves nothing.
+     */
+    constructor(options: ResolvedCoreOptions, sink: ITimingSink | undefined, clock?: MonotonicClock, traceContext?: ITraceContextProvider);
+    /**
+     * Start the measurement and arrange for the sample to be recorded once the
+     * connection closes, then hand the request straight on.
+     *
+     * The route is read inside the listener rather than here: at middleware time
+     * the router has not matched yet, so `req.route` is still empty. By the time
+     * the connection closes it is populated — including for a request a guard
+     * rejected, since matching happens before guards run.
+     *
+     * The trace lookup is tried in the live context first and in this moment's
+     * captured context second; see this file's header for the measurements that
+     * decided that order.
+     *
+     * @param request - The framework request object.
+     * @param response - The framework response object.
+     * @param next - Continues the chain; called synchronously and unconditionally.
+     */
+    use(request: RequestShape, response: ResponseShape, next: () => void): void;
+    /**
+     * Build the sample and hand it to the sink, guarding both steps.
+     *
+     * @param request - The framework request object.
+     * @param response - The framework response object.
+     * @param start - Monotonic timestamp captured before the chain ran.
+     * @param trace - The span identifiers already resolved by the caller, which
+     *   owns the choice of which context to read them from.
+     */
+    private record;
+}
+
 /**
  * @fileoverview Stable `BYMAX_*` error-code catalog and HTTP-status derivation.
  * These codes are the machine-readable half of the error envelope contract and
@@ -824,4 +1133,4 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiOptions, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, buildErrorEnvelope, codeForStatus };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };