bazis 0.100.7 → 0.101.0

package/core/app/messages.ts

@@ -11,7 +11,7 @@ export type AppLanguage = "en" | "ru";
  * `validationFailed`, `unknownField` and type names (`typeName.number`).
  * Placeholders: `{property}`, `{min}`, `{name}`, … as in the built-in texts.
  */
-export type AppMessages = Partial<Record<HttpMessageKey | ValidationCode | "validationFailed" | "unknownField" | `typeName.${string}`, string>>;
+export type AppMessages = Partial<Record<HttpMessageKey | ValidationCode | "validationFailed" | "unknownField" | "duplicate" | "tooManyValues" | `typeName.${string}`, string>>;
 
 const CATALOGS: Readonly<Record<AppLanguage, Readonly<Record<string, string>>>> = {
   en: { ...EN_HTTP_MESSAGES, ...EN_VALIDATION_MESSAGES },

package/core/di/errors/InvalidProviderError.ts

@@ -1,9 +1,10 @@
 import { DiError } from "./DiError";
 
 export class InvalidProviderError extends DiError {
-  public constructor(tokenName: string) {
+  /** `message` replaces the default text when the caller knows more (the module and position). */
+  public constructor(tokenName: string, message?: string) {
     super(
-      `Provider for "${tokenName}" has unknown shape: expected one of useClass/useFactory/useValue.`,
+      message ?? `Provider for "${tokenName}" has unknown shape: expected one of useClass/useFactory/useValue.`,
     );
   }
 }

package/core/di/errors/ScopedServiceFromRootError.ts

@@ -4,6 +4,7 @@ import { DiError } from "./DiError";
 
 export class ScopedServiceFromRootError extends DiError {
   public constructor(token: Token<unknown>) {
-    super(`Cannot resolve scoped service "${tokenToDebugName(token)}" from root provider.`);
+    const name = tokenToDebugName(token);
+    super(`Cannot resolve scoped service "${name}" from root provider. A scoped service lives in a request or a scope: create one with provider.createScope(), resolve "${name}" from it and dispose the scope when done.`);
   }
 }

package/core/di/internal/GraphValidator.ts

@@ -64,8 +64,12 @@ export class GraphValidator {
     issues: Set<string>,
   ): void {
     if (registrationPath.has(registration.id)) {
-      const cyclePath = [...tokenPath, registration.token].map((token) => tokenToDebugName(token)).join(" -> ");
-      issues.add(`Cycle detected: ${cyclePath}`);
+      // One cycle is reached from each of its members: report it once, as the cycle itself.
+      const start = tokenPath.indexOf(registration.token);
+      const members = (start >= 0 ? tokenPath.slice(start) : tokenPath).map((token) => tokenToDebugName(token));
+      const first = members.indexOf([...members].sort()[0] as string);
+      const canonical = [...members.slice(first), ...members.slice(0, first)];
+      issues.add(`Cycle detected: ${[...canonical, canonical[0]].join(" -> ")}`);
       return;
     }
 

package/core/di/module/createContainer.ts

@@ -4,7 +4,7 @@ import { HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, type HostedService } from "../ex
 import { SERVICE_PROVIDER, SERVICE_PROVIDER_BY_TYPE } from "../extensions/service-provider-token";
 import { isClassProvider, ProviderDefinition, type Provider } from "../provider";
 import { getClassDeps } from "../internal/classDeps";
-import { DiError, ModuleEncapsulationError } from "../errors";
+import { DiError, InvalidProviderError, ModuleEncapsulationError } from "../errors";
 import { OpenGenericRegistration } from "../internal/OpenGenericRegistration";
 import { tokenToDebugName, type Class } from "../token";
 import type { BuildServiceProviderOptions } from "../types";
@@ -133,6 +133,7 @@ export function createContainer(rootModule: BazisModuleRef, options?: CreateCont
     const providers = moduleRef.providers;
     if (providers) {
       for (let index = 0; index < providers.length; index += 1) {
+        assertProviderDefinition(providers[index], record.name, index);
         collection.add(providers[index] as ProviderDefinition);
       }
     }
@@ -311,3 +312,19 @@ function normalizeLateGeneratedClassDeps(definition: ProviderDefinition): Provid
   const normalizedProvider = { ...provider, deps: generatedDeps } as Provider<unknown>;
   return new ProviderDefinition(normalizedProvider, definition.lifetime, definition.key);
 }
+
+/**
+ * A module lists registrations made by singleton/scoped/transient/…; a raw
+ * `{ provide: X }` object used to crash later with a bare TypeError.
+ */
+function assertProviderDefinition(value: unknown, moduleName: string, index: number): void {
+  const provider = (value as { provider?: unknown } | null | undefined)?.provider;
+  if (typeof provider === "object" && provider !== null && "provide" in provider) return;
+  const provide = (value as { provide?: unknown } | null | undefined)?.provide;
+  const name = typeof provide === "function" ? provide.name : typeof provide === "string" ? provide : String(provide ?? value);
+  throw new InvalidProviderError(
+    name,
+    `Module "${moduleName}": providers[${index}] is not a provider registration${provide === undefined ? "" : ` ({ provide: ${name} })`}. `
+      + `Register it with singleton(${name}), scoped(${name}), transient(${name}), singletonValue(TOKEN, value) or singletonFactory(TOKEN, [deps], factory).`,
+  );
+}

package/core/http/Binding/ParameterBinder.ts

@@ -1,4 +1,5 @@
 import { ListQueryError, parseListQuery } from "../../../library/jsonapi";
+import { bindSourceModel } from "./sourceModelBinder";
 import { UnsupportedMediaTypeError, frameworkBadRequest } from "../Errors/HttpError";
 import type { HttpContext } from "../HttpContext/HttpContext";
 import type { ParameterBinding } from "./bindings";
@@ -83,6 +84,13 @@ export async function bindArguments(
       case "query":
         args[index] = binding.array ? bindArray(binding, ctx) : bindValue(binding, ctx.query(binding.name ?? ""), "query");
         break;
+      case "header":
+        args[index] = bindValue(binding, ctx.header(binding.name ?? ""), "header");
+        break;
+      case "queryModel":
+      case "headerModel":
+        args[index] = await bindSourceModel(binding, ctx);
+        break;
       case "body": {
         const contentType = ctx.header("content-type") ?? "";
         if (defaults.consumes) {

package/core/http/Binding/autoBindings.ts

@@ -1,9 +1,10 @@
 import { optionsFromSchema } from "../../../library/jsonapi";
-import { AMBIGUOUS_REQUEST_MODEL, findRequestModelByName } from "./requestModelRegistry";
+import { AMBIGUOUS_REQUEST_MODEL, findRequestModelByName, findRequestModelShape } from "./requestModelRegistry";
+import { wireNamesOf } from "./sources";
 import { AMBIGUOUS_LIST_MODEL, findListModelByName } from "./listModelRegistry";
 import { HttpSetupError } from "../Errors/HttpError";
 import type { Class } from "../../di";
-import type { ParameterBinding } from "./bindings";
+import type { ParameterBinding, SourceModelField } from "./bindings";
 import type { GeneratedBindingSpec } from "./generatedSpec";
 
 type GeneratedControllerClass = abstract new (...args: never[]) => object;
@@ -32,8 +33,9 @@ export function registerGeneratedBindings(
  * - `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.
+ * An explicit source comes from the type markers FromQuery/FromHeader/FromBody/
+ * FromRoute, including query and header models; 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).
  */
@@ -56,6 +58,14 @@ function toBinding(spec: GeneratedBindingSpec, controllerName: string, methodNam
       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, array: spec.array };
+    case "header":
+      return { source: "header", name: spec.name?.toLowerCase(), type: spec.type, optional: spec.optional };
+    case "queryModel":
+    case "headerModel": {
+      const source = spec.source === "queryModel" ? "query" : "header";
+      const model = resolveModel(spec, `${source} model`, controllerName, methodName, models);
+      return { source: spec.source, model, optional: spec.optional, fields: sourceModelFields(model, source, `${controllerName}.${methodName}`) };
+    }
     case "context":
       return { source: "context" };
     case "request":
@@ -83,28 +93,70 @@ function toBinding(spec: GeneratedBindingSpec, controllerName: string, methodNam
       }
       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 };
+    case "body":
+      return spec.model ? { source: "body", model: resolveModel(spec, "body model", controllerName, methodName, models) } : { source: "body" };
+  }
+}
+
+function resolveModel(spec: GeneratedBindingSpec, label: string, controllerName: string, methodName: string, models?: ReadonlyMap<string, Class<object>>): Class<object> {
+  const name = spec.model ?? "";
+  // An explicit target controller always resolves through its own
+  // constructor-local index. Name fallback is legacy/default-only.
+  const model = models === undefined ? findRequestModelByName(name) : models.get(name);
+  if (model === undefined) {
+    throw new HttpSetupError(
+      `${controllerName}.${methodName}: ${label} "${name}" 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}: ${label} name "${name}" is ambiguous (several classes share it). ` +
+        `Rename one of the classes.`,
+    );
+  }
+  return model;
+}
+
+const FORBIDDEN_FIELDS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * The fields of a query or header model, resolved once at startup: the
+ * instance's own fields plus the generated shape, each with its wire name and
+ * type. Query strings and headers are flat strings, so a nested model field
+ * (or a header array) is a setup error instead of a silent `undefined`.
+ */
+function sourceModelFields(model: Class<object>, source: "query" | "header", action: string): readonly SourceModelField[] {
+  let instance: object;
+  try {
+    instance = new (model as unknown as new () => object)();
+  } catch (error) {
+    throw new HttpSetupError(`${action}: ${source} model "${model.name}" must be constructible without arguments: ${(error as Error).message}`);
+  }
+  const shape = findRequestModelShape(model as unknown as new () => object) ?? {};
+  const names = wireNamesOf(model, source);
+  const properties = new Set([...Object.keys(instance), ...Object.keys(shape), ...names.keys()]);
+  const fields: SourceModelField[] = [];
+  const wires = new Map<string, string>();
+  for (const property of properties) {
+    if (FORBIDDEN_FIELDS.has(property)) continue;
+    const field = shape[property];
+    if (field !== undefined && "model" in field) {
+      throw new HttpSetupError(`${action}: ${source} model "${model.name}" field "${property}" is an object; ${source} models take string, number, boolean${source === "query" ? " and arrays of them" : ""}.`);
+    }
+    const array = field?.array === true;
+    if (array && source === "header") {
+      throw new HttpSetupError(`${action}: header model "${model.name}" field "${property}" is an array; a header model field takes one value.`);
+    }
+    const wire = names.get(property) ?? (source === "header" ? property.toLowerCase() : property);
+    const other = wires.get(wire);
+    if (other !== undefined) {
+      throw new HttpSetupError(`${action}: ${source} model "${model.name}" binds "${wire}" to both "${other}" and "${property}".`);
     }
+    wires.set(wire, property);
+    fields.push({ property, wire, type: field !== undefined && "primitive" in field ? field.primitive : "string", array });
   }
+  return Object.freeze(fields);
 }
 
 /** Internal generated-runtime transaction support. */

package/core/http/Binding/bindings.ts

@@ -3,7 +3,18 @@ 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 type BindingSource = "route" | "query" | "header" | "body" | "queryModel" | "headerModel" | "request" | "response" | "context" | "list";
+
+/** One field of a query or header model, resolved once at startup. */
+export interface SourceModelField {
+  /** Property on the model instance. */
+  readonly property: string;
+  /** Name in the request: the query parameter, or the lower-case header name. */
+  readonly wire: string;
+  readonly type: "string" | "number" | "boolean";
+  /** Every value of a repeated query parameter (`?tag=a&tag=b`). */
+  readonly array: boolean;
+}
 
 export interface ParameterBinding {
   readonly source: BindingSource;
@@ -13,8 +24,10 @@ export interface ParameterBinding {
   readonly optional?: boolean;
   /** Query array: all values of the name (`?tag=a&tag=b`), each converted by `type`. */
   readonly array?: boolean;
-  /** Body model class (instantiated, sanitized and validated). */
+  /** Body, query or header model class (instantiated and validated). */
   readonly model?: Class<object>;
+  /** Fields of a query or header model with their wire names and types. */
+  readonly fields?: readonly SourceModelField[];
   /** Whitelist/limits for the class-based list binding (JSON:API list query). */
   readonly listOptions?: ListQueryOptions;
 }

package/core/http/Binding/generatedSpec.ts

@@ -6,8 +6,8 @@
  * 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 source: "route" | "query" | "header" | "body" | "queryModel" | "headerModel" | "context" | "request" | "response" | "list";
+  /** Name of the route/query parameter, or the header (`FromHeader<string, "x-request-id">`). */
   readonly name?: string;
   /** Primitive conversion (for query, and route params without a constraint in the template). */
   readonly type?: "int" | "number" | "bool" | "string";
@@ -15,6 +15,6 @@ export interface GeneratedBindingSpec {
   readonly optional?: boolean;
   /** A query array (`tag: string[]`): every `?tag=` value, each converted by `type`. */
   readonly array?: boolean;
-  /** DTO class name (resolved through the generated target; `@RequestModel()` classes are the fallback). */
+  /** Body, query or header model class name (resolved through the generated target; `@RequestModel()` classes are the fallback). */
   readonly model?: string;
 }

package/core/http/Binding/sourceModelBinder.ts

@@ -0,0 +1,87 @@
+import { ModelValidationError } from "../Errors/HttpError";
+import type { HttpContext } from "../HttpContext/HttpContext";
+import type { ParameterBinding, SourceModelField } from "./bindings";
+import { tryConvert, INVALID, type ValueType } from "./convert";
+import type { ModelValidationIssue, ModelValidator } from "./modelValidator";
+
+/** Values one query parameter may carry: bounds the work for `?tag=…` repeated thousands of times. */
+export const MAX_QUERY_VALUES = 100;
+
+const VALUE_TYPES: Readonly<Record<SourceModelField["type"], ValueType>> = { string: "string", number: "number", boolean: "bool" };
+
+/**
+ * A query or header model: every declared field is read from the request by
+ * its wire name, converted to the field type and then checked by the model's
+ * `@Validator` rules — before the action runs. All problems come in one 400,
+ * named as the client sent them (`page_size`, `x-tenant-id`). Undeclared
+ * parameters are ignored; a field that is absent keeps its initializer.
+ */
+export async function bindSourceModel(binding: ParameterBinding, ctx: HttpContext): Promise<object> {
+  const model = binding.model as new () => object;
+  const instance = new model() as Record<string, unknown>;
+  const source = binding.source === "headerModel" ? "header" : "query";
+  const issues: ModelValidationIssue[] = [];
+  const failed = new Set<string>();
+  const validator = ctx.modelValidator;
+  const say = (code: string, params: Readonly<Record<string, unknown>>, english: string): ModelValidationIssue => ({
+    property: params.property as string,
+    message: validator?.message?.(code, params) ?? english,
+    code,
+    params,
+  });
+
+  for (const field of binding.fields ?? []) {
+    const raw = source === "query" ? ctx.url.searchParams.getAll(field.wire) : headerValues(ctx, field.wire);
+    if (raw.length === 0) continue;
+    if (!field.array && raw.length > 1) {
+      // `?page_size=10&page_size=1000`: the proxy and the app could read
+      // different values, so neither is taken.
+      issues.push(say("duplicate", { property: field.wire }, `Parameter "${field.wire}" must be given once`));
+      failed.add(field.property);
+      continue;
+    }
+    if (raw.length > MAX_QUERY_VALUES) {
+      issues.push(say("tooManyValues", { property: field.wire, max: MAX_QUERY_VALUES }, `Parameter "${field.wire}" accepts at most ${MAX_QUERY_VALUES} values`));
+      failed.add(field.property);
+      continue;
+    }
+    const values: unknown[] = [];
+    for (const text of raw) {
+      const value = tryConvert(text, VALUE_TYPES[field.type]);
+      if (value === INVALID) {
+        const params = { property: field.wire, expected: field.type, actual: "string" };
+        issues.push(say("type", params, `Field "${field.wire}" must be of type ${field.type}, got: string`));
+        failed.add(field.property);
+        break;
+      }
+      values.push(value);
+    }
+    if (!failed.has(field.property)) instance[field.property] = field.array ? values : values[0];
+  }
+
+  const result = validator === undefined ? undefined : await (validator.validateAsync?.(instance) ?? validator.validate(instance));
+  const wires = new Map((binding.fields ?? []).map((field) => [field.property, field.wire]));
+  for (const error of result?.errors ?? []) {
+    if (failed.has(error.property)) continue;
+    issues.push(onTheWire(error, wires, validator));
+  }
+  if (issues.length > 0) {
+    throw new ModelValidationError(issues, validator?.message?.("validationFailed", {}) ?? "Validation failed");
+  }
+  return instance;
+}
+
+/** A header field takes one value; `fetch` already joins repeated headers. */
+function headerValues(ctx: HttpContext, name: string): string[] {
+  const value = ctx.header(name);
+  return value === undefined ? [] : [value];
+}
+
+/** A rule error renamed to the wire name, the message rendered again with it. */
+function onTheWire(error: ModelValidationIssue, wires: ReadonlyMap<string, string>, validator: ModelValidator | undefined): ModelValidationIssue {
+  const wire = wires.get(error.property);
+  if (wire === undefined || wire === error.property) return error;
+  if (error.params === undefined || error.code === undefined) return { ...error, property: wire };
+  const params = { ...error.params, property: wire };
+  return { property: wire, message: validator?.message?.(error.code, params) ?? error.message, code: error.code, params };
+}

package/core/http/Binding/sources.ts

@@ -0,0 +1,76 @@
+// Standard TC39 decorators have no parameter decorators, so the source of a
+// controller argument is part of its type: `size: FromQuery<number, "page_size">`.
+// The types are erased at runtime; `bazis codegen` reads them from the method
+// signature. On a field of a query or header model the same names are field
+// decorators that set the name on the wire: `@FromQuery("page_size") pageSize = 20`.
+
+// Bun runs standard decorators natively, but Symbol.metadata may be missing.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const QUERY_NAMES = Symbol.for("bazis:http:query-names");
+const HEADER_NAMES = Symbol.for("bazis:http:header-names");
+
+/**
+ * From the query string. A primitive (`FromQuery<number>`, optionally with the
+ * name on the wire: `FromQuery<number, "page_size">`) or a class whose fields
+ * are bound and validated like a request body: `FromQuery<SearchQuery>`.
+ */
+export type FromQuery<T, Name extends string = never> = [Name] extends [never] ? T : T;
+/** From a request header: `FromHeader<string, "x-request-id">` or a header model `FromHeader<TenantHeaders>`. */
+export type FromHeader<T, Name extends string = never> = [Name] extends [never] ? T : T;
+/** From the JSON body: a request-model class, bound and validated before the action runs. */
+export type FromBody<T> = T;
+/** From a route parameter: `FromRoute<number>` or `FromRoute<string, "slug">`. */
+export type FromRoute<T, Name extends string = never> = [Name] extends [never] ? T : T;
+
+/** Query parameter name of a query-model field: `@FromQuery("page_size") pageSize = 20`. */
+export function FromQuery(name: string): (value: undefined, context: ClassFieldDecoratorContext) => void {
+  return (_value, context) => setWireName(context, QUERY_NAMES, "FromQuery", checkedName(name, "FromQuery", QUERY_NAME));
+}
+
+/** Header name of a header-model field: `@FromHeader("x-tenant-id") tenantId!: string`. */
+export function FromHeader(name: string): (value: undefined, context: ClassFieldDecoratorContext) => void {
+  return (_value, context) => setWireName(context, HEADER_NAMES, "FromHeader", checkedName(name, "FromHeader", HEADER_NAME).toLowerCase());
+}
+
+/** Wire names of a query or header model: field name → name in the request. */
+export function wireNamesOf(model: object, source: "query" | "header"): ReadonlyMap<string, string> {
+  const metadata = (model as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as WireNameMetadata | undefined;
+  return metadata?.[source === "query" ? QUERY_NAMES : HEADER_NAMES] ?? EMPTY;
+}
+
+interface WireNameMetadata {
+  [QUERY_NAMES]?: Map<string, string>;
+  [HEADER_NAMES]?: Map<string, string>;
+}
+
+const EMPTY: ReadonlyMap<string, string> = new Map();
+/** Printable ASCII without spaces; `[]` stay allowed for names like `ids[]`. */
+const QUERY_NAME = /^[\x21-\x7e]{1,256}$/;
+/** RFC 9110 token: the characters a header name may contain. */
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,256}$/;
+
+function checkedName(name: string, decorator: string, pattern: RegExp): string {
+  if (typeof name !== "string" || !pattern.test(name)) {
+    throw new TypeError(`@${decorator}: invalid name ${JSON.stringify(name)}.`);
+  }
+  return name;
+}
+
+function setWireName(context: ClassFieldDecoratorContext, key: typeof QUERY_NAMES | typeof HEADER_NAMES, decorator: string, name: string): void {
+  if (context.static || context.private || typeof context.name !== "string") {
+    throw new TypeError(`@${decorator}: "${String(context.name)}" must be a public instance field.`);
+  }
+  const metadata = context.metadata as WireNameMetadata;
+  // Metadata is inherited prototypically: copy on the first write to this class.
+  if (!Object.prototype.hasOwnProperty.call(metadata, key)) {
+    metadata[key] = new Map(metadata[key] ?? []);
+  }
+  const names = metadata[key]!;
+  for (const [field, existing] of names) {
+    if (existing === name && field !== context.name) {
+      throw new TypeError(`@${decorator}: "${name}" is used by both "${field}" and "${context.name}".`);
+    }
+  }
+  names.set(context.name, name);
+}

package/core/http/Errors/HttpError.ts

@@ -1,3 +1,4 @@
+import { KernelError } from "../../kernel";
 import type { ModelValidationIssue } from "../Binding/modelValidator";
 import { englishHttpMessage, type HttpMessageKey, type LocalizedMessage, type MessageParams } from "./messages";
 
@@ -111,11 +112,7 @@ export function frameworkBadRequest(key: HttpMessageKey, params?: MessageParams,
 
 /**
  * Misconfigured routes/controllers (duplicate route, bad template, missing
- * @Controller). Thrown at startup, never at request time — fail fast.
+ * @Controller). Thrown at startup, never at request time — fail fast. A
+ * KernelError: the start reports it as a configuration error of the code.
  */
-export class HttpSetupError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "HttpSetupError";
-  }
-}
+export class HttpSetupError extends KernelError {}

package/core/http/OpenApi/openApiDocument.ts

@@ -122,6 +122,7 @@ function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
       input.versioning,
       version,
       routeParamSchemas(input.routeTemplate),
+      input.generated,
     ),
     requestBody: createRequestBody(input.bindings, input.action, input.generated),
     responses: {
@@ -173,6 +174,7 @@ function collectParameters(
   versioning: ApiVersioningOptions | undefined,
   version: string | undefined,
   routeSchemas: Readonly<Record<string, OpenApiSchema>>,
+  generated: GeneratedOpenApiMetadata,
 ): OpenApiParameter[] {
   const parameters: OpenApiParameter[] = [];
   for (const binding of bindings) {
@@ -197,6 +199,20 @@ function collectParameters(
           });
         }
         break;
+      case "header":
+        if (binding.name) {
+          parameters.push({
+            name: binding.name,
+            in: "header",
+            required: binding.optional !== true && binding.defaultValue === undefined,
+            schema: schemaForValueType(binding.type),
+          });
+        }
+        break;
+      case "queryModel":
+      case "headerModel":
+        parameters.push(...sourceModelParameters(binding, generated));
+        break;
       case "list":
         parameters.push(...listParameters(binding));
         break;
@@ -216,6 +232,35 @@ function collectParameters(
   return parameters;
 }
 
+/**
+ * One parameter per field of a query or header model, under its wire name.
+ * Types, rules and descriptions come from the generated schema of the model
+ * (the same schema a body model gets), `required` from its `@Validator` rules.
+ */
+function sourceModelParameters(binding: ParameterBinding, generated: GeneratedOpenApiMetadata): OpenApiParameter[] {
+  const schema = binding.model ? generated.schemas[binding.model.name] : undefined;
+  const properties = (schema?.properties ?? {}) as Readonly<Record<string, OpenApiSchema>>;
+  const required = new Set(Array.isArray(schema?.required) ? (schema.required as string[]) : []);
+  const location = binding.source === "headerModel" ? "header" : "query";
+  // In the order the class declares its fields, like the body schema.
+  const order = Object.keys(properties);
+  const position = (property: string) => { const index = order.indexOf(property); return index < 0 ? order.length : index; };
+  const fields = [...(binding.fields ?? [])].sort((left, right) => position(left.property) - position(right.property));
+  return fields.map((field) => {
+    const property = properties[field.property];
+    const fallback: OpenApiSchema = field.array ? { type: "array", items: { type: field.type } } : { type: field.type };
+    const description = typeof property?.description === "string" ? property.description : undefined;
+    return {
+      name: field.wire,
+      in: location,
+      required: required.has(field.property),
+      schema: property ?? fallback,
+      ...(description !== undefined ? { description } : {}),
+      ...(field.array ? { style: "form", explode: true } : {}),
+    };
+  });
+}
+
 function listParameters(binding: ParameterBinding): OpenApiParameter[] {
   const options = binding.listOptions ?? (binding.model ? optionsFromSchema(binding.model) : {});
   const parameters: OpenApiParameter[] = [

package/core/http/README.md

@@ -60,8 +60,45 @@ Instead there are ASP.NET-style conventions that codegen infers from the signatu
 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.
+generated files are not replaced. Use a supported type or an explicit source
+(below); for raw bodies take `ctx: HttpContext`, and inject services into the
+constructor.
+
+### Explicit sources: `FromQuery`, `FromHeader`, `FromBody`, `FromRoute`
+
+When the convention is not what you want, the parameter type says where the
+value comes from. The markers are type aliases (erased at runtime) that codegen
+reads through the type checker; on a field of a query or header model the same
+names are field decorators that set the name on the wire:
+
+```ts
+export class SearchQuery {
+  @Validator({ required: true, minLength: 2 }) q!: string;
+  @FromQuery("page_size") @Validator({ integer: true, range: [1, 100] }) pageSize = 20;
+  tags: string[] = [];
+}
+export class TenantHeaders {
+  @FromHeader("x-tenant-id") @Validator({ required: true, uuid: true }) tenantId!: string;
+}
+
+@Get() search(query: FromQuery<SearchQuery>, headers: FromHeader<TenantHeaders>) {}
+@Get(":id") item(id: FromRoute<number>, size: FromQuery<number, "page_size"> = 10, requestId?: FromHeader<string, "x-request-id">) {}
+@Post() create(body: FromBody<CreateItem>) {}
+```
+
+- A query or header model is bound like a body and validated by its
+  `@Validator` rules before the action runs: every problem in one 400, under
+  the name the client sent (`page_size`, `x-tenant-id`).
+- Only declared fields are read; undeclared parameters are ignored. A repeated
+  single parameter is a 400 (`duplicate`), an array takes at most 100 values
+  (`tooManyValues`). Header names match case-insensitively.
+- Query models take `string`, `number`, `boolean` and arrays of them; header
+  models one value per field. A nested object is a startup `HttpSetupError`.
+- OpenAPI lists the model fields as `query`/`header` parameters with the
+  schema, rules and JSDoc of the model.
+- Misuse (`FromHeader<string[]>`, a name on a model, `FromRoute` outside the
+  template, `FromBody<string>`) is `BAZIS_HTTP_BINDING_UNRESOLVED`.
+
 Checking allowed values belongs to the Validator or the service.
 
 A `ctx: HttpContext` parameter stays a regular supported input. For older manual

package/core/http/SPEC.md

@@ -943,7 +943,7 @@ The guard class is registered in DI as a regular `scoped`/`singleton` provider.
 | `rateLimit` is in-memory | not shared between processes |
 | Preflight without the global `cors` | a per-route `cors()` registers no OPTIONS handler |
 | Several `@Controller` on a class | not supported: one controller class |
-| Parameter decorators | codegen infers argument sources from the signature |
+| Parameter decorators | not in TC39: codegen infers the source from the signature or from the type markers `FromQuery`/`FromHeader`/`FromBody`/`FromRoute` |
 | Middleware on abstract/private methods | route decorators apply only to public instance methods |
 
 ---

package/core/http/index.ts

@@ -59,6 +59,7 @@ export {
 
 // Binding
 export type { BindingSource, ParameterBinding } from "./Binding/bindings";
+export { FromHeader, FromQuery, type FromBody, type FromRoute } from "./Binding/sources";
 export type { ValueType } from "./Binding/convert";
 export { RequestModel } from "./Binding/RequestModel";
 

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.100.7" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.101.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/kernel/Bazis.ts

@@ -69,9 +69,17 @@ export class Bazis {
     } catch (error) {
       stopWaiting?.();
       if (error instanceof ShutdownTimeoutError) {
+        // A failed start whose cleanup is stuck: report why the start failed
+        // first, otherwise only the cleanup timeout would be visible.
+        const startFailure = error.cause;
+        if (startFailure !== undefined) {
+          if (screen !== undefined) screen.failed(startFailure, kernel);
+          else console.error(`[bazis] application failed: ${formatStartupFailure(startFailure)}`);
+        }
         // Graceful shutdown is stuck: hanging handles would keep the process
         // alive forever, so this is the one place a hard exit is correct.
-        console.error(`[bazis] ${redactSensitiveText(error.message)} Forcing exit.`);
+        const text = startFailure === undefined ? error.message : `Cleanup after the failed start did not finish within ${error.timeoutMs}ms.`;
+        console.error(`[bazis] ${redactSensitiveText(text)} Forcing exit.`);
         process.exit(1);
       }
       // Configuration problems surfacing at start (e.g. options fail-fast)

package/core/kernel/LifecycleCoordinator.ts

@@ -97,7 +97,16 @@ export class LifecycleCoordinator {
 
     try {
       for (let index = 0; index < this.hooks.length; index += 1) {
-        await this.invokeHook(() => (this.hooks[index] as LifecycleHook).onInit?.(), signal);
+        const hook = this.hooks[index] as LifecycleHook;
+        if (hook.onInit === undefined) continue;
+        // A hung onInit is named by the startup timeout, like a hosted service.
+        const name = `hook ${hook.constructor?.name ?? "LifecycleHook"}.onInit`;
+        this.pending.add(name);
+        try {
+          await this.invokeHook(() => hook.onInit?.(), signal);
+        } finally {
+          this.pending.delete(name);
+        }
       }
 
       const phases = groupByPhase(hosted);

package/core/kernel/config/defineConfig.ts

@@ -184,7 +184,11 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
       const priority = Math.max(...candidates.map(candidate => candidate.priority));
       const winners = candidates.filter(candidate => candidate.priority === priority);
       const selected = winners[0];
-      if (winners.some(candidate => candidate.raw !== selected?.raw)) issue(key, "conflict", "conflicting environment aliases");
+      if (winners.some(candidate => candidate.raw !== selected?.raw)) {
+        // Names only: the values may be secrets.
+        const variables = [...new Set(winners.map(candidate => candidate.name))];
+        issue(key, "conflict", `conflicting environment aliases: ${variables.join(" and ")} are set to different values; set only one`);
+      }
       const raw = selected?.raw ?? (isSecret(cell) || isEnum(cell) ? cell.default : cell);
       let value: ConfigValueType | undefined;
       if (type === "secret") {

package/core/kernel/startupFailure.ts

@@ -1,6 +1,6 @@
 import { inspect } from "node:util";
 import { redactSensitive, redactSensitiveText } from "../../library/redaction";
-import { StartupFailuresError } from "./errors";
+import { ShutdownTimeoutError, StartupFailuresError, StartupTimeoutError } from "./errors";
 
 const MAX_CAUSES = 5;
 /** Properties already printed in the header, the frames or the cause chain. */
@@ -32,7 +32,9 @@ export function formatStartupFailure(error: unknown): string {
     // Services that failed together: the list above is the report; the
     // aggregate's own frames are the kernel's, not the application's.
     if (!(current instanceof StartupFailuresError)) lines.push(...(current.stack ?? "").split("\n").filter((line) => /^\s+at /.test(line)));
-    const details = Object.fromEntries(Object.entries(current).filter(([name]) => !SHOWN.has(name)));
+    // Timeouts already say their limit and what was pending in the message.
+    const restated = current instanceof StartupTimeoutError || current instanceof ShutdownTimeoutError;
+    const details = restated ? {} : Object.fromEntries(Object.entries(current).filter(([name]) => !SHOWN.has(name)));
     if (Object.keys(details).length > 0) lines.push(inspect(redactSensitive(details), INSPECT));
     current = current.cause;
   }

package/core/scripts/di-generate.ts

@@ -194,7 +194,7 @@ let fatalErrors: string[] = [];
 
 // HTTP binding conventions inferred from controller method signatures.
 interface HttpBindingSpec {
-  source: "route" | "query" | "body" | "context" | "request" | "response" | "list";
+  source: "route" | "query" | "header" | "body" | "queryModel" | "headerModel" | "context" | "request" | "response" | "list";
   name?: string;
   type?: "int" | "number" | "bool" | "string";
   optional?: boolean;
@@ -244,6 +244,9 @@ const CONTEXT_TYPES: Record<string, HttpBindingSpec["source"]> = {
   Request: "request",
   ResponseBuilder: "response",
 };
+// Explicit argument sources of bazis/core/http: `size: FromQuery<number, "page_size">`.
+type SourceMarkerKind = "FromQuery" | "FromHeader" | "FromBody" | "FromRoute";
+const SOURCE_MARKERS: ReadonlySet<string> = new Set<SourceMarkerKind>(["FromQuery", "FromHeader", "FromBody", "FromRoute"]);
 let program: ts.Program;
 let programFiles = new Map<string, ts.SourceFile>();
 // Framework sources outside the scanned project (node_modules/bazis, vendor/bazis).
@@ -1464,6 +1467,25 @@ function collectControllerBindings(node: ts.ClassDeclaration, controllerName: st
       const paramName = param.name.text;
       const optional = param.questionToken !== undefined || param.initializer !== undefined;
       const typeNode = param.type;
+
+      // An explicit source: FromQuery<…>, FromHeader<…>, FromBody<…>, FromRoute<…>.
+      const marker = typeNode ? sourceMarker(typeNode) : undefined;
+      if (marker !== undefined) {
+        const spec = markerBindingSpec(marker, paramName, optional, routeParams);
+        if (typeof spec === "string") {
+          failed = spec;
+          break;
+        }
+        if (spec.source === "body") {
+          bodyCount += 1;
+          if (bodyCount > 1) {
+            failed = "more than one body (class-typed) parameter";
+            break;
+          }
+        }
+        specs.push(spec);
+        continue;
+      }
       const keywordType = typeNode ? typeNode.getText().trim() : undefined;
       const refName = typeNode ? getTypeReferenceName(typeNode) : undefined;
 
@@ -1511,7 +1533,7 @@ function collectControllerBindings(node: ts.ClassDeclaration, controllerName: st
     if (failed) {
       fatalErrors.push(
         `BAZIS_HTTP_BINDING_UNRESOLVED: controller "${controllerName}.${name}" (${filePath}): cannot infer bindings (${failed}). ` +
-          `Use supported parameter types; read headers or raw bodies through HttpContext, and inject services in the constructor.`,
+          `Use supported parameter types or mark the source with FromQuery/FromHeader/FromBody/FromRoute; read raw bodies through HttpContext, and inject services in the constructor.`,
       );
       continue;
     }
@@ -1519,6 +1541,77 @@ function collectControllerBindings(node: ts.ClassDeclaration, controllerName: st
   }
 }
 
+interface SourceMarker {
+  readonly kind: SourceMarkerKind;
+  readonly inner?: ts.TypeNode;
+  /** The name on the wire from the second type argument. */
+  readonly name?: string;
+  readonly problem?: string;
+}
+
+/**
+ * A parameter type that is one of the source markers of bazis/core/http,
+ * resolved through the type checker: an aliased import (`FromQuery as Q`)
+ * works, an application type that happens to be called FromQuery does not.
+ */
+function sourceMarker(node: ts.TypeNode): SourceMarker | undefined {
+  if (!ts.isTypeReferenceNode(node)) return undefined;
+  const typeName = ts.isQualifiedName(node.typeName) ? node.typeName.right : node.typeName;
+  const symbol = checker.getSymbolAtLocation(typeName);
+  if (symbol === undefined) return undefined;
+  const target = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+  const kind = target.getName();
+  if (!SOURCE_MARKERS.has(kind)) return undefined;
+  const fromFramework = target.declarations?.some((declaration) =>
+    /\/core\/http\/Binding\/sources(\.d)?\.ts$/.test(declaration.getSourceFile().fileName.replaceAll("\\", "/")));
+  if (!fromFramework) return undefined;
+  const [inner, name] = node.typeArguments ?? [];
+  const marker = kind as SourceMarkerKind;
+  if (inner === undefined) return { kind: marker, problem: `${kind} needs a type argument` };
+  if (name === undefined) return { kind: marker, inner };
+  if (ts.isLiteralTypeNode(name) && ts.isStringLiteral(name.literal) && name.literal.text.length > 0) {
+    return { kind: marker, inner, name: name.literal.text };
+  }
+  return { kind: marker, problem: `the name in ${kind}<…, "name"> must be a non-empty string literal` };
+}
+
+/** The binding of an explicitly sourced parameter, or why it cannot be bound. */
+function markerBindingSpec(marker: SourceMarker, paramName: string, optional: boolean, routeParams: ReadonlySet<string>): HttpBindingSpec | string {
+  if (marker.problem !== undefined || marker.inner === undefined) return marker.problem ?? `${marker.kind} needs a type argument`;
+  const inner = marker.inner;
+  const primitive = PRIMITIVE_QUERY_TYPES[inner.getText().trim()];
+  const elementKeyword = arrayElementKeyword(inner);
+  const element = elementKeyword !== undefined ? PRIMITIVE_QUERY_TYPES[elementKeyword] : undefined;
+  const model = getTypeReferenceName(inner);
+  const name = marker.name ?? paramName;
+  const type = (value: HttpBindingSpec["type"]) => (value === "string" ? undefined : value);
+  switch (marker.kind) {
+    case "FromRoute":
+      if (!routeParams.has(name)) return `FromRoute parameter "${name}" is not in the route template`;
+      if (primitive === undefined) return `FromRoute<${inner.getText()}> takes string, number or boolean`;
+      return { source: "route", name, type: type(primitive), optional };
+    case "FromQuery":
+      if (element !== undefined) return { source: "query", name, type: type(element), optional, array: true };
+      if (primitive !== undefined) return { source: "query", name, type: type(primitive), optional };
+      if (model !== undefined && marker.name === undefined) {
+        return listRequestClassNames.has(model) ? { source: "list", model, optional } : { source: "queryModel", model, optional };
+      }
+      return model !== undefined
+        ? `FromQuery<${model}, "…">: a query model takes no name; name its fields with @FromQuery("…")`
+        : `FromQuery<${inner.getText()}> takes string, number, boolean, an array of them or a query model class`;
+    case "FromHeader":
+      if (element !== undefined) return `FromHeader<${inner.getText()}>: a header takes one value`;
+      if (primitive !== undefined) return { source: "header", name, type: type(primitive), optional };
+      if (model !== undefined && marker.name === undefined) return { source: "headerModel", model, optional };
+      return model !== undefined
+        ? `FromHeader<${model}, "…">: a header model takes no name; name its fields with @FromHeader("…")`
+        : `FromHeader<${inner.getText()}> takes string, number, boolean or a header model class`;
+    case "FromBody":
+      if (model === undefined || primitive !== undefined || element !== undefined) return `FromBody<${inner.getText()}> takes a request-model class; read a raw body through HttpContext`;
+      return { source: "body", model, optional };
+  }
+}
+
 interface ControllerAction {
   readonly name: string;
   /** Declaration whose route decorators give the routes. */
@@ -1619,7 +1712,7 @@ function resolveRequestModelImports(): RequestModelImport[] {
   for (const methods of Object.values(httpBindings)) {
     for (const specs of Object.values(methods)) {
       for (const spec of specs) {
-        if (spec.source === "body" && spec.model !== undefined) {
+        if ((spec.source === "body" || spec.source === "queryModel" || spec.source === "headerModel") && spec.model !== undefined) {
           modelNames.add(spec.model);
         }
       }
@@ -1956,7 +2049,7 @@ function usedOpenApiSchemaNames(
   for (const methods of Object.values(httpBindings)) {
     for (const specs of Object.values(methods)) {
       for (const spec of specs) {
-        if ((spec.source === "body" || spec.source === "list") && spec.model !== undefined) {
+        if ((spec.source === "body" || spec.source === "list" || spec.source === "queryModel" || spec.source === "headerModel") && spec.model !== undefined) {
           add(spec.model);
         }
       }

package/library/http-client/HttpClient.ts

@@ -1,4 +1,5 @@
 import { HttpClientError, HttpErrorCode } from "./errors";
+import { assertKnownOptions } from "./configKeys";
 import { InspectableRedirectProtocol as redirectProtocol } from "./redirectProtocol";
 import { InterceptorManager } from "./interceptors";
 import { trackDownload } from "./progress";
@@ -85,6 +86,7 @@ export class HttpClient {
   };
 
   public constructor(defaults: RequestConfig = {}) {
+    assertKnownOptions(defaults, "the client defaults");
     this.defaults = defaults;
     this.interceptors = {
       request: new InterceptorManager<ResolvedRequestConfig>(),
@@ -106,6 +108,11 @@ export class HttpClient {
   public request<T = unknown>(configOrUrl: RequestConfig | string, maybeConfig: RequestConfig = {}): Promise<HttpResponse<T>> {
     const config: RequestConfig =
       typeof configOrUrl === "string" ? { ...maybeConfig, url: configOrUrl } : configOrUrl;
+    try {
+      assertKnownOptions(config, "the request config");
+    } catch (error) {
+      return Promise.reject(error);
+    }
     const merged = this.mergeConfig(this.defaults, config);
 
     // axios ordering: request interceptors run last-registered-first.

package/library/http-client/configKeys.ts

@@ -0,0 +1,36 @@
+import { HttpClientError } from "./errors";
+import type { RequestConfig } from "./types";
+
+/**
+ * Every option of {@link RequestConfig}, checked so a misspelled one is not
+ * silently ignored. A record, not a list: a new option fails typecheck until
+ * it is added here.
+ */
+const OPTIONS: Readonly<Record<keyof RequestConfig, true>> = {
+  url: true, method: true, baseUrl: true, headers: true, params: true, paramsSerializer: true, data: true,
+  transformRequest: true, transformResponse: true, onDownloadProgress: true, timeoutMs: true, maxResponseBytes: true,
+  signal: true, responseType: true, withCredentials: true, credentials: true, auth: true,
+  allowCrossOriginCredentials: true, validateStatus: true, retry: true, propagateCorrelation: true,
+  correlationHeaders: true, fetch: true, inspectableRedirects: true, redirect: true, maxRedirects: true, cache: true,
+  mode: true, keepalive: true, meta: true,
+};
+const KNOWN: ReadonlySet<string> = new Set(Object.keys(OPTIONS));
+
+/** axios names with a different spelling here. */
+const AXIOS_NAMES: Readonly<Record<string, keyof RequestConfig>> = {
+  timeout: "timeoutMs",
+  maxContentLength: "maxResponseBytes",
+};
+
+/**
+ * Rejects an option the client does not know. Without it `baseURL` (the axios
+ * spelling) was dropped, and every call failed with ERR_NETWORK
+ * "fetch() URL is invalid".
+ */
+export function assertKnownOptions(config: object, where: string): void {
+  for (const key of Object.keys(config)) {
+    if (KNOWN.has(key)) continue;
+    const suggestion = AXIOS_NAMES[key] ?? [...KNOWN].find((known) => known.toLowerCase() === key.toLowerCase());
+    throw new HttpClientError(`Unknown HttpClient option "${key}" in ${where}${suggestion === undefined ? "" : `; did you mean "${suggestion}"?`}`);
+  }
+}

package/library/validation/MessageRegistry.ts

@@ -40,6 +40,8 @@ export const EN_VALIDATION_MESSAGES: Readonly<Record<string, string>> = Object.f
   asyncCustomInSyncCall:
     'Field "{property}": an async custom check is not supported by synchronous validate(); use validateAsync()',
   unknownField: 'Field "{property}" is forbidden or not declared by the model.',
+  duplicate: 'Parameter "{property}" must be given once',
+  tooManyValues: 'Parameter "{property}" accepts at most {max} values',
 });
 const BUILT_IN = EN_VALIDATION_MESSAGES;
 
@@ -86,6 +88,8 @@ export const RU_VALIDATION_MESSAGES: Readonly<Record<string, string>> = Object.f
   asyncCustomInSyncCall:
     'Поле "{property}": асинхронная custom-проверка не поддерживается синхронным validate(), используйте validateAsync()',
   unknownField: 'Поле "{property}" запрещено или не объявлено в модели',
+  duplicate: 'Параметр "{property}" передан несколько раз',
+  tooManyValues: 'Параметр "{property}": максимум значений — {max}',
   "typeName.string": "строка",
   "typeName.number": "число",
   "typeName.int": "целое число",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.100.7",
+  "version": "0.101.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",