bazis 0.97.0 → 0.97.2

package/core/http/HttpServer.ts

@@ -150,8 +150,15 @@ export class HttpServer implements HostedService {
     if (this.options.securityHeaders !== false) {
       serverChain.push(securityHeaders(this.options.securityHeaders ?? {}));
     }
+    // Unexpected errors go to the application logger, like the access log.
+    const errorLogger = this.resolver.tryResolve(LOGGER);
     serverChain.push(
-      errorHandler({ exposeDetails, ...this.options.errorHandler, onUnexpectedError: this.collectErrorHook() }),
+      errorHandler({
+        exposeDetails,
+        ...(errorLogger ? { logger: errorLogger } : {}),
+        ...this.options.errorHandler,
+        onUnexpectedError: this.collectErrorHook(),
+      }),
     );
     this.shortCircuitChain = [...serverChain];
     serverChain.push(...this.collectServerMiddleware());

package/core/http/Middleware/errorHandler.ts

@@ -1,4 +1,5 @@
-import { redactSensitive } from "../../../library/redaction";
+import { REQUEST_ID_STATE_KEY, type Logger } from "../../kernel";
+import { redactSensitive, redactSensitiveText } from "../../../library/redaction";
 import type { HttpContext } from "../HttpContext/HttpContext";
 import { HttpError } from "../Errors/HttpError";
 import type { HttpMiddleware } from "./types";
@@ -9,10 +10,20 @@ export interface ErrorHandlerOptions {
    * never enable in production).
    */
   exposeDetails?: boolean;
-  /** Called for non-{@link HttpError} failures (self-wired via `HTTP_ERROR_HOOK`, e.g. the logging module). */
+  /**
+   * Notified of every non-{@link HttpError} failure, for example to send it to
+   * an error tracker; `HTTP_ERROR_HOOK` registrations are merged in. It does not
+   * replace logging: the error is logged as well.
+   */
   onUnexpectedError?: (ctx: HttpContext, error: unknown) => void;
-  /** Fallback when {@link onUnexpectedError} is omitted or does not handle the error. */
+  /** Replaces the built-in logging of unexpected errors. */
   logError?: (error: unknown) => void;
+  /**
+   * Logger for unexpected errors when {@link logError} is absent: one `error`
+   * line with the method, path, request id and the redacted error. The server
+   * passes the application `LOGGER`; without either, `console.error` is used.
+   */
+  logger?: Logger;
 }
 
 function jsonResponse(status: number, body: unknown, extraHeaders?: readonly [string, string][]): Response {
@@ -33,9 +44,30 @@ function safeJsonResponse(status: number, body: unknown, extraHeaders?: readonly
   }
 }
 
+type ErrorLog = (ctx: HttpContext, error: unknown) => void;
+
+function resolveErrorLog(options: ErrorHandlerOptions): ErrorLog {
+  const { logError, logger } = options;
+  if (logError) {
+    return (_ctx, error) => logError(error);
+  }
+  if (logger) {
+    return (ctx, error) => {
+      const requestId = ctx.state.get(REQUEST_ID_STATE_KEY);
+      logger.error(`${ctx.method} ${ctx.path} failed`, {
+        method: ctx.method,
+        path: ctx.path,
+        ...(typeof requestId === "string" ? { requestId } : {}),
+        error: redactSensitive(error),
+      });
+    };
+  }
+  return (_ctx, error) => console.error("[http] unhandled error:", redactSensitive(error));
+}
+
 function safelyReportUnexpected(
   options: ErrorHandlerOptions,
-  fallback: (error: unknown) => void,
+  log: ErrorLog,
   ctx: HttpContext,
   error: unknown,
 ): void {
@@ -43,13 +75,13 @@ function safelyReportUnexpected(
     options.onUnexpectedError?.(ctx, error);
   } catch (hookError) {
     try {
-      fallback(hookError);
+      log(ctx, hookError);
     } catch {
       // Logging hooks are best-effort; response safety is primary.
     }
   }
   try {
-    fallback(error);
+    log(ctx, error);
   } catch {
     // A broken sink must not escape the HTTP error boundary.
   }
@@ -61,7 +93,7 @@ function safelyReportUnexpected(
  * else becomes 500 Internal Server Error.
  */
 export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware {
-  const fallback = options.logError ?? ((error: unknown) => console.error("[http] unhandled error:", redactSensitive(error)));
+  const log = resolveErrorLog(options);
   return async (ctx, next) => {
     try {
       await next();
@@ -87,12 +119,14 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
         );
         return;
       }
-      safelyReportUnexpected(options, fallback, ctx, error);
+      safelyReportUnexpected(options, log, ctx, error);
       ctx.response = options.exposeDetails
         ? safeJsonResponse(500, {
             error: "Internal Server Error",
-            message: error instanceof Error ? error.message : String(error),
-            stack: error instanceof Error ? error.stack : undefined,
+            // 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" });
     }

package/core/http/SPEC.md

@@ -405,9 +405,10 @@ Exported from `bazis/core/http`. They are connected through `@Middleware(...)`,
 
 | `ErrorHandlerOptions` field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `exposeDetails` | `boolean` | `httpModule({ exposeErrorDetails })` / environment | message/stack in 500 responses; never enable in production |
-| `onUnexpectedError` | `(ctx, error) => void` | DI `HTTP_ERROR_HOOK` hooks | called for non-`HttpError` failures |
-| `logError` | `(error) => void` | `console.error` | fallback when no hook handles the error |
+| `exposeDetails` | `boolean` | `httpModule({ exposeErrorDetails })` / environment | redacted message/stack in 500 responses; never enable in production |
+| `onUnexpectedError` | `(ctx, error) => void` | DI `HTTP_ERROR_HOOK` hooks | notification for non-`HttpError` failures (e.g. an error tracker); the error is still logged |
+| `logError` | `(error) => void` | — | replaces the built-in logging of unexpected errors |
+| `logger` | `Logger` | the application `LOGGER` | one `error` line: `"<METHOD> <path> failed"` with `method`, `path`, `requestId` and the redacted `error`; `console.error` when there is no logger |
 
 `HttpError` → JSON with its status; anything else → 500.
 

package/core/http/middlewareTokens.ts

@@ -31,8 +31,8 @@ export const ROUTE_MIDDLEWARE_COMPOSER = createToken<RouteMiddlewareComposerRegi
 
 /**
  * Hook invoked by the built-in error boundary on a non-{@link HttpError}
- * failure. Self-wiring: e.g. the logging module registers one to record the
- * error, keeping `@/core/http` free of logging imports. Collected via `resolveAll`.
+ * failure, for example to report it to an error tracker. It is a notification:
+ * the error is still logged and answered with 500. Collected via `resolveAll`.
  */
 export type HttpErrorHook = (ctx: HttpContext, error: unknown) => void;
 

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.97.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.97.2" }, 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/ApplicationLifetime.ts

@@ -14,6 +14,7 @@ export class ApplicationLifetime {
   private readonly stopRequestListeners: ((exitCode: number) => void)[] = [];
   private startedFlag = false;
   private stoppingFlag = false;
+  private stoppedFlag = false;
 
   public get isStarted(): boolean {
     return this.startedFlag;
@@ -23,15 +24,35 @@ export class ApplicationLifetime {
     return this.stoppingFlag;
   }
 
+  /**
+   * Runs `callback` once the application has started. A subscription made
+   * after that moment (for example in a service first created by a request)
+   * runs right away, like .NET's ApplicationStarted; a failure of such a late
+   * callback is an unhandled error (logged, graceful stop with exit code 1).
+   */
   public onStarted(callback: LifetimeCallback): void {
+    if (this.startedFlag) {
+      runLate(callback);
+      return;
+    }
     this.startedCallbacks.push(callback);
   }
 
+  /** Runs `callback` when graceful shutdown begins; right away if it already has. */
   public onStopping(callback: LifetimeCallback): void {
+    if (this.stoppingFlag) {
+      runLate(callback);
+      return;
+    }
     this.stoppingCallbacks.push(callback);
   }
 
+  /** Runs `callback` after the application has stopped; right away if it already has. */
   public onStopped(callback: LifetimeCallback): void {
+    if (this.stoppedFlag) {
+      runLate(callback);
+      return;
+    }
     this.stoppedCallbacks.push(callback);
   }
 
@@ -61,10 +82,17 @@ export class ApplicationLifetime {
 
   /** @internal */
   public async notifyStopped(): Promise<void> {
+    this.stoppedFlag = true;
     await runCallbacks(this.stoppedCallbacks);
   }
 }
 
+// A late subscription runs on its own: a rejection surfaces as an unhandled
+// error instead of disappearing silently.
+function runLate(callback: LifetimeCallback): void {
+  void Promise.resolve().then(callback);
+}
+
 // A failing subscriber must not break the rest of the lifecycle chain:
 // run everything, then report all failures at once.
 async function runCallbacks(callbacks: readonly LifetimeCallback[], signal?: AbortSignal): Promise<void> {

package/core/kernel/README.md

@@ -16,7 +16,7 @@ Contracts of the lifecycle and configuration fixes: [partial passport](MODULE.md
 ## Lifecycle
 
 - `LifecycleCoordinator.ts`: boot/shutdown order: options fail-fast → `onInit` → hosted services by phase → `onBootstrap`; shutdown in reverse order with `shutdownTimeout`; rollback when startup fails.
-- `ApplicationLifetime.ts`: injectable lifetime: `onStarted/onStopping/onStopped` + programmatic `stop(exitCode)`.
+- `ApplicationLifetime.ts`: injectable lifetime: `onStarted/onStopping/onStopped` (a subscription made after its moment runs right away) + programmatic `stop(exitCode)`.
 - `lifecycleHooks.ts`: the `LIFECYCLE_HOOK` token (enumerable) + `addLifecycleHook`.
 - `Environment.ts`: the environment (`development|production|test`) from `BAZIS_ENV`/`NODE_ENV`, the `debug` flag.
 - `SupervisedHostedService.ts`: retry with exponential backoff; passes the startup signal and stops retrying on cancellation.

package/core/kernel/config/defineConfig.ts

@@ -156,33 +156,35 @@ 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)) issues.push(`${fullKey(key)}: conflicting environment aliases`);
+      if (winners.some(candidate => candidate.raw !== selected?.raw)) issues.push(`${fullKey(key)} — conflicting environment aliases`);
       const raw = selected?.raw ?? (isSecret(cell) || isEnum(cell) ? cell.default : cell);
       let value: ConfigValueType | undefined;
       if (type === "secret") {
-        if (typeof raw !== "string" || !raw.trim()) issues.push(`${fullKey(key)}: required non-empty secret is not set (${names.get(key)!.join(", ")})`);
+        if (typeof raw !== "string" || !raw.trim()) issues.push(`${fullKey(key)} — required non-empty secret is not set (${names.get(key)!.join(", ")})`);
         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`);
         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`);
       } else if (typeof raw === "string") value = raw;
-      else issues.push(`${fullKey(key)}: expected a string`);
+      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)} — value is not one of the declared enum values`);
       try {
         const issue = validators[key]?.(value);
-        if (issue) issues.push(`${fullKey(key)}: ${issue}`);
-      } catch { issues.push(`${fullKey(key)}: validator failed`); }
+        if (issue) issues.push(`${fullKey(key)} — ${issue}`);
+      } catch { issues.push(`${fullKey(key)} — validator failed`); }
       values.set(key, value);
       inspection.push(Object.freeze({ key: fullKey(key), type: type as ConfigInspection["type"], env: names.get(key)!, source: selected?.source ?? (override === undefined ? "default" : environment), value: safeValue(fullKey(key), value) }));
     }
     if (issues.length) {
+      // "key — text", not "key: text": the console redaction would read
+      // "db.password: required" as a secret value and hide the word "required".
       let message = issues.join("; ");
       for (const [key, value] of values) {
         const sensitive = value instanceof Secret ? value.reveal() : typeof value === "string" && isSensitiveKey(key) ? value : undefined;

package/package.json

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