bazis 0.96.1

package/core/grpc/decorators.ts

@@ -0,0 +1,82 @@
+import type { ServiceDefinition } from "./serviceDefinition";
+import type { Class } from "../di";
+import type { GrpcControllerDefinition } from "./contracts";
+import type { RequestModelClass } from "../http/Binding/requestModelRegistry";
+
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+const GRPC_META = Symbol("bazis:grpc:controller");
+
+interface ControllerMetadata {
+  service?: ServiceDefinition;
+  methods: Map<string | symbol, string>;
+  requestModels: Map<string | symbol, RequestModelClass>;
+}
+interface Carrier { [GRPC_META]?: ControllerMetadata }
+
+function ownMetadata(metadata: object): ControllerMetadata {
+  const carrier = metadata as Carrier;
+  if (!Object.hasOwn(carrier, GRPC_META)) {
+    const parent = carrier[GRPC_META];
+    carrier[GRPC_META] = { service: parent?.service, methods: new Map(parent?.methods), requestModels: new Map(parent?.requestModels) };
+  }
+  return carrier[GRPC_META]!;
+}
+
+/** Bind a controller to a generated codec definition or grpcService(). */
+export function GrpcController(service: ServiceDefinition) {
+  return (_value: Class<object>, context: ClassDecoratorContext): void => {
+    if (!service || typeof service !== "object" || Object.keys(service).length === 0) {
+      throw new TypeError("@GrpcController requires a non-empty gRPC service definition.");
+    }
+    const snapshot: Record<string, ServiceDefinition[string]> = Object.create(null);
+    for (const [name, method] of Object.entries(service)) {
+      if (!method || typeof method.path !== "string" || !/^\/[^/]+\/[^/]+$/.test(method.path)
+        || typeof method.requestStream !== "boolean" || typeof method.responseStream !== "boolean"
+        || typeof method.requestDeserialize !== "function" || typeof method.responseSerialize !== "function") {
+        throw new TypeError(`Invalid gRPC service method: ${name}.`);
+      }
+      snapshot[name] = Object.freeze({ ...method });
+    }
+    ownMetadata(context.metadata).service = Object.freeze(snapshot);
+  };
+}
+
+/** Request/response values for unary; AsyncIterable values for streaming sides. */
+export function GrpcMethod(rpcName?: string, requestModel?: RequestModelClass) {
+  if (requestModel !== undefined && (typeof requestModel !== "function" || !requestModel.prototype)) {
+    throw new TypeError("gRPC requestModel must be a DTO class.");
+  }
+  return (_value: unknown, context: ClassMethodDecoratorContext): void => {
+    if (context.static || context.private) throw new TypeError("@GrpcMethod requires a public instance method.");
+    const name = rpcName ?? (typeof context.name === "string" ? context.name : "");
+    if (typeof name !== "string" || name.trim().length === 0) throw new TypeError("gRPC method name must not be empty.");
+    const meta = ownMetadata(context.metadata);
+    meta.methods.set(context.name, name);
+    // A redecorated override must not silently retain the base method's DTO.
+    if (requestModel === undefined) meta.requestModels.delete(context.name);
+    else meta.requestModels.set(context.name, requestModel);
+  };
+}
+
+/** @internal Resolve aliases and reject contract mismatches before opening a port. */
+export function grpcControllerDefinition(controller: Class<object>): GrpcControllerDefinition {
+  const carrier = (controller as unknown as { [Symbol.metadata]?: Carrier })[Symbol.metadata];
+  const meta = carrier?.[GRPC_META];
+  if (!meta?.service) throw new TypeError(`${controller.name} must use @GrpcController().`);
+  const methods = new Map<string, string | symbol>();
+  for (const [methodName, rpcName] of meta.methods) {
+    const keys = Object.keys(meta.service).filter((key) => {
+      const rpc = meta.service![key]!;
+      return key === rpcName || rpc.originalName === rpcName || rpc.path.split("/").at(-1) === rpcName;
+    });
+    if (keys.length !== 1) throw new TypeError(`${controller.name}.${String(methodName)}: unknown or ambiguous RPC ${rpcName}.`);
+    const key = keys[0]!;
+    if (methods.has(key)) throw new TypeError(`${controller.name}: duplicate RPC ${rpcName}.`);
+    if (typeof controller.prototype[methodName] !== "function") throw new TypeError(`Missing RPC handler ${String(methodName)}.`);
+    methods.set(key, methodName);
+  }
+  for (const key of Object.keys(meta.service)) {
+    if (!methods.has(key)) throw new TypeError(`${controller.name}: RPC ${key} is missing @GrpcMethod().`);
+  }
+  return Object.freeze({ controller, service: meta.service, methods, requestModels: new Map(meta.requestModels) });
+}

package/core/grpc/grpcClientProvider.ts

@@ -0,0 +1,9 @@
+import { singletonFactory, type ProviderDefinition, type Token } from "../di";
+import { GrpcClient } from "./GrpcClient";
+import type { GrpcClientOptions } from "./clientContracts";
+import type { ServiceDefinition } from "./serviceDefinition";
+
+/** Container-owned singleton: lazy network connection and automatic dispose(). */
+export function grpcClientProvider(service: ServiceDefinition, options: GrpcClientOptions, token: Token<GrpcClient> = GrpcClient): ProviderDefinition<GrpcClient> {
+  return singletonFactory(token, [], () => new GrpcClient(service, options));
+}

package/core/grpc/index.ts

@@ -0,0 +1,17 @@
+export { GrpcController, GrpcMethod } from "./decorators";
+export { GrpcError } from "./GrpcError";
+export { grpcModule } from "./Grpc.module";
+export { GrpcServer } from "./GrpcServer";
+export { GrpcClient } from "./GrpcClient";
+export { grpcClientProvider } from "./grpcClientProvider";
+export type { GrpcClientOptions, GrpcClientTlsOptions, GrpcCallOptions, GrpcResponse, GrpcResponseStream } from "./clientContracts";
+export { grpcService, loadGrpcPackage } from "./protobuf";
+export type { GrpcContext, GrpcModuleOptions } from "./contracts";
+export { Metadata, type MetadataValue } from "./Metadata";
+export { ServerCredentials } from "./ServerCredentials";
+export { GrpcStatus } from "./GrpcStatus";
+export type { MethodDefinition, ServiceDefinition, PackageDefinition, ServerOptions } from "./serviceDefinition";
+export type { ProtoLoaderOptions } from "./ProtoSchema";
+/** @internal Codegen attachment channel, not an application registration API. */
+export { GRPC_REQUEST_BINDINGS } from "./GrpcBinding.contract";
+export type { ModelValidator, ModelValidationIssue } from "../http/Binding/modelValidator";

package/core/grpc/moduleControllers.ts

@@ -0,0 +1,38 @@
+import {
+  createModuleOwnedProviderChannel, registerModuleOwnedProviderContributor, scoped,
+  type Class, type BazisModuleRef,
+} from "../di";
+import type { GrpcControllerDefinition } from "./contracts";
+import { grpcControllerDefinition } from "./decorators";
+
+declare module "../di/module/types/BazisModule" {
+  interface BazisModuleMetadata {
+    /** gRPC controllers, automatically scoped to one RPC by core/grpc. */
+    readonly grpcControllers?: readonly Class<object>[];
+  }
+}
+
+export const GRPC_CONTROLLERS = createModuleOwnedProviderChannel<GrpcControllerDefinition, object>("gRPC controllers");
+
+registerModuleOwnedProviderContributor((metadata, context) => {
+  const seen = new Set<Class<object>>();
+  for (const controller of metadata.grpcControllers ?? []) {
+    if (seen.has(controller)) continue;
+    seen.add(controller);
+    context.addScoped(GRPC_CONTROLLERS, scoped(controller), grpcControllerDefinition(controller));
+  }
+});
+
+/** @internal Discover only the feature tree published by this transport. */
+export function collectGrpcControllers(roots: readonly BazisModuleRef[], extra: readonly Class<object>[] = []): Set<Class<object>> {
+  const result = new Set(extra);
+  const visited = new Set<BazisModuleRef>();
+  const visit = (module: BazisModuleRef): void => {
+    if (visited.has(module)) return;
+    visited.add(module);
+    for (const child of module.imports ?? []) visit(child);
+    for (const controller of module.grpcControllers ?? []) result.add(controller);
+  };
+  for (const root of roots) visit(root);
+  return result;
+}

package/core/grpc/protobuf.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import type { ServiceDefinition, PackageDefinition } from "./serviceDefinition";
+import { ProtoParser } from "./ProtoParser";
+import { ProtoCodec } from "./ProtoCodec";
+import { resolveProtoType, type ProtoSchema, type ProtoLoaderOptions } from "./ProtoSchema";
+
+/** Select a service by its fully qualified protobuf name. */
+export function grpcService(definition: PackageDefinition, serviceName: string): ServiceDefinition {
+  const service = definition[serviceName];
+  if (!service || "format" in service || Object.keys(service).length === 0) {
+    throw new TypeError(`Protobuf service not found: ${serviceName}.`);
+  }
+  return service as ServiceDefinition;
+}
+
+/** Load proto3 contracts without a package dependency or external compiler. */
+export function loadGrpcPackage(filename: string | readonly string[], options: ProtoLoaderOptions = {}): PackageDefinition {
+  validateOptions(options);
+  options = Object.freeze({ ...options, includeDirs: options.includeDirs && Object.freeze([...options.includeDirs]) });
+  const roots = typeof filename === "string" ? [filename] : filename;
+  if (!Array.isArray(roots) || roots.length === 0 || roots.some((file) => typeof file !== "string" || !file)) throw new TypeError("Expected protobuf filename(s).");
+  const schema: ProtoSchema = { messages: new Map(), enums: new Map(), services: new Map() };
+  const loaded = new Set<string>();
+  let schemaBytes = 0;
+  const load = (file: string, depth: number): void => {
+    file = path.resolve(file);
+    if (loaded.has(file)) return;
+    if (depth > 64 || loaded.size >= 256) throw new TypeError("Protobuf import graph exceeds limit.");
+    loaded.add(file);
+    const source = readFileSync(file, "utf8");
+    if ((schemaBytes += Buffer.byteLength(source)) > 16 * 1024 * 1024) throw new TypeError("Protobuf schema graph exceeds 16 MiB.");
+    const parser = new ProtoParser(source, schema, file);
+    parser.parse();
+    for (const imported of parser.imports) {
+      const candidates = [path.resolve(path.dirname(file), imported), ...(options.includeDirs ?? []).map((dir) => path.resolve(dir, imported))];
+      const resolved = candidates.find((candidate) => existsSync(candidate));
+      if (!resolved) throw new TypeError("Protobuf import not found: " + imported);
+      load(resolved, depth + 1);
+    }
+  };
+  for (const root of roots) load(root, 0);
+  const codec = new ProtoCodec(schema, options);
+  const definition: PackageDefinition = Object.create(null);
+  for (const name of schema.messages.keys()) definition[name] = { format: "Bazis proto3 message" };
+  for (const name of schema.enums.keys()) definition[name] = { format: "Bazis proto3 enum" };
+  for (const [name, methods] of schema.services) {
+    const service: ServiceDefinition = Object.create(null);
+    for (const method of methods) {
+      const input = resolveProtoType(schema, method.input, name);
+      const output = resolveProtoType(schema, method.output, name);
+      if (!schema.messages.has(input) || !schema.messages.has(output)) throw new TypeError("RPC input/output must be protobuf messages.");
+      service[method.name] = {
+        path: "/" + name + "/" + method.name,
+        originalName: method.name[0]!.toLowerCase() + method.name.slice(1),
+        requestStream: method.requestStream, responseStream: method.responseStream,
+        requestSerialize: (value) => codec.encode(input, value),
+        requestDeserialize: (buffer) => codec.decode(input, buffer),
+        responseSerialize: (value) => codec.encode(output, value),
+        responseDeserialize: (buffer) => codec.decode(output, buffer),
+      };
+    }
+    definition[name] = service;
+  }
+  return definition;
+}
+
+function validateOptions(options: ProtoLoaderOptions): void {
+  if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("Invalid protobuf options.");
+  const booleans = new Set(["keepCase", "defaults", "arrays", "objects", "oneofs"]);
+  const known = new Set([...booleans, "longs", "enums", "bytes", "includeDirs"]);
+  for (const [key, value] of Object.entries(options)) {
+    if (!known.has(key)) throw new TypeError("Unsupported protobuf option: " + key);
+    if (booleans.has(key) && typeof value !== "boolean") throw new TypeError("Invalid protobuf option: " + key);
+  }
+  if (options.longs !== undefined && ![String, Number, BigInt].includes(options.longs)) throw new TypeError("Invalid protobuf longs option.");
+  if (options.enums !== undefined && ![String, Number].includes(options.enums)) throw new TypeError("Invalid protobuf enums option.");
+  if (options.bytes !== undefined && ![String, Array, Buffer].includes(options.bytes)) throw new TypeError("Invalid protobuf bytes option.");
+  if (options.includeDirs !== undefined && (!Array.isArray(options.includeDirs) || options.includeDirs.some((dir) => typeof dir !== "string" || !dir))) throw new TypeError("Invalid protobuf includeDirs.");
+}

package/core/grpc/serviceDefinition.ts

@@ -0,0 +1,20 @@
+/** A codec contract, compatible structurally with generated protobuf services. */
+export interface MethodDefinition<Request = any, Response = any> {
+  readonly path: string;
+  readonly requestStream: boolean;
+  readonly responseStream: boolean;
+  readonly requestSerialize: (value: Request) => Buffer;
+  readonly requestDeserialize: (buffer: Buffer) => Request;
+  readonly responseSerialize: (value: Response) => Buffer;
+  readonly responseDeserialize: (buffer: Buffer) => Response;
+  readonly originalName?: string;
+}
+export type ServiceDefinition = Record<string, MethodDefinition>;
+export type PackageDefinition = Record<string, ServiceDefinition | { readonly format: string }>;
+
+/** Supported transport controls. Unknown controls fail before opening a port. */
+export interface ServerOptions {
+  readonly "grpc.max_receive_message_length"?: number;
+  readonly "grpc.max_send_message_length"?: number;
+  readonly "grpc.max_concurrent_streams"?: number;
+}

package/core/http/Authorization/Authorize.ts

@@ -0,0 +1,52 @@
+import {
+  setActionAllowAnonymous,
+  setActionAuthorize,
+  setControllerAllowAnonymous,
+  setControllerAuthorize,
+  type AuthorizeCheck,
+} from "./metadata";
+
+type AnyClass = abstract new (...args: never[]) => unknown;
+type AnyMethod = (...args: never[]) => unknown;
+type ClassOrMethodDecorator = (
+  value: AnyClass | AnyMethod,
+  context: ClassDecoratorContext | ClassMethodDecoratorContext,
+) => void;
+
+/**
+ * Protects a controller or a single action: the route gets the
+ * {@link AuthorizeCheck} function. The HTTP kernel does not know *what* it
+ * checks: JWT, login/password, Telegram sign-in and so on. Several checks
+ * can be passed; all of them must pass.
+ *
+ * ```ts
+ * @Authorize(requireTokenKind(TokenKind.Admin))   // access token kind
+ * @Authorize(loginMatches)                         // login/password matched
+ * @Authorize(telegramVerified)                     // Telegram sign-in
+ * ```
+ *
+ * Check result semantics, see {@link AuthorizeCheck}: `false` → 403,
+ * `throw` → the status of the thrown `HttpError`.
+ */
+export function Authorize(check: AuthorizeCheck, ...rest: AuthorizeCheck[]): ClassOrMethodDecorator {
+  const checks = [check, ...rest];
+
+  return (_value, context) => {
+    if (context.kind === "class") {
+      setControllerAuthorize(context.metadata, { checks });
+      return;
+    }
+    setActionAuthorize(context.metadata, context.name, { checks });
+  };
+}
+
+/** Public route: overrides `@Authorize` declared on the controller. */
+export function AllowAnonymous(): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      setControllerAllowAnonymous(context.metadata);
+      return;
+    }
+    setActionAllowAnonymous(context.metadata, context.name);
+  };
+}

package/core/http/Authorization/authorizeComposer.ts

@@ -0,0 +1,31 @@
+import { ForbiddenError } from "../Errors/HttpError";
+import type { HttpMiddleware } from "../Middleware/types";
+import type { RouteMiddlewareComposer } from "../options";
+import { resolveAuthorizeMeta } from "./metadata";
+
+/**
+ * Built-in composer for `@Authorize`. The HTTP server puts it first among
+ * the per-route composers. For routes that require authorization it returns
+ * middleware that runs all checks in order: any that returns `false` → `403`;
+ * a check may throw an `HttpError` itself (for example
+ * `UnauthorizedError` → `401`).
+ */
+export function createAuthorizeComposer(): RouteMiddlewareComposer {
+  return (controllerClass, methodName) => {
+    const meta = resolveAuthorizeMeta(controllerClass, methodName);
+    if (meta.allowAnonymous || meta.authorize === undefined) {
+      return [];
+    }
+
+    const { checks } = meta.authorize;
+    const middleware: HttpMiddleware = async (ctx, next) => {
+      for (const check of checks) {
+        if (!(await check(ctx))) {
+          throw new ForbiddenError();
+        }
+      }
+      await next();
+    };
+    return [middleware];
+  };
+}

package/core/http/Authorization/metadata.ts

@@ -0,0 +1,158 @@
+import type { HttpContext } from "../HttpContext/HttpContext";
+
+// Same one-line polyfill as the rest of the HTTP module: Bun executes TC39
+// decorators natively, but Symbol.metadata may be missing in the runtime.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const AUTHORIZE_META = Symbol.for("bazis:http:authorize");
+
+/**
+ * Access check for `@Authorize`. Receives the request context and decides
+ * whether to let it through. The HTTP kernel does not know *what* is checked
+ * (JWT kind, login/password, a successful Telegram sign-in and so on): that
+ * is entirely inside the function.
+ *
+ * - `true`: access granted;
+ * - `false`: access denied (the kernel answers `403 Forbidden`);
+ * - `throw`: the function defines the response itself by throwing an `HttpError`
+ *   (for example `UnauthorizedError` → `401` when there are no credentials at all).
+ *
+ * Dependencies (services, DB) come from `ctx.services` (the request scope).
+ */
+export type AuthorizeCheck = (ctx: HttpContext) => boolean | Promise<boolean>;
+
+/** Authorization requirement: one or more checks (all must pass). */
+export interface AuthorizeOptions {
+  readonly checks: readonly AuthorizeCheck[];
+}
+
+interface AuthActionMeta {
+  authorize?: AuthorizeOptions;
+  allowAnonymous?: boolean;
+  /** Declaration made on this exact class/method metadata object. */
+  declaration?: "authorize" | "anonymous";
+}
+
+interface AuthControllerMeta {
+  authorize?: AuthorizeOptions;
+  allowAnonymous?: boolean;
+  /** Declaration made on this exact class metadata object. */
+  declaration?: "authorize" | "anonymous";
+  actions: Map<string | symbol, AuthActionMeta>;
+}
+
+interface AuthMetadataCarrier {
+  [AUTHORIZE_META]?: AuthControllerMeta;
+}
+
+function emptyMeta(): AuthControllerMeta {
+  return { actions: new Map() };
+}
+
+function cloneMeta(source: AuthControllerMeta): AuthControllerMeta {
+  const actions = new Map<string | symbol, AuthActionMeta>();
+  for (const [name, action] of source.actions) {
+    // Values inherit, declaration markers do not: the first decorator on a
+    // subclass must override its base rather than accidentally accumulate it.
+    actions.set(name, {
+      authorize: action.authorize,
+      allowAnonymous: action.allowAnonymous,
+    });
+  }
+  return {
+    authorize: source.authorize,
+    allowAnonymous: source.allowAnonymous,
+    actions,
+  };
+}
+
+/**
+ * Own (copy-on-write) authorization metadata of the decorated class. TC39
+ * metadata is inherited prototypically from the parent: the first write in a
+ * subclass clones the inherited state.
+ */
+function ownMeta(metadata: object): AuthControllerMeta {
+  const carrier = metadata as AuthMetadataCarrier;
+  if (!Object.prototype.hasOwnProperty.call(carrier, AUTHORIZE_META)) {
+    const inherited = carrier[AUTHORIZE_META];
+    carrier[AUTHORIZE_META] = inherited ? cloneMeta(inherited) : emptyMeta();
+  }
+  return carrier[AUTHORIZE_META]!;
+}
+
+function ownActionMeta(metadata: object, methodName: string | symbol): AuthActionMeta {
+  const meta = ownMeta(metadata);
+  let action = meta.actions.get(methodName);
+  if (!action) {
+    action = {};
+    meta.actions.set(methodName, action);
+  }
+  return action;
+}
+
+export function setControllerAuthorize(metadata: object, options: AuthorizeOptions): void {
+  const meta = ownMeta(metadata);
+  meta.authorize = meta.declaration === "authorize" && meta.authorize
+    ? { checks: [...options.checks, ...meta.authorize.checks] }
+    : options;
+  meta.declaration = "authorize";
+  delete meta.allowAnonymous;
+}
+
+export function setControllerAllowAnonymous(metadata: object): void {
+  const meta = ownMeta(metadata);
+  meta.allowAnonymous = true;
+  meta.declaration = "anonymous";
+  delete meta.authorize;
+}
+
+export function setActionAuthorize(metadata: object, methodName: string | symbol, options: AuthorizeOptions): void {
+  const action = ownActionMeta(metadata, methodName);
+  action.authorize = action.declaration === "authorize" && action.authorize
+    ? { checks: [...options.checks, ...action.authorize.checks] }
+    : options;
+  action.declaration = "authorize";
+  delete action.allowAnonymous;
+}
+
+export function setActionAllowAnonymous(metadata: object, methodName: string | symbol): void {
+  const action = ownActionMeta(metadata, methodName);
+  action.allowAnonymous = true;
+  action.declaration = "anonymous";
+  delete action.authorize;
+}
+
+/** Effective route requirement (the method overrides the controller). */
+export interface ResolvedAuthorizeMeta {
+  readonly allowAnonymous: boolean;
+  readonly authorize?: AuthorizeOptions;
+}
+
+/**
+ * Resolves the authorization requirement of a specific action. Precedence:
+ * `@AllowAnonymous`/`@Authorize` on the method override those declared on the class.
+ */
+export function resolveAuthorizeMeta(ctor: object, methodName: string | symbol): ResolvedAuthorizeMeta {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | AuthMetadataCarrier
+    | undefined;
+  const meta = metadata?.[AUTHORIZE_META];
+  if (!meta) {
+    return { allowAnonymous: false };
+  }
+
+  const action = meta.actions.get(methodName);
+  if (action?.allowAnonymous) {
+    return { allowAnonymous: true };
+  }
+  if (action?.authorize) {
+    return { allowAnonymous: false, authorize: action.authorize };
+  }
+  if (meta.allowAnonymous) {
+    return { allowAnonymous: true };
+  }
+  if (meta.authorize) {
+    return { allowAnonymous: false, authorize: meta.authorize };
+  }
+  return { allowAnonymous: false };
+}

package/core/http/Binding/ParameterBinder.ts

@@ -0,0 +1,109 @@
+import { ListQueryError, parseListQuery } from "../../../library/jsonapi";
+import { BadRequestError, UnsupportedMediaTypeError } from "../Errors/HttpError";
+import type { HttpContext } from "../HttpContext/HttpContext";
+import type { ParameterBinding } from "./bindings";
+import { convertOr400 } from "./convert";
+import { bindModel } from "./modelBinder";
+
+/** Per-action constraints affecting binding (from decorators). */
+export interface BindingDefaults {
+  /** `@Consumes(...)`: required request Content-Type for body access. */
+  consumes?: string;
+}
+
+function bindValue(binding: ParameterBinding, raw: string | undefined, kind: string): unknown {
+  if (raw === undefined) {
+    if (binding.defaultValue !== undefined) {
+      return binding.defaultValue;
+    }
+    if (binding.optional) {
+      return undefined;
+    }
+    throw new BadRequestError(`Missing required ${kind} parameter "${binding.name}"`);
+  }
+  return binding.type && binding.type !== "string" ? convertOr400(raw, binding.type, binding.name ?? "?") : raw;
+}
+
+/**
+ * Resolves generated binding descriptors into the action's argument list.
+ * All conversions fail with 400 (never 500); body parse errors and model
+ * validation are handled by the body branch.
+ */
+export async function bindArguments(
+  bindings: readonly ParameterBinding[],
+  ctx: HttpContext,
+  defaults: BindingDefaults,
+): Promise<unknown[]> {
+  const args: unknown[] = new Array(bindings.length);
+  for (let index = 0; index < bindings.length; index += 1) {
+    const binding = bindings[index]!;
+    switch (binding.source) {
+      case "route": {
+        const value = binding.name !== undefined ? ctx.params[binding.name] : undefined;
+        // Route params are already constraint-converted; re-convert only when
+        // the binding asks for a different primitive type.
+        if (value === undefined) {
+          args[index] = bindValue(binding, undefined, "route");
+        } else if (binding.type && binding.type !== "string" && typeof value === "string") {
+          args[index] = convertOr400(value, binding.type, binding.name ?? "?");
+        } else {
+          args[index] = value;
+        }
+        break;
+      }
+      case "query":
+        args[index] = bindValue(binding, ctx.query(binding.name ?? ""), "query");
+        break;
+      case "body": {
+        const contentType = ctx.header("content-type") ?? "";
+        if (defaults.consumes) {
+          if (!contentType.toLowerCase().startsWith(defaults.consumes.toLowerCase())) {
+            throw new UnsupportedMediaTypeError(defaults.consumes);
+          }
+        } else if (!isJsonMediaType(contentType)) {
+          // Convention-based body-model binding is a JSON boundary. Requiring
+          // a non-simple media type also prevents cross-origin text/plain POSTs
+          // from bypassing the browser's CORS preflight.
+          throw new UnsupportedMediaTypeError("application/json");
+        }
+        const data = await ctx.json();
+        args[index] = binding.model ? bindModel(binding.model, data, ctx.modelValidator, { primitiveTypes: true }) : data;
+        break;
+      }
+      case "request":
+        args[index] = ctx.request;
+        break;
+      case "response":
+        args[index] = ctx.res;
+        break;
+      case "context":
+        args[index] = ctx;
+        break;
+      case "list": {
+        let parsed;
+        try {
+          parsed = parseListQuery(ctx.url.searchParams, binding.listOptions);
+        } catch (error) {
+          if (error instanceof ListQueryError) {
+            throw new BadRequestError("Invalid list query", error.problems);
+          }
+          throw error;
+        }
+        if (binding.model) {
+          // Class-based list request (extends ListRequest): instantiate and
+          // populate the parsed sort/filters/page so the action gets a typed object.
+          args[index] = Object.assign(new (binding.model as new () => object)(), parsed);
+        } else {
+          args[index] = parsed;
+        }
+        break;
+      }
+    }
+  }
+  return args;
+}
+
+function isJsonMediaType(contentType: string): boolean {
+  const mediaType = contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+  return mediaType === "application/json" || mediaType.endsWith("+json");
+}

package/core/http/Binding/RequestModel.ts

@@ -0,0 +1,27 @@
+import { registerRequestModelClass, type RequestModelClass } from "./requestModelRegistry";
+
+/**
+ * Marks a class as a request model (DTO) addressable by name.
+ *
+ * Needed only for DTOs declared outside the scanned sources (for example in
+ * another package). Codegen registers all other DTOs from method signatures:
+ *
+ * ```ts
+ * @RequestModel()
+ * class CreateUserDto {
+ *   @Validator({ required: true, minLength: 3 })
+ *   name!: string;
+ * }
+ *
+ * // In the controller the parameter type is enough:
+ * @Post()
+ * create(dto: CreateUserDto) { ... }
+ * ```
+ *
+ * DTOs in the application sources do not need the decorator.
+ */
+export function RequestModel() {
+  return (value: RequestModelClass, _context: ClassDecoratorContext): void => {
+    registerRequestModelClass(value);
+  };
+}