bazis 0.96.1

package/core/http/Versioning/VersionReader.ts

@@ -0,0 +1,20 @@
+import type { ApiVersioningOptions } from "../options";
+
+/**
+ * Resolves the API version requested by the client. For the `"url"` source
+ * versions are static path segments (no per-request work, returns undefined);
+ * `"query"`/`"header"` read the configured parameter.
+ */
+export type VersionReader = (request: Request, url: URL) => string | undefined;
+
+export function createVersionReader(options: ApiVersioningOptions | undefined): VersionReader {
+  if (!options || options.source === "url") {
+    return () => undefined;
+  }
+  if (options.source === "query") {
+    const name = options.parameterName ?? "api-version";
+    return (_request, url) => url.searchParams.get(name) ?? options.defaultVersion;
+  }
+  const header = options.headerName ?? "x-api-version";
+  return (request) => request.headers.get(header) ?? options.defaultVersion;
+}

package/core/http/WebSocketUpgrade.ts

@@ -0,0 +1,29 @@
+import type { Server, WebSocketHandler } from "bun";
+import { createToken } from "../di";
+
+/**
+ * Port for sharing the HTTP listener with a WebSocket runtime (DIP): the HTTP
+ * module owns the `Bun.serve` loop and only knows this interface, while the
+ * `websocket` module provides the implementation. This keeps `@/core/http`
+ * free of any WebSocket imports.
+ *
+ * Contract of {@link tryUpgrade}:
+ * - `null`     — not a WebSocket request for us; continue normal HTTP handling.
+ * - `undefined`— the connection was upgraded; return nothing to Bun.
+ * - `Response` — reject the handshake with this response (e.g. 401/403).
+ */
+export interface WebSocketUpgrade {
+  /** Runs once before serving (adapter wiring, gateway `onGatewayInit`). */
+  initialize(): void | Promise<void>;
+  // The concrete connection-data generic lives in the websocket module; the
+  // HTTP layer stays agnostic, so `any` is used deliberately here.
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  tryUpgrade(request: Request, server: Server<any>): Promise<Response | undefined | null>;
+  /** The handler passed to `Bun.serve({ websocket })`. */
+  createBunHandler(): WebSocketHandler<any>;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+  close(): void | Promise<void>;
+}
+
+/** Optional: when registered, {@link HttpServer} shares its port for upgrades. */
+export const WEBSOCKET_UPGRADE = createToken<WebSocketUpgrade>("BazisWebSocketUpgrade");

package/core/http/composeRouteMiddlewareComposers.ts

@@ -0,0 +1,21 @@
+import type { RouteMiddlewareComposer } from "./options";
+
+/**
+ * Chains multiple route middleware composers (e.g. JWT auth + output cache).
+ *
+ * ```ts
+ * routeMiddlewareComposer: composeRouteMiddlewareComposers(
+ *   authorizationComposer,
+ *   otherComposer,
+ * ),
+ * ```
+ *
+ * Most modules instead self-wire via the `ROUTE_MIDDLEWARE_COMPOSER` DI token,
+ * which `httpModule` collects automatically.
+ */
+export function composeRouteMiddlewareComposers(
+  ...composers: readonly RouteMiddlewareComposer[]
+): RouteMiddlewareComposer {
+  return (controllerClass, methodName, httpMeta, action) =>
+    composers.flatMap((composer) => composer(controllerClass, methodName, httpMeta, action));
+}

package/core/http/correlation/createCorrelationIdMiddleware.ts

@@ -0,0 +1,79 @@
+import {
+  REQUEST_ID_HEADER,
+  REQUEST_ID_STATE_KEY,
+  TRACEPARENT_HEADER,
+  TRACEPARENT_STATE_KEY,
+  runWithRequestContextAsync,
+} from "../../kernel";
+import type { HttpMiddleware } from "../Middleware/types";
+
+export interface CorrelationIdMiddlewareOptions {
+  readonly headerName?: string;
+  readonly generateId?: () => string;
+  /** Validate an inbound request id. Default: conservative visible ASCII, max 128 chars. */
+  readonly validateIncomingId?: (value: string) => boolean;
+}
+
+const DEFAULT_REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:@/+\-=]{0,127}$/;
+const TRACEPARENT = /^[\da-f]{2}-([\da-f]{32})-([\da-f]{16})-[\da-f]{2}(?:-[\x21-\x7e]+)?$/i;
+
+/**
+ * Ensures one correlation ID per HTTP request: reads `x-request-id` or
+ * generates a UUID, stores it on {@link HttpContext.state}, echoes it on the
+ * response, and binds it to async local storage for application logs.
+ */
+export function createCorrelationIdMiddleware(
+  options: CorrelationIdMiddlewareOptions = {},
+): HttpMiddleware {
+  const headerName = options.headerName ?? REQUEST_ID_HEADER;
+  const generateId = options.generateId ?? (() => crypto.randomUUID());
+  const validateIncomingId = options.validateIncomingId ?? ((value: string) => DEFAULT_REQUEST_ID.test(value));
+
+  return async (ctx, next) => {
+    const incoming = ctx.header(headerName);
+    const trimmedIncoming = incoming?.trim();
+    const generated = (): string => {
+      const value = generateId().trim();
+      return validateIncomingId(value) ? value : crypto.randomUUID();
+    };
+    const requestId = trimmedIncoming && validateIncomingId(trimmedIncoming) ? trimmedIncoming : generated();
+    ctx.state.set(REQUEST_ID_STATE_KEY, requestId);
+
+    const traceparent = ctx.header(TRACEPARENT_HEADER);
+    const normalizedTraceparent = normalizeTraceparent(traceparent);
+    if (normalizedTraceparent !== undefined) {
+      ctx.state.set(TRACEPARENT_STATE_KEY, normalizedTraceparent);
+    }
+
+    const context = {
+      requestId,
+      ...(normalizedTraceparent !== undefined ? { traceparent: normalizedTraceparent } : {}),
+    };
+
+    await runWithRequestContextAsync(context, async () => {
+      await next();
+    });
+
+    if (ctx.response !== undefined && !ctx.response.headers.has(headerName)) {
+      const headers = new Headers(ctx.response.headers);
+      headers.set(headerName, requestId);
+      ctx.response = new Response(ctx.response.body, {
+        status: ctx.response.status,
+        statusText: ctx.response.statusText,
+        headers,
+      });
+    }
+  };
+}
+
+function normalizeTraceparent(value: string | undefined): string | undefined {
+  if (value === undefined || value.length > 512) {
+    return undefined;
+  }
+  const normalized = value.trim().toLowerCase();
+  const match = TRACEPARENT.exec(normalized);
+  if (!match || match[1] === "0".repeat(32) || match[2] === "0".repeat(16) || normalized.startsWith("ff-")) {
+    return undefined;
+  }
+  return normalized;
+}

package/core/http/httpModule.ts

@@ -0,0 +1,48 @@
+import { DI, HOSTED_SERVICE, Module, SERVICE_PROVIDER, collectModuleControllers, type BazisModule, type ProviderDefinition } from "../di";
+import { HttpServer } from "./HttpServer";
+import type { HttpModuleOptions } from "./options";
+
+/**
+ * Builds the HTTP module: discovers controllers from `imports` (and optional
+ * `controllers` on feature modules) and registers the HttpServer hosted service.
+ *
+ * ```ts
+ * @Module({
+ *   controllers: [UsersController],
+ *   providers: [scoped(IUserStore, UserService, [repositoryFor(User)] as const)],
+ * })
+ * export class UsersModule {}
+ *
+ * export const AppModule = createApp({
+ *   imports: [UsersModule],
+ *   http: { port: 3000, prefix: "api" },
+ * }).module;
+ *
+ * await Bazis.run(AppModule);
+ * ```
+ */
+export function httpModule(options: HttpModuleOptions): BazisModule {
+  const allControllers = collectModuleControllers(options.imports ?? [], options.controllers);
+
+  const serverOptions: HttpModuleOptions = {
+    ...options,
+    controllers: allControllers,
+  };
+
+  const providers: ProviderDefinition[] = [
+    DI.singleton(
+      DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => {
+        return new HttpServer(serverOptions, resolver.resolve(SERVICE_PROVIDER), resolver);
+      }),
+    ),
+  ];
+
+  @Module({
+    imports: options.imports,
+    providers,
+    controllers: options.controllers,
+  })
+  class HttpModule {}
+
+  return HttpModule;
+}

package/core/http/index.ts

@@ -0,0 +1,140 @@
+/**
+ * HTTP module of the Bazis framework (ASP.NET Core-inspired).
+ *
+ * Controllers are classes with TC39 decorators; routes are compiled into a
+ * radix tree at startup; every request runs in its own DI scope. No external
+ * dependencies, compatible with `bun build --compile`.
+ */
+export { httpModule } from "./httpModule";
+export { HttpServer } from "./HttpServer";
+export { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
+export type {
+  ApiVersioningOptions,
+  HealthEndpointOptions,
+  HttpModuleOptions,
+  RouteMiddlewareComposer,
+} from "./options";
+export type { OpenApiDocsOptions } from "../../library/openapi";
+export { composeRouteMiddlewareComposers } from "./composeRouteMiddlewareComposers";
+export {
+  HTTP_ERROR_HOOK,
+  ROUTE_MIDDLEWARE_COMPOSER,
+  SERVER_MIDDLEWARE,
+  sortByOrder,
+  type HttpErrorHook,
+  type RouteMiddlewareComposerRegistration,
+  type ServerMiddlewareRegistration,
+} from "./middlewareTokens";
+
+// HttpContext
+export { HttpContext, type RouteParams } from "./HttpContext/HttpContext";
+export { ResponseBuilder } from "./HttpContext/ResponseBuilder";
+export { PRINCIPAL_STATE_KEY, type RequestPrincipal } from "./HttpContext/principal";
+
+// Authorization
+export { Authorize, AllowAnonymous } from "./Authorization/Authorize";
+export { createAuthorizeComposer } from "./Authorization/authorizeComposer";
+export {
+  resolveAuthorizeMeta,
+  type AuthorizeCheck,
+  type AuthorizeOptions,
+  type ResolvedAuthorizeMeta,
+} from "./Authorization/metadata";
+
+// Decorators
+export { Controller } from "./Decorators/controller";
+export { All, Delete, Get, Head, Options, Patch, Post, Put, type RouteOptions } from "./Decorators/routes";
+export {
+  ActionFilter,
+  ApiVersion,
+  Catch,
+  Consumes,
+  HttpCode,
+  Middleware,
+  Produces,
+} from "./Decorators/attributes";
+
+// Binding
+export type { BindingSource, ParameterBinding } from "./Binding/bindings";
+export type { ValueType } from "./Binding/convert";
+export { RequestModel } from "./Binding/RequestModel";
+
+// Universal list request (sorting/filtering/paging): a declarative
+// request class bound by signature. Engine and types live in `@/library/jsonapi`.
+export {
+  ListRequest,
+  Filterable,
+  ListOptions,
+  Sortable,
+  buildListDocument,
+  serializeListQuery,
+  type BuildListDocumentOptions,
+  type FilterOperator,
+  type ListDocument,
+  type ListQuery,
+} from "../../library/jsonapi";
+export {
+  AMBIGUOUS_REQUEST_MODEL,
+  findRequestModelByName,
+  findRequestModelShape,
+  registerRequestModelClass,
+  registerRequestModelShape,
+  type RequestModelFieldShape,
+  type RequestModelNestedFieldShape,
+  type RequestModelPrimitive,
+  type RequestModelPrimitiveFieldShape,
+  type RequestModelClass,
+  type RequestModelShape,
+} from "./Binding/requestModelRegistry";
+export {
+  useModelValidator,
+  getModelValidator,
+  type ModelValidator,
+  type ModelValidationIssue,
+} from "./Binding/modelValidator";
+
+// Results
+export { HttpResult } from "./Results/HttpResult";
+export {
+  Accepted,
+  BadRequest,
+  Conflict,
+  Created,
+  File,
+  Forbidden,
+  InternalServerError,
+  NoContent,
+  NotFound,
+  Ok,
+  Redirect,
+  StatusCode,
+  Unauthorized,
+} from "./Results/results";
+
+// Middleware
+export { accessLog, type AccessLogEntry, type AccessLogOptions } from "./Middleware/accessLog";
+export { cors, type CorsOptions } from "./Middleware/cors";
+export { createCorrelationIdMiddleware, type CorrelationIdMiddlewareOptions } from "./correlation/createCorrelationIdMiddleware";
+export { errorHandler, type ErrorHandlerOptions } from "./Middleware/errorHandler";
+export { rateLimit, type RateLimitOptions } from "./Middleware/rateLimit";
+export {
+  securityHeaders,
+  type HstsOptions,
+  type SecurityHeadersOptions,
+} from "./Middleware/securityHeaders";
+export type { ActionFilterHooks, HttpMiddleware } from "./Middleware/types";
+
+// Errors
+export {
+  BadRequestError,
+  ForbiddenError,
+  HttpError,
+  HttpSetupError,
+  MethodNotAllowedError,
+  ModelValidationError,
+  NotFoundError,
+  PayloadTooLargeError,
+  TooManyRequestsError,
+  UnauthorizedError,
+  UnsupportedMediaTypeError,
+} from "./Errors/HttpError";

package/core/http/middlewareTokens.ts

@@ -0,0 +1,48 @@
+import { createToken } from "../di";
+import type { HttpContext } from "./HttpContext/HttpContext";
+import type { HttpMiddleware } from "./Middleware/types";
+import type { RouteMiddlewareComposer } from "./options";
+
+/**
+ * Server-wide middleware contributed through DI (self-wiring): a module just
+ * registers a {@link SERVER_MIDDLEWARE} provider and `httpModule` collects all
+ * of them via `resolveAll` — no return values threaded by hand.
+ */
+export interface ServerMiddlewareRegistration {
+  /** Lower runs more outer/earlier (default 0). */
+  readonly order?: number;
+  readonly middleware: HttpMiddleware;
+}
+
+/** Per-route middleware composer contributed through DI (self-wiring). */
+export interface RouteMiddlewareComposerRegistration {
+  /** Lower runs first (default 0). */
+  readonly order?: number;
+  readonly compose: RouteMiddlewareComposer;
+}
+
+/** Enumerable token: register any number of server middleware contributions. */
+export const SERVER_MIDDLEWARE = createToken<ServerMiddlewareRegistration>("BazisServerMiddleware");
+
+/** Enumerable token: register any number of route middleware composers. */
+export const ROUTE_MIDDLEWARE_COMPOSER = createToken<RouteMiddlewareComposerRegistration>(
+  "BazisRouteMiddlewareComposer",
+);
+
+/**
+ * Hook invoked by the built-in error boundary on a non-{@link HttpError}
+ * failure. Self-wiring: e.g. the logging module registers one to record the
+ * error, keeping `@/core/http` free of logging imports. Collected via `resolveAll`.
+ */
+export type HttpErrorHook = (ctx: HttpContext, error: unknown) => void;
+
+/** Enumerable token: register any number of unexpected-error hooks. */
+export const HTTP_ERROR_HOOK = createToken<HttpErrorHook>("BazisHttpErrorHook");
+
+/** Stable order by `order ?? 0` (registration order preserved within a tier). */
+export function sortByOrder<T extends { readonly order?: number }>(items: readonly T[]): T[] {
+  return [...items]
+    .map((item, index) => ({ item, index }))
+    .sort((a, b) => (a.item.order ?? 0) - (b.item.order ?? 0) || a.index - b.index)
+    .map(({ item }) => item);
+}

package/core/http/options.ts

@@ -0,0 +1,134 @@
+import type { Class } from "../di";
+import type { AccessLogOptions } from "./Middleware/accessLog";
+import type { CorsOptions } from "./Middleware/cors";
+import type { ErrorHandlerOptions } from "./Middleware/errorHandler";
+import type { SecurityHeadersOptions } from "./Middleware/securityHeaders";
+import type { HttpMiddleware } from "./Middleware/types";
+import type { ActionMeta, ControllerMeta } from "./Decorators/metadata";
+import type { OpenApiDocsOptions } from "../../library/openapi";
+import type { ModelValidator } from "./Binding/modelValidator";
+
+/** Built-in health endpoint (liveness/readiness probe). */
+export interface HealthEndpointOptions {
+  /** Absolute path served outside routing/pipeline (default "/health"). */
+  readonly path?: string;
+  /** Include check-provided diagnostic details. Default: false. */
+  readonly exposeDetails?: boolean;
+  /** Maximum time for the aggregate health check. Default: 5000ms. `0` disables it. */
+  readonly timeoutMs?: number;
+  /** Cache a completed report for this many milliseconds. Default: 0 (single-flight only). */
+  readonly cacheMs?: number;
+}
+
+/** Composes per-route middleware from controller metadata at startup (e.g. JWT authorization). */
+export type RouteMiddlewareComposer = (
+  controllerClass: Class<object>,
+  methodName: string | symbol,
+  httpMeta: ControllerMeta,
+  action: ActionMeta,
+) => readonly HttpMiddleware[];
+
+/** How the requested API version is read. */
+export interface ApiVersioningOptions {
+  /**
+   * - `"url"` — version is a path segment: `/api/v1.0/users` (fastest:
+   *   static match, default);
+   * - `"query"` — `?api-version=1.0` (parameter name configurable);
+   * - `"header"` — custom header (default `x-api-version`).
+   */
+  readonly source: "url" | "query" | "header";
+  /** Query parameter name for `source: "query"` (default "api-version"). */
+  readonly parameterName?: string;
+  /** Header name for `source: "header"` (default "x-api-version"). */
+  readonly headerName?: string;
+  /** Version assumed when the request does not specify one. */
+  readonly defaultVersion?: string;
+}
+
+export interface HttpModuleOptions {
+  /**
+   * Permit explicitly negotiated redirects for exact browser-side limits.
+   * The HttpClient must also enable inspectableRedirects. Default: false.
+   * Authorized/CORS-allowed clients can then inspect each redirect Location.
+   */
+  readonly inspectableRedirects?: boolean;
+  /**
+   * Controller classes (decorated with @Controller). Optional when controllers
+   * are declared on imported modules via `controllers` on `BazisModule`.
+   */
+  readonly controllers?: readonly Class<object>[];
+  /** Request-model validator captured by this HTTP server instance. */
+  readonly validator?: ModelValidator;
+  /**
+   * Modules providing the controllers' dependencies. Controllers live inside
+   * the returned HttpModule, so their dependencies must be visible to it:
+   * either listed here or exported by global modules.
+   */
+  readonly imports?: readonly import("../di").BazisModuleRef[];
+  /** Listen port (default 3000; 0 — random free port). */
+  readonly port?: number;
+  readonly hostname?: string;
+  /** Global route prefix, e.g. "api". */
+  readonly prefix?: string;
+  /** Global middleware (after the built-in error handler, before controller ones). */
+  readonly middleware?: readonly HttpMiddleware[];
+  /**
+   * Per-route middleware inserted after controller/action middleware, argument
+   * binding and `ActionFilter.before`, but before controller/action execution.
+   * Built-in `@Authorize` runs before controller middleware and therefore also
+   * ahead of any composer provided here.
+   */
+  readonly routeMiddlewareComposer?: RouteMiddlewareComposer;
+  /** Global CORS: response headers + automatic preflight answers. `false` (default) — off. */
+  readonly cors?: CorsOptions | false;
+  /**
+   * Security response headers (secure-by-default). Enabled with conservative
+   * defaults when omitted; pass an object to tune (HSTS/CSP are opt-in) or
+   * `false` to disable entirely.
+   */
+  readonly securityHeaders?: SecurityHeadersOptions | false;
+  /** Options for the built-in error boundary (e.g. logging hook from hosting). */
+  readonly errorHandler?: ErrorHandlerOptions;
+  /** API versioning; required to honor @ApiVersion (default: url source when any controller is versioned). */
+  readonly versioning?: ApiVersioningOptions;
+  /**
+   * Include error details in 500 responses. Default: `Environment.debug`
+   * when the kernel is present, otherwise false.
+   */
+  readonly exposeErrorDetails?: boolean;
+  /**
+   * Max request body size in bytes. Requests advertising a larger
+   * `Content-Length` get a clean 413 before the body is read; unsized/chunked
+   * bodies are capped while framework body readers consume the stream.
+   * Default: 1 MiB. `0` disables the framework check.
+   */
+  readonly maxBodyBytes?: number;
+  /** Per-connection idle timeout in seconds (Bun.serve, 0–255). Default: Bun's. */
+  readonly idleTimeoutSeconds?: number;
+  /** Maximum wait for request-scope disposal. Default 5000ms; `0` restores an unbounded wait. */
+  readonly requestScopeDisposeTimeoutMs?: number;
+  /**
+   * Built-in health endpoint. `true` serves `/health`; pass an object to set
+   * the path. Resolves the kernel `HealthService` (200 healthy / 503 unhealthy);
+   * bypasses application routing/middleware but retains built-in error handling,
+   * security/CORS headers and access logging.
+   */
+  readonly health?: HealthEndpointOptions | boolean;
+  /**
+   * Built-in generated API docs. No user-facing Swagger decorators are needed:
+   * `bun run di:generate` derives request models and schemas from controllers.
+   *
+   * Default: enabled in debug environments, disabled in production. `true`
+   * serves `/docs` and `/docs/openapi.json`; pass an object to change paths or
+   * title/version.
+   */
+  readonly docs?: OpenApiDocsOptions | boolean;
+  /**
+   * Access log for every request (method, path, status, duration, correlation
+   * id). `true` enables the default single-line sink; pass an object to plug a
+   * structured sink or skip predicate. Installed outermost.
+   */
+  readonly accessLog?: AccessLogOptions | boolean;
+  /** Hosted-service startup phase (default 10 — after infrastructure). */
+  readonly phase?: number;
+}

package/core/http-client/index.ts

@@ -0,0 +1,105 @@
+/**
+ * Core DI/correlation integration for the pure `@/library/http-client`.
+ *
+ * The HTTP engine lives in the library (framework-agnostic). This module only
+ * wires it into the runtime: DI tokens, a module factory, and kernel-based
+ * correlation propagation. All library symbols are re-exported for convenience.
+ *
+ * ```ts
+ * import { httpClientModule, HTTP_CLIENT } from "@/core/http-client";
+ *
+ * @Module({ imports: [httpClientModule({ default: { baseUrl: "https://api" } })] })
+ * class AppModule {}
+ * ```
+ */
+import { DI, Module, createToken, type BazisModule, type ProviderDefinition } from "../di";
+import { getOutboundCorrelationHeaders } from "../kernel";
+import {
+  HttpClient,
+  HttpClientFactoryBuilder,
+  type HttpClientFactory,
+  type HeaderBag,
+  type RequestConfig,
+} from "../../library/http-client";
+
+export * from "../../library/http-client";
+
+/** Named-clients factory token. */
+export const HTTP_CLIENT_FACTORY = createToken<HttpClientFactory>("IHttpClientFactory");
+/** Default injectable {@link HttpClient} token. */
+export const HTTP_CLIENT = createToken<HttpClient>("HttpClient");
+
+export interface HttpClientModuleConfig {
+  /** Named clients resolvable via `HTTP_CLIENT_FACTORY.createClient(name)`. */
+  readonly clients?: Readonly<Record<string, RequestConfig>>;
+  /** Defaults for the injectable {@link HTTP_CLIENT} and `createClient()`. */
+  readonly default?: RequestConfig;
+  /** Correlation header source. Default: the kernel async request context. */
+  readonly correlationHeaders?: () => HeaderBag;
+  /** Default per-request timeout in ms (server-side safety). Default: 30000. */
+  readonly timeoutMs?: number;
+  /** Default maximum response body size. Default: 16 MiB. `0` disables it. */
+  readonly maxResponseBytes?: number;
+}
+
+/**
+ * Registers the outbound HTTP client in DI with correlation propagation wired
+ * to the kernel request context:
+ * - {@link HTTP_CLIENT_FACTORY} — named clients (fail-fast on unknown names);
+ * - {@link HTTP_CLIENT} — the default injectable {@link HttpClient}.
+ */
+export function httpClientModule(config: HttpClientModuleConfig = {}): BazisModule {
+  const correlationHeaders = config.correlationHeaders ?? getOutboundCorrelationHeaders;
+  const moduleTimeoutMs = resolveLimit(config.timeoutMs, 30_000, "httpClientModule timeoutMs");
+  const moduleMaxResponseBytes = resolveLimit(
+    config.maxResponseBytes,
+    16 * 1024 * 1024,
+    "httpClientModule maxResponseBytes",
+  );
+  const defaultConfig = config.default ?? {};
+  const defaults: RequestConfig = {
+    ...defaultConfig,
+    timeoutMs: resolveLimit(defaultConfig.timeoutMs, moduleTimeoutMs, "httpClientModule default.timeoutMs"),
+    maxResponseBytes: resolveLimit(
+      defaultConfig.maxResponseBytes,
+      moduleMaxResponseBytes,
+      "httpClientModule default.maxResponseBytes",
+    ),
+    correlationHeaders: defaultConfig.correlationHeaders ?? correlationHeaders,
+  };
+
+  const builder = new HttpClientFactoryBuilder();
+  builder.useDefault(defaults);
+  for (const [name, clientConfig] of Object.entries(config.clients ?? {})) {
+    builder.addClient(name, {
+      ...clientConfig,
+      timeoutMs: resolveLimit(clientConfig.timeoutMs, defaults.timeoutMs!, `httpClientModule clients.${name}.timeoutMs`),
+      maxResponseBytes: resolveLimit(
+        clientConfig.maxResponseBytes,
+        defaults.maxResponseBytes!,
+        `httpClientModule clients.${name}.maxResponseBytes`,
+      ),
+    });
+  }
+  const factory = builder.build();
+
+  const providers: ProviderDefinition[] = [
+    DI.singleton(DI.valueProvider(HTTP_CLIENT_FACTORY, factory)),
+    DI.singleton(
+      DI.factoryProvider(HTTP_CLIENT, [HTTP_CLIENT_FACTORY], (resolved: HttpClientFactory) => resolved.createClient()),
+    ),
+  ];
+
+  @Module({ providers })
+  class HttpClientModule {}
+
+  return HttpClientModule;
+}
+
+function resolveLimit(value: number | undefined, fallback: number, field: string): number {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 0) {
+    throw new TypeError(`${field} must be a non-negative safe integer`);
+  }
+  return resolved;
+}