bazis 0.96.1

package/core/http/OpenApi/generatedOpenApiRegistry.ts

@@ -0,0 +1,102 @@
+import type { GeneratedOpenApiMetadata, GeneratedOpenApiOperationMetadata, OpenApiSchema } from "../../../library/openapi";
+
+export type GeneratedOpenApiSchemaModel = abstract new (...args: never[]) => object;
+
+const EMPTY_GENERATED_OPENAPI_METADATA: GeneratedOpenApiMetadata = Object.freeze({
+  schemas: Object.freeze({}),
+  operations: Object.freeze({}),
+});
+
+interface GeneratedOpenApiTargetSlice {
+  readonly metadata: GeneratedOpenApiMetadata;
+  readonly controllers?: ReadonlySet<abstract new (...args: never[]) => object>;
+}
+
+let registered: GeneratedOpenApiTargetSlice[] = [];
+let schemaNamesByModel = new Map<GeneratedOpenApiSchemaModel, string>();
+
+export function registerGeneratedOpenApiMetadata(
+  metadata: GeneratedOpenApiMetadata,
+  controllers?: readonly (abstract new (...args: never[]) => object)[],
+): void {
+  if (metadata === EMPTY_GENERATED_OPENAPI_METADATA || registered.some((entry) => entry.metadata === metadata)) {
+    return;
+  }
+  registered.push({ metadata, ...(controllers === undefined ? {} : { controllers: new Set(controllers) }) });
+}
+
+/**
+ * Binds a real runtime model constructor to the exact generated component
+ * schema. This is the nominal bridge used by code-first consumers such as
+ * @UiProfile; they must not rediscover schemas through `ctor.name`.
+ */
+export function registerGeneratedOpenApiSchemaModel(
+  model: GeneratedOpenApiSchemaModel,
+  schemaName: string,
+): void {
+  const normalized = schemaName.trim();
+  if (normalized.length === 0) {
+    throw new TypeError("Generated OpenAPI schema model name must not be empty.");
+  }
+  const existing = schemaNamesByModel.get(model);
+  if (existing !== undefined && existing !== normalized) {
+    throw new TypeError(
+      `OpenAPI model ${model.name || "<anonymous>"} is already bound to schema ${existing}; ` +
+        `cannot also bind it to ${normalized}.`,
+    );
+  }
+  schemaNamesByModel.set(model, normalized);
+}
+
+/** Exact generated component schema name for a runtime model constructor. */
+export function getGeneratedOpenApiSchemaName(
+  model: GeneratedOpenApiSchemaModel,
+): string | undefined {
+  return schemaNamesByModel.get(model);
+}
+
+export function getGeneratedOpenApiMetadata(controllers?: readonly (abstract new (...args: never[]) => object)[]): GeneratedOpenApiMetadata {
+  const requested = controllers === undefined ? undefined : new Set(controllers);
+  const selected = requested === undefined
+    ? registered
+    : registered.filter((entry) => entry.controllers === undefined || [...requested].some((controller) => entry.controllers?.has(controller) === true));
+  if (selected.length === 0) {
+    return EMPTY_GENERATED_OPENAPI_METADATA;
+  }
+
+  const schemas: Record<string, OpenApiSchema> = {};
+  const operations: Record<string, Record<string, GeneratedOpenApiOperationMetadata>> = {};
+  for (let index = 0; index < selected.length; index += 1) {
+    const metadata = selected[index]!.metadata;
+    Object.assign(schemas, metadata.schemas);
+    for (const [controllerName, methods] of Object.entries(metadata.operations)) {
+      operations[controllerName] ??= {};
+      Object.assign(operations[controllerName], methods);
+    }
+  }
+
+  return Object.freeze({
+    schemas: Object.freeze(schemas),
+    operations: Object.freeze(operations),
+  });
+}
+
+/** Internal generated-runtime transaction support. */
+export function snapshotGeneratedOpenApiRegistry(): { readonly registered: readonly GeneratedOpenApiTargetSlice[]; readonly schemaNamesByModel: typeof schemaNamesByModel } {
+  return {
+    registered: registered.map((entry) => ({
+      metadata: entry.metadata,
+      ...(entry.controllers === undefined ? {} : { controllers: new Set(entry.controllers) }),
+    })),
+    schemaNamesByModel: new Map(schemaNamesByModel),
+  };
+}
+
+/** Internal generated-runtime transaction support. */
+export function restoreGeneratedOpenApiRegistry(snapshot: ReturnType<typeof snapshotGeneratedOpenApiRegistry>): void {
+  registered = snapshot.registered.map((entry) => ({
+    metadata: entry.metadata,
+    ...(entry.controllers === undefined ? {} : { controllers: new Set(entry.controllers) }),
+  }));
+  schemaNamesByModel = snapshot.schemaNamesByModel;
+}

package/core/http/OpenApi/openApiDocs.ts

@@ -0,0 +1,75 @@
+import type { Class } from "../../di";
+import { Environment } from "../../kernel";
+import {
+  renderOpenApiHtml,
+  serveOpenApiDocs,
+  type OpenApiDocsOptions,
+  type PreparedOpenApiDocs,
+} from "../../../library/openapi";
+import { buildHttpOpenApiDocument } from "./openApiDocument";
+import type { ApiVersioningOptions } from "../options";
+
+interface PrepareOpenApiDocsInput {
+  readonly option?: OpenApiDocsOptions | boolean;
+  readonly controllers: readonly Class<object>[];
+  readonly globalPrefix?: string;
+  readonly versioning?: ApiVersioningOptions;
+  readonly environment?: Environment;
+}
+
+const DEFAULT_UI_PATH = "/docs";
+const DEFAULT_TITLE = "Bazis API";
+const DEFAULT_VERSION = "1.0.0";
+
+export { serveOpenApiDocs };
+
+export function prepareOpenApiDocs(input: PrepareOpenApiDocsInput): PreparedOpenApiDocs | undefined {
+  if (!isEnabled(input.option, input.environment)) {
+    return undefined;
+  }
+  const options = normalizeOptions(input.option);
+  const uiPath = normalizeAbsolutePath(options.path ?? DEFAULT_UI_PATH);
+  const specPath = normalizeAbsolutePath(options.specPath ?? joinDocsPath(uiPath, "openapi.json"));
+  const title = options.title ?? DEFAULT_TITLE;
+  const version = options.version ?? DEFAULT_VERSION;
+  const document = buildHttpOpenApiDocument({
+    controllers: input.controllers,
+    globalPrefix: input.globalPrefix,
+    versioning: input.versioning,
+    title,
+    version,
+  });
+  const json = JSON.stringify(document, null, 2);
+  return {
+    uiPath,
+    specPath,
+    document,
+    json,
+    html: renderOpenApiHtml(title, specPath),
+  };
+}
+
+function isEnabled(option: OpenApiDocsOptions | boolean | undefined, environment: Environment | undefined): boolean {
+  if (typeof option === "boolean") {
+    return option;
+  }
+  if (option !== undefined) {
+    return option.enabled ?? true;
+  }
+  return environment?.debug ?? false;
+}
+
+function normalizeOptions(option: OpenApiDocsOptions | boolean | undefined): OpenApiDocsOptions {
+  return typeof option === "object" && option !== null ? option : {};
+}
+
+function normalizeAbsolutePath(path: string): string {
+  const trimmed = path.trim();
+  const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const parts = prefixed.split("/").filter((part) => part.length > 0);
+  return `/${parts.join("/")}`;
+}
+
+function joinDocsPath(base: string, child: string): string {
+  return `${base.replace(/\/+$/, "")}/${child.replace(/^\/+/, "")}`;
+}

package/core/http/OpenApi/openApiDocument.ts

@@ -0,0 +1,356 @@
+import type { Class } from "../../di";
+import { createHash } from "node:crypto";
+import {
+  buildOpenApiDocument,
+  type OpenApiCatalogOperation,
+  type OpenApiDocumentBuildInput as LibraryOpenApiDocumentBuildInput,
+  type OpenApiParameter,
+  type OpenApiSchema,
+} from "../../../library/openapi";
+import { optionsFromSchema } from "../../../library/jsonapi";
+import { resolveAuthorizeMeta } from "../Authorization/metadata";
+import type { ParameterBinding } from "../Binding/bindings";
+import { resolveGeneratedBindings } from "../Binding/autoBindings";
+import { controllerMetaOf, type ActionMeta, type ControllerMeta } from "../Decorators/metadata";
+import { joinPaths } from "../Routing/template";
+import { getGeneratedOpenApiMetadata } from "./generatedOpenApiRegistry";
+import type { ApiVersioningOptions } from "../options";
+import type { GeneratedOpenApiMetadata } from "../../../library/openapi";
+
+export interface HttpOpenApiDocumentBuildInput {
+  readonly controllers: readonly Class<object>[];
+  readonly globalPrefix?: string;
+  readonly versioning?: ApiVersioningOptions;
+  readonly title: string;
+  readonly version: string;
+}
+
+export function buildHttpOpenApiDocument(input: HttpOpenApiDocumentBuildInput): OpenApiSchema {
+  const generated = getGeneratedOpenApiMetadata(input.controllers);
+  const documentInput: LibraryOpenApiDocumentBuildInput = {
+    title: input.title,
+    version: input.version,
+    schemas: generated.schemas,
+    operations: collectOpenApiOperations(input, generated),
+    generatedBy: "bazis:di-generate",
+  };
+  return buildOpenApiDocument(documentInput);
+}
+
+function collectOpenApiOperations(
+  input: HttpOpenApiDocumentBuildInput,
+  generated: GeneratedOpenApiMetadata,
+): OpenApiCatalogOperation[] {
+  const operations: OpenApiCatalogOperation[] = [];
+  for (const controllerClass of input.controllers) {
+    const meta = controllerMetaOf(controllerClass);
+    if (!meta?.isController) {
+      continue;
+    }
+    for (const [methodName, action] of meta.actions) {
+      if (action.routes.length === 0) {
+        continue;
+      }
+      const bindings = resolveGeneratedBindings(controllerClass, methodName) ?? [];
+      for (const route of action.routes) {
+        operations.push(createOperation({
+          controllerClass,
+          methodName,
+          meta,
+          action,
+          bindings,
+          httpMethod: route.httpMethod,
+          path: fullOpenApiPath(input.globalPrefix, input.versioning?.source, meta, action, route.template),
+          routeTemplate: joinPaths(meta.prefix, route.template),
+          versioning: input.versioning,
+          generated,
+        }));
+      }
+    }
+  }
+  return operations;
+}
+
+interface CreateOperationInput {
+  readonly controllerClass: Class<object>;
+  readonly methodName: string | symbol;
+  readonly meta: ControllerMeta;
+  readonly action: ActionMeta;
+  readonly bindings: readonly ParameterBinding[];
+  readonly httpMethod: string;
+  readonly path: string;
+  readonly routeTemplate: string;
+  readonly versioning?: ApiVersioningOptions;
+  readonly generated: GeneratedOpenApiMetadata;
+}
+
+function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
+  const methodName = String(input.methodName);
+  const version = input.action.version ?? input.meta.version;
+  const auth = resolveAuthorizeMeta(input.controllerClass, input.methodName);
+  const generatedOperation = input.generated.operations[input.controllerClass.name]?.[methodName];
+  const status = String(successStatus(input.httpMethod, input.action));
+  const responseSchema = generatedOperation?.response;
+  const contentType = input.action.produces ?? "application/json";
+
+  return {
+    path: input.path,
+    httpMethod: input.httpMethod,
+    tag: tagName(input.meta, input.controllerClass),
+    operationId: stableHttpOperationId(input.httpMethod, input.path),
+    summary: `${normalizedMethod(input.httpMethod)} ${input.path}`,
+    parameters: collectParameters(
+      input.bindings,
+      input.versioning,
+      version,
+      routeParamSchemas(input.routeTemplate),
+    ),
+    requestBody: createRequestBody(input.bindings, input.action, input.generated),
+    responses: {
+      [status]: responseSchema && status !== "204"
+        ? {
+            description: "Success",
+            content: {
+              [contentType]: {
+                schema: responseSchema,
+              },
+            },
+          }
+        : { description: "Success" },
+    },
+    authorized: !auth.allowAnonymous && auth.authorize !== undefined,
+    ...(version !== undefined ? { versions: [version] } : {}),
+  };
+}
+
+/**
+ * Stable transport identity owned by HTTP/OpenAPI. Controller and handler
+ * names are intentionally excluded: renaming implementation symbols must not
+ * invalidate compiled UI references or generated clients.
+ */
+function stableHttpOperationId(httpMethod: string, canonicalPath: string): string {
+  const method = normalizedMethod(httpMethod).toLowerCase();
+  const slug = readableOperationPath(canonicalPath);
+  const digest = createHash("sha256")
+    .update(JSON.stringify([method, canonicalPath]))
+    .digest("hex")
+    .slice(0, 32);
+  return `http_${method}_${slug}__${digest}`;
+}
+
+function readableOperationPath(path: string): string {
+  const slug = path
+    .replace(/\{([^{}]+)\}/g, " by $1 ")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 80)
+    .replace(/_+$/g, "");
+  return slug.length > 0 ? slug : "root";
+}
+
+function collectParameters(
+  bindings: readonly ParameterBinding[],
+  versioning: ApiVersioningOptions | undefined,
+  version: string | undefined,
+  routeSchemas: Readonly<Record<string, OpenApiSchema>>,
+): OpenApiParameter[] {
+  const parameters: OpenApiParameter[] = [];
+  for (const binding of bindings) {
+    switch (binding.source) {
+      case "route":
+        if (binding.name) {
+          parameters.push({
+            name: binding.name,
+            in: "path",
+            required: true,
+            schema: routeSchemas[binding.name] ?? schemaForValueType(binding.type),
+          });
+        }
+        break;
+      case "query":
+        if (binding.name) {
+          parameters.push({
+            name: binding.name,
+            in: "query",
+            required: binding.optional !== true && binding.defaultValue === undefined,
+            schema: schemaForValueType(binding.type),
+          });
+        }
+        break;
+      case "list":
+        parameters.push(...listParameters(binding));
+        break;
+      default:
+        break;
+    }
+  }
+  if (version !== undefined && versioning !== undefined && versioning.source !== "url") {
+    const name = versioning.source === "query" ? (versioning.parameterName ?? "api-version") : (versioning.headerName ?? "x-api-version");
+    parameters.push({
+      name,
+      in: versioning.source,
+      required: versioning.defaultVersion === undefined,
+      schema: { type: "string", enum: [version] },
+    });
+  }
+  return parameters;
+}
+
+function listParameters(binding: ParameterBinding): OpenApiParameter[] {
+  const options = binding.listOptions ?? (binding.model ? optionsFromSchema(binding.model) : {});
+  const parameters: OpenApiParameter[] = [
+    {
+      name: "sort", in: "query", required: false, schema: { type: "string" },
+      "x-bazis-sort-fields": [...(options.sort ?? [])],
+    },
+    { name: "page[number]", in: "query", required: false, schema: { type: "integer", minimum: 1 } },
+    {
+      name: "page[size]",
+      in: "query",
+      required: false,
+      schema: pageSizeSchema(options.page?.maxSize),
+    },
+  ];
+  if (options.include && options.include.length > 0) {
+    parameters.push({ name: "include", in: "query", required: false, schema: { type: "string", enum: options.include } });
+  }
+  for (const [field, operators] of Object.entries(options.filter ?? {})) {
+    for (const operator of operators) {
+      parameters.push({
+        name: `filter[${field}][${operator}]`,
+        in: "query",
+        required: false,
+        schema: { type: "string" },
+      });
+    }
+  }
+  return parameters;
+}
+
+function pageSizeSchema(maximum: number | undefined): OpenApiSchema {
+  return maximum === undefined ? { type: "integer", minimum: 1 } : { type: "integer", minimum: 1, maximum };
+}
+
+function createRequestBody(
+  bindings: readonly ParameterBinding[],
+  action: ActionMeta,
+  generated: GeneratedOpenApiMetadata,
+): OpenApiSchema | undefined {
+  const body = bindings.find((binding) => binding.source === "body");
+  if (!body) {
+    return undefined;
+  }
+  const schema = body.model ? schemaForModel(body.model.name, generated) : { type: "object" };
+  return {
+    required: body.optional !== true,
+    content: {
+      [action.consumes ?? "application/json"]: {
+        schema,
+      },
+    },
+  };
+}
+
+function schemaForModel(name: string, generated: GeneratedOpenApiMetadata): OpenApiSchema {
+  return generated.schemas[name] !== undefined
+    ? { $ref: `#/components/schemas/${name}` }
+    : { type: "object", "x-bazis-model": name };
+}
+
+function schemaForValueType(type: ParameterBinding["type"]): OpenApiSchema {
+  switch (type) {
+    case "int":
+      return { type: "integer" };
+    case "number":
+      return { type: "number" };
+    case "bool":
+      return { type: "boolean" };
+    case "string":
+    case undefined:
+      return { type: "string" };
+  }
+}
+
+function routeParamSchemas(template: string): Record<string, OpenApiSchema> {
+  const schemas: Record<string, OpenApiSchema> = {};
+  for (const segment of template.split("/")) {
+    const param = /^:([A-Za-z_][A-Za-z0-9_]*)(?:\(([a-z]+)\))?$/.exec(segment);
+    if (param) {
+      schemas[param[1] as string] = schemaForConstraint(param[2]);
+      continue;
+    }
+    const wildcard = /^\*([A-Za-z_][A-Za-z0-9_]*)?$/.exec(segment);
+    if (wildcard) {
+      schemas[(wildcard[1] as string | undefined) ?? "rest"] = { type: "string" };
+    }
+  }
+  return schemas;
+}
+
+function schemaForConstraint(constraint: string | undefined): OpenApiSchema {
+  switch (constraint) {
+    case "int":
+      return { type: "integer" };
+    case "number":
+      return { type: "number" };
+    case "bool":
+      return { type: "boolean" };
+    case "uuid":
+      return { type: "string", format: "uuid" };
+    case "alpha":
+      return { type: "string", pattern: "^[A-Za-z]+$" };
+    default:
+      return { type: "string" };
+  }
+}
+
+function successStatus(method: string, action: ActionMeta): number {
+  if (action.httpCode !== undefined) {
+    return action.httpCode;
+  }
+  return method === "DELETE" ? 204 : 200;
+}
+
+function tagName(meta: ControllerMeta, controllerClass: Class<object>): string {
+  const firstPrefix = meta.prefix?.split("/").find((part) => part.length > 0);
+  return firstPrefix ?? controllerClass.name.replace(/Controller$/, "");
+}
+
+function fullOpenApiPath(
+  globalPrefix: string | undefined,
+  versionSource: "url" | "query" | "header" | undefined,
+  meta: ControllerMeta,
+  action: ActionMeta,
+  template: string,
+): string {
+  const version = action.version ?? meta.version;
+  const versionSegment = (versionSource === undefined || versionSource === "url") && version !== undefined ? `v${version}` : undefined;
+  const joined = joinPaths(globalPrefix, versionSegment, meta.prefix, template);
+  return `/${templateToOpenApiPath(joined)}`;
+}
+
+function templateToOpenApiPath(template: string): string {
+  if (template === "") {
+    return "";
+  }
+  return template
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map((segment) => {
+      if (segment.startsWith(":")) {
+        const match = /^:([A-Za-z_][A-Za-z0-9_]*)/.exec(segment);
+        return match ? `{${match[1]}}` : segment;
+      }
+      if (segment.startsWith("*")) {
+        const name = segment.length > 1 ? segment.slice(1) : "rest";
+        return `{${name}}`;
+      }
+      return segment;
+    })
+    .join("/");
+}
+
+function normalizedMethod(method: string): string {
+  return method === "*" ? "ANY" : method;
+}

package/core/http/README.md

@@ -0,0 +1,139 @@
+# src/bazis/core/http: HTTP module (in the spirit of ASP.NET Core)
+
+Controllers are classes with standard TC39 decorators; routes are compiled into a
+radix tree at startup; each request lives in its own DI scope.
+No external dependencies, no reflection, compatible with `bun build --compile`
+(checked by the shared `bun run build:bin`).
+
+The full specification of middleware and `@Middleware`: [SPEC.md](./SPEC.md).
+
+## Quick start
+
+First create an application by the [guide](../../../../docs/QUICKSTART.md), then
+the module `bunx bazis g module Echo --empty`. To try it without a database, replace
+the content of the generated `Echo.module.ts` with this code and fill in its `MODULE.md`:
+
+```ts
+import { Module } from "bazis/core/di";
+import { Controller, Get, Post, RequestModel } from "bazis/core/http";
+import { Validator } from "bazis/library/validation";
+
+@RequestModel()
+export class EchoRequest {
+  @Validator({ required: true, type: "string", minLength: 3, maxLength: 100 })
+  text!: string;
+}
+
+@Controller("echo")
+export class EchoController {
+  @Get(":id(int)")
+  getById(id: number) { return { id }; }
+
+  @Post()
+  send(body: EchoRequest) { return { text: body.text }; }
+}
+
+@Module({ controllers: [EchoController], exports: [] })
+export class EchoModule {}
+```
+
+`bun run dev` runs codegen before the application. GET `/echo/42` returns
+`{"id":42}`; POST `/echo` with `{"text":"hello"}` returns `{"text":"hello"}`.
+An invalid body gets HTTP 400. If the host sets a prefix, add it to the path.
+Parameter bindings are inferred from the signature before the run; TypeScript is
+not analyzed on each request. For service dependencies a constructor and
+`scoped(IService, Service)` are enough: the same codegen infers the usual `deps`.
+
+## Binding conventions (instead of parameter decorators)
+
+**Parameter** decorators (`getUser(@Param("id") id)`) do not exist in the TC39
+standard, and `experimentalDecorators` would break the other framework modules.
+Instead there are ASP.NET-style conventions that codegen infers from the signature:
+
+| Method parameter | Binding |
+|---|---|
+| the name matches the route `:name` | the route value (converted by the constraint/type) |
+| a DTO class from the application sources | the request body + `@Validator` validation (errors -> 400) |
+| `HttpContext` / `Request` / `ResponseBuilder` | context / raw request / response builder |
+| a primitive (`string`/`number`/`boolean` or inferred from the default) | a query parameter; `?` and a default -> optional |
+
+If no convention can be inferred (for example a union of string literals, no
+annotation or two body classes), `di:generate` fails with
+`BAZIS_HTTP_BINDING_UNRESOLVED`, the method name and the reason. The previous
+generated files are not replaced. Use a supported type; for headers and raw
+bodies take `ctx: HttpContext`, and inject services into the constructor.
+Checking allowed values belongs to the Validator or the service.
+
+A `ctx: HttpContext` parameter stays a regular supported input. For older manual
+HTTP assembly without generated metadata there is a runtime fallback with one
+HttpContext; it does not replace codegen for typed actions.
+
+### Nested request DTOs
+
+`di:generate` also reads the field types of a request model and registers the shape
+for recursive hydration without `reflect-metadata`. So the usual DX works for
+objects and arrays too:
+
+```ts
+export class AddressRequest {
+  @Validator({ required: true })
+  city!: string;
+}
+
+export class CreateUserRequest {
+  @Validator({ required: true, nested: true })
+  address!: AddressRequest;
+
+  @Validator({ nested: true })
+  previousAddresses!: AddressRequest[];
+}
+```
+
+Both classes must be named top-level exports. The binder creates real instances
+of nested DTOs, removes unknown and prototype-polluting fields at every level,
+then runs validation with paths like `address.city` and
+`previousAddresses[0].city`. An ambiguous type with `nested: true` (for example a
+union of two classes) stops codegen; with missing or stale generated metadata the
+standard validator rejects a plain object fail-closed.
+
+A request body field declared exactly as `string`, `number` or `boolean`
+(also `| null`, optional or an array of such values) is checked against the
+JSON type without `@Validator`: `{"done":"yes"}` for `done?: boolean` gives 400
+with the code `type`. Codegen takes the type from the sources; literal unions, enums,
+`Date` and mixed unions are not checked; they need `@Validator`.
+Required-ness is still set with `required: true`. The check applies only at the
+HTTP boundary: gRPC and Agent use the same binder without it.
+
+Open JSON fields (`Record<string, unknown>`, `{}`, `unknown[]`) keep regular user
+keys, but the binder clones them recursively and removes `__proto__`,
+`constructor`, `prototype` at any depth. Cycles, nesting deeper than 64 containers
+and overly complex graphs are rejected with 400 before reaching the action.
+
+## Folder map
+
+| Folder/file | Purpose |
+|---|---|
+| `Decorators/` | `@Controller`, `@Get`/`@Post`/... (+ inline options `{ code, produces, consumes, version, middleware }`), `@HttpCode`, `@Produces`, `@Consumes`, `@Middleware`, `@ApiVersion`, `@Catch`, `@ActionFilter`; metadata stored through `Symbol.metadata` |
+| `Routing/` | template parser (`:id(int)`, `:u(uuid)`, `*rest`), a radix tree with backtracking, pipeline assembly at startup |
+| `Binding/` | binding descriptors, type conversion (400 on error), model binding with prototype pollution protection and `@Validator` validation |
+| `Results/` | `Ok`, `Created`, `NotFound`, `Redirect`, `File` (through `Bun.file`) and result normalization with an automatic Content-Type |
+| `Middleware/` | the pipeline, `cors` (+ preflight), `errorHandler`, `rateLimit`; the access log is `@/logging/http` |
+| `Versioning/` | reads the API version from a URL segment, a query parameter or a header |
+| `HttpContext/` | the request context (params, DI scope, body cache) and `ResponseBuilder` |
+| `Errors/` | `HttpError` and subclasses (4xx/5xx), `ModelValidationError`, `HttpSetupError` |
+| `HttpServer.ts` | hosted service: `Bun.serve`, a scope per request, 404/405/preflight without the pipeline |
+| `httpModule.ts` | the `BazisModule` factory: scoped controllers + the server |
+
+## Guarantees
+
+- **Performance**: all metadata is processed at startup; per request there is a
+  radix lookup O(segments), a compiled pipeline and a DI scope; the body is parsed
+  once (cached in the context).
+- **Resilience**: a global error boundary is always installed
+  (`HttpError` -> status, anything else -> 500 without details in production);
+  `@Catch` on a controller for domain errors; broken JSON/conversions -> 400, not 500.
+- **Security**: prototype pollution is filtered in model binding and in route
+  parameter names; `..`/`%zz` in the path -> 400; CORS with preflight; auth hooks
+  in as regular middleware (`@Middleware` or global); `rateLimit` is one line.
+- **Configuration errors** (a duplicate route, an unknown constraint, a class
+  without `@Controller`) are `HttpSetupError` at startup, not at runtime.

package/core/http/Results/HttpResult.ts

@@ -0,0 +1,19 @@
+/**
+ * An action result: a recipe for building the final `Response`.
+ * Returned by the fluent helpers (`Ok`, `Created`, `NotFound`, ...).
+ */
+export class HttpResult {
+  constructor(
+    readonly status: number,
+    /** Body value: object/array -> JSON, string -> text, Blob/bytes -> as-is, undefined -> empty. */
+    readonly body?: unknown,
+    readonly headers?: readonly [string, string][],
+    /** Explicit Content-Type (overrides automatic negotiation). */
+    readonly contentType?: string,
+  ) {}
+
+  /** Returns a copy with an extra header. */
+  withHeader(name: string, value: string): HttpResult {
+    return new HttpResult(this.status, this.body, [...(this.headers ?? []), [name, value]], this.contentType);
+  }
+}