bazis 0.136.0 → 0.138.0

package/core/http/Decorators/routes.ts

@@ -1,5 +1,6 @@
 import type { HttpMiddleware } from "../Middleware/types";
 import { HttpSetupError } from "../Errors/HttpError";
+import type { HttpResult } from "../Results/HttpResult";
 import { ownActionMeta, ownRoutes } from "./metadata";
 
 type MethodDecorator = (value: (...args: never[]) => unknown, context: ClassMethodDecoratorContext) => void;
@@ -27,6 +28,11 @@ export interface RouteOptions {
   readonly version?: string;
   /** Route middleware (= `@Middleware` on the method). */
   readonly middleware?: readonly HttpMiddleware[];
+  /**
+   * What `null` or `undefined` from the action means, as a result helper:
+   * `{ nullAs: NotFound }` answers 404 with the standard body instead of 204.
+   */
+  readonly nullAs?: () => HttpResult;
   /** Maximum body size: an integer and a binary unit together, for example `4mb`. */
   readonly maxBodySize?: `${bigint}${"b" | "kb" | "mb" | "gb"}`;
 }
@@ -59,6 +65,12 @@ function route(httpMethod: string, templateOrOptions?: string | RouteOptions, ma
       if (options.middleware !== undefined) {
         action.middleware.push(...options.middleware);
       }
+      if (options.nullAs !== undefined) {
+        if (typeof options.nullAs !== "function") {
+          throw new HttpSetupError("nullAs must be a result helper, for example NotFound.");
+        }
+        action.nullAs = options.nullAs;
+      }
       if (options.maxBodySize !== undefined) {
         const maxBodyBytes = parseRouteMaxBodySize(options.maxBodySize);
         if (action.maxBodyBytes !== undefined && action.maxBodyBytes !== maxBodyBytes) {

package/core/http/Errors/HttpError.ts

@@ -1,6 +1,6 @@
 import { KernelError } from "../../kernel";
 import type { ModelValidationIssue } from "../Binding/modelValidator";
-import { englishHttpMessage, type HttpMessageKey, type LocalizedMessage, type MessageParams } from "./messages";
+import { englishHttpMessage, STATUS_MESSAGE_KEYS, type HttpMessageKey, type LocalizedMessage, type MessageParams } from "./messages";
 
 /**
  * Base class for errors that map directly to an HTTP response.
@@ -14,7 +14,7 @@ export class HttpError extends Error {
     readonly details?: unknown,
     /**
      * Key and parameters of the message: the error handler renders it in the
-     * application language (`runApp({ language, messages })`); `message` is the
+     * application language (`@App({ language, messages })`); `message` is the
      * English text. Errors created with their own text have no key.
      */
     readonly localized?: LocalizedMessage,
@@ -59,6 +59,14 @@ export class NotFoundError extends HttpError {
   }
 }
 
+/** The request conflicts with what is stored: the name is taken, the record changed meanwhile. */
+export class ConflictError extends HttpError {
+  constructor(message?: string, details?: unknown) {
+    const [text, localized] = textOf(message, "conflict");
+    super(409, text, details, localized);
+  }
+}
+
 export class MethodNotAllowedError extends HttpError {
   constructor(readonly allow: readonly string[]) {
     super(405, englishHttpMessage("methodNotAllowed"), undefined, { key: "methodNotAllowed" });
@@ -116,3 +124,9 @@ export function frameworkBadRequest(key: HttpMessageKey, params?: MessageParams,
  * KernelError: the start reports it as a configuration error of the code.
  */
 export class HttpSetupError extends KernelError {}
+
+/** An error of a status with the framework text for it, translated at the response: what an empty result helper stands for. */
+export function httpErrorOfStatus(status: number): HttpError {
+  const key = STATUS_MESSAGE_KEYS[status] ?? (status >= 500 ? "serverError" : "clientError");
+  return new HttpError(status, englishHttpMessage(key), undefined, { key });
+}

package/core/http/Http.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "../kernel";
+
+/**
+ * Where the HTTP server listens. `BAZIS_HTTP__HOST` and `BAZIS_HTTP__PORT` set it
+ * from the environment. Outside `production` the server is reachable from this
+ * machine only; in `production` it listens on every interface.
+ *
+ * A `port` or `hostname` written in `@App({ http })` is fixed in code and wins.
+ */
+export const httpConfig = defineConfig("http", {
+  default: {
+    host: "127.0.0.1",
+    port: 3000,
+  },
+  production: {
+    host: "0.0.0.0",
+  },
+  validate: {
+    port: (port) => (Number.isInteger(port) && port >= 0 && port <= 65535 ? undefined : "must be a TCP port (0-65535)"),
+    host: (host) => (host.trim() === "" ? "must not be empty" : undefined),
+  },
+});

package/core/http/HttpContext/HttpContext.ts

@@ -50,7 +50,7 @@ export class HttpContext {
     /** Validator captured by the owning HTTP server. */
     readonly modelValidator?: ModelValidator,
     /**
-     * Response language of this request: `runApp({ language })`, or the best
+     * Response language of this request: `@App({ language })`, or the best
      * match of `Accept-Language` when several languages are supported.
      * `undefined` without `language`.
      */

package/core/http/HttpServer.ts

@@ -19,10 +19,11 @@ import { defaultAuthorizeChecks } from "./Authorization/metadata";
 import type { Router } from "./Routing/Router";
 import { parseRequestPath } from "./Routing/template";
 import { assertVersioningOptions, createVersionReader, type VersionReader } from "./Versioning/VersionReader";
-import { HTTP_ERROR_HOOK, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOrder } from "./middlewareTokens";
+import { HTTP_ERROR_HOOK, HTTP_ERROR_MAPPER, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOrder } from "./middlewareTokens";
 import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions, HttpServerOptions } from "./options";
 import { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
-import { HttpSetupError } from "./Errors/HttpError";
+import { HttpSetupError, type HttpError } from "./Errors/HttpError";
+import { httpConfig } from "./Http.config";
 import { clientAddress, trustedProxies, type TrustedProxies } from "./HttpContext/clientAddress";
 import { EN_HTTP_MESSAGES, formatMessage, languageHeaders, type HttpMessageKey, type MessageParams, type SelectedLanguage } from "./Errors/messages";
 import { getModelValidator, type ModelValidator } from "./Binding/modelValidator";
@@ -180,6 +181,7 @@ export class HttpServer implements HostedService {
         ...(this.options.languages ? { languages: this.options.languages } : {}),
         ...this.options.errorHandler,
         onUnexpectedError: this.collectErrorHook(),
+        map: this.collectErrorMapper(),
       }),
     );
     this.shortCircuitChain = [...serverChain];
@@ -281,14 +283,14 @@ export class HttpServer implements HostedService {
   }
 
   private async startBunServer(create: (listen: ListenOptions) => ReturnType<typeof Bun.serve>): Promise<ReturnType<typeof Bun.serve>> {
-    const attempts = this.options.port === 0 ? 10 : 1;
+    const listen = this.listenOptions();
+    const attempts = listen.port === 0 ? 10 : 1;
     let lastError: unknown;
     for (let attempt = 0; attempt < attempts; attempt += 1) {
-      const listen = await this.resolveListenOptions();
       try {
         return create(listen);
       } catch (error) {
-        if (this.options.port !== 0 || !isAddressInUse(error)) {
+        if (listen.port !== 0 || !isAddressInUse(error)) {
           throw error;
         }
         lastError = error;
@@ -297,12 +299,14 @@ export class HttpServer implements HostedService {
     throw lastError;
   }
 
-  private async resolveListenOptions(): Promise<ListenOptions> {
-    const hostname = this.options.hostname ?? (this.options.port === 0 ? "127.0.0.1" : undefined);
+  /** The address: what the options fix in code, otherwise the `http` settings. */
+  private listenOptions(): ListenOptions {
+    const settings = this.resolver.tryResolve(httpConfig.token);
     // Let the operating system reserve an ephemeral port atomically. Picking a
     // random port in user space creates a check/use race between concurrent
     // application or test processes and can still exhaust every retry.
-    const port = this.options.port ?? 3000;
+    const port = this.options.port ?? settings?.get("port") ?? 3000;
+    const hostname = this.options.hostname ?? (this.options.port === 0 ? "127.0.0.1" : settings?.get("host"));
     return {
       port,
       ...(hostname !== undefined ? { hostname } : {}),
@@ -332,6 +336,22 @@ export class HttpServer implements HostedService {
     };
   }
 
+  /** Explicit `options.errorHandler.map` first, then DI {@link HTTP_ERROR_MAPPER} mappers; the first answer wins. */
+  private collectErrorMapper(): ((error: unknown) => HttpError | undefined) | undefined {
+    const explicit = this.options.errorHandler?.map;
+    const mappers = [...(explicit === undefined ? [] : [explicit]), ...this.resolver.resolveAll(HTTP_ERROR_MAPPER)];
+    if (mappers.length === 0) {
+      return undefined;
+    }
+    return (error) => {
+      for (const mapper of mappers) {
+        const mapped = mapper(error);
+        if (mapped !== undefined) return mapped;
+      }
+      return undefined;
+    };
+  }
+
   /** Explicit `options.routeMiddlewareComposer` (order 0) merged with DI {@link ROUTE_MIDDLEWARE_COMPOSER}. */
   private collectRouteComposer(): RouteMiddlewareComposer | undefined {
     const explicit = this.options.routeMiddlewareComposer
@@ -400,7 +420,7 @@ export class HttpServer implements HostedService {
     return request.method === "HEAD" ? stripBody(response) : response;
   }
 
-  /** The response language of a request; `undefined` without `runApp({ language })`. */
+  /** The response language of a request; `undefined` without `@App({ language })`. */
   private selected(request: Request | undefined): SelectedLanguage | undefined {
     try {
       return this.options.languages?.select(request?.headers.get("accept-language"));

package/core/http/Middleware/errorHandler.ts

@@ -28,6 +28,12 @@ export interface ErrorHandlerOptions {
    * mistake and is not logged or sent to `onUnexpectedError`.
    */
   status?: (error: unknown) => number | undefined;
+  /**
+   * Turns a non-{@link HttpError} failure into an HttpError, with its own text
+   * and details; `HTTP_ERROR_MAPPER` registrations are merged in. Asked before
+   * {@link status}. A mapped 5xx is still logged as unexpected.
+   */
+  map?: (error: unknown) => HttpError | undefined;
   /**
    * Logger for unexpected errors when {@link logError} is absent: one `error`
    * line with the method, path, request id and the redacted error. The server
@@ -114,7 +120,16 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
   return async (ctx, next) => {
     try {
       await next();
-    } catch (error) {
+    } catch (thrown) {
+      let error = thrown;
+      if (!(thrown instanceof HttpError) && options.map !== undefined) {
+        let mapped: HttpError | undefined;
+        try { mapped = options.map(thrown); } catch { mapped = undefined; }
+        if (mapped instanceof HttpError) {
+          if (mapped.status >= 500) safelyReportUnexpected(options, log, ctx, thrown);
+          error = mapped;
+        }
+      }
       const selected = options.languages?.select(ctx.header("accept-language"));
       const text = textRenderer(selected?.localize);
       const language = languageHeaders(options.languages, selected);

package/core/http/OpenApi/openApiDocument.ts

@@ -23,7 +23,7 @@ export interface HttpOpenApiDocumentBuildInput {
   readonly versioning?: ApiVersioningOptions;
   readonly title: string;
   readonly version: string;
-  /** Default checks of `runApp({ http: { authorize } })`: such routes are secured too. */
+  /** Default checks of `@App({ http: { authorize } })`: such routes are secured too. */
   readonly authorize?: readonly AuthorizeCheck[];
 }
 
@@ -87,7 +87,42 @@ function collectOpenApiOperations(
       }
     }
   }
-  return operations;
+  return withCreatedLocation(operations);
+}
+
+/**
+ * Documents the automatic `Location` of a 201: the server sets it when the
+ * body has `id` and a GET route answers `<path>/<id>`.
+ */
+function withCreatedLocation(operations: OpenApiCatalogOperation[]): OpenApiCatalogOperation[] {
+  const itemPaths = new Set<string>();
+  for (const operation of operations) {
+    const parent = /^(.*)\/\{[^{}/]+\}$/u.exec(operation.path)?.[1];
+    if (operation.httpMethod === "GET" && parent !== undefined) {
+      itemPaths.add(parent);
+    }
+  }
+  return operations.map((operation) => {
+    const created = operation.responses["201"];
+    if (!created || !itemPaths.has(operation.path.replace(/\/+$/u, ""))) {
+      return operation;
+    }
+    return {
+      ...operation,
+      responses: {
+        ...operation.responses,
+        "201": {
+          ...created,
+          headers: {
+            Location: {
+              description: "Address of the created item, when the response has `id`.",
+              schema: { type: "string" },
+            },
+          },
+        },
+      },
+    };
+  });
 }
 
 interface CreateOperationInput {
@@ -140,7 +175,7 @@ function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
             },
           }
         : { description: "Success" },
-      ...errorResponses(errorStatuses(input.bindings, authorized, generatedOperation?.errors)),
+      ...errorResponses(errorStatuses(input.bindings, authorized, generatedOperation?.errors, input.action)),
     },
     authorized,
     ...(version !== undefined ? { versions: [version] } : {}),
@@ -380,15 +415,19 @@ function successStatus(method: string, action: ActionMeta, generated: number | u
 /**
  * Errors the operation can answer with: 400 when the request carries values
  * that are converted or validated (body, list query, query and header values
- * and models, typed route parameters), 401/403 under @Authorize, and the
- * errors the method body returns or throws itself.
+ * and models, typed route parameters), 401/403 under @Authorize, the status of
+ * `nullAs`, and the errors the method body returns or throws itself.
  */
 function errorStatuses(
   bindings: readonly ParameterBinding[],
   authorized: boolean,
   generated: readonly number[] | undefined,
+  action: ActionMeta,
 ): number[] {
   const statuses = new Set(generated ?? []);
+  // `nullAs: NotFound` is an answer of the route the method body does not show.
+  const instead = action.nullAs?.().status;
+  if (instead !== undefined && instead >= 400) statuses.add(instead);
   const validated = bindings.some((binding) =>
     binding.source === "body" || binding.source === "list" || binding.source === "query" || binding.source === "header"
     || binding.source === "queryModel" || binding.source === "headerModel"

package/core/http/Results/normalize.ts

@@ -1,4 +1,5 @@
 import type { HttpContext } from "../HttpContext/HttpContext";
+import { httpErrorOfStatus } from "../Errors/HttpError";
 import { HttpResult } from "./HttpResult";
 
 /** Per-action response defaults coming from decorators. */
@@ -7,6 +8,26 @@ export interface ResponseDefaults {
   httpCode?: number;
   /** `@Produces(...)` value. */
   produces?: string;
+  /** `nullAs` of the route: the result that stands for `null` and `undefined`. */
+  nullAs?: () => HttpResult;
+  /**
+   * Address of a created item for an automatic `Location` header: given the
+   * `id` of a 201 body, returns the address or `undefined` when the
+   * application has no GET route for it.
+   */
+  locate?: (ctx: HttpContext, id: string | number) => string | undefined;
+}
+
+/** `id` of a 201 body that can name the created item. */
+function createdItemId(body: unknown): string | number | undefined {
+  if (body === null || typeof body !== "object" || Array.isArray(body) || isBinaryBody(body)) {
+    return undefined;
+  }
+  const id = (body as { id?: unknown }).id;
+  if (typeof id === "number" && Number.isFinite(id)) {
+    return id;
+  }
+  return typeof id === "string" && id !== "" ? id : undefined;
 }
 
 type ResponseBody = ConstructorParameters<typeof Response>[0];
@@ -26,15 +47,24 @@ function isBinaryBody(body: unknown): body is Blob | Uint8Array | ArrayBuffer |
  * - `string` — text/plain (unless `@Produces` says otherwise);
  * - `Blob`/bytes/stream — binary passthrough;
  * - any other object/array/number/boolean — JSON;
- * - `undefined`/`null` — empty body, 204 (or `@HttpCode`).
+ * - `undefined`/`null` — empty body, 204 (or `@HttpCode`), unless the route says `nullAs`.
  *
  * Status priority: result helper > `@HttpCode` > `ctx.res.status(...)` > default.
  * Headers from `ctx.res.header(...)` are merged into every non-raw response.
+ *
+ * A 201 without `Location` whose body is an object with `id` gets
+ * `Location: <request path>/<id>` when a GET route answers that address.
  */
 export function normalizeResult(result: unknown, ctx: HttpContext, defaults: ResponseDefaults): Response {
   if (result instanceof Response) {
     return result;
   }
+  if ((result === null || result === undefined) && defaults.nullAs !== undefined) {
+    const instead = defaults.nullAs();
+    // An error goes through the error handler: the standard body, in the language of the request.
+    if (instead.status >= 400) throw httpErrorOfStatus(instead.status);
+    result = instead;
+  }
 
   const builderStatus = ctx.res.statusOverride;
   const builderHeaders = ctx.res.headers;
@@ -63,6 +93,13 @@ export function normalizeResult(result: unknown, ctx: HttpContext, defaults: Res
   for (const [name, value] of builderHeaders) {
     headers.append(name, value);
   }
+  if (status === 201 && defaults.locate && !headers.has("location")) {
+    const id = createdItemId(body);
+    const location = id === undefined ? undefined : defaults.locate(ctx, id);
+    if (location !== undefined) {
+      headers.set("location", location);
+    }
+  }
 
   let payload: ResponseBody = null;
   if (body === undefined || body === null) {

package/core/http/Results/results.ts

@@ -5,8 +5,11 @@ export function Ok(body?: unknown): HttpResult {
   return new HttpResult(200, body);
 }
 
-/** 201 Created with optional Location header. */
-export function Created(location?: string, body?: unknown): HttpResult {
+/**
+ * 201 Created. Without `location` the server derives it: a body with `id`
+ * gets `Location: <request path>/<id>` when a GET route answers that address.
+ */
+export function Created(body?: unknown, location?: string): HttpResult {
   return new HttpResult(201, body, location ? [["location", location]] : undefined);
 }
 

package/core/http/Routing/RouterBuilder.ts

@@ -23,7 +23,7 @@ export interface RegisteredRoute {
   readonly anonymous: boolean;
 }
 import { Router, type RouteAction } from "./Router";
-import { joinPaths, parseTemplate } from "./template";
+import { joinPaths, parseRequestPath, parseTemplate } from "./template";
 
 type ControllerInstance = Record<string | symbol, (...args: unknown[]) => unknown>;
 
@@ -43,6 +43,8 @@ export class RouterBuilder {
   private readonly authorizeComposer: RouteMiddlewareComposer;
   /** Every route of the last {@link build}, in registration order. */
   readonly routes: RegisteredRoute[] = [];
+  /** Router of the last {@link build}: automatic `Location` looks up GET routes in it. */
+  private router?: Router;
 
   constructor(
     /** Middleware prepended to every route: [logger?, cors?, errorHandler, ...global]. */
@@ -58,6 +60,7 @@ export class RouterBuilder {
 
   build(controllers: readonly Class<object>[]): Router {
     const router = new Router();
+    this.router = router;
     for (const controllerClass of controllers) {
       const meta = controllerMetaOf(controllerClass);
       if (!meta?.isController) {
@@ -122,6 +125,23 @@ export class RouterBuilder {
     }
   }
 
+  /**
+   * Address of an item created by a request: the request path plus `/<id>`,
+   * but only when a GET route of this application answers it.
+   */
+  private locateCreated(ctx: HttpContext, id: string | number): string | undefined {
+    const segments = parseRequestPath(ctx.url.pathname);
+    if (!segments || !this.router) {
+      return undefined;
+    }
+    const value = String(id);
+    const match = this.router.match("GET", [...segments, value], ctx.apiVersion);
+    if (match.kind !== "matched") {
+      return undefined;
+    }
+    return `${ctx.url.pathname.replace(/\/+$/u, "")}/${encodeURIComponent(value)}`;
+  }
+
   /**
    * Precompiles binding + ActionFilter.before as a boundary middleware and
    * controller execution + ActionFilter.after as the terminal. This lets
@@ -138,7 +158,12 @@ export class RouterBuilder {
     const catches = meta.catches;
     const bindings = resolveGeneratedBindings(controllerClass, methodName);
     assertBindingsFresh(controllerClass, methodName, bindings);
-    const responseDefaults = { httpCode: action.httpCode, produces: action.produces };
+    const responseDefaults = {
+      httpCode: action.httpCode,
+      nullAs: action.nullAs,
+      produces: action.produces,
+      locate: (ctx: HttpContext, id: string | number) => this.locateCreated(ctx, id),
+    };
     const bindingDefaults = { consumes: action.consumes };
     const token = controllerClass as unknown as Token<object>;
     const boundArguments = new WeakMap<HttpContext, readonly unknown[]>();

package/core/http/httpModule.ts

@@ -1,24 +1,25 @@
-import { DI, HOSTED_SERVICE, Module, SERVICE_PROVIDER, collectModuleControllers, type BazisModule, type ProviderDefinition } from "../di";
+import { HOSTED_SERVICE, Module, SERVICE_PROVIDER, collectModuleControllers, type BazisModule, type ProviderDefinition } from "../di";
+import { DI } from "../di/lowLevel";
 import { HttpServer } from "./HttpServer";
+import { httpConfig } from "./Http.config";
 import type { HttpModuleOptions, HttpServerOptions } from "./options";
 
 /**
  * Builds the HTTP module: discovers the `controllers` of the modules in
- * `imports` and registers the HttpServer hosted service.
+ * `imports` and registers the HttpServer hosted service. The address comes from
+ * {@link httpConfig} unless the options fix it.
  *
  * ```ts
  * @Module({
  *   controllers: [UsersController],
- *   providers: [scoped(IUserStore, UserService, [repositoryFor(User)] as const)],
+ *   providers: [scoped(IUserStore, UserService)],
  * })
  * export class UsersModule {}
  *
- * export const AppModule = createApp({
- *   imports: [UsersModule],
- *   http: { port: 3000, prefix: "api" },
- * }).module;
+ * @App({ modules: [UsersModule], http: { prefix: "api" } })
+ * export class Application {}
  *
- * await Bazis.run(AppModule);
+ * await runApp(Application);
  * ```
  */
 export function httpModule(options: HttpModuleOptions): BazisModule {
@@ -37,6 +38,7 @@ export function httpModule(options: HttpModuleOptions): BazisModule {
 
   @Module({
     imports: options.imports,
+    config: httpConfig,
     providers,
   })
   class HttpModule {}

package/core/http/index.ts

@@ -6,6 +6,7 @@
  * dependencies, compatible with `bun build --compile`.
  */
 export { httpModule } from "./httpModule";
+export { httpConfig } from "./Http.config";
 export { HttpServer } from "./HttpServer";
 export { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
 export type {
@@ -18,10 +19,12 @@ export type { OpenApiDocsOptions } from "../../library/openapi";
 export { composeRouteMiddlewareComposers } from "./composeRouteMiddlewareComposers";
 export {
   HTTP_ERROR_HOOK,
+  HTTP_ERROR_MAPPER,
   ROUTE_MIDDLEWARE_COMPOSER,
   SERVER_MIDDLEWARE,
   sortByOrder,
   type HttpErrorHook,
+  type HttpErrorMapper,
   type RouteMiddlewareComposerRegistration,
   type ServerMiddlewareRegistration,
 } from "./middlewareTokens";
@@ -131,6 +134,7 @@ export type { ActionFilterHooks, HttpMiddleware } from "./Middleware/types";
 // Errors
 export {
   BadRequestError,
+  ConflictError,
   ForbiddenError,
   HttpError,
   HttpSetupError,

package/core/http/middlewareTokens.ts

@@ -1,4 +1,5 @@
 import { createToken } from "../di";
+import type { HttpError } from "./Errors/HttpError";
 import type { HttpContext } from "./HttpContext/HttpContext";
 import type { HttpMiddleware } from "./Middleware/types";
 import type { RouteMiddlewareComposer } from "./options";
@@ -39,6 +40,17 @@ export type HttpErrorHook = (ctx: HttpContext, error: unknown) => void;
 /** Enumerable token: register any number of unexpected-error hooks. */
 export const HTTP_ERROR_HOOK = createToken<HttpErrorHook>("BazisHttpErrorHook");
 
+/**
+ * Turns a failure that is not an {@link HttpError} into one: a module that owns
+ * a kind of errors says how they answer. `undefined` leaves the error to the
+ * next mapper and then to 500. The ORM registers one for database errors.
+ * Collected via `resolveAll`.
+ */
+export type HttpErrorMapper = (error: unknown) => HttpError | undefined;
+
+/** Enumerable token: register any number of error mappers. */
+export const HTTP_ERROR_MAPPER = createToken<HttpErrorMapper>("BazisHttpErrorMapper");
+
 /** Stable order by `order ?? 0` (registration order preserved within a tier). */
 export function sortByOrder<T extends { readonly order?: number }>(items: readonly T[]): T[] {
   return [...items]

package/core/http/options.ts

@@ -72,8 +72,12 @@ export interface HttpModuleOptions {
    * either listed here or exported by global modules.
    */
   readonly imports?: readonly import("../di").BazisModuleRef[];
-  /** Listen port (default 3000; 0 — random free port). */
+  /**
+   * Fixes the listen port in code (0 — a random free port). Leave it out: the
+   * port then comes from the `http.port` setting, 3000 unless `BAZIS_HTTP__PORT` says otherwise.
+   */
   readonly port?: number;
+  /** Fixes the listen address in code. Leave it out: it comes from the `http.host` setting (`BAZIS_HTTP__HOST`). */
   readonly hostname?: string;
   /** Global route prefix, e.g. "api". */
   readonly prefix?: string;

package/core/http-client/httpClients.ts

@@ -1,4 +1,5 @@
-import { DI, registerModuleMetadataExpander, type BazisModuleMetadata, type BazisModuleRef, type ServiceResolver } from "../di";
+import { registerModuleMetadataExpander, type BazisModuleMetadata, type BazisModuleRef, type ServiceResolver } from "../di";
+import { DI } from "../di/lowLevel";
 import { getOutboundCorrelationHeaders, type ConfigDefinition } from "../kernel";
 import { HttpClientBase, HttpClientError, type RequestConfig } from "../../library/http-client";
 

package/core/infra/Infra.ts

@@ -1,5 +1,4 @@
 import {
-  DI,
   HOSTED_SERVICE,
   Module,
   createToken,
@@ -12,6 +11,7 @@ import {
   type BazisModuleRef,
   type ProviderDefinition,
 } from "../di";
+import { DI } from "../di/lowLevel";
 import { ConfigRegistry, HEALTH_CHECK, StartupReport } from "../kernel";
 import { InfraError, type InfraConnector } from "./InfraConnector";
 import { InfraLifecycle } from "./InfraLifecycle";
@@ -136,7 +136,7 @@ function buildInfraDefinitions(manifest: InfraManifest): {
 
 /**
  * Dynamic infrastructure module (a plain metadata object): the same as
- * `@Infra`, but without a class. Handy for `imports` or `runApp({ infra })`.
+ * `@Infra`, but without a class. Handy for `imports` or `@App({ infra })`.
  */
 export function infraModule(manifest: InfraManifest): BazisModuleRef {
   try {
@@ -153,7 +153,7 @@ export function infraModule(manifest: InfraManifest): BazisModuleRef {
 /**
  * Infrastructure decorator. Puts the metadata of a regular **global module**
  * on the class, so the class becomes a valid `BazisModuleRef`: it can be passed
- * to `runApp({ infra: AppInfra })` or to `imports`.
+ * to `@App({ infra: AppInfra })` or to `imports`.
  *
  * The class stays pure metadata (like `@Module`) and is **never instantiated**:
  * only the clients it lists live and hold state.

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.136.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.138.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/infra/connectors/codex/contracts.ts

@@ -52,7 +52,7 @@ const EN_CODEX_MESSAGES: Readonly<Record<CodexErrorCode, string>> = Object.freez
   LOGIN_EXPIRED: "The sign-in window expired. Start signing in again.",
 });
 
-/** Russian texts for every code; `runApp({ language: "ru" })` turns them on. */
+/** Russian texts for every code; `@App({ language: "ru" })` turns them on. */
 export const RU_CODEX_MESSAGES: Readonly<Record<CodexErrorCode, string>> = Object.freeze({
   NOT_CONFIGURED: "Подключение ChatGPT не настроено на сервере.",
   UNAVAILABLE: "Codex App Server недоступен. Проверьте его установку и настройки.",
@@ -73,7 +73,7 @@ let own: Partial<Record<CodexErrorCode, string>> = {};
 let messages: Readonly<Record<CodexErrorCode, string>> = EN_CODEX_MESSAGES;
 
 /**
- * @internal `runApp({ language })` sets the language of the texts. It is
+ * @internal `@App({ language })` sets the language of the texts. It is
  * process-wide, like the texts themselves: the last started application wins.
  */
 export function useCodexLanguage(name: keyof typeof CODEX_LANGUAGES): void {
@@ -81,7 +81,7 @@ export function useCodexLanguage(name: keyof typeof CODEX_LANGUAGES): void {
   messages = Object.freeze({ ...language, ...own });
 }
 
-/** `message` is user-facing text for `code`, in the language of `runApp({ language })`. */
+/** `message` is user-facing text for `code`, in the language of `@App({ language })`. */
 export class CodexError extends Error {
   constructor(readonly code: CodexErrorCode) { super(messages[code]); this.name = "CodexError"; }
 

package/core/infra/connectors/llm.ts

@@ -1,6 +1,7 @@
 import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
 import { AGENT_MODEL_PROVIDER, AGENT_RUNTIME_OPTIONS, AgentRuntime, type AgentModelProvider } from "../../agent";
-import { DI, DiError, HOSTED_SERVICE, SERVICE_PROVIDER, type ProviderDefinition } from "../../di";
+import { DiError, HOSTED_SERVICE, SERVICE_PROVIDER, type ProviderDefinition } from "../../di";
+import { DI } from "../../di/lowLevel";
 import { LOGGER } from "../../kernel/logging/Logger";
 import { reader, requireValue, settingNames } from "../connectorConfig";
 import { InfraError, type InfraConnector } from "../InfraConnector";