@mpen/routekit 0.1.0 → 0.1.2

package/dist/middleware.d.mts

@@ -0,0 +1,388 @@
+import { E as OneOrMany, O as RequestContext, a as MiddlewareResponseDeclaration, c as AcceptMediaRange, h as HandlerContext, i as MiddlewareControls, k as RequestMiddleware, n as DeclaredMiddleware, o as MiddlewareResponseDeclarations, p as ContextMiddleware, r as DefineMiddlewareOptions, s as defineMiddleware, u as AnyContext, y as MaybePromise } from "./router-Cwb7ak0J.mjs";
+import { HttpMethod, HttpMethod as HttpMethod$1 } from "@mpen/http";
+import { LogLevel, LogRecordTransform, TerminalLogRecordFormatter } from "@mpen/logger";
+
+//#region src/router/middleware/request-id-ctx.d.ts
+declare global {
+  var _reloadCounter: number;
+  var _globalRequestCounter: number;
+}
+interface ExtraContext {
+  prefix: string;
+  /**
+   * Number of times this server has been hot-reloaded.
+   */
+  hotReloadCounter: number;
+  /**
+   * Sequential request number for this middleware instance.
+   */
+  requestCounter: number;
+  /**
+   * Sequential request number across request id middleware instances.
+   */
+  globalRequestCounter: number;
+}
+/**
+ * Options for [`requestIdCtx`]{@link requestIdCtx}.
+ *
+ * @example
+ * ```ts
+ * const options: RequestIdCtxOptions = {
+ *     writeHeaderName: 'x-request-id',
+ *     generate: () => crypto.randomUUID(),
+ * }
+ * ```
+ *
+ * @typeParam Ctx - Context available before request id generation.
+ */
+interface RequestIdCtxOptions<Ctx extends object = AnyContext> {
+  /**
+   * Prefix used by the default generator. Defaults to an empty string.
+   */
+  prefix?: string;
+  /**
+   * Header(s) to check for a request id. Defaults to common request/trace headers.
+   * Set to `null` or an empty array to disable header reads.
+   */
+  readHeaderName?: OneOrMany<string> | null;
+  /**
+   * Response header name to write the request id into.
+   */
+  writeHeaderName?: string;
+  /**
+   * Custom request id generator used when no read header is present.
+   *
+   * @param ctx - Current request context.
+   * @param extra - Prefix and counter values maintained by this middleware.
+   * @returns Request identifier.
+   */
+  generate?: (ctx: HandlerContext<Ctx>, extra: ExtraContext) => string;
+}
+/**
+ * Attach a correlated request id to every final response and contextual logger record.
+ *
+ * @example
+ * ```ts
+ * router.useRequest(requestIdCtx({
+ *   readHeaderName: ['x-request-id', 'x-trace-id'],
+ *   writeHeaderName: 'x-request-id',
+ *   generate: () => crypto.randomUUID(),
+ * }))
+ * ```
+ *
+ * @param options - Configuration for reading, generating, and writing request ids.
+ * @returns Request-boundary middleware that populates `requestId` and logger context.
+ * @typeParam Ctx - Context available before request id generation.
+ */
+declare function requestIdCtx<Ctx extends object = AnyContext>(options?: RequestIdCtxOptions<Ctx>): RequestMiddleware<{
+  requestId: string;
+}, Ctx>;
+//#endregion
+//#region src/router/middleware/request-logger.d.ts
+/**
+ * Options for [`requestLogger`]{@link requestLogger}.
+ *
+ * @example
+ * ```ts
+ * const options: RequestLoggerOptions = {
+ *     completionLevel: response => response.status >= 500 ? LogLevel.ERROR : LogLevel.INFO,
+ * }
+ * ```
+ */
+interface RequestLoggerOptions {
+  /**
+   * Activity label used for start and completion records.
+   * @defaultValue `'request'`
+   */
+  activityName?: string;
+  /**
+   * Completion severity or a function selecting severity from the final response.
+   */
+  completionLevel?: LogLevel | ((response: Response) => LogLevel);
+  /**
+   * Header containing a trusted proxy-provided original client address.
+   *
+   * Only configure this when direct clients cannot provide or alter this header. For
+   * `x-forwarded-for`, the first comma-separated address is recorded as `client.address`.
+   *
+   * @example
+   * ```ts
+   * requestLogger({ trustedClientAddressHeader: 'x-forwarded-for' })
+   * ```
+   */
+  trustedClientAddressHeader?: string;
+}
+/**
+ * Log a timed request activity through the request's contextual logger.
+ *
+ * @example
+ * ```ts
+ * router.useRequest(requestIdCtx())
+ * router.useRequest(requestLogger())
+ * ```
+ *
+ * @param options - Request activity naming and severity options.
+ * @returns Request-boundary middleware that logs final status and duration.
+ * @typeParam Ctx - Context containing the correlated request identifier.
+ */
+declare function requestLogger<Ctx extends {
+  requestId: string;
+} & object = AnyContext & {
+  requestId: string;
+}>(options?: RequestLoggerOptions): RequestMiddleware<{}, Ctx>;
+//#endregion
+//#region src/router/middleware/request-logger-format.d.ts
+/**
+ * Transform Routekit request activity records into production JSON access logs.
+ *
+ * Removes the fallback activity message from `http.server.request` records while preserving
+ * normal application log messages written through the same contextual logger.
+ *
+ * @example
+ * ```ts
+ * import { JsonLogger } from '@mpen/logger'
+ * import { transformRoutekitJsonLogRecord } from '@mpen/routekit/middleware'
+ *
+ * const logger = new JsonLogger({
+ *     transformRecord: transformRoutekitJsonLogRecord,
+ * })
+ * ```
+ *
+ * @param record - Record emitted by a logger.
+ * @returns The transformed record, or `undefined` to use the original record.
+ */
+declare const transformRoutekitJsonLogRecord: LogRecordTransform;
+/**
+ * Format Routekit request context for terminal logs.
+ *
+ * Renders compact request start/completion lines, color-correlated request identifiers, status
+ * codes, elapsed time, and response sizes while leaving unrelated records to
+ * [`TerminalLogger`]{@link import('@mpen/logger').TerminalLogger}'s default renderer.
+ *
+ * @example
+ * ```ts
+ * import { TerminalLogger } from '@mpen/logger'
+ * import { formatRoutekitTerminalLogRecord } from '@mpen/routekit/middleware'
+ *
+ * const logger = new TerminalLogger({
+ *     formatRecord: formatRoutekitTerminalLogRecord,
+ * })
+ * ```
+ *
+ * @param record - Record emitted by a logger.
+ * @param terminal - Terminal formatting helpers.
+ * @returns Formatted terminal output, or `undefined` to use the default renderer.
+ */
+declare const formatRoutekitTerminalLogRecord: TerminalLogRecordFormatter;
+//#endregion
+//#region src/router/middleware/body-limit.d.ts
+interface MaxContentSizeOptions {
+  maxSize: number;
+}
+/**
+ * Enforce a maximum request body size while preserving access to the incoming stream.
+ *
+ * @example
+ * ```ts
+ * router.use(bodyLimit({maxSize: 1024 * 1024}))
+ * ```
+ *
+ * @param options - Configuration for maximum request body size enforcement.
+ * @returns Middleware that rejects oversized bodies and mismatched Content-Length values.
+ */
+declare function bodyLimit<Ctx extends object = AnyContext>(options: MaxContentSizeOptions): DeclaredMiddleware<{}, Ctx>;
+//#endregion
+//#region src/router/middleware/start-time-ctx.d.ts
+declare const startTimeCtx: () => ContextMiddleware<{
+  startTime: number;
+}>;
+//#endregion
+//#region src/router/middleware/accept-ctx.d.ts
+/**
+ * Attach parsed Accept header values to the request context.
+ *
+ * @returns Middleware that adds `accept` to the request context.
+ */
+declare const acceptCtx: () => ContextMiddleware<{
+  accept: AcceptMediaRange[];
+}>;
+//#endregion
+//#region src/router/middleware/cors.d.ts
+type CorsOriginResolver<Ctx extends object> = (origin: string | null, ctx: RequestContext<Ctx>) => MaybePromise<string | null | undefined | false>;
+type CorsMethodsResolver<Ctx extends object> = (origin: string | null, ctx: RequestContext<Ctx>) => MaybePromise<OneOrMany<string>>;
+interface CorsOptions<Ctx extends object = AnyContext> {
+  /**
+   * Allowed origin(s) for cross-origin requests.
+   * Use `'*'` to allow all origins.
+   */
+  origin: OneOrMany<string | URL | RegExp> | CorsOriginResolver<Ctx>;
+  /**
+   * Allowed methods to echo in preflight responses.
+   */
+  allowMethods?: OneOrMany<string> | CorsMethodsResolver<Ctx>;
+  /**
+   * Allowed headers to echo in preflight responses.
+   */
+  allowHeaders?: OneOrMany<string>;
+  /**
+   * Response headers that should be exposed to the browser.
+   */
+  exposeHeaders?: OneOrMany<string>;
+  /**
+   * Max age (seconds) for caching preflight responses.
+   */
+  maxAge?: number;
+  /**
+   * Whether to set Access-Control-Allow-Credentials.
+   */
+  credentials?: boolean;
+  /**
+   * Allow localhost and loopback origins for local development.
+   */
+  allowLocalhost?: boolean;
+  /**
+   * Convenience flag that enables localhost allowances.
+   */
+  dev?: boolean;
+  /**
+   * HTTP status to use for preflight responses.
+   */
+  preflightStatus?: number;
+}
+/**
+ * Attach CORS response headers and handle OPTIONS preflight requests.
+ *
+ * @example
+ * ```ts
+ * router.use(cors({origin: '*'}))
+ * router.use(cors({origin: ['https://app.example.com'], credentials: true}))
+ * router.use(cors({origin: 'https://app.example.com', dev: true}))
+ * ```
+ *
+ * @param options - Configuration for origin, preflight, and header behavior.
+ * @returns Middleware that applies CORS headers to matching requests.
+ */
+declare function cors<Ctx extends object = AnyContext>(options: CorsOptions<Ctx>): DeclaredMiddleware<{}, Ctx>;
+//#endregion
+//#region src/router/middleware/rate-limit.d.ts
+interface RateBucket {
+  windowMs: number;
+  scale: number;
+}
+interface AsnRecord {
+  asn: number;
+  organization: string;
+}
+interface RateLimitIdentityInput {
+  userId: string | number | null | undefined;
+  ipAddress: string;
+}
+type MethodLimit = number | Partial<Record<HttpMethod$1, number>>;
+interface EndpointLimit {
+  pattern: string | URLPattern | ConstructorParameters<typeof URLPattern>;
+  /**
+   * Max requests per baseWindowMs before bucket expansion.
+   */
+  limit: MethodLimit;
+}
+type AsnClass = 'cloud' | 'hosting' | 'cdn' | 'residential' | 'mobile' | 'unknown' | (string & {});
+interface FixedWindowCounter {
+  resetAtMs: number;
+  count: number;
+}
+interface RateLimitStorage<C> {
+  /**
+   * Return null/undefined if missing or expired.
+   */
+  readCounter(ctx: C, key: string): Promise<FixedWindowCounter | null | undefined>;
+  /**
+   * ttlMs MUST be respected by the implementation.
+   * Redis implementations should set key expiry accordingly.
+   */
+  writeCounter(ctx: C, key: string, counter: FixedWindowCounter, ttlMs: number): Promise<void>;
+}
+interface RateLimitOptions<C> {
+  getUserId(ctx: C): Promise<string | number | null | undefined>;
+  /**
+   * Default implementation:
+   * - X-Forwarded-For (first IP)
+   * - else X-Real-IP
+   */
+  getIpAddress?: (ctx: C) => Promise<string>;
+  /**
+   * Used to scale country + ASN caps.
+   * Called once during initialization.
+   */
+  getGlobalPeakConcurrentUsers(ctx: C): Promise<number>;
+  baseWindowMs: number;
+  baseMaxRequestsPerBaseWindow: number;
+  /**
+   * Applied when userId is falsy and identity falls back to IP.
+   */
+  anonymousIpMultiplier: number;
+  addRetryAfterHeader: boolean;
+  buckets: RateBucket[];
+  normalizeQuery?: (url: URL) => string;
+  endpointLimits: EndpointLimit[];
+  includeQueryInEndpointKey: boolean;
+  maxmindAsnDatabase?: string;
+  maxmindCountryDatabase?: string;
+  getAsn?(ctx: C, input: RateLimitIdentityInput): Promise<AsnRecord | null>;
+  getCountryCode?(ctx: C, input: RateLimitIdentityInput): Promise<string | null>;
+  asnToClass?: (asn: number, organization: string) => AsnClass;
+  scales: {
+    country?: Record<string, number> & {
+      unknown: number;
+      other: number;
+    };
+    asnClass?: Record<string, number> & {
+      unknown: number;
+    };
+    subnet: {
+      ipv4: number;
+      ipv6: number;
+      byAsnClass?: Record<string, number> & {
+        unknown: number;
+      };
+      ipv4Prefix?: number;
+      ipv6Prefix?: number;
+    };
+  };
+  /**
+   * If omitted, use in-memory LRU store.
+   */
+  storage?: RateLimitStorage<C>;
+  inMemory?: {
+    maxEntries?: number;
+    /**
+     * Extra retention (ms) after the fixed window reset before eviction.
+     * Defaults to 1000ms for a small safety buffer.
+     */
+    ttlMs?: number;
+  };
+}
+/**
+ * Enforce per-identity, subnet, ASN, country, and endpoint rate limits using fixed-window buckets.
+ *
+ * @example
+ * ```ts
+ * router.use(rateLimit({
+ *   getUserId: async ({user}) => user?.id,
+ *   getGlobalPeakConcurrentUsers: async () => 5000,
+ *   baseWindowMs: 60_000,
+ *   baseMaxRequestsPerBaseWindow: 120,
+ *   anonymousIpMultiplier: 0.5,
+ *   addRetryAfterHeader: true,
+ *   buckets: [{windowMs: 60_000, scale: 1}],
+ *   endpointLimits: [{pattern: '/login', limit: {POST: 10}}],
+ *   includeQueryInEndpointKey: false,
+ *   scales: {subnet: {ipv4: 2, ipv6: 1}},
+ * }))
+ * ```
+ *
+ * @param options - Configuration for identity sources, buckets, scaling, and storage.
+ * @returns Middleware that enforces rate limits and returns 429 responses when exceeded.
+ */
+declare function rateLimit<Ctx extends object = AnyContext>(options: RateLimitOptions<RequestContext<Ctx>>): DeclaredMiddleware<{}, Ctx>;
+//#endregion
+export { type AsnClass, type AsnRecord, type CorsOptions, type DeclaredMiddleware, type DefineMiddlewareOptions, type EndpointLimit, type FixedWindowCounter, type HttpMethod, type MethodLimit, type MiddlewareControls, type MiddlewareResponseDeclaration, type MiddlewareResponseDeclarations, type RateBucket, type RateLimitIdentityInput, type RateLimitOptions, type RateLimitStorage, type RequestIdCtxOptions, type RequestLoggerOptions, acceptCtx, bodyLimit, cors, defineMiddleware, formatRoutekitTerminalLogRecord, rateLimit, requestIdCtx, requestLogger, startTimeCtx, transformRoutekitJsonLogRecord };