bazis 0.100.6 → 0.100.8

package/core/http/Errors/messages.ts

@@ -0,0 +1,158 @@
+/** Placeholder values of a message template: `{name}` -> `params.name`. */
+export type MessageParams = Readonly<Record<string, unknown>>;
+
+/**
+ * Turns a message key and its parameters into text in the application
+ * language; `undefined` keeps the English text the error was created with.
+ * `runApp` builds it from its `language` and `messages` options.
+ */
+export type Localize = (key: string, params: MessageParams) => string | undefined;
+
+/** A message key and parameters carried by an error, rendered at the response. */
+export interface LocalizedMessage {
+  readonly key: string;
+  readonly params?: MessageParams;
+}
+
+/** Keys of the texts the HTTP layer writes itself. */
+export type HttpMessageKey =
+  | "badRequest"
+  | "unauthorized"
+  | "forbidden"
+  | "notFound"
+  | "methodNotAllowed"
+  | "conflict"
+  | "gone"
+  | "preconditionFailed"
+  | "payloadTooLarge"
+  | "unsupportedMediaType"
+  | "unprocessableContent"
+  | "locked"
+  | "tooManyRequests"
+  | "clientError"
+  | "internalServerError"
+  | "badGateway"
+  | "serviceUnavailable"
+  | "gatewayTimeout"
+  | "serverError"
+  | "malformedPath"
+  | "unsupportedApiVersion"
+  | "malformedJson"
+  | "malformedForm"
+  | "bodyNotObject"
+  | "bodyTooDeep"
+  | "bodyTooComplex"
+  | "bodyCyclic"
+  | "missingParameter"
+  | "invalidParameter"
+  | "invalidListQuery";
+
+export const EN_HTTP_MESSAGES: Readonly<Record<HttpMessageKey, string>> = Object.freeze({
+  badRequest: "Bad Request",
+  unauthorized: "Unauthorized",
+  forbidden: "Forbidden",
+  notFound: "Not Found",
+  methodNotAllowed: "Method Not Allowed",
+  conflict: "Conflict",
+  gone: "Gone",
+  preconditionFailed: "Precondition Failed",
+  payloadTooLarge: "Payload Too Large",
+  unsupportedMediaType: "Unsupported Media Type: expected {expected}",
+  unprocessableContent: "Unprocessable Content",
+  locked: "Locked",
+  tooManyRequests: "Too Many Requests",
+  clientError: "Client Error",
+  internalServerError: "Internal Server Error",
+  badGateway: "Bad Gateway",
+  serviceUnavailable: "Service Unavailable",
+  gatewayTimeout: "Gateway Timeout",
+  serverError: "Server Error",
+  malformedPath: "Malformed request path",
+  unsupportedApiVersion: "Unsupported API version",
+  malformedJson: "Malformed JSON in request body",
+  malformedForm: "Malformed form data in request body",
+  bodyNotObject: "Request body must be a JSON object",
+  bodyTooDeep: "Request body is too deeply nested",
+  bodyTooComplex: "Request body is too complex",
+  bodyCyclic: "Request body must be acyclic JSON",
+  missingParameter: 'Missing required {kind} parameter "{name}"',
+  invalidParameter: 'Parameter "{name}" must be of type {type}, got: "{value}"',
+  invalidListQuery: "Invalid list query",
+});
+
+export const RU_HTTP_MESSAGES: Readonly<Record<HttpMessageKey, string>> = Object.freeze({
+  badRequest: "Некорректный запрос",
+  unauthorized: "Требуется аутентификация",
+  forbidden: "Доступ запрещён",
+  notFound: "Не найдено",
+  methodNotAllowed: "Метод не поддерживается",
+  conflict: "Конфликт",
+  gone: "Ресурс удалён",
+  preconditionFailed: "Предусловие не выполнено",
+  payloadTooLarge: "Слишком большой запрос",
+  unsupportedMediaType: "Неподдерживаемый тип содержимого: ожидается {expected}",
+  unprocessableContent: "Невозможно обработать данные",
+  locked: "Ресурс заблокирован",
+  tooManyRequests: "Слишком много запросов",
+  clientError: "Ошибка в запросе",
+  internalServerError: "Внутренняя ошибка сервера",
+  badGateway: "Ошибка внешнего сервиса",
+  serviceUnavailable: "Сервис недоступен",
+  gatewayTimeout: "Внешний сервис не ответил вовремя",
+  serverError: "Ошибка сервера",
+  malformedPath: "Некорректный путь запроса",
+  unsupportedApiVersion: "Неподдерживаемая версия API",
+  malformedJson: "Тело запроса — некорректный JSON",
+  malformedForm: "Некорректные данные формы в теле запроса",
+  bodyNotObject: "Тело запроса должно быть JSON-объектом",
+  bodyTooDeep: "Слишком глубокая вложенность в теле запроса",
+  bodyTooComplex: "Тело запроса слишком сложное",
+  bodyCyclic: "Тело запроса не должно содержать циклов",
+  missingParameter: 'Не передан обязательный параметр "{name}"',
+  invalidParameter: 'Параметр "{name}": ожидается {type}, получено: "{value}"',
+  invalidListQuery: "Некорректные параметры списка",
+});
+
+/** Reason-phrase keys of the statuses the error handler writes for unexpected errors. */
+export const STATUS_MESSAGE_KEYS: Readonly<Record<number, HttpMessageKey>> = Object.freeze({
+  400: "badRequest", 401: "unauthorized", 403: "forbidden", 404: "notFound", 405: "methodNotAllowed",
+  409: "conflict", 410: "gone", 412: "preconditionFailed", 413: "payloadTooLarge", 415: "unsupportedMediaType",
+  422: "unprocessableContent", 423: "locked", 429: "tooManyRequests", 500: "internalServerError",
+  502: "badGateway", 503: "serviceUnavailable", 504: "gatewayTimeout",
+});
+
+/** Parameters whose value is a type name, translated through `typeName.<name>` keys. */
+const TYPE_PARAMS = new Set(["expected", "actual", "type"]);
+
+/**
+ * Substitutes `{name}` placeholders. Unknown placeholders stay as they are.
+ * With `lookup`, a type name in `expected`/`actual`/`type` is replaced by the
+ * `typeName.<name>` text when the catalog has one ("number" -> "число").
+ */
+export function formatMessage(template: string, params: MessageParams, lookup?: (key: string) => string | undefined): string {
+  return template.replace(/\{(\w+)\}/g, (placeholder, name: string) => {
+    if (!Object.prototype.hasOwnProperty.call(params, name) || params[name] === undefined) return placeholder;
+    const value = params[name];
+    if (lookup !== undefined && TYPE_PARAMS.has(name) && typeof value === "string") {
+      const typeName = lookup(`typeName.${value}`);
+      if (typeName !== undefined) return typeName;
+    }
+    return stringifyParam(value);
+  });
+}
+
+function stringifyParam(value: unknown): string {
+  if (typeof value === "object" && value !== null && !(value instanceof RegExp)) {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+/** English text of a framework message, used when the app sets no language. */
+export function englishHttpMessage(key: HttpMessageKey, params: MessageParams = {}): string {
+  return formatMessage(EN_HTTP_MESSAGES[key], params);
+}

package/core/http/HttpContext/HttpContext.ts

@@ -1,5 +1,5 @@
 import type { ServiceScope } from "../../di";
-import { BadRequestError, PayloadTooLargeError } from "../Errors/HttpError";
+import { PayloadTooLargeError, frameworkBadRequest } from "../Errors/HttpError";
 import { ResponseBuilder } from "./ResponseBuilder";
 import type { ModelValidator } from "../Binding/modelValidator";
 
@@ -75,7 +75,7 @@ export class HttpContext {
       try {
         return JSON.parse(text) as T;
       } catch {
-        throw new BadRequestError("Malformed JSON in request body");
+        throw frameworkBadRequest("malformedJson");
       }
     });
     return this.bodyPromise as Promise<T>;
@@ -94,7 +94,7 @@ export class HttpContext {
         if (error instanceof PayloadTooLargeError) {
           throw error;
         }
-        throw new BadRequestError("Malformed form data in request body");
+        throw frameworkBadRequest("malformedForm");
       }) as ReturnType<Request["formData"]>;
   }
 

package/core/http/HttpServer.ts

@@ -22,6 +22,7 @@ import { HTTP_ERROR_HOOK, ROUTE_MIDDLEWARE_COMPOSER, SERVER_MIDDLEWARE, sortByOr
 import type { HealthEndpointOptions, RouteMiddlewareComposer, HttpModuleOptions, HttpServerOptions } from "./options";
 import { WEBSOCKET_UPGRADE, type WebSocketUpgrade } from "./WebSocketUpgrade";
 import { HttpSetupError } from "./Errors/HttpError";
+import { EN_HTTP_MESSAGES, formatMessage, type HttpMessageKey, type MessageParams } from "./Errors/messages";
 import { getModelValidator, type ModelValidator } from "./Binding/modelValidator";
 
 const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
@@ -166,6 +167,7 @@ export class HttpServer implements HostedService {
       errorHandler({
         exposeDetails,
         ...(errorLogger ? { logger: errorLogger } : {}),
+        ...(this.options.localize ? { localize: this.options.localize } : {}),
         ...this.options.errorHandler,
         onUnexpectedError: this.collectErrorHook(),
       }),
@@ -384,13 +386,23 @@ export class HttpServer implements HostedService {
     return request.method === "HEAD" ? stripBody(response) : response;
   }
 
+  /** A response text the server writes itself, in the application language. */
+  private text(key: HttpMessageKey, params: MessageParams = {}): string {
+    const english = formatMessage(EN_HTTP_MESSAGES[key], params);
+    try {
+      return this.options.localize?.(key, params) ?? english;
+    } catch {
+      return english;
+    }
+  }
+
   private transportError(error: unknown): Response {
     try {
       console.error("[http] transport failed:", redactSensitive(error));
     } catch {
       // Best-effort diagnostics only.
     }
-    const response = json(500, { error: "Internal Server Error" });
+    const response = json(500, { error: this.text("internalServerError") });
     if (this.options.securityHeaders !== false) {
       applySecurityHeaders(response, this.options.securityHeaders ?? {});
     }
@@ -434,9 +446,9 @@ export class HttpServer implements HostedService {
     if (!segments) {
       if (this.maxBodyBytes !== undefined && exceedsBodyLimit(request, this.maxBodyBytes)) {
         return this.runShortCircuit(request, url, clientIp, () =>
-          json(413, { error: "Payload Too Large", details: { maxBytes: this.maxBodyBytes } }));
+          json(413, { error: this.text("payloadTooLarge"), details: { maxBytes: this.maxBodyBytes } }));
       }
-      return this.runShortCircuit(request, url, clientIp, () => json(400, { error: "Malformed request path" }));
+      return this.runShortCircuit(request, url, clientIp, () => json(400, { error: this.text("malformedPath") }));
     }
 
     const match = this.router!.match(request.method, segments, this.readVersion(request, url));
@@ -445,18 +457,18 @@ export class HttpServer implements HostedService {
       : this.maxBodyBytes;
     if (effectiveMaxBodyBytes !== undefined && exceedsBodyLimit(request, effectiveMaxBodyBytes)) {
       return this.runShortCircuit(request, url, clientIp, () =>
-        json(413, { error: "Payload Too Large", details: { maxBytes: effectiveMaxBodyBytes } }));
+        json(413, { error: this.text("payloadTooLarge"), details: { maxBytes: effectiveMaxBodyBytes } }));
     }
     if (match.kind === "not-found") {
-      return this.runShortCircuit(request, url, clientIp, () => json(404, { error: "Not Found" }));
+      return this.runShortCircuit(request, url, clientIp, () => json(404, { error: this.text("notFound") }));
     }
     if (match.kind === "method-not-allowed") {
       return this.runShortCircuit(request, url, clientIp, () =>
-        json(405, { error: "Method Not Allowed" }, { allow: match.allow.join(", ") }));
+        json(405, { error: this.text("methodNotAllowed") }, { allow: match.allow.join(", ") }));
     }
     if (match.kind === "unsupported-version") {
       return this.runShortCircuit(request, url, clientIp, () =>
-        json(400, { error: "Unsupported API version", details: { supported: match.supported } }));
+        json(400, { error: this.text("unsupportedApiVersion"), details: { supported: match.supported } }));
     }
 
     const scope = this.provider.createScope();
@@ -475,7 +487,7 @@ export class HttpServer implements HostedService {
       await runPipeline(match.action.chain, ctx);
       // The error boundary always sets a response on failure; an empty
       // response here means no middleware produced one.
-      const response = this.prepareClientResponse(ctx.response ?? json(404, { error: "Not Found" }), request);
+      const response = this.prepareClientResponse(ctx.response ?? json(404, { error: this.text("notFound") }), request);
       if (request.method === "HEAD") return stripBody(response);
       if (!response.body) return response;
       this.trackResponse(holdResponseScope(response, request.signal, () =>
@@ -520,7 +532,7 @@ export class HttpServer implements HostedService {
     let scopeTransferred = false;
     try {
       await runPipeline([...this.shortCircuitChain, terminal], ctx);
-      const response = this.prepareClientResponse(ctx.response ?? json(500, { error: "Internal Server Error" }), request);
+      const response = this.prepareClientResponse(ctx.response ?? json(500, { error: this.text("internalServerError") }), request);
       if (request.method === "HEAD") return stripBody(response);
       if (!response.body) return response;
       this.trackResponse(holdResponseScope(response, request.signal, () =>

package/core/http/Middleware/errorHandler.ts

@@ -2,7 +2,8 @@ import { REQUEST_ID_STATE_KEY, type Logger } from "../../kernel";
 import { redactSensitive, redactSensitiveText } from "../../../library/redaction";
 import { HttpClientError, HttpErrorCode } from "../../../library/http-client/errors";
 import type { HttpContext } from "../HttpContext/HttpContext";
-import { HttpError } from "../Errors/HttpError";
+import { HttpError, ModelValidationError } from "../Errors/HttpError";
+import { EN_HTTP_MESSAGES, STATUS_MESSAGE_KEYS, type HttpMessageKey, type Localize } from "../Errors/messages";
 import { upstreamFailure } from "../Errors/upstreamFailure";
 import type { HttpMiddleware } from "./types";
 
@@ -33,6 +34,13 @@ export interface ErrorHandlerOptions {
    * passes the application `LOGGER`; without either, `console.error` is used.
    */
   logger?: Logger;
+  /**
+   * Renders framework texts (`Not Found`, validation messages, …) in the
+   * application language; `runApp` builds it from `language` and `messages`.
+   * Without it the texts stay English. Messages an application passes to an
+   * error itself are never changed.
+   */
+  localize?: Localize;
 }
 
 function jsonResponse(status: number, body: unknown, extraHeaders?: readonly [string, string][]): Response {
@@ -103,6 +111,7 @@ function safelyReportUnexpected(
  */
 export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware {
   const log = resolveErrorLog(options);
+  const text = textRenderer(options.localize);
   return async (ctx, next) => {
     try {
       await next();
@@ -125,14 +134,23 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
         if (headers !== undefined) {
           extra.push(...Object.entries(headers));
         }
+        const message = error.localized === undefined ? error.message : text(error.localized.key, error.localized.params, error.message);
+        const details = error instanceof ModelValidationError
+          ? error.errors.map((issue) => ({
+              property: issue.property,
+              message: issue.params === undefined || issue.code === undefined ? issue.message : text(issue.code, issue.params, issue.message),
+              code: issue.code,
+            }))
+          : error.details;
         ctx.response = safeJsonResponse(
           error.status,
-          error.details === undefined ? { error: error.message } : { error: error.message, details: error.details },
+          details === undefined ? { error: message } : { error: message, details },
           extra,
         );
         return;
       }
-      const [status, title] = unexpectedStatus(error, options.status);
+      const [status, key] = unexpectedStatus(error, options.status);
+      const title = text(key, {}, EN_HTTP_MESSAGES[key]);
       if (status >= 500) safelyReportUnexpected(options, log, ctx, error);
       ctx.response = options.exposeDetails
         ? safeJsonResponse(status, {
@@ -154,19 +172,27 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
  * and stays 500, like everything else. Upstream details never reach the
  * client; the log keeps the full error.
  */
-const REASONS: Readonly<Record<number, string>> = {
-  400: "Bad Request", 404: "Not Found", 409: "Conflict", 410: "Gone", 412: "Precondition Failed", 422: "Unprocessable Content",
-  423: "Locked", 429: "Too Many Requests", 500: "Internal Server Error", 502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout",
-};
-
-function unexpectedStatus(error: unknown, mapper?: (error: unknown) => number | undefined): readonly [number, string] {
+function unexpectedStatus(error: unknown, mapper?: (error: unknown) => number | undefined): readonly [number, HttpMessageKey] {
   if (error instanceof HttpClientError && error.code !== undefined) {
-    return error.code === HttpErrorCode.Timeout ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
+    return error.code === HttpErrorCode.Timeout ? [504, "gatewayTimeout"] : [502, "badGateway"];
   }
   const upstream = upstreamFailure(error);
-  if (upstream !== undefined) return upstream === "timeout" ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
+  if (upstream !== undefined) return upstream === "timeout" ? [504, "gatewayTimeout"] : [502, "badGateway"];
   let mapped: number | undefined;
   try { mapped = mapper?.(error); } catch { mapped = undefined; }
-  if (mapped !== undefined && Number.isInteger(mapped) && mapped >= 400 && mapped <= 599) return [mapped, REASONS[mapped] ?? (mapped >= 500 ? "Server Error" : "Client Error")];
-  return [500, "Internal Server Error"];
+  if (mapped !== undefined && Number.isInteger(mapped) && mapped >= 400 && mapped <= 599) return [mapped, STATUS_MESSAGE_KEYS[mapped] ?? (mapped >= 500 ? "serverError" : "clientError")];
+  return [500, "internalServerError"];
+}
+
+/** Text of a message key in the application language, or the English fallback. */
+function textRenderer(localize: Localize | undefined): (key: string, params: Readonly<Record<string, unknown>> | undefined, fallback: string) => string {
+  if (localize === undefined) return (_key, _params, fallback) => fallback;
+  return (key, params, fallback) => {
+    try {
+      return localize(key, params ?? {}) ?? fallback;
+    } catch {
+      // A broken catalog must not turn an error response into a 500.
+      return fallback;
+    }
+  };
 }

package/core/http/index.ts

@@ -141,4 +141,5 @@ export {
   UnauthorizedError,
   UnsupportedMediaTypeError,
 } from "./Errors/HttpError";
+export { EN_HTTP_MESSAGES, RU_HTTP_MESSAGES, type HttpMessageKey, type Localize, type LocalizedMessage } from "./Errors/messages";
 export { markUpstreamFailure, upstreamFailure, type UpstreamFailure } from "./Errors/upstreamFailure";

package/core/http/options.ts

@@ -2,6 +2,7 @@ import type { Class } from "../di";
 import type { AccessLogOptions } from "./Middleware/accessLog";
 import type { CorsOptions } from "./Middleware/cors";
 import type { ErrorHandlerOptions } from "./Middleware/errorHandler";
+import type { Localize } from "./Errors/messages";
 import type { SecurityHeadersOptions } from "./Middleware/securityHeaders";
 import type { HttpMiddleware } from "./Middleware/types";
 import type { ActionMeta, ControllerMeta } from "./Decorators/metadata";
@@ -58,6 +59,12 @@ export interface HttpModuleOptions {
   readonly inspectableRedirects?: boolean;
   /** Request-model validator captured by this HTTP server instance. */
   readonly validator?: ModelValidator;
+  /**
+   * Renders framework response texts in the application language. `runApp`
+   * sets it from its `language` and `messages` options; without it the
+   * texts are English.
+   */
+  readonly localize?: Localize;
   /**
    * Modules providing the controllers' dependencies. Controllers live inside
    * the returned HttpModule, so their dependencies must be visible to it:

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.6" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.100.8" }, 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/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}"?`}`);
+  }
+}