okengine 0.23.0 → 0.23.2

package/src/drivers/postgres.test.ts

@@ -9,6 +9,7 @@ import {
   isPostgresConnectionNoise,
   isSharedPostgresPaused,
   pauseSharedPostgresClients,
+  PostgresDriverError,
   resumeSharedPostgresClients,
   SharedPostgresPausedError,
   sharedPostgresClient,
@@ -101,3 +102,62 @@ describe("pauseSharedPostgresClients", () => {
     expect(isPostgresConnectionNoise(new Error("relation missing"))).toBe(false);
   });
 });
+
+describe("PostgresDriverError", () => {
+  test("a non-Error rejection copies SQLSTATE fields and sets cause", async () => {
+    const cause = {
+      code: "ERR_POSTGRES_SERVER_ERROR",
+      errno: "23505",
+      constraint: "users_pkey",
+      table: "users",
+      column: "id",
+      message: "duplicate key",
+    };
+    const conn = await connectPostgres({
+      client: {
+        async unsafe() {
+          throw cause;
+        },
+      },
+    });
+    let caught: unknown;
+    try {
+      await conn.query("SELECT 1");
+    } catch (err) {
+      caught = err;
+    } finally {
+      await conn.close();
+    }
+    expect(caught).toBeInstanceOf(PostgresDriverError);
+    const wrapped = caught as PostgresDriverError;
+    expect(wrapped.code).toBe("ERR_POSTGRES_SERVER_ERROR");
+    expect(wrapped.errno).toBe("23505");
+    expect(wrapped.constraint).toBe("users_pkey");
+    expect(wrapped.table).toBe("users");
+    expect(wrapped.column).toBe("id");
+    expect(wrapped.cause).toBe(cause);
+  });
+
+  test("an Error rejection is rethrown unchanged", async () => {
+    const original = Object.assign(new Error("duplicate key"), {
+      code: "23505",
+      errno: "23505",
+    });
+    const conn = await connectPostgres({
+      client: {
+        async unsafe() {
+          throw original;
+        },
+      },
+    });
+    let caught: unknown;
+    try {
+      await conn.query("SELECT 1");
+    } catch (err) {
+      caught = err;
+    } finally {
+      await conn.close();
+    }
+    expect(caught).toBe(original);
+  });
+});

package/src/drivers/postgres.ts

@@ -87,6 +87,80 @@ export class SharedPostgresPausedError extends Error {
   }
 }
 
+/**
+ * Bun.SQL rejected with a value that is not an {@link Error}.
+ *
+ * {@link Error.cause} is the original rejection. `code`, `errno`,
+ * `constraint`, `table`, and `column` are copied when the driver sent them
+ * so SQLSTATE mapping can read a plain object the same way it reads an Error.
+ */
+export class PostgresDriverError extends Error {
+  /** Driver `code` (`ERR_POSTGRES_*` or a five-character SQLSTATE). */
+  readonly code?: string;
+  /** SQLSTATE string, or a numeric errno when the driver sent one. */
+  readonly errno?: string | number;
+  /** Constraint name, when the driver sent one. */
+  readonly constraint?: string;
+  /** Table name, when the driver sent one. */
+  readonly table?: string;
+  /** Column name, when the driver sent one. */
+  readonly column?: string;
+
+  /**
+   * @param cause - Non-Error rejection from Bun.SQL
+   */
+  constructor(cause: unknown) {
+    super(postgresRejectionMessage(cause), { cause });
+    this.name = "PostgresDriverError";
+    if (cause === null || typeof cause !== "object") return;
+    const row = cause as Record<string, unknown>;
+    const code = readDriverString(row, "code");
+    const constraint = readDriverString(row, "constraint");
+    const table = readDriverString(row, "table");
+    const column = readDriverString(row, "column");
+    const errno = readDriverErrno(row);
+    if (code !== undefined) this.code = code;
+    if (errno !== undefined) this.errno = errno;
+    if (constraint !== undefined) this.constraint = constraint;
+    if (table !== undefined) this.table = table;
+    if (column !== undefined) this.column = column;
+  }
+}
+
+function postgresRejectionMessage(cause: unknown): string {
+  if (cause !== null && typeof cause === "object" && "message" in cause) {
+    const message = (cause as { message: unknown }).message;
+    if (typeof message === "string" && message.length > 0) return message;
+  }
+  return "Postgres query failed";
+}
+
+function readDriverString(row: Record<string, unknown>, key: string): string | undefined {
+  const value = row[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function readDriverErrno(row: Record<string, unknown>): string | number | undefined {
+  const value = row.errno;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.length > 0) return value;
+  return undefined;
+}
+
+/**
+ * Await a Bun.SQL call. Non-Error rejections become {@link PostgresDriverError}.
+ *
+ * @param query - Driver promise
+ */
+async function settlePostgres<T>(query: PromiseLike<T>): Promise<T> {
+  try {
+    return await query;
+  } catch (err) {
+    if (err instanceof Error) throw err;
+    throw new PostgresDriverError(err);
+  }
+}
+
 /**
  * Resolve the Postgres URL (injected, `DATABASE_URL`, then localhost).
  *
@@ -270,14 +344,14 @@ export async function withPinnedPostgres<T>(
   if (typeof client.reserve === "function") {
     const reserved = await client.reserve();
     try {
-      await reserved.unsafe("BEGIN");
+      await settlePostgres(reserved.unsafe("BEGIN"));
       try {
         const result = await fn(reserved);
-        await reserved.unsafe("COMMIT");
+        await settlePostgres(reserved.unsafe("COMMIT"));
         return result;
       } catch (err) {
         try {
-          await reserved.unsafe("ROLLBACK");
+          await settlePostgres(reserved.unsafe("ROLLBACK"));
         } catch {
           // Already aborted.
         }
@@ -365,14 +439,14 @@ function wrapPostgresClient(
       // Shared wrappers outlive pause — fail soft before Bun.SQL reconnects.
       if (opts.shared) assertSharedPostgresReady();
       const pg = toPostgresParams(sql, params);
-      const result = await client.unsafe(pg, [...params]);
+      const result = await settlePostgres(client.unsafe(pg, [...params]));
       if (Array.isArray(result)) return result as SqlRow[];
       return Array.from(result as ArrayLike<SqlRow>);
     },
     async exec(sql, params = []) {
       if (opts.shared) assertSharedPostgresReady();
       const pg = toPostgresParams(sql, params);
-      const result = await client.unsafe(pg, [...params]);
+      const result = await settlePostgres(client.unsafe(pg, [...params]));
       if (
         result &&
         typeof result === "object" &&

package/src/drivers/signal-compete.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Two consumers, one bus: postgres SKIP LOCKED and redis consumer groups.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { signal } from "../elements/signal.ts";
+import {
+  openPostgresChannelLedger,
+  type ChannelLedgerSql,
+} from "../elements/channel/sql-ledger.ts";
+import { createPostgresSignalFake, openPostgresSignal } from "./signal-postgres.ts";
+import {
+  createBunSignalRedisClient,
+  createSignalRedisFake,
+  openRedisSignal,
+  SIGNAL_REDIS_MIN_IDLE_MS,
+} from "./signal-redis.ts";
+
+function decls(name: string, retries = 3) {
+  const decl = signal.once(name, { retries, deadLetter: true });
+  return new Map([[decl.name, decl]]);
+}
+
+describe("postgres signal competing consumers", () => {
+  test("one message is delivered once across two buses", async () => {
+    const sql = createPostgresSignalFake();
+    const name = "order-placed";
+    const a = await openPostgresSignal({ signals: decls(name), sql });
+    const b = await openPostgresSignal({ signals: decls(name), sql });
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      got.push("a");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await Bun.sleep(5);
+    await a.drain();
+    await b.drain();
+    expect(got).toHaveLength(1);
+    await a.close();
+    await b.close();
+  });
+});
+
+describe("redis streams competing consumers", () => {
+  test("one message is delivered once across two groups", async () => {
+    const redis = createSignalRedisFake();
+    const name = "order-placed";
+    const shared = { signals: decls(name), redis, compete: true as const };
+    const a = await openRedisSignal({ ...shared, consumerId: "a" });
+    const b = await openRedisSignal({ ...shared, consumerId: "b" });
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      got.push("a");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await a.drain();
+    await b.drain();
+    expect(got).toHaveLength(1);
+    await a.close();
+    await b.close();
+  });
+
+  test("a failed handler leaves the entry pending for redelivery", async () => {
+    const redis = createSignalRedisFake();
+    const name = "flaky";
+    const bus = await openRedisSignal({
+      signals: decls(name, 2),
+      redis,
+      compete: true,
+      consumerId: "a",
+    });
+    let calls = 0;
+    await bus.subscribe(name, "a", async () => {
+      calls += 1;
+      if (calls === 1) throw new Error("boom");
+    });
+    await bus.emit(name, { id: "1" });
+    await bus.drain();
+    expect(calls).toBe(1);
+    await bus.drain();
+    expect(calls).toBe(2);
+    await bus.close();
+  });
+
+  test("another consumer reclaims an unacked entry", async () => {
+    let nowMs = 0;
+    const now = () => nowMs;
+    const redis = createSignalRedisFake({ now });
+    const name = "handoff";
+    const shared = { signals: decls(name, 3), redis, compete: true as const, now };
+    const a = await openRedisSignal({ ...shared, consumerId: "a" });
+    const b = await openRedisSignal({ ...shared, consumerId: "b" });
+    let aCalls = 0;
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      aCalls += 1;
+      throw new Error("down");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await a.drain();
+    nowMs += SIGNAL_REDIS_MIN_IDLE_MS;
+    await b.drain();
+    expect(aCalls).toBe(1);
+    expect(got).toEqual(["b"]);
+    await a.close();
+    await b.close();
+  });
+
+  test.skipIf(!process.env.REDIS_URL)("REDIS_URL: two clients ack once", async () => {
+    const url = process.env.REDIS_URL;
+    const name = `oke-compete-${Date.now()}`;
+    const redisA = createBunSignalRedisClient(url);
+    const redisB = createBunSignalRedisClient(url);
+    const a = await openRedisSignal({
+      signals: decls(name),
+      redis: redisA,
+      compete: true,
+      consumerId: "a",
+    });
+    const b = await openRedisSignal({
+      signals: decls(name),
+      redis: redisB,
+      compete: true,
+      consumerId: "b",
+    });
+    const got: string[] = [];
+    await a.subscribe(name, "a", async () => {
+      got.push("a");
+    });
+    await b.subscribe(name, "b", async () => {
+      got.push("b");
+    });
+    await a.emit(name, { id: "1" });
+    await a.drain();
+    await b.drain();
+    expect(got).toHaveLength(1);
+    await a.close();
+    await b.close();
+  });
+});
+
+function memoryLedgerSql(): ChannelLedgerSql {
+  const consent = new Map<string, { subject: string; medium: string; at: number }>();
+  const bounce = new Map<string, { subject: string; medium: string; at: number }>();
+  const receipts = new Map<string, string>();
+
+  function pair(params: readonly unknown[]): string {
+    return `${String(params[0])}\0${String(params[1])}`;
+  }
+
+  return {
+    async query(sql) {
+      if (sql.includes("oke_channel_consent")) {
+        return [...consent.values()];
+      }
+      if (sql.includes("oke_channel_bounce")) {
+        return [...bounce.values()];
+      }
+      if (sql.includes("oke_channel_receipt")) {
+        return [...receipts.entries()].map(([id, body]) => ({ id, body }));
+      }
+      return [];
+    },
+    async exec(sql, params = []) {
+      if (sql.startsWith("CREATE")) return { changes: 0 };
+      if (sql.includes("INSERT INTO oke_channel_consent")) {
+        consent.set(pair(params), {
+          subject: String(params[0]),
+          medium: String(params[1]),
+          at: Number(params[2]),
+        });
+        return { changes: 1 };
+      }
+      if (sql.includes("DELETE FROM oke_channel_consent")) {
+        consent.delete(pair(params));
+        return { changes: 1 };
+      }
+      if (sql.includes("INSERT INTO oke_channel_bounce")) {
+        bounce.set(pair(params), {
+          subject: String(params[0]),
+          medium: String(params[1]),
+          at: Number(params[2]),
+        });
+        return { changes: 1 };
+      }
+      if (sql.includes("DELETE FROM oke_channel_bounce")) {
+        bounce.delete(pair(params));
+        return { changes: 1 };
+      }
+      if (sql.includes("INSERT INTO oke_channel_receipt")) {
+        receipts.set(String(params[0]), String(params[1]));
+        return { changes: 1 };
+      }
+      if (sql.includes("UPDATE oke_channel_receipt")) {
+        receipts.set(String(params[1]), String(params[0]));
+        return { changes: 1 };
+      }
+      return { changes: 0 };
+    },
+  };
+}
+
+describe("channel ledger across instances", () => {
+  test("consent and suppression written on A are visible to B", async () => {
+    const sql = memoryLedgerSql();
+    const a = await openPostgresChannelLedger(sql);
+    const b = await openPostgresChannelLedger(sql);
+    a.suppression.optOut("a@b.c", "email");
+    a.suppression.addPriorBounce("c@d.e", "sms");
+    a.receipts.record({
+      id: "r1",
+      template: "note",
+      to: "a@b.c",
+      medium: "email",
+      status: "sent",
+      attempts: [],
+      at: 1,
+    });
+    await a.flush();
+    await b.reload();
+    expect(b.consent.isOptedOut("a@b.c", "email")).toBe(true);
+    expect(b.suppression.isSuppressed("c@d.e", "sms")).toEqual({
+      suppressed: true,
+      reason: "prior-bounce",
+    });
+    expect(b.receipts.all()).toHaveLength(1);
+    expect(b.receipts.all()[0]?.id).toBe("r1");
+  });
+});

package/src/drivers/signal-postgres.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Postgres broadcast/live fan-out: shared table, per-instance cursor.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { signal } from "../elements/signal.ts";
+import type { SignalDecl } from "../elements/signal/declare.ts";
+import {
+  POSTGRES_SIGNAL_FANOUT_SQL,
+  createPostgresSignalFake,
+  openPostgresSignal,
+  postgresSignalFakeBranches,
+} from "./signal-postgres.ts";
+
+const legacyInsert = `INSERT INTO oke_signal_messages (id, signal, payload, ordering_key, delivery, attempts, failures, created_at, available_at, status, locked_by, lease_expires_at, delivered_to, parent_run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+
+async function expectRejects(pending: Promise<unknown>, message: string): Promise<void> {
+  let err: unknown;
+  try {
+    await pending;
+  } catch (caught) {
+    err = caught;
+  }
+  if (!(err instanceof Error)) {
+    throw new Error("expected the statement to throw");
+  }
+  expect(err.message).toContain(message);
+}
+
+describe("postgres signal fake SQL branches", () => {
+  test("an unmatched statement throws", async () => {
+    const sql = createPostgresSignalFake();
+    await expectRejects(sql.query("SELECT 1"), "unsupported query");
+    await expectRejects(sql.exec("VACUUM oke_signal_messages"), "unsupported exec");
+  });
+
+  test("broadcast/live statements each hit exactly one branch", async () => {
+    const sql = createPostgresSignalFake({ now: () => 4_200 });
+    expect(postgresSignalFakeBranches(POSTGRES_SIGNAL_FANOUT_SQL.insert)).toEqual(["insert-db-at"]);
+    expect(postgresSignalFakeBranches(POSTGRES_SIGNAL_FANOUT_SQL.poll)).toEqual(["fanout-poll"]);
+    expect(postgresSignalFakeBranches(POSTGRES_SIGNAL_FANOUT_SQL.backfill)).toEqual([
+      "backfill-db-at",
+    ]);
+    expect(postgresSignalFakeBranches(POSTGRES_SIGNAL_FANOUT_SQL.index)).toEqual([
+      "index-delivery-db-at",
+    ]);
+    expect(postgresSignalFakeBranches(legacyInsert)).toEqual(["insert-message"]);
+
+    await sql.exec(legacyInsert, [
+      "old",
+      "s",
+      "null",
+      null,
+      "broadcast",
+      0,
+      "[]",
+      50,
+      50,
+      "pending",
+      null,
+      null,
+      "[]",
+      null,
+    ]);
+    await sql.exec(POSTGRES_SIGNAL_FANOUT_SQL.backfill);
+    await sql.exec(POSTGRES_SIGNAL_FANOUT_SQL.index);
+    await sql.exec(POSTGRES_SIGNAL_FANOUT_SQL.insert, [
+      "new",
+      "s",
+      "null",
+      null,
+      "broadcast",
+      0,
+      "[]",
+      1,
+      1,
+      "pending",
+      null,
+      null,
+      "[]",
+      null,
+    ]);
+
+    const rows = await sql.query(POSTGRES_SIGNAL_FANOUT_SQL.poll, [0]);
+    expect(rows.find((row) => row.id === "old")?.db_at).toBe(50);
+    const fresh = rows.find((row) => row.id === "new");
+    expect(fresh?.db_at).toBe(4_200);
+    expect(fresh?.db_now).toBe(4_200);
+  });
+});
+
+describe("postgres broadcast and live fan-out", () => {
+  test("a broadcast and a live message on A reach B", async () => {
+    const sql = createPostgresSignalFake();
+    const news = signal.broadcast("news");
+    const feed = signal.live("feed", { optional: true });
+    const signals = new Map<string, SignalDecl>([
+      [news.name, news],
+      [feed.name, feed],
+    ]);
+    const a = await openPostgresSignal({ signals, sql });
+    const b = await openPostgresSignal({ signals, sql });
+    const got: string[] = [];
+    await a.subscribe("news", "a", async () => {
+      got.push("a");
+    });
+    await b.subscribe("news", "b", async () => {
+      got.push("b");
+    });
+
+    const iterA = a.live("feed")[Symbol.asyncIterator]();
+    const iterB = b.live("feed")[Symbol.asyncIterator]();
+    const nextA = iterA.next();
+    const nextB = iterB.next();
+    await Bun.sleep(10);
+
+    await a.emit("news", { id: "1" });
+    await a.emit("feed", { n: 1 });
+    await a.drain();
+    await b.drain();
+
+    expect(got.slice().sort()).toEqual(["a", "b"]);
+    const [liveA, liveB] = await Promise.all([nextA, nextB]);
+    expect(liveA.value?.payload).toEqual({ n: 1 });
+    expect(liveB.value?.payload).toEqual({ n: 1 });
+    await iterA.return?.();
+    await iterB.return?.();
+    await a.close();
+    await b.close();
+  });
+
+  test("cursor starts at head so a row written before boot is not delivered", async () => {
+    let t = 5_000;
+    const sql = createPostgresSignalFake({ now: () => t });
+    const news = signal.broadcast("news", { optional: true });
+    const signals = new Map<string, SignalDecl>([[news.name, news]]);
+    const writer = await openPostgresSignal({ signals, sql, lagMs: 30_000 });
+    await writer.emit("news", { n: 1 });
+    await writer.close();
+
+    t = 6_000;
+    const reader = await openPostgresSignal({ signals, sql, lagMs: 30_000 });
+    const got: unknown[] = [];
+    await reader.subscribe("news", "b", async (message) => {
+      got.push(message.payload);
+    });
+    await reader.drain();
+    expect(got).toEqual([]);
+    await reader.close();
+  });
+
+  test("lagMs dedupes the same id across overlapping polls", async () => {
+    let t = 10_000;
+    const sql = createPostgresSignalFake({ now: () => t });
+    const news = signal.broadcast("news");
+    const signals = new Map<string, SignalDecl>([[news.name, news]]);
+    const bus = await openPostgresSignal({ signals, sql, lagMs: 30_000 });
+    const got: unknown[] = [];
+    await bus.subscribe("news", "a", async (message) => {
+      got.push(message.payload);
+    });
+    await bus.emit("news", { n: 1 });
+    t = 15_000;
+    await bus.drain();
+    t = 20_000;
+    await bus.drain();
+    expect(got).toEqual([{ n: 1 }]);
+    await bus.close();
+  });
+});