okengine 0.20.0 → 0.21.0

package/src/elements/store/kv-errors.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Redis-wire KV errors → ServiceUnavailable (availability / retry exhaust).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { isFlowFailure } from "../../kernel/hooks.ts";
+import { createRedisFakeClient, redisDriver } from "../../drivers/redis.ts";
+import { memoryDrivers } from "../../drivers/memory.ts";
+import { store } from "./declare.ts";
+import { isRetryableKvError, kvErrorToFailure } from "./kv-errors.ts";
+import { createStoreRuntime, type KvStoreFxHandle } from "./runtime.ts";
+
+describe("kvErrorToFailure", () => {
+  test("connection / cluster → ServiceUnavailable without copying message", () => {
+    const closed = kvErrorToFailure(
+      Object.assign(new Error("Connection closed"), { code: "ECONNREFUSED" }),
+    );
+    expect(closed?.error.code).toBe("ServiceUnavailable");
+    expect(JSON.stringify(closed)).not.toContain("Connection closed");
+
+    expect(kvErrorToFailure(new Error("CLUSTERDOWN The cluster is down"))?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(
+      kvErrorToFailure(new Error("READONLY You can't write against a read only replica."))?.error
+        .code,
+    ).toBe("ServiceUnavailable");
+    expect(
+      kvErrorToFailure(new Error("OOM command not allowed when used memory > 'maxmemory'."))?.error
+        .code,
+    ).toBe("ServiceUnavailable");
+    expect(isFlowFailure(closed)).toBe(true);
+  });
+
+  test("BUSY / TRYAGAIN left thrown until retryable: unavailable", () => {
+    const busy = new Error("BUSY Redis is busy running a script");
+    expect(isRetryableKvError(busy)).toBe(true);
+    expect(kvErrorToFailure(busy, { retryable: "leave" })).toBeUndefined();
+    expect(kvErrorToFailure(busy, { retryable: "unavailable" })?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(
+      kvErrorToFailure(new Error("TRYAGAIN Multiple keys request during rehashing"), {
+        retryable: "leave",
+      }),
+    ).toBeUndefined();
+  });
+
+  test("WRONGTYPE / NOSCRIPT stay unmapped", () => {
+    expect(
+      kvErrorToFailure(
+        new Error("WRONGTYPE Operation against a key holding the wrong kind of value"),
+      ),
+    ).toBeUndefined();
+    expect(
+      kvErrorToFailure(new Error("NOSCRIPT No matching script. Please use EVAL.")),
+    ).toBeUndefined();
+    expect(kvErrorToFailure(new Error("boom"))).toBeUndefined();
+  });
+
+  test("walks .cause for connection failures", () => {
+    const wrapped = {
+      message: "kv get failed",
+      cause: Object.assign(new Error("Connection closed"), { code: "ECONNRESET" }),
+    };
+    expect(kvErrorToFailure(wrapped)?.error.code).toBe("ServiceUnavailable");
+    expect(JSON.stringify(kvErrorToFailure(wrapped))).not.toContain("kv get failed");
+  });
+});
+
+describe("openKv maps Redis throws", () => {
+  test("connection failure on get becomes ServiceUnavailable", async () => {
+    const fake = createRedisFakeClient();
+    fake.get = async () => {
+      throw Object.assign(new Error("Connection closed"), { code: "ECONNREFUSED" });
+    };
+    const sessions = store.kv("sessions");
+    const runtime = createStoreRuntime({
+      drivers: {
+        kv: redisDriver,
+        files: memoryDrivers.files,
+        index: memoryDrivers.index,
+      },
+      kv: { sessions: { client: fake } },
+    });
+    runtime.register(sessions);
+    const handle = (await runtime.open(sessions, { effects: {} })) as KvStoreFxHandle;
+    try {
+      await handle.get("sid");
+      throw new Error("expected mapped failure");
+    } catch (err) {
+      expect(isFlowFailure(err)).toBe(true);
+      expect((err as { error: { code: string } }).error.code).toBe("ServiceUnavailable");
+      expect(JSON.stringify(err)).not.toContain("Connection closed");
+    }
+    await runtime.close();
+  });
+});

package/src/elements/store/kv-errors.ts

@@ -0,0 +1,139 @@
+/**
+ * Map Redis-wire KV errors to typed {@link FlowFailure} values.
+ *
+ * Lives on the store path — not the kernel edge graph. Availability and
+ * retryable script/cluster replies become `ServiceUnavailable`. Programmer
+ * mistakes (`WRONGTYPE`, `NOSCRIPT`) stay unmapped so the HTTP encoder
+ * sanitizes them as `InternalError`.
+ */
+
+import { fail } from "../../kernel/fail-helpers.ts";
+import type { FlowFailure } from "../../kernel/errors.ts";
+import type { BuiltinErrorMap } from "../../kernel/builtin-errors.ts";
+
+/** How to treat Redis `BUSY` / `TRYAGAIN` / `LOADING`. */
+export type KvRetryableMode = "leave" | "unavailable";
+
+/** Options for {@link kvErrorToFailure}. */
+export interface KvErrorToFailureOptions {
+  /**
+   * `leave` — return `undefined` so {@link flow.retry} can rethrow.
+   * `unavailable` — map to `ServiceUnavailable` after retries exhaust.
+   */
+  readonly retryable?: KvRetryableMode;
+}
+
+type KvFailure = FlowFailure<BuiltinErrorMap["ServiceUnavailable"]>;
+
+type KvErrShape = {
+  readonly name?: unknown;
+  readonly code?: unknown;
+  readonly errno?: unknown;
+  readonly message?: unknown;
+  readonly cause?: unknown;
+};
+
+const RETRY_TOKEN = new Set(["BUSY", "BUSYKEY", "TRYAGAIN", "LOADING"]);
+const UNAVAILABLE_TOKEN = new Set([
+  "CLUSTERDOWN",
+  "MASTERDOWN",
+  "READONLY",
+  "MISCONF",
+  "OOM",
+  "MOVED",
+  "ASK",
+  "UNBLOCKED",
+]);
+const CONN_CODE = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EPIPE",
+  "ENETUNREACH",
+  "EAI_AGAIN",
+  "ECONNABORTED",
+]);
+
+/**
+ * True when `err` is a Redis `BUSY` / `TRYAGAIN` / `LOADING` reply.
+ *
+ * Left thrown during retries; mapped to `ServiceUnavailable` after exhaust.
+ *
+ * @param err - Caught driver error
+ */
+export function isRetryableKvError(err: unknown): boolean {
+  return walk(err, (node) => retrySignal(node));
+}
+
+/**
+ * Map a Redis-wire KV error to `ServiceUnavailable`, or `undefined` when it
+ * is not an availability / retryable Redis failure.
+ *
+ * @param err - Caught value from `fx.store` KV ops
+ * @param options - Retryable handling
+ */
+export function kvErrorToFailure(
+  err: unknown,
+  options: KvErrorToFailureOptions = {},
+): KvFailure | undefined {
+  const retryable = options.retryable ?? "leave";
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (!current || typeof current !== "object") break;
+    if (retrySignal(current)) {
+      if (retryable === "leave") return undefined;
+      return fail.serviceUnavailable();
+    }
+    if (isUnavailable(current)) return fail.serviceUnavailable();
+    current = causeOf(current);
+  }
+  return undefined;
+}
+
+function retrySignal(err: unknown): boolean {
+  return RETRY_TOKEN.has(redisToken(err));
+}
+
+function isUnavailable(err: unknown): boolean {
+  const token = redisToken(err);
+  if (UNAVAILABLE_TOKEN.has(token)) return true;
+  if (CONN_CODE.has(token)) return true;
+  if (/^ERR_REDIS_(CONNECTION|CONNECT|CLOSED|TIMEOUT|NETWORK)/.test(token)) return true;
+  const message = errMessage(err);
+  if (/max number of clients/i.test(message)) return true;
+  if (/connection (closed|refused|reset|timed out)/i.test(message)) return true;
+  if (/socket hang up|connect econn|read econn/i.test(message)) return true;
+  if (/ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EPIPE/i.test(message)) return true;
+  return false;
+}
+
+function redisToken(err: unknown): string {
+  if (!err || typeof err !== "object") return "";
+  const e = err as KvErrShape;
+  if (typeof e.code === "string" && e.code.length > 0) return e.code.toUpperCase();
+  const message = typeof e.message === "string" ? e.message.trim() : "";
+  const first = /^([A-Za-z][A-Za-z0-9_]+)/.exec(message)?.[1];
+  return first ? first.toUpperCase() : "";
+}
+
+function errMessage(err: unknown): string {
+  if (!err || typeof err !== "object") return "";
+  const message = (err as KvErrShape).message;
+  return typeof message === "string" ? message : "";
+}
+
+function causeOf(err: unknown): unknown {
+  if (!err || typeof err !== "object") return undefined;
+  return (err as KvErrShape).cause;
+}
+
+function walk(err: unknown, pred: (node: unknown) => boolean): boolean {
+  let current: unknown = err;
+  for (let i = 0; i < 4; i++) {
+    if (pred(current)) return true;
+    current = causeOf(current);
+    if (current === undefined) break;
+  }
+  return false;
+}

package/src/elements/store/resource.ts

@@ -14,7 +14,7 @@
 
 import { flow, type AnyFlowDef, type FlowDef, type FlowErrorMap } from "../../kernel/flow.ts";
 import { applyBoundaryContract, stampBoundaryContract } from "../../kernel/boundary-contract.ts";
-import { fail } from "../../kernel/errors.ts";
+import { fail } from "../../kernel/fail-helpers.ts";
 import type { Fx } from "../../kernel/fx.ts";
 import {
   openLiveStream,
@@ -53,7 +53,11 @@ export interface ResourceOptions {
    * used to extend `update` with the path id (wire sends `{ id, ...patch }`).
    */
   readonly idSchema?: unknown;
-  /** Typed errors for get / update / remove (default `{ NotFound }`). */
+  /**
+   * Extra typed errors for get / update / remove.
+   *
+   * Built-in `NotFound` is always on — omit unless tightening the payload.
+   */
   readonly errors?: FlowErrorMap;
   /** `:id` column; defaults to the table primary key. */
   readonly id?: unknown;
@@ -191,7 +195,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
   const { mode, limit, maxLimit, cursorColumns: resolvedCursor } = scope;
   const countMode = scope.count;
 
-  const errors = options.errors ?? ({ NotFound: {} as never } as FlowErrorMap);
+  const errors = options.errors;
   const breaking = options.breaking === true;
 
   /** Run the list query and shape rows + meta. */
@@ -309,7 +313,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
         findById(t: unknown, id: string): Promise<SqlRow | null>;
       };
       const row = await store.findById(table, String(id));
-      if (!row) return fail("NotFound", {});
+      if (!row) return fail.notFound();
       return row;
     },
   });
@@ -341,7 +345,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
         update(t: unknown): { set(row: SqlRow): { where(w: unknown): Promise<number> } };
       };
       const existing = await store.findById(table, String(id));
-      if (!existing) return fail("NotFound", {});
+      if (!existing) return fail.notFound();
       if (Object.keys(patch).length > 0) {
         await store
           .update(table)
@@ -349,7 +353,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
           .where(leafOp(idDrizzleCol, "=", String(id)));
       }
       const row = await store.findById(table, String(id));
-      if (!row) return fail("NotFound", {});
+      if (!row) return fail.notFound();
       return row;
     },
   });
@@ -371,7 +375,7 @@ export function resource(db: SqlStoreDecl, table: unknown, options: ResourceOpti
         delete(t: unknown, id: string): Promise<boolean>;
       };
       const deleted = await store.delete(table, String(id));
-      if (!deleted) return fail("NotFound", {});
+      if (!deleted) return fail.notFound();
       return fx.json.empty();
     },
   });

package/src/elements/store/runtime.ts

@@ -44,6 +44,7 @@ import type {
   StoreDecl,
 } from "./declare.ts";
 import { openSqlKvNamespace } from "./kv-sql.ts";
+import { withStoreErrorMap } from "./store-errors.ts";
 import { createGatedFilesStoreHandle, type GatedFilesFxBridge } from "./files-fx.ts";
 import {
   createFilesImagePipeline,
@@ -434,14 +435,15 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
       kvNs.set(decl.name, ns);
     }
     const driverId = ns.driverId;
+    const handle = ns;
     return {
       ref: `kv:${decl.name}`,
       driverId,
-      get: (key) => ns!.get(key),
-      set: (key, value, ttl) => ns!.set(key, value, ttl),
-      delete: (key) => ns!.delete(key),
-      list: (prefix) => ns!.list(prefix),
-      ttlMs: (key) => ns!.ttlMs(key),
+      get: (key) => withStoreErrorMap(() => handle.get(key)),
+      set: (key, value, ttl) => withStoreErrorMap(() => handle.set(key, value, ttl)),
+      delete: (key) => withStoreErrorMap(() => handle.delete(key)),
+      list: (prefix) => withStoreErrorMap(() => handle.list(prefix)),
+      ttlMs: (key) => withStoreErrorMap(() => handle.ttlMs(key)),
     };
   }
 
@@ -458,19 +460,22 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
       });
       fileBuckets.set(decl.name, bucket);
     }
+    const handle = bucket;
     const access = {
-      get: (key: string) => bucket!.get(key),
-      put: (key: string, data: Uint8Array | string) => bucket!.put(key, data),
+      get: (key: string) => withStoreErrorMap(() => handle.get(key)),
+      put: (key: string, data: Uint8Array | string) =>
+        withStoreErrorMap(() => handle.put(key, data)),
     };
     return {
       ref: `files:${decl.name}`,
-      driverId: bucket.driverId,
-      put: (key, data) => bucket!.put(key, data),
-      get: (key) => bucket!.get(key),
-      delete: (key) => bucket!.delete(key),
-      list: (prefix) => bucket!.list(prefix),
+      driverId: handle.driverId,
+      put: (key, data) => withStoreErrorMap(() => handle.put(key, data)),
+      get: (key) => withStoreErrorMap(() => handle.get(key)),
+      delete: (key) => withStoreErrorMap(() => handle.delete(key)),
+      list: (prefix) => withStoreErrorMap(() => handle.list(prefix)),
       image: (source, imageOpts) => createFilesImagePipeline(access, source, imageOpts),
-      putImage: (key, data, putOpts) => putImageToBucket(access, key, data, putOpts),
+      putImage: (key, data, putOpts) =>
+        withStoreErrorMap(() => putImageToBucket(access, key, data, putOpts)),
     };
   }
 

package/src/elements/store/sql-errors.test.ts

@@ -0,0 +1,197 @@
+/**
+ * SQLSTATE / SQLite constraint → typed FlowFailure.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { isFlowFailure } from "../../kernel/hooks.ts";
+import { isRetryableSqlError, sqlErrorToFailure } from "./sql-errors.ts";
+
+describe("sqlErrorToFailure", () => {
+  test("unique / exclusion → Conflict  without copying message", () => {
+    const unique = sqlErrorToFailure({
+      code: "23505",
+      message: 'duplicate key value violates unique constraint "users_email_key"',
+      detail: "Key (email)=(a@b.c) already exists.",
+      constraint: "users_email_key",
+      table: "users",
+      column: "email",
+    });
+    expect(unique?.error.code).toBe("Conflict");
+    expect(unique?.error.data).toEqual({
+      sqlstate: "23505",
+      constraint: "users_email_key",
+      table: "users",
+      column: "email",
+    });
+    expect(JSON.stringify(unique)).not.toContain("already exists");
+    expect(JSON.stringify(unique)).not.toContain("a@b.c");
+
+    const exclusion = sqlErrorToFailure({ code: "23P01", constraint: "no_overlap" });
+    expect(exclusion?.error.code).toBe("Conflict");
+  });
+
+  test("restrict / restrict_violation → ForeignKey", () => {
+    expect(sqlErrorToFailure({ code: "23001", table: "notes" })?.error.code).toBe("ForeignKey");
+  });
+
+  test("invalid / too_long / out_of_range → DatabaseError 422 reasons", () => {
+    expect(sqlErrorToFailure({ code: "22P02" })?.error.data).toMatchObject({
+      reason: "invalid",
+      sqlstate: "22P02",
+    });
+    expect(sqlErrorToFailure({ code: "22007" })?.error.data).toMatchObject({ reason: "invalid" });
+    expect(sqlErrorToFailure({ code: "22023" })?.error.data).toMatchObject({ reason: "invalid" });
+    expect(sqlErrorToFailure({ code: "42804" })?.error.data).toMatchObject({ reason: "invalid" });
+    expect(sqlErrorToFailure({ code: "22001", column: "title" })?.error.data).toMatchObject({
+      reason: "too_long",
+      column: "title",
+    });
+    expect(sqlErrorToFailure({ code: "22003" })?.error.data).toMatchObject({
+      reason: "out_of_range",
+    });
+    expect(sqlErrorToFailure({ code: "22008" })?.error.data).toMatchObject({
+      reason: "out_of_range",
+    });
+  });
+
+  test("walks Drizzle .cause for unique SQLSTATE", () => {
+    const wrapped = {
+      message: "Failed query: insert into users constraint users_email_key",
+      cause: {
+        code: "23505",
+        constraint: "users_email_key",
+        message: 'duplicate key value violates unique constraint "users_email_key"',
+      },
+    };
+    const mapped = sqlErrorToFailure(wrapped);
+    expect(mapped?.error.code).toBe("Conflict");
+    expect(mapped?.error.data).toMatchObject({ constraint: "users_email_key", sqlstate: "23505" });
+    expect(JSON.stringify(mapped)).not.toContain("duplicate key");
+  });
+
+  test("foreign key → ForeignKey", () => {
+    const fk = sqlErrorToFailure({
+      code: "23503",
+      table: "notes",
+      constraint: "notes_user_id_fkey",
+      message: 'insert or update on table "notes" violates foreign key constraint',
+    });
+    expect(fk?.error.code).toBe("ForeignKey");
+    expect(fk?.error.data).toMatchObject({
+      sqlstate: "23503",
+      table: "notes",
+      constraint: "notes_user_id_fkey",
+    });
+    expect(JSON.stringify(fk)).not.toContain("violates");
+  });
+
+  test("not_null / check → DatabaseError reasons", () => {
+    const notNull = sqlErrorToFailure({ code: "23502", column: "title", table: "posts" });
+    expect(notNull?.error.code).toBe("DatabaseError");
+    expect(notNull?.error.data).toMatchObject({ reason: "not_null", column: "title" });
+
+    const check = sqlErrorToFailure({ code: "23514", constraint: "positive_clicks" });
+    expect(check?.error.code).toBe("DatabaseError");
+    expect(check?.error.data).toMatchObject({ reason: "check", constraint: "positive_clicks" });
+  });
+
+  test("40001 / 40P01 left thrown until retryable: unavailable", () => {
+    const ser = { code: "40001", message: "could not serialize access" };
+    expect(isRetryableSqlError(ser)).toBe(true);
+    expect(sqlErrorToFailure(ser, { retryable: "leave" })).toBeUndefined();
+    const exhausted = sqlErrorToFailure(ser, { retryable: "unavailable" });
+    expect(exhausted?.error.code).toBe("ServiceUnavailable");
+    expect(JSON.stringify(exhausted)).not.toContain("serialize");
+
+    expect(sqlErrorToFailure({ code: "40P01" }, { retryable: "leave" })).toBeUndefined();
+    expect(sqlErrorToFailure({ code: "40P01" }, { retryable: "unavailable" })?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(isRetryableSqlError({ code: "55P03" })).toBe(true);
+    expect(sqlErrorToFailure({ code: "55P03" }, { retryable: "leave" })).toBeUndefined();
+    expect(sqlErrorToFailure({ code: "55P03" }, { retryable: "unavailable" })?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+  });
+
+  test("connection / paused → ServiceUnavailable", () => {
+    expect(sqlErrorToFailure({ code: "08006" })?.error.code).toBe("ServiceUnavailable");
+    expect(sqlErrorToFailure({ code: "53300" })?.error.code).toBe("ServiceUnavailable");
+    expect(sqlErrorToFailure({ code: "53100" })?.error.code).toBe("ServiceUnavailable");
+    expect(sqlErrorToFailure({ code: "57P01" })?.error.code).toBe("ServiceUnavailable");
+    expect(sqlErrorToFailure({ code: "57014" })?.error.code).toBe("ServiceUnavailable");
+    expect(sqlErrorToFailure({ code: "25P03" })?.error.code).toBe("ServiceUnavailable");
+    expect(sqlErrorToFailure({ code: "ERR_POSTGRES_CONNECTION_CLOSED" })?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+    expect(
+      sqlErrorToFailure({ name: "SharedPostgresPausedError", code: "ERR_OKE_POSTGRES_PAUSED" })
+        ?.error.code,
+    ).toBe("ServiceUnavailable");
+  });
+
+  test("sqlite UNIQUE / FK / NOT NULL / CHECK", () => {
+    const unique = sqlErrorToFailure({
+      name: "SQLiteError",
+      message: "UNIQUE constraint failed: users.email",
+      errno: 2067,
+    });
+    expect(unique?.error.code).toBe("Conflict");
+    expect(unique?.error.data).toMatchObject({ table: "users", column: "email" });
+
+    const fk = sqlErrorToFailure({
+      name: "SQLiteError",
+      message: "FOREIGN KEY constraint failed",
+      errno: 787,
+    });
+    expect(fk?.error.code).toBe("ForeignKey");
+
+    const notNull = sqlErrorToFailure({
+      name: "SQLiteError",
+      message: "NOT NULL constraint failed: posts.title",
+    });
+    expect(notNull?.error.data).toMatchObject({
+      reason: "not_null",
+      table: "posts",
+      column: "title",
+    });
+
+    const check = sqlErrorToFailure({
+      name: "SQLiteError",
+      message: "CHECK constraint failed: positive_clicks",
+    });
+    expect(check?.error.data).toMatchObject({ reason: "check", constraint: "positive_clicks" });
+
+    const pk = sqlErrorToFailure({
+      name: "SQLiteError",
+      message: "PRIMARY KEY constraint failed: users.id",
+      errno: 1555,
+    });
+    expect(pk?.error.code).toBe("Conflict");
+    expect(pk?.error.data).toMatchObject({ table: "users", column: "id" });
+  });
+
+  test("sqlite busy left thrown until retryable: unavailable", () => {
+    const busy = {
+      name: "SQLiteError",
+      code: "SQLITE_BUSY",
+      errno: 5,
+      message: "database is locked",
+    };
+    expect(isRetryableSqlError(busy)).toBe(true);
+    expect(sqlErrorToFailure(busy, { retryable: "leave" })).toBeUndefined();
+    expect(sqlErrorToFailure(busy, { retryable: "unavailable" })?.error.code).toBe(
+      "ServiceUnavailable",
+    );
+  });
+
+  test("unknown SQLSTATE → DatabaseError unknown; non-SQL stays undefined", () => {
+    const other = sqlErrorToFailure({ code: "22012", message: "division by zero" });
+    expect(other?.error.code).toBe("DatabaseError");
+    expect(other?.error.data).toMatchObject({ reason: "unknown", sqlstate: "22012" });
+    expect(JSON.stringify(other)).not.toContain("division");
+
+    expect(sqlErrorToFailure(new Error("boom"))).toBeUndefined();
+    expect(isFlowFailure(sqlErrorToFailure({ code: "23505" }))).toBe(true);
+  });
+});