okengine 0.6.1 → 0.7.0

package/src/drivers/signal-engine.ts

@@ -11,21 +11,25 @@ import { dirname } from "node:path";
 import type { SignalDecl } from "../elements/signal/declare.ts";
 import type { SignalDelivery } from "../manifest/types.ts";
 import { DryRunWriteIsolationError, setDryRunMessageId, withDryRun } from "../kernel/dry-run.ts";
-import type {
-  DeadLetter,
-  LiveHandler,
-  SignalBus,
-  SignalDiscardOptions,
-  SignalDriverId,
-  SignalFailureReason,
-  SignalHandler,
-  SignalMessage,
-  SignalOpenOptions,
-  SignalReplayOptions,
-  SignalReplayResult,
-  SignalStats,
-  SignalTransaction,
-  SignalUnsubscribe,
+import { OkeError, OKE_ERRORS } from "../kernel/errors.ts";
+import {
+  SIGNAL_DEFAULT_LEASE_MS,
+  validateSignalEmitPayload,
+  type DeadLetter,
+  type LiveHandler,
+  type SignalBus,
+  type SignalDiscardOptions,
+  type SignalDriverId,
+  type SignalEmitOptions,
+  type SignalFailureReason,
+  type SignalHandler,
+  type SignalMessage,
+  type SignalOpenOptions,
+  type SignalReplayOptions,
+  type SignalReplayResult,
+  type SignalStats,
+  type SignalTransaction,
+  type SignalUnsubscribe,
 } from "./signal-types.ts";
 
 /** Internal mutable message. */
@@ -33,6 +37,8 @@ interface MutMessage {
   id: string;
   signal: string;
   payload: unknown;
+  /** Optional per-key ordering token (`once` serialization). */
+  key: string | null;
   delivery: SignalDelivery;
   attempts: number;
   failures: SignalFailureReason[];
@@ -41,6 +47,8 @@ interface MutMessage {
   status: "pending" | "inflight" | "delivered" | "dead";
   /** For once: which consumer holds the claim. */
   lockedBy: string | null;
+  /** For once: when the claim lease expires (epoch ms); null when unlocked. */
+  leaseExpiresAt: number | null;
   /** For broadcast: subscriber ids that already received. */
   deliveredTo: Set<string>;
 }
@@ -48,9 +56,10 @@ interface MutMessage {
 /** Persisted snapshot for chaos recovery. */
 interface Snapshot {
   messages: Array<
-    Omit<MutMessage, "deliveredTo" | "lockedBy"> & {
+    Omit<MutMessage, "deliveredTo" | "lockedBy" | "leaseExpiresAt"> & {
       deliveredTo: string[];
       lockedBy: string | null;
+      leaseExpiresAt: number | null;
     }
   >;
   writes: Array<[string, unknown]>;
@@ -76,6 +85,7 @@ export async function createSignalEngine(
   const now = options.now ?? (() => Date.now());
   const signals = options.signals;
   const durablePath = options.durablePath;
+  const leaseMs = options.leaseMs ?? SIGNAL_DEFAULT_LEASE_MS;
 
   let messages: MutMessage[] = [];
   let writes = new Map<string, unknown>();
@@ -152,7 +162,9 @@ export async function createSignalEngine(
     if (snap) {
       messages = snap.messages.map((m) => ({
         ...m,
+        key: m.key ?? null,
         lockedBy: m.lockedBy,
+        leaseExpiresAt: m.leaseExpiresAt ?? null,
         deliveredTo: new Set(m.deliveredTo),
       }));
       writes = new Map(snap.writes);
@@ -166,6 +178,7 @@ export async function createSignalEngine(
         id: m.id,
         signal: m.signal,
         payload: m.payload,
+        key: m.key,
         delivery: m.delivery,
         attempts: m.attempts,
         failures: m.failures,
@@ -173,6 +186,7 @@ export async function createSignalEngine(
         availableAt: m.availableAt,
         status: m.status,
         lockedBy: m.lockedBy,
+        leaseExpiresAt: m.leaseExpiresAt,
         deliveredTo: [...m.deliveredTo],
       })),
       writes: [...writes.entries()],
@@ -189,13 +203,38 @@ export async function createSignalEngine(
     return decl;
   }
 
-  function stageEmit(stagedMessages: MutMessage[], name: string, payload: unknown): void {
+  function hasSubscriber(name: string): boolean {
+    if (consumers.some((c) => c.signal === name)) return true;
+    const live = liveHandlers.get(name);
+    return live !== undefined && live.size > 0;
+  }
+
+  function assertEmitAllowed(name: string): void {
+    const decl = requireDecl(name);
+    if (decl.optional) return;
+    if (hasSubscriber(name)) return;
+    throw new OkeError(OKE_ERRORS.ORPHAN_EMIT, {
+      flow: "unknown",
+      resource: name,
+    });
+  }
+
+  async function stageEmit(
+    stagedMessages: MutMessage[],
+    name: string,
+    payload: unknown,
+    options?: SignalEmitOptions,
+  ): Promise<void> {
     const decl = requireDecl(name);
+    assertEmitAllowed(name);
+    const value = await validateSignalEmitPayload(name, decl, payload);
     const t = now();
+    const key = typeof options?.key === "string" && options.key.length > 0 ? options.key : null;
     stagedMessages.push({
       id: crypto.randomUUID(),
       signal: name,
-      payload: payload ?? null,
+      payload: value,
+      key,
       delivery: decl.delivery,
       attempts: 0,
       failures: [],
@@ -203,6 +242,7 @@ export async function createSignalEngine(
       availableAt: t,
       status: "pending",
       lockedBy: null,
+      leaseExpiresAt: null,
       deliveredTo: new Set(),
     });
   }
@@ -218,9 +258,9 @@ export async function createSignalEngine(
         if (done) throw new Error("transaction finished");
         stagedWrites.set(key, value);
       },
-      async emit(signal, payload) {
+      async emit(signal, payload, options) {
         if (done) throw new Error("transaction finished");
-        stageEmit(stagedMessages, signal, payload);
+        await stageEmit(stagedMessages, signal, payload, options);
       },
       async commit() {
         if (done) throw new Error("transaction finished");
@@ -240,9 +280,13 @@ export async function createSignalEngine(
     return Promise.resolve(tx);
   }
 
-  async function emit(signal: string, payload?: unknown): Promise<void> {
+  async function emit(
+    signal: string,
+    payload?: unknown,
+    options?: SignalEmitOptions,
+  ): Promise<void> {
     const tx = await begin();
-    await tx.emit(signal, payload);
+    await tx.emit(signal, payload, options);
     await tx.commit();
   }
 
@@ -287,6 +331,7 @@ export async function createSignalEngine(
       id: m.id,
       signal: m.signal,
       payload: m.payload,
+      ...(m.key !== null ? { key: m.key } : {}),
       delivery: m.delivery,
       attempts: m.attempts,
       failures: [...m.failures],
@@ -296,18 +341,40 @@ export async function createSignalEngine(
     };
   }
 
+  /** True when another same-(signal, key) message holds an unexpired lease. */
+  function keyHeldByOther(candidate: MutMessage, t: number): boolean {
+    if (candidate.key === null) return false;
+    return messages.some(
+      (other) =>
+        other !== candidate &&
+        other.signal === candidate.signal &&
+        other.key === candidate.key &&
+        other.status === "inflight" &&
+        other.leaseExpiresAt !== null &&
+        other.leaseExpiresAt > t,
+    );
+  }
+
   /**
-   * Claim the next `once` message with SKIP LOCKED semantics.
+   * Claim the next `once` message with SKIP LOCKED + lazy lease reclaim.
+   *
+   * Eligible: pending/unlocked, or inflight whose `leaseExpiresAt` has passed,
+   * and not blocked by a same-key unexpired inflight (per-key serialization).
+   * No background sweeper — reclaim happens only at claim time.
    */
   function claimOnce(signal: string, consumerId: string): MutMessage | null {
     const t = now();
     for (const m of messages) {
       if (m.signal !== signal || m.delivery !== "once") continue;
-      if (m.status !== "pending") continue;
       if (m.availableAt > t) continue;
-      if (m.lockedBy !== null) continue;
+      const pendingOk = m.status === "pending" && m.lockedBy === null;
+      const leaseExpired =
+        m.status === "inflight" && m.leaseExpiresAt !== null && m.leaseExpiresAt <= t;
+      if (!pendingOk && !leaseExpired) continue;
+      if (keyHeldByOther(m, t)) continue;
       m.status = "inflight";
       m.lockedBy = consumerId;
+      m.leaseExpiresAt = t + leaseMs;
       m.attempts += 1;
       return m;
     }
@@ -320,10 +387,12 @@ export async function createSignalEngine(
       await consumer.handler(toPublic(m));
       m.status = "delivered";
       m.lockedBy = null;
+      m.leaseExpiresAt = null;
       noteDelivered();
     } catch (err) {
       m.failures.push(failureFromError(err, m.attempts));
       m.lockedBy = null;
+      m.leaseExpiresAt = null;
       if (m.attempts > decl.retries) {
         if (decl.deadLetter) {
           m.status = "dead";
@@ -348,6 +417,9 @@ export async function createSignalEngine(
       const m = claimOnce(consumer.signal, consumer.subscriberId);
       if (!m) continue;
       progress = true;
+      // Persist claim + lease before the handler runs so a crash mid-handler
+      // leaves a reclaimable inflight row (not a silent pending that never locked).
+      await persist();
       await deliverOnce(m, consumer);
     }
     return progress;
@@ -571,6 +643,7 @@ export async function createSignalEngine(
         if (!options.dryRun) {
           m.status = "pending";
           m.lockedBy = null;
+          m.leaseExpiresAt = null;
           m.availableAt = now();
           m.attempts = 0;
           if (m.delivery === "broadcast") {

package/src/drivers/signal-nats.ts

@@ -87,8 +87,8 @@ export async function openNatsSignal(options: SignalOpenOptions): Promise<Signal
 
   return {
     driverId: "nats",
-    async emit(signal, payload) {
-      await outbox.emit(signal, payload);
+    async emit(signal, payload, options) {
+      await outbox.emit(signal, payload, options);
       await relayToNats(signal, payload);
     },
     async begin() {
@@ -96,9 +96,9 @@ export async function openNatsSignal(options: SignalOpenOptions): Promise<Signal
       const tx = await outbox.begin();
       return {
         write: (k, v) => tx.write(k, v),
-        async emit(signal, payload) {
+        async emit(signal, payload, options) {
           staged.push({ signal, payload });
-          await tx.emit(signal, payload);
+          await tx.emit(signal, payload, options);
         },
         async commit() {
           await tx.commit();