okengine 0.6.0 → 0.7.0

package/src/elements/signal/key-ordering.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Per-key serialization for `once` — same (signal, key) never claimed
+ * concurrently; emission order preserved; lease reclaim is the unlock.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  createPostgresSignalFake,
+  memorySignalDriver,
+  postgresSignalDriver,
+  type SignalBus,
+} from "../../drivers/index.ts";
+import { signal } from "./declare.ts";
+import { createSignalRuntime } from "./runtime.ts";
+
+const openBuses: SignalBus[] = [];
+const closers: Array<{ close(): Promise<void> }> = [];
+
+afterEach(async () => {
+  while (openBuses.length) {
+    await openBuses.pop()!.close();
+  }
+  while (closers.length) {
+    await closers.pop()!.close();
+  }
+});
+
+describe("signal key ordering · memory", () => {
+  test("same key: never concurrent; complete in emission order", async () => {
+    const once = signal("order-events", {
+      delivery: "once",
+      retries: 3,
+      deadLetter: true,
+    });
+    const bus = await memorySignalDriver.open({
+      signals: new Map([[once.name, once]]),
+    });
+    openBuses.push(bus);
+
+    let inflight = 0;
+    let maxInflight = 0;
+    const completed: number[] = [];
+    const started = Promise.withResolvers<void>();
+    let startedCount = 0;
+
+    const handler = async (m: { payload: unknown }) => {
+      inflight += 1;
+      maxInflight = Math.max(maxInflight, inflight);
+      startedCount += 1;
+      if (startedCount === 1) started.resolve();
+      // Hold long enough for a concurrent drain to attempt the sibling.
+      await Bun.sleep(40);
+      completed.push((m.payload as { seq: number }).seq);
+      inflight -= 1;
+    };
+
+    await bus.subscribe("order-events", "worker-a", handler);
+    await bus.subscribe("order-events", "worker-b", handler);
+
+    await bus.emit("order-events", { seq: 1 }, { key: "ord_42" });
+    await bus.emit("order-events", { seq: 2 }, { key: "ord_42" });
+
+    // Concurrent drains: without key locking both messages would be inflight.
+    const d1 = bus.drain();
+    const d2 = bus.drain();
+    await started.promise;
+    await Promise.all([d1, d2]);
+
+    expect(maxInflight).toBe(1);
+    expect(completed).toEqual([1, 2]);
+  });
+
+  test("different keys: may process concurrently", async () => {
+    const once = signal("order-events", {
+      delivery: "once",
+      retries: 3,
+      deadLetter: true,
+    });
+    const bus = await memorySignalDriver.open({
+      signals: new Map([[once.name, once]]),
+    });
+    openBuses.push(bus);
+
+    let inflight = 0;
+    let maxInflight = 0;
+    const gate = Promise.withResolvers<void>();
+    let waiting = 0;
+
+    const handler = async () => {
+      inflight += 1;
+      maxInflight = Math.max(maxInflight, inflight);
+      waiting += 1;
+      if (waiting === 2) gate.resolve();
+      await gate.promise;
+      inflight -= 1;
+    };
+
+    await bus.subscribe("order-events", "worker-a", handler);
+    await bus.subscribe("order-events", "worker-b", handler);
+
+    await bus.emit("order-events", { seq: 1 }, { key: "ord_a" });
+    await bus.emit("order-events", { seq: 2 }, { key: "ord_b" });
+
+    await Promise.all([bus.drain(), bus.drain()]);
+    expect(maxInflight).toBe(2);
+  });
+
+  test("no key: unchanged competing-consumer (both may run concurrent)", async () => {
+    const once = signal("order-events", {
+      delivery: "once",
+      retries: 3,
+      deadLetter: true,
+    });
+    const bus = await memorySignalDriver.open({
+      signals: new Map([[once.name, once]]),
+    });
+    openBuses.push(bus);
+
+    let inflight = 0;
+    let maxInflight = 0;
+    const gate = Promise.withResolvers<void>();
+    let waiting = 0;
+
+    const handler = async () => {
+      inflight += 1;
+      maxInflight = Math.max(maxInflight, inflight);
+      waiting += 1;
+      if (waiting === 2) gate.resolve();
+      await gate.promise;
+      inflight -= 1;
+    };
+
+    await bus.subscribe("order-events", "worker-a", handler);
+    await bus.subscribe("order-events", "worker-b", handler);
+
+    await bus.emit("order-events", { seq: 1 });
+    await bus.emit("order-events", { seq: 2 });
+
+    await Promise.all([bus.drain(), bus.drain()]);
+    expect(maxInflight).toBe(2);
+  });
+});
+
+describe("signal key ordering · postgres", () => {
+  test("same-key pending blocked while sibling holds unexpired lease", async () => {
+    let t = 10_000;
+    const once = signal("order-events", { delivery: "once", retries: 3 });
+    const sql = createPostgresSignalFake({ now: () => t });
+    const runtime = createSignalRuntime({
+      driver: postgresSignalDriver,
+      sql,
+      now: () => t,
+      leaseMs: 50,
+    });
+    closers.push(runtime);
+    runtime.register(once);
+    const bus = await runtime.start();
+
+    // msg1 holds the key via message-level lease; msg2 is pending same key.
+    await sql.exec(
+      `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) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        "m1",
+        "order-events",
+        JSON.stringify({ seq: 1 }),
+        "ord_42",
+        "once",
+        1,
+        "[]",
+        t - 2_000,
+        t - 2_000,
+        "inflight",
+        "dead-worker",
+        t + 1_000,
+        "[]",
+      ],
+    );
+    await sql.exec(
+      `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) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        "m2",
+        "order-events",
+        JSON.stringify({ seq: 2 }),
+        "ord_42",
+        "once",
+        0,
+        "[]",
+        t - 1_000,
+        t - 1_000,
+        "pending",
+        null,
+        null,
+        "[]",
+      ],
+    );
+
+    const got: number[] = [];
+    await bus.subscribe("order-events", "rescue", async (m) => {
+      got.push((m.payload as { seq: number }).seq);
+    });
+
+    await bus.drain();
+    expect(got).toEqual([]);
+
+    // Same lease clock unlocks the key — no second timeout system.
+    t = 10_000 + 1_001;
+    await bus.drain();
+    expect(got).toEqual([1, 2]);
+  });
+
+  test("emit with key then drain preserves emission order", async () => {
+    const once = signal("order-events", {
+      delivery: "once",
+      retries: 3,
+      deadLetter: true,
+    });
+    const bus = await postgresSignalDriver.open({
+      signals: new Map([[once.name, once]]),
+      sql: createPostgresSignalFake(),
+    });
+    openBuses.push(bus);
+
+    const completed: number[] = [];
+    await bus.subscribe("order-events", "worker-a", async (m) => {
+      completed.push((m.payload as { seq: number }).seq);
+    });
+    await bus.subscribe("order-events", "worker-b", async (m) => {
+      completed.push((m.payload as { seq: number }).seq);
+    });
+
+    await bus.emit("order-events", { seq: 1 }, { key: "ord_42" });
+    await bus.emit("order-events", { seq: 2 }, { key: "ord_42" });
+    await bus.drain();
+    expect(completed).toEqual([1, 2]);
+  });
+});
+
+describe("signal key ordering · lease reclaim", () => {
+  test("memory: expired same-key inflight reclaims; successor then runs", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-key-lease-"));
+    const durablePath = join(dir, "bus.json");
+    const marker = join(dir, "claimed");
+    try {
+      let t = 5_000;
+      const once = signal("order-events", {
+        delivery: "once",
+        retries: 3,
+        deadLetter: true,
+      });
+      const r1 = createSignalRuntime({
+        driver: memorySignalDriver,
+        durablePath,
+        now: () => t,
+        leaseMs: 50,
+      });
+      closers.push(r1);
+      r1.register(once);
+      const b1 = await r1.start();
+
+      await b1.subscribe("order-events", "slow", async (m) => {
+        if ((m.payload as { seq: number }).seq === 1) {
+          await Bun.write(marker, "1");
+          await Bun.sleep(60_000);
+        }
+      });
+
+      await b1.emit("order-events", { seq: 1 }, { key: "ord_42" });
+      await b1.emit("order-events", { seq: 2 }, { key: "ord_42" });
+
+      const drainPromise = b1.drain();
+      for (let i = 0; i < 80; i++) {
+        if (await Bun.file(marker).exists()) break;
+        await Bun.sleep(5);
+      }
+      expect(await Bun.file(marker).exists()).toBe(true);
+
+      // Crash while holding the key lock (message-level lease).
+      await r1.close();
+      void drainPromise.catch(() => {});
+      closers.pop();
+
+      t = 5_000 + 100; // past leaseMs — same reclaim clock as unkeyed once
+      const r2 = createSignalRuntime({
+        driver: memorySignalDriver,
+        durablePath,
+        now: () => t,
+        leaseMs: 50,
+      });
+      closers.push(r2);
+      r2.register(once);
+      const b2 = await r2.start();
+      const got: number[] = [];
+      await b2.subscribe("order-events", "rescue", async (m) => {
+        got.push((m.payload as { seq: number }).seq);
+      });
+      await b2.drain();
+      expect(got).toEqual([1, 2]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/elements/signal/lease-reclaim.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Lazy lease reclaim at claim time — no background sweeper.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  createPostgresSignalFake,
+  memorySignalDriver,
+  postgresSignalDriver,
+} from "../../drivers/index.ts";
+import { signal } from "./declare.ts";
+import { createSignalRuntime } from "./runtime.ts";
+
+const closers: Array<{ close(): Promise<void> }> = [];
+
+afterEach(async () => {
+  while (closers.length) {
+    await closers.pop()!.close();
+  }
+});
+
+describe("signal lease reclaim", () => {
+  test("memory: expired inflight is reclaimed at next claim after crash", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-lease-"));
+    const durablePath = join(dir, "bus.json");
+    const marker = join(dir, "claimed");
+    try {
+      let t = 5_000;
+      const once = signal("order-placed", {
+        delivery: "once",
+        retries: 3,
+        deadLetter: true,
+      });
+      const r1 = createSignalRuntime({
+        driver: memorySignalDriver,
+        durablePath,
+        now: () => t,
+        leaseMs: 50,
+      });
+      closers.push(r1);
+      r1.register(once);
+      const b1 = await r1.start();
+      await b1.subscribe("order-placed", "slow", async () => {
+        await Bun.write(marker, "1");
+        await Bun.sleep(60_000);
+      });
+      await b1.emit("order-placed", { n: 42 });
+      const drainPromise = b1.drain();
+      for (let i = 0; i < 80; i++) {
+        if (await Bun.file(marker).exists()) break;
+        await Bun.sleep(5);
+      }
+      expect(await Bun.file(marker).exists()).toBe(true);
+      // Strand the inflight claim (persisted before handler) by closing the bus.
+      await r1.close();
+      void drainPromise.catch(() => {});
+      closers.pop();
+
+      t = 5_000 + 100; // past leaseMs
+      const r2 = createSignalRuntime({
+        driver: memorySignalDriver,
+        durablePath,
+        now: () => t,
+        leaseMs: 50,
+      });
+      closers.push(r2);
+      r2.register(once);
+      const b2 = await r2.start();
+      const got: unknown[] = [];
+      await b2.subscribe("order-placed", "rescue", async (m) => {
+        got.push(m.payload);
+      });
+      await b2.drain();
+      expect(got).toEqual([{ n: 42 }]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("postgres: expired inflight reclaimed in the same claim query", async () => {
+    let t = 10_000;
+    const once = signal("order-placed", { delivery: "once", retries: 3 });
+    const sql = createPostgresSignalFake({ now: () => t });
+    const runtime = createSignalRuntime({
+      driver: postgresSignalDriver,
+      sql,
+      now: () => t,
+      leaseMs: 50,
+    });
+    closers.push(runtime);
+    runtime.register(once);
+    const bus = await runtime.start();
+
+    await sql.exec(
+      `INSERT INTO oke_signal_messages (id, signal, payload, delivery, attempts, failures, created_at, available_at, status, locked_by, lease_expires_at, delivered_to) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        "stranded-1",
+        "order-placed",
+        JSON.stringify({ id: "stranded" }),
+        "once",
+        1,
+        "[]",
+        t - 1_000,
+        t - 1_000,
+        "inflight",
+        "dead-worker",
+        t - 1,
+        "[]",
+      ],
+    );
+
+    const got: unknown[] = [];
+    await bus.subscribe("order-placed", "rescue", async (m) => {
+      got.push(m.payload);
+    });
+    await bus.drain();
+    expect(got).toEqual([{ id: "stranded" }]);
+  });
+});

package/src/elements/signal/optional-emit.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Zero-subscriber emit — OKE1042 when optional is unset/false; allow when true.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  createPostgresSignalFake,
+  memorySignalDriver,
+  postgresSignalDriver,
+  type SignalBus,
+  type SignalDriver,
+} from "../../drivers/index.ts";
+import { OkeError } from "../../kernel/errors.ts";
+import { signal, type SignalDecl } from "./declare.ts";
+
+const openBuses: SignalBus[] = [];
+
+afterEach(async () => {
+  while (openBuses.length) {
+    await openBuses.pop()!.close();
+  }
+});
+
+async function openBus(
+  driver: SignalDriver,
+  decls: readonly SignalDecl[],
+  extra: Record<string, unknown> = {},
+): Promise<SignalBus> {
+  const bus = await driver.open({
+    signals: new Map(decls.map((d) => [d.name, d])),
+    ...extra,
+  });
+  openBuses.push(bus);
+  return bus;
+}
+
+for (const { label, driver, setup } of [
+  { label: "memory", driver: memorySignalDriver, setup: () => ({}) },
+  {
+    label: "postgres",
+    driver: postgresSignalDriver,
+    setup: () => ({ sql: createPostgresSignalFake() }),
+  },
+] as const) {
+  describe(`signal optional emit · ${label}`, () => {
+    test("optional unset/false: emit with zero subscribers throws OKE1042", async () => {
+      const once = signal("order-placed", { delivery: "once" });
+      expect(once.optional).toBe(false);
+      const bus = await openBus(driver, [once], setup());
+
+      let err: unknown;
+      try {
+        await bus.emit("order-placed", { id: "1" });
+      } catch (e) {
+        err = e;
+      }
+      expect(err).toBeInstanceOf(OkeError);
+      expect((err as OkeError).code).toBe(1042);
+      expect((err as Error).message).toContain("OKE1042");
+      expect((err as Error).message).toContain("no subscriber");
+    });
+
+    test("optional: true allows emit with zero subscribers", async () => {
+      const once = signal("hook", {
+        delivery: "once",
+        optional: true,
+      });
+      const bus = await openBus(driver, [once], setup());
+      await bus.emit("hook", { ok: true });
+      await bus.drain();
+      const stats = await bus.inspect("hook");
+      expect(stats[0]?.pending).toBe(1);
+    });
+  });
+}

package/src/elements/signal/order-lifecycle.test.ts

@@ -0,0 +1,130 @@
+/**
+ * One order domain — all three delivery modes together.
+ *
+ * Teaching scenario (mirrored on the Signal docs page):
+ * - `once`        order-placed   → competing fulfillment workers (+ retry/DLQ)
+ * - `broadcast`   order-changed  → cache invalidation AND notification (fan-out)
+ * - `live`        order-status   → client-visible feed via bus.live() replay
+ *
+ * Exclusive claim / retries / DLQ / live replay physics are proven in
+ * delivery-modes.test.ts; this file only asserts the coherent wiring.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { memorySignalDriver, type SignalBus } from "../../drivers/index.ts";
+import { signal } from "./declare.ts";
+
+const openBuses: SignalBus[] = [];
+
+afterEach(async () => {
+  while (openBuses.length) {
+    await openBuses.pop()!.close();
+  }
+});
+
+describe("signal order lifecycle · once + broadcast + live", () => {
+  test("one placed order: exclusive fulfill, fan-out side effects, live status replay", async () => {
+    // once — queued job: exactly one competing consumer fulfills
+    const orderPlaced = signal("order-placed", {
+      delivery: "once",
+      retries: 2,
+      deadLetter: true,
+    });
+    // broadcast — same domain event fan-out: every subscriber gets a copy
+    const orderChanged = signal("order-changed", {
+      delivery: "broadcast",
+    });
+    // live — client-visible status feed (bus.live; createClient has no subscribe yet)
+    const orderStatus = signal("order-status", {
+      delivery: "live",
+      optional: true,
+    });
+
+    const bus = await memorySignalDriver.open({
+      signals: new Map([
+        [orderPlaced.name, orderPlaced],
+        [orderChanged.name, orderChanged],
+        [orderStatus.name, orderStatus],
+      ]),
+    });
+    openBuses.push(bus);
+
+    const fulfilled: string[] = [];
+    const cacheHits: string[] = [];
+    const notifyHits: string[] = [];
+
+    await bus.subscribe("order-placed", "fulfillment-a", async (m) => {
+      const { orderId } = m.payload as { orderId: string };
+      fulfilled.push(`a:${orderId}`);
+      await bus.emit("order-changed", { orderId, kind: "placed" });
+      await bus.emit("order-status", { orderId, status: "fulfilling" });
+      await bus.emit("order-status", { orderId, status: "shipped" });
+    });
+    await bus.subscribe("order-placed", "fulfillment-b", async (m) => {
+      const { orderId } = m.payload as { orderId: string };
+      fulfilled.push(`b:${orderId}`);
+      await bus.emit("order-changed", { orderId, kind: "placed" });
+      await bus.emit("order-status", { orderId, status: "fulfilling" });
+      await bus.emit("order-status", { orderId, status: "shipped" });
+    });
+
+    await bus.subscribe("order-changed", "cache-invalidate", async (m) => {
+      cacheHits.push((m.payload as { orderId: string }).orderId);
+    });
+    await bus.subscribe("order-changed", "notify-customer", async (m) => {
+      notifyHits.push((m.payload as { orderId: string }).orderId);
+    });
+
+    await bus.emit("order-placed", { orderId: "ord_42", total: 49.5 });
+    await bus.emit("order-status", { orderId: "ord_42", status: "placed" });
+    await bus.drain();
+
+    // once: exactly one competing worker claimed the job
+    expect(fulfilled).toHaveLength(1);
+    expect(fulfilled[0] === "a:ord_42" || fulfilled[0] === "b:ord_42").toBe(true);
+
+    // broadcast: both independent subscribers received the fan-out
+    expect(cacheHits).toEqual(["ord_42"]);
+    expect(notifyHits).toEqual(["ord_42"]);
+
+    // live: late subscriber replays the full retained status history
+    const feed: Array<{ orderId: string; status: string }> = [];
+    await bus.live("order-status", (payload) => {
+      feed.push(payload as { orderId: string; status: string });
+    });
+    expect(feed).toEqual([
+      { orderId: "ord_42", status: "placed" },
+      { orderId: "ord_42", status: "fulfilling" },
+      { orderId: "ord_42", status: "shipped" },
+    ]);
+  });
+
+  test("once retries then DLQ still apply inside the same domain", async () => {
+    // Light reuse of once retry/DLQ — full matrix lives in delivery-modes.test.ts.
+    const orderPlaced = signal("order-placed", {
+      delivery: "once",
+      retries: 1,
+      deadLetter: true,
+    });
+    const bus = await memorySignalDriver.open({
+      signals: new Map([[orderPlaced.name, orderPlaced]]),
+    });
+    openBuses.push(bus);
+
+    let attempts = 0;
+    await bus.subscribe("order-placed", "fulfillment", async () => {
+      attempts += 1;
+      throw new Error(`payment-gateway-${attempts}`);
+    });
+
+    await bus.emit("order-placed", { orderId: "ord_fail" });
+    await bus.drain();
+
+    expect(attempts).toBe(2); // retries + 1
+    const dlq = await bus.deadLetters("order-placed");
+    expect(dlq).toHaveLength(1);
+    expect(dlq[0]!.payload).toEqual({ orderId: "ord_fail" });
+    expect(dlq[0]!.failures.map((f) => f.attempt)).toEqual([1, 2]);
+  });
+});