bazis 0.98.24 → 0.98.25

package/core/http/Middleware/errorHandler.ts

@@ -19,6 +19,13 @@ export interface ErrorHandlerOptions {
   onUnexpectedError?: (ctx: HttpContext, error: unknown) => void;
   /** Replaces the built-in logging of unexpected errors. */
   logError?: (error: unknown) => void;
+  /**
+   * Status for a non-{@link HttpError} failure, for example
+   * `databaseErrorStatus` from `bazis/core/orm`; `undefined` keeps 500. The
+   * body stays the standard reason phrase. A mapped 4xx is the client's
+   * mistake and is not logged or sent to `onUnexpectedError`.
+   */
+  status?: (error: unknown) => number | 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
@@ -124,8 +131,8 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
         );
         return;
       }
-      safelyReportUnexpected(options, log, ctx, error);
-      const [status, title] = unexpectedStatus(error);
+      const [status, title] = unexpectedStatus(error, options.status);
+      if (status >= 500) safelyReportUnexpected(options, log, ctx, error);
       ctx.response = options.exposeDetails
         ? safeJsonResponse(status, {
             error: title,
@@ -146,9 +153,17 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
  * 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] {
+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] {
   if (error instanceof HttpClientError && error.code !== undefined) {
     return error.code === HttpErrorCode.Timeout ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
   }
+  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"];
 }

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.24" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.25" }, 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/orm/databaseErrorStatus.ts

@@ -0,0 +1,35 @@
+import {
+  CheckViolationError,
+  EntityNotFoundError,
+  ForeignKeyViolationError,
+  LockTimeoutError,
+  NotNullViolationError,
+  OrmTransactionScopeError,
+  OrmValidationError,
+  TransactionOutcomeUnknownError,
+  UniqueViolationError,
+} from "../../library/orm";
+
+/** SQLSTATEs a client may retry: serialization failure, deadlock, statement timeout. */
+const RETRYABLE = new Set(["40001", "40P01", "57014"]);
+
+/**
+ * HTTP status for a database error, for `http: { errorHandler: { status:
+ * databaseErrorStatus } }`: 409 for a unique or foreign key conflict, 422 for
+ * a check, not-null or entity validation failure, 404 for `first()` without a
+ * row, 503 when the database did not answer, a lock or the transaction timed
+ * out, or a retryable conflict happened. Anything else stays 500.
+ */
+export function databaseErrorStatus(error: unknown): number | undefined {
+  if (error instanceof UniqueViolationError || error instanceof ForeignKeyViolationError) return 409;
+  if (error instanceof CheckViolationError || error instanceof NotNullViolationError || error instanceof OrmValidationError) return 422;
+  if (error instanceof EntityNotFoundError) return 404;
+  if (error instanceof LockTimeoutError || error instanceof TransactionOutcomeUnknownError) return 503;
+  if (error instanceof OrmTransactionScopeError && / timed out after \d+ ms/.test(error.message)) return 503;
+  if (typeof error === "object" && error !== null) {
+    const { errno, code } = error as { errno?: unknown; code?: unknown };
+    if (typeof errno === "string" && RETRYABLE.has(errno)) return 503;
+    if (typeof code === "string" && code.startsWith("ERR_POSTGRES_CONNECTION")) return 503;
+  }
+  return undefined;
+}

package/core/orm/index.ts

@@ -10,6 +10,7 @@ export { OrmConnectionLifecycle, OrmLifecycle, OrmProviderReadyLifecycle } from
 export { IRepository, repositoryFor } from "./repository";
 export { registerRepositories } from "./registerRepositories";
 export { paginate, type PageResult } from "./listQuery";
+export { databaseErrorStatus } from "./databaseErrorStatus";
 
 import { registerModuleMetadataExpander, type BazisModuleRef } from "../di";
 import { OrmOwnedStoreAdmissionError, type DbContext } from "../../library/orm";

package/library/orm/Providers/PostgresProvider.ts

@@ -749,7 +749,7 @@ export class PostgresProvider implements DatabaseProvider {
         // Both query() and execute() can write in autocommit mode. Once handed
         // to the driver, a missing reply is not proof that replay is safe.
         if (autocommit && nativeQuery !== undefined && !isConfirmedStatementRejection(error)) {
-          const unknown = this.uncertainty(error);
+          const unknown = this.uncertainty(error, "statement");
           if (owner) {
             owner.unknownOutcome ??= unknown;
             owner.state = "quarantined";
@@ -1205,7 +1205,7 @@ export class PostgresProvider implements DatabaseProvider {
     } catch { return false; }
   }
 
-  private uncertainty(cause?: unknown, phase: "commit" | "cancellation" = "commit"): TransactionOutcomeUnknownError {
+  private uncertainty(cause?: unknown, phase: "commit" | "cancellation" | "statement" = "commit"): TransactionOutcomeUnknownError {
     const error = new TransactionOutcomeUnknownError(cause, phase); this.uncertainErrors.add(error); return error;
   }
 

package/library/orm/Providers/transactionOutcome.ts

@@ -5,13 +5,22 @@ import type { TransactionCallback } from "./types";
 export class TransactionOutcomeUnknownError extends DbUpdateError {
   readonly code = "ORM_TRANSACTION_OUTCOME_UNKNOWN";
   readonly outcome = "unknown";
-  constructor(override readonly cause?: unknown, readonly phase: "commit" | "cancellation" = "commit") {
+  /** `statement`: a statement sent outside a transaction got no answer (a timeout or a lost connection). */
+  constructor(override readonly cause?: unknown, readonly phase: "commit" | "cancellation" | "statement" = "commit") {
     super(phase === "commit"
       ? "Transaction outcome is unknown. Reconcile database state and use a new DbContext before saving again."
-      : "Transaction cancellation is unconfirmed. Reconcile database state and use a new DbContext before saving again.");
+      : phase === "statement"
+        ? `The database did not answer a statement sent outside a transaction${statementReason(cause)}. If the statement changed data, its outcome is unknown: check the data and use a new DbContext before saving again.`
+        : "Transaction cancellation is unconfirmed. Reconcile database state and use a new DbContext before saving again.");
   }
 }
 
+function statementReason(cause: unknown): string {
+  if (!(cause instanceof Error) || cause.message === "") return "";
+  const message = cause.message.replace(/\.$/, "");
+  return `: ${cause.name === "Error" || cause.name.startsWith("Orm") ? message : `${cause.name}: ${message}`}`;
+}
+
 export function isUnknownTransactionOutcome(error: unknown): boolean {
   const pending = [error];
   const seen = new Set<unknown>();

package/library/orm/Saving/SaveExecutor.ts

@@ -1,5 +1,5 @@
 import { Validator } from "../../validation";
-import { DbUpdateError, isCommittedOutcome, OrmValidationError, UniqueViolationError } from "../errors";
+import { DbUpdateError, isCommittedOutcome, OrmValidationError, translateDatabaseError } from "../errors";
 import { isDatabaseGenerated, type EntityModel } from "../Metadata/types";
 import { maxRowsPerInsert } from "../Providers/limits";
 import { decodeProperty } from "../Providers/propertyConversion";
@@ -170,7 +170,7 @@ export class SaveExecutor {
         // idempotent fallback also protects custom/top-level providers.
         this.restoreGeneratedKeys(generatedKeys);
         for (const token of tokens) this.restoreRollbackToken(token);
-        throw UniqueViolationError.from(error);
+        throw translateDatabaseError(error);
       }
       throw error;
     }

package/library/orm/Transactions/TransactionScopeCoordinator.ts

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { DbContext } from "../DbContext";
-import { ConcurrentTransactionScopeError, differentProviderMessage, OrmDatabaseTimeError, OrmProviderIdentityMismatchError, OrmTransactionScopeError } from "../errors";
+import { ConcurrentTransactionScopeError, differentProviderMessage, OrmDatabaseTimeError, OrmProviderIdentityMismatchError, OrmTransactionScopeError, translateDatabaseError } from "../errors";
 import { baseProvider, withPostgresScopeOptions, createObservedProvider, postgresTransactionCapability, rootAuthority, withProviderDispatchObserver, withoutProviderDispatchObserver, type CancellableProviderDispatch } from "../Providers/ormTransactionRuntime";
 import type { DatabaseProvider } from "../Providers/types";
 import { OrmTransaction, type OrmDatabaseTimeV1, type OrmTransactionScopeOptions } from "./OrmTransaction";
@@ -86,7 +86,9 @@ export function observedProvider(context: object, provider: DatabaseProvider): D
   const authority = rootAuthority(provider);
   const fence = <T>(operation: () => Promise<T>, view = views.getStore()): Promise<T> => {
     if (uncertainContexts.has(token)) return Promise.reject(new TransactionOutcomeUnknownError());
-    const guarded = () => operation().catch((error) => { if (postgresTransactionCapability(provider)?.isOutcomeUncertain?.(error)) uncertainContexts.add(token); throw error; });
+    // Known SQLSTATEs (unique, foreign key, check, not null, lock timeout)
+    // reach the context's caller as ORM errors; the outcome check sees the raw one.
+    const guarded = () => operation().catch((error) => { if (postgresTransactionCapability(provider)?.isOutcomeUncertain?.(error)) uncertainContexts.add(token); throw translateDatabaseError(error); });
     if (!view) return guarded();
     const frame = view.frame;
     if (frame.authority !== authority || !view.enrolled.has(token) || frame.state !== "active" || frame.activeChild !== undefined) {

package/library/orm/errors.ts

@@ -192,6 +192,89 @@ export class UniqueViolationError extends DbUpdateError {
   }
 }
 
+/** Reads a non-empty string field of a driver error. */
+function driverField(cause: object, name: string): string | undefined {
+  const value = (cause as Record<string, unknown>)[name];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** Copies the SQLSTATE so transaction-outcome checks see the same server rejection. */
+function copyServerCode(target: object, cause: object): void {
+  for (const name of ["errno", "code"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(cause, name);
+    if (descriptor && "value" in descriptor) Object.defineProperty(target, name, { value: descriptor.value, enumerable: true });
+  }
+}
+
+/** A foreign key constraint was violated (SQLSTATE 23503). */
+export class ForeignKeyViolationError extends DbUpdateError {
+  readonly constraint: string | undefined;
+  readonly table: string | undefined;
+  constructor(cause: object) {
+    const constraint = driverField(cause, "constraint");
+    super(`Foreign key constraint${constraint === undefined ? "" : ` "${constraint}"`} violated: the row refers to a missing row, or a row that other rows refer to was deleted.`, { cause });
+    this.constraint = constraint;
+    this.table = driverField(cause, "table");
+    copyServerCode(this, cause);
+  }
+}
+
+/** A CHECK constraint was violated (SQLSTATE 23514). */
+export class CheckViolationError extends DbUpdateError {
+  readonly constraint: string | undefined;
+  readonly table: string | undefined;
+  constructor(cause: object) {
+    const constraint = driverField(cause, "constraint");
+    super(constraint === undefined ? "Check constraint violated." : `Check constraint "${constraint}" violated.`, { cause });
+    this.constraint = constraint;
+    this.table = driverField(cause, "table");
+    copyServerCode(this, cause);
+  }
+}
+
+/** A NOT NULL column got NULL (SQLSTATE 23502). */
+export class NotNullViolationError extends DbUpdateError {
+  readonly column: string | undefined;
+  readonly table: string | undefined;
+  constructor(cause: object) {
+    const column = driverField(cause, "column");
+    const table = driverField(cause, "table");
+    super(column === undefined ? "A NOT NULL column got NULL." : `Column "${column}"${table === undefined ? "" : ` of table "${table}"`} does not accept NULL.`, { cause });
+    this.column = column;
+    this.table = table;
+    copyServerCode(this, cause);
+  }
+}
+
+/** A lock was not granted within `lock_timeout` (SQLSTATE 55P03). */
+export class LockTimeoutError extends OrmError {
+  constructor(cause: object) {
+    super("A lock was not granted within lockTimeoutMs: another transaction holds the row or table. Retry the operation, or shorten the transaction that holds the lock.", { cause });
+    copyServerCode(this, cause);
+  }
+}
+
+const TRANSLATED: Readonly<Record<string, new (cause: object) => OrmError>> = {
+  "23505": UniqueViolationError,
+  "23503": ForeignKeyViolationError,
+  "23514": CheckViolationError,
+  "23502": NotNullViolationError,
+  "55P03": LockTimeoutError,
+};
+
+/**
+ * A driver error with a known SQLSTATE as its ORM error (unique, foreign key,
+ * check, not-null violation, lock timeout); anything else unchanged. The
+ * original error is `cause`; messages carry constraint and column names only,
+ * never row values.
+ */
+export function translateDatabaseError(error: unknown): unknown {
+  if (error === null || typeof error !== "object" || error instanceof OrmError) return error;
+  const errno = Object.getOwnPropertyDescriptor(error, "errno");
+  const Translated = errno && "value" in errno && typeof errno.value === "string" ? TRANSLATED[errno.value] : undefined;
+  return Translated === undefined ? error : new Translated(error);
+}
+
 /** The entity failed validation before saving. */
 export class OrmValidationError extends DbUpdateError {
   constructor(

package/library/orm/index.ts

@@ -151,6 +151,11 @@ export {
   OrmError,
   OrmValidationError,
   UniqueViolationError,
+  ForeignKeyViolationError,
+  CheckViolationError,
+  NotNullViolationError,
+  LockTimeoutError,
+  translateDatabaseError,
   PostCommitError,
   isCommittedOutcome,
   OrmTransactionScopeError,

package/package.json

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