bazis 0.96.1

package/core/http/Binding/autoBindings.ts

@@ -0,0 +1,125 @@
+import { optionsFromSchema } from "../../../library/jsonapi";
+import { AMBIGUOUS_REQUEST_MODEL, findRequestModelByName } from "./requestModelRegistry";
+import { AMBIGUOUS_LIST_MODEL, findListModelByName } from "./listModelRegistry";
+import { HttpSetupError } from "../Errors/HttpError";
+import type { Class } from "../../di";
+import type { ParameterBinding } from "./bindings";
+import type { GeneratedBindingSpec } from "./generatedSpec";
+
+type GeneratedControllerClass = abstract new (...args: never[]) => object;
+
+// Generated target constructors remain process-owned. Map snapshots make a
+// failed multi-owner publication fully reversible.
+let targetBindings = new Map<GeneratedControllerClass, Readonly<Record<string, readonly GeneratedBindingSpec[]>>>();
+let targetModels = new Map<GeneratedControllerClass, ReadonlyMap<string, Class<object>>>();
+
+/** Registers an isolated generated target slice without relying on class.name. */
+export function registerGeneratedBindings(
+  controller: Class<object>,
+  bindings: Readonly<Record<string, readonly GeneratedBindingSpec[]>>,
+  models?: ReadonlyMap<string, Class<object>>,
+): void {
+  targetBindings.set(controller, bindings);
+  if (models !== undefined) targetModels.set(controller, models);
+}
+
+/**
+ * Binding conventions inferred by codegen (`bun run di:generate`) from the
+ * controller method signature, the counterpart of DI auto deps:
+ *
+ * - a parameter named like a route `:name` -> from the route;
+ * - a class type -> request body plus validation;
+ * - `HttpContext` / `Request` / `ResponseBuilder` -> context/raw request/builder;
+ * - other primitives -> query (converted by type; `?`/default -> optional).
+ *
+ * Headers and raw bodies are read through HttpContext; services are injected
+ * into the constructor. Any DTO class parameter is treated as the request body.
+ * Model names are resolved once at startup; configuration errors are
+ * `HttpSetupError` (fail fast).
+ */
+export function resolveGeneratedBindings(
+  controller: GeneratedControllerClass,
+  methodName: string | symbol,
+): readonly ParameterBinding[] | undefined {
+  const controllerName = controller.name;
+  const specs = targetBindings.get(controller)?.[String(methodName)];
+  if (specs === undefined) {
+    return undefined;
+  }
+  const models = targetModels.get(controller);
+  return specs.map((spec) => toBinding(spec, controllerName, String(methodName), models));
+}
+
+function toBinding(spec: GeneratedBindingSpec, controllerName: string, methodName: string, models?: ReadonlyMap<string, Class<object>>): ParameterBinding {
+  switch (spec.source) {
+    case "route":
+      return { source: "route", name: spec.name, type: spec.type, optional: spec.optional };
+    case "query":
+      return { source: "query", name: spec.name, type: spec.type, optional: spec.optional };
+    case "context":
+      return { source: "context" };
+    case "request":
+      return { source: "request" };
+    case "response":
+      return { source: "response" };
+    case "list": {
+      if (!spec.model) {
+        return { source: "list" };
+      }
+      // An explicit target controller always resolves through its own
+      // constructor-local index. Name fallback is legacy/default-only.
+      const ctor = models === undefined ? findListModelByName(spec.model) : models.get(spec.model);
+      if (ctor === undefined) {
+        throw new HttpSetupError(
+          `${controllerName}.${methodName}: list model "${spec.model}" is not registered. ` +
+            `Make sure the class extends ListRequest and its module is imported, then run \`bun run di:generate\`.`,
+        );
+      }
+      if (ctor === AMBIGUOUS_LIST_MODEL) {
+        throw new HttpSetupError(
+          `${controllerName}.${methodName}: list model name "${spec.model}" is ambiguous (several classes share it). ` +
+            `Rename one of the classes.`,
+        );
+      }
+      return { source: "list", model: ctor as Class<object>, listOptions: optionsFromSchema(ctor) };
+    }
+    case "body": {
+      if (!spec.model) {
+        return { source: "body" };
+      }
+      // An explicit target controller always resolves through its own
+      // constructor-local index. Name fallback is legacy/default-only.
+      const model = models === undefined ? findRequestModelByName(spec.model) : models.get(spec.model);
+      if (model === undefined) {
+        throw new HttpSetupError(
+          `${controllerName}.${methodName}: body model "${spec.model}" is not registered. ` +
+            `Regenerate the target metadata; for an external DTO use @RequestModel() and import its module.`,
+        );
+      }
+      if (model === AMBIGUOUS_REQUEST_MODEL) {
+        throw new HttpSetupError(
+          `${controllerName}.${methodName}: body model name "${spec.model}" is ambiguous (several classes share it). ` +
+            `Rename one of the classes.`,
+        );
+      }
+      return { source: "body", model };
+    }
+  }
+}
+
+/** Internal generated-runtime transaction support. */
+export function snapshotGeneratedBindings(): {
+  readonly targetBindings: typeof targetBindings;
+  readonly targetModels: typeof targetModels;
+} {
+  return {
+    targetBindings: new Map(targetBindings),
+    targetModels: new Map(targetModels),
+  };
+}
+
+/** Internal generated-runtime transaction support. */
+export function restoreGeneratedBindings(snapshot: ReturnType<typeof snapshotGeneratedBindings>): void {
+  targetBindings = snapshot.targetBindings;
+  targetModels = snapshot.targetModels;
+}

package/core/http/Binding/bindings.ts

@@ -0,0 +1,19 @@
+import type { Class } from "../../di";
+import type { ListQueryOptions } from "../../../library/jsonapi";
+import type { ValueType } from "./convert";
+
+/** Internal descriptors resolved from generated action signatures. */
+export type BindingSource = "route" | "query" | "body" | "request" | "response" | "context" | "list";
+
+export interface ParameterBinding {
+  readonly source: BindingSource;
+  readonly name?: string;
+  readonly type?: ValueType;
+  readonly defaultValue?: unknown;
+  readonly optional?: boolean;
+  /** Body model class (instantiated, sanitized and validated). */
+  readonly model?: Class<object>;
+  /** Whitelist/limits for the class-based list binding (JSON:API list query). */
+  readonly listOptions?: ListQueryOptions;
+}
+

package/core/http/Binding/convert.ts

@@ -0,0 +1,48 @@
+import { BadRequestError } from "../Errors/HttpError";
+
+/** Primitive conversion targets for query/header/route values. */
+export type ValueType = "string" | "int" | "number" | "bool";
+
+/** Sentinel: conversion failed (distinguishable from any valid value). */
+export const INVALID: unique symbol = Symbol("invalid");
+
+const INT_PATTERN = /^-?\d+$/;
+
+/** Converts a raw string; returns INVALID instead of throwing (hot path). */
+export function tryConvert(raw: string, type: ValueType): string | number | boolean | typeof INVALID {
+  switch (type) {
+    case "string":
+      return raw;
+    case "int": {
+      if (!INT_PATTERN.test(raw)) {
+        return INVALID;
+      }
+      const value = Number(raw);
+      return Number.isSafeInteger(value) ? value : INVALID;
+    }
+    case "number": {
+      if (raw === "") {
+        return INVALID;
+      }
+      const value = Number(raw);
+      return Number.isFinite(value) ? value : INVALID;
+    }
+    case "bool":
+      if (raw === "true" || raw === "1") {
+        return true;
+      }
+      if (raw === "false" || raw === "0") {
+        return false;
+      }
+      return INVALID;
+  }
+}
+
+/** Converts or throws 400 with the parameter name in the message. */
+export function convertOr400(raw: string, type: ValueType, parameterName: string): string | number | boolean {
+  const value = tryConvert(raw, type);
+  if (value === INVALID) {
+    throw new BadRequestError(`Parameter "${parameterName}" must be of type ${type}, got: "${raw}"`);
+  }
+  return value;
+}

package/core/http/Binding/generatedSpec.ts

@@ -0,0 +1,18 @@
+/**
+ * Format of the generated binding conventions (`bun run di:generate`).
+ *
+ * Plain data without class references: the body model is given **by name** and
+ * resolved at startup through the class index of the generated target.
+ * The spec stores the name; a separate generated target supplies the constructors.
+ */
+export interface GeneratedBindingSpec {
+  readonly source: "route" | "query" | "body" | "context" | "request" | "response" | "list";
+  /** Name of the route/query parameter. */
+  readonly name?: string;
+  /** Primitive conversion (for query, and route params without a constraint in the template). */
+  readonly type?: "int" | "number" | "bool" | "string";
+  /** The parameter is declared with `?` or a default value. */
+  readonly optional?: boolean;
+  /** DTO class name (resolved through the generated target; `@RequestModel()` classes are the fallback). */
+  readonly model?: string;
+}

package/core/http/Binding/listModelRegistry.ts

@@ -0,0 +1,47 @@
+/**
+ * "Class name -> class" registry for list requests (`ListRequest` subclasses).
+ *
+ * Like {@link requestModelRegistry}: generated binding conventions refer to
+ * the class by name (the generated file is plain data), and the class itself
+ * is resolved from this registry when the server starts. Registration comes
+ * from the app-owned generated runtime (`src/generated/bazis/httpListModels.ts`).
+ */
+
+/** Marker: several different classes are registered under one name. */
+export const AMBIGUOUS_LIST_MODEL: unique symbol = Symbol("ambiguous-list-model");
+
+export type ListModelClass = new () => object;
+
+let registry = new Map<string, ListModelClass | typeof AMBIGUOUS_LIST_MODEL>();
+
+/** Registers a list-request class (called from the generated runtime). */
+export function registerListModelClass(ctor: ListModelClass): void {
+  const name = ctor.name;
+  if (!name) {
+    return;
+  }
+  const existing = registry.get(name);
+  if (existing === undefined) {
+    registry.set(name, ctor);
+  } else if (existing !== ctor) {
+    registry.set(name, AMBIGUOUS_LIST_MODEL);
+  }
+}
+
+/**
+ * Class by name: `undefined` if not registered, `AMBIGUOUS_LIST_MODEL` if the
+ * name is ambiguous (two different classes).
+ */
+export function findListModelByName(name: string): ListModelClass | typeof AMBIGUOUS_LIST_MODEL | undefined {
+  return registry.get(name);
+}
+
+/** Internal generated-runtime transaction support. */
+export function snapshotListModelRegistry(): typeof registry {
+  return new Map(registry);
+}
+
+/** Internal generated-runtime transaction support. */
+export function restoreListModelRegistry(snapshot: ReturnType<typeof snapshotListModelRegistry>): void {
+  registry = snapshot;
+}

package/core/http/Binding/modelBinder.ts

@@ -0,0 +1,345 @@
+import type { Class } from "../../di";
+import { BadRequestError, ModelValidationError } from "../Errors/HttpError";
+import { getModelValidator, type ModelValidator } from "./modelValidator";
+import {
+  findRequestModelShape,
+  type RequestModelClass,
+  type RequestModelFieldShape,
+  type RequestModelNestedFieldShape,
+  type RequestModelPrimitiveFieldShape,
+} from "./requestModelRegistry";
+
+/** Keys that must never be copied from external input (prototype pollution). */
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const MAX_JSON_DEPTH = 64;
+const MAX_JSON_NODES = 100_000;
+
+interface BindingTraversal {
+  readonly stack: WeakSet<object>;
+  readonly options: ModelBindingOptions;
+  nodes: number;
+}
+
+/** Internal binding policy; HTTP keeps its historical stripping defaults. */
+export interface ModelBindingOptions {
+  readonly unknownFields?: "strip" | "reject";
+  readonly declaredFields?: (model: RequestModelClass) => readonly string[] | undefined;
+  /** Protobuf bytes only; HTTP/Agent keep their strict JSON boundary. */
+  readonly allowBinary?: boolean;
+  /**
+   * Reject a JSON value whose type differs from a field declared exactly as
+   * `string`, `number` or `boolean` (from generated shapes). HTTP enables it;
+   * gRPC (int64 as string/bigint) and agents keep their own conversions.
+   */
+  readonly primitiveTypes?: boolean;
+}
+
+/**
+ * Binds a parsed JSON body to a model class instance:
+ *
+ * 1. requires a plain JSON object (not array/primitive) — otherwise 400;
+ * 2. copies only fields declared by the class (plus explicit setters),
+ *    stripping unknown and prototype-polluting names;
+ * 3. runs `@Validator` rules of the model — failures become a 400 with the
+ *    full list of validation errors (`ModelValidationError`).
+ *
+ * The model class must have a parameterless constructor. Class-typed nested
+ * DTOs (including arrays) are recursively hydrated from metadata emitted by
+ * `bun run di:generate`; initialized nested DTO fields remain supported as a
+ * runtime fallback.
+ */
+export function bindModel<T extends object>(model: Class<T>, data: unknown, validator?: ModelValidator, options: ModelBindingOptions = {}): T {
+  if (!isPlainJsonObject(data)) {
+    throw new BadRequestError("Request body must be a JSON object");
+  }
+  const traversal: BindingTraversal = { stack: new WeakSet(), nodes: 0, options };
+  const instance = hydrateModel(model as RequestModelClass, data, "", traversal, 0) as T;
+  const activeValidator = validator ?? getModelValidator();
+  if (activeValidator !== undefined) {
+    const result = activeValidator.validate(instance);
+    if (!result.isValid) {
+      throw new ModelValidationError(result.errors);
+    }
+  }
+  return instance;
+}
+
+function hydrateModel(
+  model: RequestModelClass,
+  source: Record<string, unknown>,
+  path: string,
+  traversal: BindingTraversal,
+  depth: number,
+): object {
+  enterContainer(source, path, traversal, depth);
+  const instance = new model();
+  // Class fields are emitted as own properties by Bun/TypeScript. Treat that
+  // runtime shape, generated nested fields and explicit prototype setters as
+  // the input whitelist so over-posted fields never reach application code.
+  try {
+    const allowed = bindableKeys(instance, model.prototype, model, traversal.options);
+    for (const key of Object.keys(source)) {
+      if (!acceptKey(source, key, allowed, path, traversal.options)) {
+        continue;
+      }
+      const target = instance as Record<string, unknown>;
+      const fieldPath = path === "" ? key : `${path}.${key}`;
+      target[key] = bindField(model, key, target[key], source[key], fieldPath, traversal, depth + 1);
+    }
+    return instance;
+  } finally {
+    traversal.stack.delete(source);
+  }
+}
+
+function bindField(
+  model: RequestModelClass,
+  key: string,
+  template: unknown,
+  incoming: unknown,
+  path: string,
+  traversal: BindingTraversal,
+  depth: number,
+): unknown {
+  const shape = findFieldShape(model, key);
+  if (shape !== undefined && "model" in shape) {
+    return hydrateField(shape, incoming, path, traversal, depth);
+  }
+  if (shape !== undefined && traversal.options.primitiveTypes === true) {
+    checkPrimitive(shape, incoming, path);
+  }
+  return sanitizeBoundValue(template, incoming, path, traversal, depth);
+}
+
+/** `undefined` means "absent"; required-ness stays with `@Validator`. */
+function checkPrimitive(shape: RequestModelPrimitiveFieldShape, incoming: unknown, path: string): void {
+  if (incoming === undefined || (incoming === null && shape.nullable === true)) {
+    return;
+  }
+  if (shape.array !== true) {
+    if (typeof incoming !== shape.primitive) throw bindingTypeError(path, shape.primitive);
+    return;
+  }
+  if (!Array.isArray(incoming)) throw bindingTypeError(path, "array");
+  incoming.forEach((item, index) => {
+    if (!(item === null && shape.elementNullable === true) && typeof item !== shape.primitive) {
+      throw bindingTypeError(`${path}[${index}]`, shape.primitive);
+    }
+  });
+}
+
+function hydrateField(
+  shape: RequestModelNestedFieldShape,
+  incoming: unknown,
+  path: string,
+  traversal: BindingTraversal,
+  depth: number,
+): unknown {
+  if (incoming === undefined) {
+    return undefined;
+  }
+  if (incoming === null) {
+    if (shape.nullable === true) {
+      return null;
+    }
+    throw bindingTypeError(path, shape.array === true ? "array" : "object");
+  }
+  if (shape.array === true) {
+    if (!Array.isArray(incoming)) {
+      throw bindingTypeError(path, "array");
+    }
+    enterContainer(incoming, path, traversal, depth);
+    try {
+      return incoming.map((item, index) => {
+        const itemPath = `${path}[${index}]`;
+        if (item === null && shape.elementNullable === true) {
+          return null;
+        }
+        if (!isPlainJsonObject(item)) {
+          throw bindingTypeError(itemPath, "object");
+        }
+        return hydrateModel(shape.model, item, itemPath, traversal, depth + 1);
+      });
+    } finally {
+      traversal.stack.delete(incoming);
+    }
+  }
+  if (!isPlainJsonObject(incoming)) {
+    throw bindingTypeError(path, "object");
+  }
+  return hydrateModel(shape.model, incoming, path, traversal, depth);
+}
+
+function bindingTypeError(property: string, expected: string): ModelValidationError {
+  return new ModelValidationError([{
+    property: property || "$",
+    message: `Field "${property || "$"}" must be a ${expected}`,
+    code: "type",
+  }]);
+}
+
+function isPlainJsonObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value) as object | null;
+  return prototype === Object.prototype || prototype === null;
+}
+
+function findFieldShape(model: RequestModelClass, property: string): RequestModelFieldShape | undefined {
+  let current: unknown = model;
+  while (typeof current === "function" && current !== Function.prototype) {
+    const shape = findRequestModelShape(current as RequestModelClass);
+    if (shape !== undefined && Object.prototype.hasOwnProperty.call(shape, property)) {
+      return shape[property];
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  return undefined;
+}
+
+function sanitizeBoundValue(
+  template: unknown,
+  incoming: unknown,
+  path: string,
+  traversal: BindingTraversal,
+  depth: number,
+): unknown {
+  if (incoming === null || typeof incoming !== "object") {
+    return incoming;
+  }
+
+  if (traversal.options.allowBinary === true && incoming instanceof Uint8Array) {
+    return Buffer.isBuffer(incoming) ? Buffer.from(incoming) : new Uint8Array(incoming);
+  }
+
+  if (Array.isArray(incoming)) {
+    if (isNestedModel(template) || isPlainJsonObject(template)) {
+      throw bindingTypeError(path, "object");
+    }
+    enterContainer(incoming, path, traversal, depth);
+    try {
+      return incoming.map((item, index) =>
+        sanitizeBoundValue(undefined, item, `${path}[${index}]`, traversal, depth + 1)
+      );
+    } finally {
+      traversal.stack.delete(incoming);
+    }
+  }
+
+  if (!isPlainJsonObject(incoming)) {
+    throw bindingTypeError(path, "JSON object or array");
+  }
+  if (Array.isArray(template)) {
+    throw bindingTypeError(path, "array");
+  }
+
+  enterContainer(incoming, path, traversal, depth);
+  try {
+    if (isNestedModel(template)) {
+      const target = template as Record<string, unknown>;
+      const targetModel = target.constructor as RequestModelClass;
+      const allowed = bindableKeys(target, Object.getPrototypeOf(target) as object, targetModel, traversal.options);
+      for (const key of Object.keys(incoming)) {
+        if (!acceptKey(incoming, key, allowed, path, traversal.options)) {
+          continue;
+        }
+        const childPath = `${path}.${key}`;
+        target[key] = bindField(targetModel, key, target[key], incoming[key], childPath, traversal, depth + 1);
+      }
+      return target;
+    }
+
+    // Open JSON bags (`Record<string, unknown>`, `{}`, `unknown[]`) retain
+    // ordinary data keys, but are cloned recursively so forbidden keys and
+    // hostile prototypes cannot cross the HTTP boundary at any depth.
+    const output: Record<string, unknown> = {};
+    for (const key of Object.keys(incoming)) {
+      if (!acceptKey(incoming, key, undefined, path, traversal.options)) {
+        continue;
+      }
+      output[key] = sanitizeBoundValue(undefined, incoming[key], `${path}.${key}`, traversal, depth + 1);
+    }
+    return output;
+  } finally {
+    traversal.stack.delete(incoming);
+  }
+}
+
+function enterContainer(
+  value: object,
+  path: string,
+  traversal: BindingTraversal,
+  depth: number,
+): void {
+  const property = path || "$";
+  if (depth > MAX_JSON_DEPTH) {
+    throw new BadRequestError("Request body is too deeply nested", {
+      property,
+      maxDepth: MAX_JSON_DEPTH,
+    });
+  }
+  const childCount = Array.isArray(value) ? value.length : Object.keys(value).length;
+  traversal.nodes += 1 + childCount;
+  if (traversal.nodes > MAX_JSON_NODES) {
+    throw new BadRequestError("Request body is too complex", {
+      property,
+      maxNodes: MAX_JSON_NODES,
+    });
+  }
+  if (traversal.stack.has(value)) {
+    throw new BadRequestError("Request body must be acyclic JSON", { property });
+  }
+  traversal.stack.add(value);
+}
+
+function isNestedModel(value: unknown): value is object {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value) as object | null;
+  return prototype !== null && prototype !== Object.prototype &&
+    !(value instanceof Date) && !(value instanceof Map) && !(value instanceof Set) && !(value instanceof URL);
+}
+
+function acceptKey(source: object, key: string, allowed: ReadonlySet<string> | undefined, path: string, options: ModelBindingOptions): boolean {
+  if (!Object.prototype.hasOwnProperty.call(source, key)) return false;
+  if (!FORBIDDEN_KEYS.has(key) && (allowed === undefined || allowed.has(key))) return true;
+  if (options.unknownFields === "reject") {
+    const property = path === "" ? key : `${path}.${key}`;
+    throw new ModelValidationError([{ property, message: `Field "${property}" is forbidden or not declared by the model.`, code: "unknownField" }]);
+  }
+  return false;
+}
+
+function bindableKeys(instance: object, prototype: object, model: RequestModelClass, options: ModelBindingOptions): Set<string> {
+  const declared = options.declaredFields?.(model);
+  if (declared !== undefined) return new Set(declared);
+  const keys = new Set(Object.keys(instance));
+  let shapeModel: unknown = model;
+  while (typeof shapeModel === "function" && shapeModel !== Function.prototype) {
+    const shape = findRequestModelShape(shapeModel as RequestModelClass);
+    if (shape !== undefined) {
+      for (const key of Object.keys(shape)) {
+        if (!FORBIDDEN_KEYS.has(key)) {
+          keys.add(key);
+        }
+      }
+    }
+    shapeModel = Object.getPrototypeOf(shapeModel);
+  }
+  let current: object | null = prototype;
+  while (current && current !== Object.prototype) {
+    for (const key of Object.getOwnPropertyNames(current)) {
+      if (key === "constructor" || FORBIDDEN_KEYS.has(key)) {
+        continue;
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(current, key);
+      if (descriptor?.set) {
+        keys.add(key);
+      }
+    }
+    current = Object.getPrototypeOf(current) as object | null;
+  }
+  return keys;
+}

package/core/http/Binding/modelValidator.ts

@@ -0,0 +1,30 @@
+/**
+ * Request-model validation port (dependency inversion).
+ *
+ * `@/core/http` (the kernel) defines the abstraction but knows nothing about a
+ * concrete validation engine. The `@/library/validation` library implements it;
+ * the composition root (`runApp`) or a test registers the adapter through
+ * {@link useModelValidator}. Without a registered validator the bound body is
+ * not validated.
+ */
+export interface ModelValidationIssue {
+  readonly property: string;
+  readonly message: string;
+  readonly code?: string;
+}
+
+export interface ModelValidator {
+  validate(instance: object): { readonly isValid: boolean; readonly errors: readonly ModelValidationIssue[] };
+}
+
+let activeValidator: ModelValidator | undefined;
+
+/** Plugs in a concrete validator (bridge from `@/library/validation`). Idempotent. */
+export function useModelValidator(validator: ModelValidator): void {
+  activeValidator = validator;
+}
+
+/** The current validator, or `undefined` if none is plugged in. */
+export function getModelValidator(): ModelValidator | undefined {
+  return activeValidator;
+}