bazis 0.98.10 → 0.98.12

package/core/http/Middleware/errorHandler.ts

@@ -1,5 +1,6 @@
 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 type { HttpMiddleware } from "./types";
@@ -124,15 +125,30 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
         return;
       }
       safelyReportUnexpected(options, log, ctx, error);
+      const [status, title] = unexpectedStatus(error);
       ctx.response = options.exposeDetails
-        ? safeJsonResponse(500, {
-            error: "Internal Server Error",
+        ? safeJsonResponse(status, {
+            error: title,
             // Development only, but redacted like the log: a secret in an error
             // message must not reach a browser or a shared screenshot.
             message: redactSensitiveText(error instanceof Error ? error.message : String(error)),
             stack: error instanceof Error && error.stack !== undefined ? redactSensitiveText(error.stack) : undefined,
           })
-        : safeJsonResponse(500, { error: "Internal Server Error" });
+        : safeJsonResponse(status, { error: title });
     }
   };
 }
+
+/**
+ * An unhandled outbound HTTP failure is the upstream's fault, not ours:
+ * 504 when the call timed out, 502 otherwise. A client error without a code
+ * is a misconfiguration of our request (for example an invalid maxRedirects)
+ * and stays 500, like everything else. Upstream details never reach the
+ * client; the log keeps the full error.
+ */
+function unexpectedStatus(error: unknown): readonly [number, string] {
+  if (error instanceof HttpClientError && error.code !== undefined) {
+    return error.code === HttpErrorCode.Timeout ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
+  }
+  return [500, "Internal Server Error"];
+}

package/core/http-client/index.ts

@@ -16,8 +16,8 @@ import { DI, Module, createToken, type BazisModule, type ProviderDefinition } fr
 import { getOutboundCorrelationHeaders } from "../kernel";
 import {
   HttpClient,
+  HttpClientFactory,
   HttpClientFactoryBuilder,
-  type HttpClientFactory,
   type HeaderBag,
   type RequestConfig,
 } from "../../library/http-client";
@@ -44,9 +44,10 @@ export interface HttpClientModuleConfig {
 
 /**
  * Registers the outbound HTTP client in DI with correlation propagation wired
- * to the kernel request context:
- * - {@link HTTP_CLIENT_FACTORY} — named clients (fail-fast on unknown names);
- * - {@link HTTP_CLIENT} — the default injectable {@link HttpClient}.
+ * to the kernel request context. A service takes it by type:
+ * - `HttpClient` (or the {@link HTTP_CLIENT} token) — the default client;
+ * - `HttpClientFactory` (or {@link HTTP_CLIENT_FACTORY}) — named clients
+ *   (fail-fast on unknown names).
  */
 export function httpClientModule(config: HttpClientModuleConfig = {}): BazisModule {
   const correlationHeaders = config.correlationHeaders ?? getOutboundCorrelationHeaders;
@@ -83,11 +84,14 @@ export function httpClientModule(config: HttpClientModuleConfig = {}): BazisModu
   }
   const factory = builder.build();
 
+  const client = factory.createClient();
+  // One factory and one default client, under the class (injection by type)
+  // and under the original tokens.
   const providers: ProviderDefinition[] = [
+    DI.singleton(DI.valueProvider(HttpClientFactory, factory)),
     DI.singleton(DI.valueProvider(HTTP_CLIENT_FACTORY, factory)),
-    DI.singleton(
-      DI.factoryProvider(HTTP_CLIENT, [HTTP_CLIENT_FACTORY], (resolved: HttpClientFactory) => resolved.createClient()),
-    ),
+    DI.singleton(DI.valueProvider(HttpClient, client)),
+    DI.singleton(DI.valueProvider(HTTP_CLIENT, client)),
   ];
 
   @Module({ providers })

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.98.10" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.12" }, 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/config/defineConfig.ts

@@ -154,18 +154,22 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
     const values = new Map<string, ConfigValueType>();
     const inspection: ConfigInspection[] = [];
     const issues: string[] = [];
+    // A wrong value names what came and where to change it: the variable that
+    // supplied it, or the variables that can override the value from the code.
+    const got = (raw: unknown) => raw === undefined ? "" : `, got ${JSON.stringify(String(raw)).slice(0, 80)}`;
+    const source = (key: string, selected: { readonly name: string } | undefined) => ` (${selected ? selected.name : names.get(key)!.join(", ")})`;
     for (const key of keys) {
       const base = schema.default[key]!;
       const override = schema[environment]?.[key];
       const cell = override ?? base;
       const type = isSecret(base) ? "secret" : isEnum(base) ? typeof base.default : typeof base;
-      const candidates: { raw: string; source: string; priority: number }[] = [];
+      const candidates: { raw: string; source: string; priority: number; name: string }[] = [];
       for (const name of names.get(key)!) {
         const sourceKey = name.slice(ENV_PREFIX.length).toLowerCase().replaceAll("__", ".");
         const raw = configuration.get(sourceKey);
         if (raw === undefined) continue;
         const origin = configuration.origin(sourceKey);
-        candidates.push({ raw, ...origin });
+        candidates.push({ raw, ...origin, name });
       }
       const priority = Math.max(...candidates.map(candidate => candidate.priority));
       const winners = candidates.filter(candidate => candidate.priority === priority);
@@ -178,17 +182,17 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
         else value = new Secret(raw);
       } else if (type === "number") {
         const parsed = Number(raw);
-        if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issues.push(`${fullKey(key)} — expected a finite number`);
+        if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issues.push(`${fullKey(key)} — expected a finite number${got(raw)}${source(key, selected)}`);
         else value = parsed;
       } else if (type === "boolean") {
         const normalized = String(raw).toLowerCase();
         if (normalized === "true" || normalized === "1") value = true;
         else if (normalized === "false" || normalized === "0") value = false;
-        else issues.push(`${fullKey(key)} — expected a boolean`);
+        else issues.push(`${fullKey(key)} — expected a boolean (true, false, 1, 0)${got(raw)}${source(key, selected)}`);
       } else if (typeof raw === "string") value = raw;
       else issues.push(`${fullKey(key)} — expected a string`);
       if (value === undefined) continue;
-      if (isEnum(base) && !base.values.includes(value as string | number)) issues.push(`${fullKey(key)} — value is not one of the declared enum values`);
+      if (isEnum(base) && !base.values.includes(value as string | number)) issues.push(`${fullKey(key)} — ${JSON.stringify(value)} is not allowed, use one of: ${base.values.join(", ")}${source(key, selected)}`);
       try {
         const issue = validators[key]?.(value);
         if (issue) issues.push(`${fullKey(key)} — ${issue}`);

package/core/orm/databaseConnector.ts

@@ -1,4 +1,4 @@
-import { InfraError, reader, requireValue, postgresConnectionOptions, type InfraConnector, type PostgresConfigShape } from "../infra";
+import { errorMessage, InfraError, reader, requireValue, postgresConnectionOptions, type InfraConnector, type PostgresConfigShape } from "../infra";
 import type { AppConfig, ConfigRegistry } from "../kernel";
 import { postgres, type DatabaseProvider, type PostgresServerTimeouts } from "../../library/orm";
 import { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
@@ -86,16 +86,26 @@ export function ormBazisConnect<T extends PostgresOrmConfigShape>(config: AppCon
 export function ormBazisConnect(
   config: AppConfig<PostgresOrmConfigShape>,
 ): InfraConnector<DatabaseProvider> {
+  // Where the connection goes, for the startup error; never the password.
+  let target = "PostgreSQL";
   return {
     token: DATABASE_PROVIDER,
     config,
     phase: DATABASE_PHASE,
     create(configs) {
+      const c = reader(config, configs);
+      target = `PostgreSQL at ${String(c.get("host"))}:${String(c.get("port"))} (database "${String(c.get("database"))}", user "${String(c.get("username"))}")`;
       return buildPostgresProvider(config, configs);
     },
     async connect(provider, signal) {
-      if (!(await provider.ping(signal))) {
-        throw new InfraError('Infra connector "database": postgres is not reachable.');
+      if (provider.probe === undefined) {
+        if (!(await provider.ping(signal))) throw new InfraError(`Infra connector "database": cannot connect to ${target}.`);
+        return;
+      }
+      try {
+        await provider.probe(signal);
+      } catch (error) {
+        throw new InfraError(`Infra connector "database": cannot connect to ${target}: ${connectionFailure(error)}`);
       }
     },
     async dispose(provider) {
@@ -106,3 +116,12 @@ export function ormBazisConnect(
     },
   };
 }
+
+/** The driver's reason with its code: `password authentication failed for user "app" (28P01)`. */
+function connectionFailure(error: unknown): string {
+  const details = error as { errno?: unknown; code?: unknown };
+  const code = typeof details.errno === "string" && details.errno ? details.errno
+    : typeof details.code === "string" && details.code ? details.code : undefined;
+  const message = errorMessage(error);
+  return code === undefined || message.includes(code) ? message : `${message} (${code})`;
+}

package/library/http-client/HttpClient.ts

@@ -6,7 +6,9 @@ import {
   appendQuery,
   basicAuthHeader,
   isBodyInit,
+  isAbsoluteUrl,
   mergeHeaderBags,
+  pageUrl,
   resolveUrl,
   shouldPropagateCorrelation,
 } from "./serialize";
@@ -188,7 +190,8 @@ export class HttpClient {
     return { ...merged, method: String(override.method ?? base.method ?? "GET").toUpperCase() };
   }
 
-  private async dispatch<T>(config: ResolvedRequestConfig): Promise<HttpResponse<T>> {
+  private async dispatch<T>(requested: ResolvedRequestConfig): Promise<HttpResponse<T>> {
+    const config = withAbsoluteBaseUrl(requested);
     if (config.inspectableRedirects !== undefined && typeof config.inspectableRedirects !== "boolean") {
       throw new HttpClientError("inspectableRedirects must be a boolean", { config });
     }
@@ -650,6 +653,26 @@ function isReplayableBody(body: RequestInit["body"]): boolean {
     || (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
 }
 
+/**
+ * A relative `baseUrl` (`"/api"`) is resolved against the page address once,
+ * so URL building and every origin check below see an absolute base. Outside
+ * a page there is nothing to resolve it against.
+ */
+function withAbsoluteBaseUrl(config: ResolvedRequestConfig): ResolvedRequestConfig {
+  const { baseUrl } = config;
+  if (!baseUrl || isAbsoluteUrl(baseUrl)) {
+    return config;
+  }
+  const page = pageUrl();
+  if (page === undefined) {
+    throw new HttpClientError(
+      `baseUrl "${baseUrl}" is relative: outside a browser page it must be absolute, for example "http://localhost:3000${baseUrl.startsWith("/") ? "" : "/"}${baseUrl}"`,
+      { config },
+    );
+  }
+  return { ...config, baseUrl: new URL(baseUrl, page).toString() };
+}
+
 function sameOrigin(left: string, right: string): boolean {
   try {
     return new URL(left).origin === new URL(right).origin;

package/library/http-client/HttpClientFactory.ts

@@ -2,9 +2,32 @@ import { HttpClient } from "./HttpClient";
 import { HttpClientConfigError } from "./errors";
 import type { RequestConfig } from "./types";
 
-/** Resolves pre-configured named clients (à la .NET `IHttpClientFactory`). */
-export interface HttpClientFactory {
-  createClient(name?: string): HttpClient;
+/**
+ * Resolves pre-configured named clients (à la .NET `IHttpClientFactory`).
+ * An abstract class, so a service can take it by type in its constructor.
+ */
+export abstract class HttpClientFactory {
+  public abstract createClient(name?: string): HttpClient;
+}
+
+class ConfiguredHttpClientFactory extends HttpClientFactory {
+  public constructor(
+    private readonly defaults: RequestConfig,
+    private readonly named: ReadonlyMap<string, RequestConfig>,
+  ) {
+    super();
+  }
+
+  public createClient(name?: string): HttpClient {
+    if (name === undefined) {
+      return new HttpClient(this.defaults);
+    }
+    const config = this.named.get(name);
+    if (config === undefined) {
+      throw new HttpClientConfigError(name, [...this.named.keys()]);
+    }
+    return new HttpClient(this.defaults).create(config);
+  }
 }
 
 /**
@@ -27,19 +50,6 @@ export class HttpClientFactoryBuilder {
   }
 
   public build(): HttpClientFactory {
-    const named = new Map(this.named);
-    const defaults = this.defaults;
-    return {
-      createClient(name?: string): HttpClient {
-        if (name === undefined) {
-          return new HttpClient(defaults);
-        }
-        const config = named.get(name);
-        if (config === undefined) {
-          throw new HttpClientConfigError(name, [...named.keys()]);
-        }
-        return new HttpClient(defaults).create(config);
-      },
-    };
+    return new ConfiguredHttpClientFactory(this.defaults, new Map(this.named));
   }
 }

package/library/http-client/index.ts

@@ -12,7 +12,7 @@
  */
 export { HttpClient } from "./HttpClient";
 export { InspectableRedirectProtocol } from "./redirectProtocol";
-export { HttpClientFactoryBuilder, type HttpClientFactory } from "./HttpClientFactory";
+export { HttpClientFactoryBuilder, HttpClientFactory } from "./HttpClientFactory";
 export { HttpClientError, HttpClientConfigError, HttpErrorCode } from "./errors";
 export { InterceptorManager, type FulfilledFn, type RejectedFn } from "./interceptors";
 export {

package/library/http-client/serialize.ts

@@ -8,6 +8,20 @@ const ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
  * prefix), `baseUrl: "https://api/v1"` + `"/users"` → `…/v1/users`.
  * Absolute URLs and missing baseUrl pass through.
  */
+export function isAbsoluteUrl(url: string): boolean {
+  return ABSOLUTE_URL.test(url);
+}
+
+/**
+ * The address of the current page in a browser (or worker), else undefined.
+ * A relative `baseUrl` such as `"/api"` is resolved against it, like axios's
+ * `baseURL` in a browser app.
+ */
+export function pageUrl(): string | undefined {
+  const location = (globalThis as { location?: { href?: unknown } }).location;
+  return typeof location?.href === "string" ? location.href : undefined;
+}
+
 export function resolveUrl(baseUrl: string | undefined, url: string): string {
   if (!baseUrl || ABSOLUTE_URL.test(url)) {
     return url;

package/library/orm/Providers/PostgresProvider.ts

@@ -409,13 +409,17 @@ export class PostgresProvider implements DatabaseProvider {
 
   async ping(signal?: AbortSignal): Promise<boolean> {
     try {
-      await withPostgresScopeOptions({ signal }, () => this.pooledOperation((session) => this.runQuery(session, "SELECT 1", [])));
+      await this.probe(signal);
       return true;
     } catch {
       return false;
     }
   }
 
+  async probe(signal?: AbortSignal): Promise<void> {
+    await withPostgresScopeOptions({ signal }, () => this.pooledOperation((session) => this.runQuery(session, "SELECT 1", [])));
+  }
+
   async introspect(): Promise<IntrospectedSchema> {
     const tableRows = await this.query(
       `SELECT table_schema, table_name

package/library/orm/Providers/ormTransactionRuntime.ts

@@ -96,6 +96,7 @@ export function createObservedProvider(provider: DatabaseProvider, observe: Tran
     afterCommit: provider.afterCommit?.bind(provider),
     afterRollback: provider.afterRollback?.bind(provider),
     ping: (signal?: AbortSignal): Promise<boolean> => observe(() => provider.ping(signal)),
+    probe: provider.probe ? (signal?: AbortSignal): Promise<void> => observe(() => provider.probe!(signal)) : undefined,
     introspect: () => observe(() => provider.introspect()),
     schemaAdmissionCapability: schema ? {
       version: schema.version,

package/library/orm/Providers/types.ts

@@ -178,6 +178,11 @@ export interface DatabaseProvider {
   afterRollback?(callback: TransactionCallback): void;
   /** Connection check for the health check. */
   ping(signal?: AbortSignal): Promise<boolean>;
+  /**
+   * Connection check that rejects with the driver's error instead of `false`,
+   * so a startup failure can say why (wrong password, missing database, …).
+   */
+  probe?(signal?: AbortSignal): Promise<void>;
   /** Introspection of the actual database schema (for the auto-migration). */
   introspect(): Promise<IntrospectedSchema>;
   /**

package/library/orm/Saving/ExecutionStrategy.ts

@@ -103,6 +103,7 @@ export function withRetry(provider: DatabaseProvider, options?: ExecutionStrateg
     afterCommit: provider.afterCommit ? (callback) => provider.afterCommit!(callback) : undefined,
     afterRollback: provider.afterRollback ? (callback) => provider.afterRollback!(callback) : undefined,
     ping: (signal) => provider.ping(signal),
+    probe: provider.probe ? (signal) => provider.probe!(signal) : undefined,
     introspect: () => provider.introspect(),
     schemaAdmissionCapability: provider.schemaAdmissionCapability,
     withMigrationLock: provider.withMigrationLock ? (work) => provider.withMigrationLock!(work) : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.10",
+  "version": "0.98.12",
   "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",