@dudousxd/nestjs-durable-core 0.51.0 → 0.53.0

package/dist/index.cjs

@@ -22,6 +22,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CONTROL_FLOW_SIGNAL: () => CONTROL_FLOW_SIGNAL,
   CodecStateStore: () => CodecStateStore,
   ContinueAsNew: () => ContinueAsNew,
   DURABLE_OPTIONS: () => DURABLE_OPTIONS,
@@ -67,6 +68,7 @@ __export(index_exports, {
   eventPrefix: () => eventPrefix,
   eventToken: () => eventToken,
   indexWaitersByRun: () => indexWaitersByRun,
+  isWorkflowControlFlowSignal: () => isWorkflowControlFlowSignal,
   matchesAttributes: () => matchesAttributes,
   normalizeAttributeRows: () => normalizeAttributeRows,
   parseDuration: () => parseDuration,
@@ -259,6 +261,13 @@ function currentWorkflowCtx() {
 }
 __name(currentWorkflowCtx, "currentWorkflowCtx");
 
+// src/control-flow-signal.ts
+var CONTROL_FLOW_SIGNAL = Symbol.for("aviary:durable:control-flow");
+function isWorkflowControlFlowSignal(error) {
+  return typeof error === "object" && error !== null && error[CONTROL_FLOW_SIGNAL] === true;
+}
+__name(isWorkflowControlFlowSignal, "isWorkflowControlFlowSignal");
+
 // src/errors.ts
 var FatalError = class extends Error {
   static {
@@ -357,6 +366,8 @@ var WorkflowSuspended = class extends Error {
   }
   /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
   wakeAt;
+  /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
+  [CONTROL_FLOW_SIGNAL] = true;
   constructor(wakeAt) {
     super("workflow suspended");
     this.name = "WorkflowSuspended";
@@ -368,6 +379,8 @@ var ContinueAsNew = class extends Error {
     __name(this, "ContinueAsNew");
   }
   input;
+  /** Marks this as a control-flow signal — see {@link isWorkflowControlFlowSignal}. */
+  [CONTROL_FLOW_SIGNAL] = true;
   constructor(input) {
     super("workflow continued as new"), this.input = input;
     this.name = "ContinueAsNew";
@@ -940,6 +953,47 @@ var RemoteWorkflowExecutor = class {
   }
 };
 
+// src/run-waiting.ts
+var WEBHOOK_PREFIX = "wh:";
+var CHILD_PREFIX = "child:";
+var BREAKPOINT_PREFIX = "bp:";
+var EVENT_PREFIX = "event:";
+function classifyWaiterToken(token) {
+  if (token.startsWith(WEBHOOK_PREFIX)) return {
+    on: "webhook",
+    name: token
+  };
+  if (token.startsWith(BREAKPOINT_PREFIX)) return {
+    on: "breakpoint",
+    name: "breakpoint"
+  };
+  if (token.startsWith(CHILD_PREFIX)) return {
+    on: "child",
+    name: token.slice(CHILD_PREFIX.length)
+  };
+  if (token.startsWith(EVENT_PREFIX)) return {
+    on: "signal",
+    name: eventNameOf(token)
+  };
+  return {
+    on: "signal",
+    name: token
+  };
+}
+__name(classifyWaiterToken, "classifyWaiterToken");
+function resolveRunWaiting(run, waiterByRun) {
+  if (run.status !== "suspended") return void 0;
+  const waiter = waiterByRun.get(run.id);
+  return waiter ? classifyWaiterToken(waiter.token) : void 0;
+}
+__name(resolveRunWaiting, "resolveRunWaiting");
+function indexWaitersByRun(waiters) {
+  const byRun = /* @__PURE__ */ new Map();
+  for (const w of waiters) if (!byRun.has(w.runId)) byRun.set(w.runId, w);
+  return byRun;
+}
+__name(indexWaitersByRun, "indexWaitersByRun");
+
 // src/singleton-gate.ts
 var SINGLETON_RETRY_MS = 1e3;
 var SINGLETON_RETRY_JITTER_MS = 250;
@@ -1395,6 +1449,15 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         runId,
         seq: current
       });
+      const lateBuffered2 = await consumeBuffered(token, current);
+      if (lateBuffered2) {
+        await store.removeSignalWaiter({
+          token,
+          runId,
+          seq: current
+        });
+        return lateBuffered2.value;
+      }
       throw new WorkflowSuspended();
     }
     const timeoutMs = opts.timeoutMs;
@@ -1406,7 +1469,11 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     const buffered = await consumeBuffered(token, waitSeq);
     if (buffered) return buffered.value;
     if (host.clock() >= deadline) {
-      await store.takeSignalWaiter(token).catch(() => void 0);
+      await store.removeSignalWaiter({
+        token,
+        runId,
+        seq: waitSeq
+      }).catch(() => void 0);
       throw new SignalTimeoutError(token, timeoutMs);
     }
     await store.putSignalWaiter({
@@ -1414,6 +1481,15 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
       runId,
       seq: waitSeq
     });
+    const lateBuffered = await consumeBuffered(token, waitSeq);
+    if (lateBuffered) {
+      await store.removeSignalWaiter({
+        token,
+        runId,
+        seq: waitSeq
+      });
+      return lateBuffered.value;
+    }
     throw new WorkflowSuspended(deadline);
   }, "waitForSignal");
   const waitForEvent = /* @__PURE__ */ __name(async (name, opts) => {
@@ -1437,7 +1513,11 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     const waited = await readCheckpoint(waitSeq);
     if (waited && waited.status === "completed") return waited.output;
     if (host.clock() >= deadline) {
-      await store.takeSignalWaiter(token).catch(() => void 0);
+      await store.removeSignalWaiter({
+        token,
+        runId,
+        seq: waitSeq
+      }).catch(() => void 0);
       throw new SignalTimeoutError(`event:${name}`, timeoutMs);
     }
     await store.putSignalWaiter({
@@ -2583,9 +2663,46 @@ var WorkflowEngine = class {
   /**
   * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
   * boot. A run still not due re-suspends cheaply without running new work.
+  *
+  * Piggy-backs the signal-waiter reconcile safety net (see {@link reconcileSignalWaiter}): a crash
+  * between the waiter/buffer pairing ops on EITHER side (this run's own `putSignalWaiter` →
+  * `takeBufferedSignal`, or a signaler's `takeSignalWaiter` → `bufferSignal` → re-check — see
+  * `signal`'s interleaving proof) can leave both rows stranded with nothing left to pair them: the
+  * waiter's turn already suspended, the signaler that buffered it already returned. Event-wait
+  * suspends already carry a `reconcileMs` fallback `wakeAt` (see {@link reconcileWakeAt}) precisely so
+  * they show up HERE — that's what makes this due-timer pass the natural place for the sweep. One
+  * bulk waiter scan, filtered to just this tick's batch, keeps it cheap regardless of store size.
   */
   async resumeDueTimers(nowMs = this.clock()) {
-    return this.resumeLeased(await this.store.listDueTimers(nowMs, this.namespace), nowMs);
+    const due = await this.store.listDueTimers(nowMs, this.namespace);
+    if (due.length === 0) return [];
+    const waiterByRun = indexWaitersByRun(await this.store.listSignalWaiters(""));
+    return this.resumeLeased(due, nowMs, (run) => this.reconcileSignalWaiter(run, waiterByRun.get(run.id)));
+  }
+  /**
+  * The reconcile safety net's per-run check (see {@link resumeDueTimers}): if this suspended run has
+  * a registered signal waiter AND its token already has a buffered payload, pair and deliver them
+  * directly instead of falling through to a full replay. Event/child/breakpoint waiter tokens are
+  * never buffered (`publishEvent` doesn't buffer, and a child/breakpoint notifies via `signal` only
+  * once its counterpart is already registered) — so `takeBufferedSignal` on those is a guaranteed
+  * miss, and this is naturally signal-only without needing to classify the token.
+  *
+  * Returns `undefined` (not settled — `resumeLeased` proceeds with its normal `resume`) when there's
+  * no waiter or no buffered hit. Deliberately never returns `null`: a delivered signal always resumes
+  * via {@link deliverSignal}, and even a `NamespaceMismatch` there is reported as a real (non-nullish)
+  * result — returning `null` would read as "not settled" to `resumeLeased`'s `??` fallback and
+  * trigger a second, redundant `resume` call on the same run.
+  */
+  async reconcileSignalWaiter(run, waiter) {
+    if (!waiter) return void 0;
+    const buffered = await this.store.takeBufferedSignal(waiter.token);
+    if (!buffered) return void 0;
+    await this.store.removeSignalWaiter(waiter);
+    const settled = await this.deliverSignal(waiter, buffered.payload);
+    return settled ?? {
+      runId: run.id,
+      status: run.status
+    };
   }
   /**
   * Lease and execute one run by id — the worker side of dispatch. Acquires the recovery lease (so
@@ -2803,16 +2920,17 @@ var WorkflowEngine = class {
     }
     return touched;
   }
-  async signal(token, payload) {
-    const waiter = await this.store.takeSignalWaiter(token);
-    if (!waiter) {
-      await this.store.bufferSignal(token, payload);
-      return null;
-    }
+  /**
+  * Deliver a signal to an already-known waiter: write its resolving `signal:<token>` checkpoint and
+  * resume the run. Shared by {@link signal}'s direct hit, its post-buffer re-check reclaim, and the
+  * due-timer reconcile sweep ({@link reconcileSignalWaiter}) — all three resolve a waiter the exact
+  * same way.
+  */
+  async deliverSignal(waiter, payload) {
     await this.store.saveCheckpoint(instantCheckpoint({
       runId: waiter.runId,
       seq: waiter.seq,
-      name: `signal:${token}`,
+      name: `signal:${waiter.token}`,
       kind: "signal",
       output: payload,
       // Carry the awaiting command's fan group (set when a `ctx.gather_children`/`ctx.all` fan-out
@@ -2827,6 +2945,42 @@ var WorkflowEngine = class {
     });
   }
   /**
+  * Deliver an external signal to the run waiting on `token`, resume it with `payload`, and return
+  * the run result — or null if no run is (or ends up) waiting for it.
+  *
+  * Race with the waiter side (`waitForSignal`'s check → `putSignalWaiter` → re-check, same shape in
+  * the remote `waitSignal` command): a waiter can register in the sliver between this method's
+  * initial `takeSignalWaiter` miss and its `bufferSignal` write, and the naive old flow (buffer and
+  * return) would then leave BOTH a buffered payload and a registered waiter sitting in the store with
+  * nothing left to pair them — a lost wake, forever suspended.
+  *
+  * The interleaving proof: the waiter side does check → put → re-check, this side does take → buffer
+  * → re-check. Whichever side's SECOND look runs last is guaranteed to observe the other side's
+  * write, because it always follows that write in real time:
+  *  - If the waiter's `put` lands before this method's first `take`, the take just finds it directly
+  *    (the pre-existing, non-racy path).
+  *  - If the waiter's `put` lands after this method's `bufferSignal`, our re-check below either sees
+  *    it (if `put` also lands before the re-check) or the waiter's OWN post-put re-check sees our
+  *    buffer (if `put` lands after our re-check but the waiter hasn't re-checked yet either — its
+  *    re-check strictly follows its own put).
+  *  - If the waiter's `put` lands between this method's `take` and its re-`take`, the re-check below
+  *    catches it.
+  * Either way, the destructive `take*` ops (on the waiter row, on the buffer) arbitrate: whichever
+  * side actually removes the row is the one that delivers, so a signal is never delivered twice.
+  */
+  async signal(token, payload) {
+    const waiter = await this.store.takeSignalWaiter(token);
+    if (waiter) return this.deliverSignal(waiter, payload);
+    await this.store.bufferSignal(token, payload);
+    const lateWaiter = await this.store.takeSignalWaiter(token);
+    if (!lateWaiter) return null;
+    const reclaimed = await this.store.takeBufferedSignal(token);
+    if (!reclaimed) {
+      return null;
+    }
+    return this.deliverSignal(lateWaiter, reclaimed.payload);
+  }
+  /**
   * Ensure a run exists for `runId`, then deliver a signal to it — atomically race-free thanks to
   * signal buffering: if the run is new (or busy / not yet waiting), the signal is buffered and
   * consumed when it reaches `waitForSignal(token)`. The canonical **durable-entity / accumulator**
@@ -3299,6 +3453,14 @@ var WorkflowEngine = class {
         error: outcome.error
       };
     }
+    const latest = await this.store.getRun(run.id);
+    if (latest?.status === "cancelled") {
+      return {
+        runId: run.id,
+        status: "cancelled",
+        error: latest.error
+      };
+    }
     await this.store.updateRun(run.id, {
       status: "suspended",
       wakeAt: this.reconcileWakeAt(outcome.wakeAt),
@@ -3641,22 +3803,34 @@ var WorkflowEngine = class {
         }));
         wakeAt = wakeAt == null ? deadline : Math.min(wakeAt, deadline);
       } else if (cmd.kind === "waitSignal") {
-        const buffered = await this.store.takeBufferedSignal(cmd.signal);
-        if (buffered) {
+        const deliverBuffered = /* @__PURE__ */ __name(async (payload) => {
           await this.store.saveCheckpoint(instantCheckpoint({
             runId: run.id,
             seq: cmd.seq,
             name: `signal:${cmd.signal}`,
             kind: "signal",
-            output: buffered.payload
+            output: payload
           }));
           setTimeout(() => void this.resume(run.id).catch(() => void 0), 0);
+        }, "deliverBuffered");
+        const buffered = await this.store.takeBufferedSignal(cmd.signal);
+        if (buffered) {
+          await deliverBuffered(buffered.payload);
         } else {
           await this.store.putSignalWaiter({
             token: cmd.signal,
             runId: run.id,
             seq: cmd.seq
           });
+          const lateBuffered = await this.store.takeBufferedSignal(cmd.signal);
+          if (lateBuffered) {
+            await this.store.removeSignalWaiter({
+              token: cmd.signal,
+              runId: run.id,
+              seq: cmd.seq
+            });
+            await deliverBuffered(lateBuffered.payload);
+          }
         }
       } else if (cmd.kind === "startChild") {
         const childId = `${run.id}.child.${cmd.seq}`;
@@ -4516,47 +4690,6 @@ var TERMINAL_RUN_STATUSES = [
   "dead"
 ];
 
-// src/run-waiting.ts
-var WEBHOOK_PREFIX = "wh:";
-var CHILD_PREFIX = "child:";
-var BREAKPOINT_PREFIX = "bp:";
-var EVENT_PREFIX = "event:";
-function classifyWaiterToken(token) {
-  if (token.startsWith(WEBHOOK_PREFIX)) return {
-    on: "webhook",
-    name: token
-  };
-  if (token.startsWith(BREAKPOINT_PREFIX)) return {
-    on: "breakpoint",
-    name: "breakpoint"
-  };
-  if (token.startsWith(CHILD_PREFIX)) return {
-    on: "child",
-    name: token.slice(CHILD_PREFIX.length)
-  };
-  if (token.startsWith(EVENT_PREFIX)) return {
-    on: "signal",
-    name: eventNameOf(token)
-  };
-  return {
-    on: "signal",
-    name: token
-  };
-}
-__name(classifyWaiterToken, "classifyWaiterToken");
-function resolveRunWaiting(run, waiterByRun) {
-  if (run.status !== "suspended") return void 0;
-  const waiter = waiterByRun.get(run.id);
-  return waiter ? classifyWaiterToken(waiter.token) : void 0;
-}
-__name(resolveRunWaiting, "resolveRunWaiting");
-function indexWaitersByRun(waiters) {
-  const byRun = /* @__PURE__ */ new Map();
-  for (const w of waiters) if (!byRun.has(w.runId)) byRun.set(w.runId, w);
-  return byRun;
-}
-__name(indexWaitersByRun, "indexWaitersByRun");
-
 // src/codec-state-store.ts
 var CodecStateStore = class {
   static {
@@ -4664,6 +4797,9 @@ var CodecStateStore = class {
   listSignalWaiters(prefix) {
     return this.inner.listSignalWaiters(prefix);
   }
+  removeSignalWaiter(waiter) {
+    return this.inner.removeSignalWaiter(waiter);
+  }
   bufferSignal(token, payload) {
     return this.inner.bufferSignal(token, this.enc(payload));
   }
@@ -5116,6 +5252,12 @@ var InMemoryStateStore = class {
       ...w
     }));
   }
+  async removeSignalWaiter(waiter) {
+    const current = this.signalWaiters.get(waiter.token);
+    if (current && current.runId === waiter.runId && current.seq === waiter.seq) {
+      this.signalWaiters.delete(waiter.token);
+    }
+  }
   // No real DB transaction (there's no DB) — run the work and save the checkpoint. Exactly-once
   // across a crash needs a SQL store; this keeps `ctx.transaction` usable in tests / local dev.
   async transaction(work) {
@@ -5290,6 +5432,7 @@ var InMemoryTransport = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CONTROL_FLOW_SIGNAL,
   CodecStateStore,
   ContinueAsNew,
   DURABLE_OPTIONS,
@@ -5335,6 +5478,7 @@ var InMemoryTransport = class {
   eventPrefix,
   eventToken,
   indexWaitersByRun,
+  isWorkflowControlFlowSignal,
   matchesAttributes,
   normalizeAttributeRows,
   parseDuration,