@dudousxd/nestjs-durable-core 0.53.0 → 0.55.0

package/dist/index.cjs

@@ -30,6 +30,8 @@ __export(index_exports, {
   DURABLE_STEP_CONFIG: () => DURABLE_STEP_CONFIG,
   DURABLE_STEP_NAME: () => DURABLE_STEP_NAME,
   DurableWorkflow: () => DurableWorkflow,
+  EVENT_BUFFER_SCAN_LIMIT: () => EVENT_BUFFER_SCAN_LIMIT,
+  EVENT_TOKEN_PREFIX: () => EVENT_TOKEN_PREFIX,
   Entities: () => Entities,
   EventAccumulators: () => EventAccumulators,
   FatalError: () => FatalError,
@@ -68,6 +70,7 @@ __export(index_exports, {
   eventPrefix: () => eventPrefix,
   eventToken: () => eventToken,
   indexWaitersByRun: () => indexWaitersByRun,
+  isEventToken: () => isEventToken,
   isWorkflowControlFlowSignal: () => isWorkflowControlFlowSignal,
   matchesAttributes: () => matchesAttributes,
   normalizeAttributeRows: () => normalizeAttributeRows,
@@ -871,10 +874,16 @@ var EventAccumulators = class {
 // src/events.ts
 var enc = /* @__PURE__ */ __name((s) => Buffer.from(s, "utf8").toString("base64"), "enc");
 var dec = /* @__PURE__ */ __name((s) => Buffer.from(s, "base64").toString("utf8"), "dec");
+var EVENT_BUFFER_SCAN_LIMIT = 50;
+var EVENT_TOKEN_PREFIX = "event:";
 function eventPrefix(name) {
-  return `event:${enc(name)}:`;
+  return `${EVENT_TOKEN_PREFIX}${enc(name)}:`;
 }
 __name(eventPrefix, "eventPrefix");
+function isEventToken(token) {
+  return token.startsWith(EVENT_TOKEN_PREFIX);
+}
+__name(isEventToken, "isEventToken");
 function eventToken(name, match, runId, seq) {
   return `${eventPrefix(name)}${enc(JSON.stringify(match ?? {}))}:${runId}#${seq}`;
 }
@@ -957,7 +966,7 @@ var RemoteWorkflowExecutor = class {
 var WEBHOOK_PREFIX = "wh:";
 var CHILD_PREFIX = "child:";
 var BREAKPOINT_PREFIX = "bp:";
-var EVENT_PREFIX = "event:";
+var EVENT_PREFIX = EVENT_TOKEN_PREFIX;
 function classifyWaiterToken(token) {
   if (token.startsWith(WEBHOOK_PREFIX)) return {
     on: "webhook",
@@ -1181,6 +1190,21 @@ var TransportPool = class {
     ];
   }
   /**
+  * The first transport (in pool order) reporting a LIVE heartbeat for `group` — the one a
+  * convention-routed remote workflow must dispatch on. In a mixed pool (e.g. a tenant-scoped
+  * control plane pairing its namespaced transport with a bare-prefix one for operator-convention
+  * tenant workers), each transport sees a DIFFERENT keyspace: dispatching on `primary` while the
+  * live worker heartbeats on another transport parks the task on a queue nobody consumes. Returns
+  * `undefined` when no transport reports the group (mirrors the merged `listWorkerGroups` miss).
+  */
+  async transportWithLiveGroup(group) {
+    for (const { transport } of this.transports) {
+      if (!transport.listWorkerGroups) continue;
+      if ((await transport.listWorkerGroups()).includes(group)) return transport;
+    }
+    return void 0;
+  }
+  /**
   * Propagate the engine's `namespace` to every transport that partitions by it — so the same
   * namespace that scopes the store also scopes each transport's queues/keys. A transport that
   * doesn't partition (no `useNamespace`) is skipped. Idempotent; a transport given an explicit
@@ -1423,6 +1447,29 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
       value: buffered.payload
     };
   }, "consumeBuffered");
+  const consumeBufferedEvent = /* @__PURE__ */ __name(async (name, match, token, seq) => {
+    const candidates = await store.listBufferedEvents(name, EVENT_BUFFER_SCAN_LIMIT);
+    for (const candidate of candidates) {
+      if (!eventMatches(candidate.payload, match ?? {})) continue;
+      if (!await store.removeBufferedEvent(candidate.id)) continue;
+      await store.removeSignalWaiter({
+        token,
+        runId,
+        seq
+      });
+      await writeCheckpoint(instantCheckpoint({
+        runId,
+        seq,
+        name: `signal:${token}`,
+        kind: "signal",
+        output: candidate.payload
+      }));
+      return {
+        value: candidate.payload
+      };
+    }
+    return null;
+  }, "consumeBufferedEvent");
   const stampDeadline = /* @__PURE__ */ __name(async (deadlineSeq, label, timeoutMs) => {
     const recorded = await readCheckpoint(deadlineSeq);
     const deadline = recorded?.wakeAt ?? host.clock() + timeoutMs;
@@ -1503,6 +1550,8 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         runId,
         seq: current
       });
+      const bufferedHit2 = await consumeBufferedEvent(name, opts?.match, token2, current);
+      if (bufferedHit2) return bufferedHit2.value;
       throw new WorkflowSuspended();
     }
     const timeoutMs = opts.timeoutMs;
@@ -1525,6 +1574,8 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
       runId,
       seq: waitSeq
     });
+    const bufferedHit = await consumeBufferedEvent(name, opts.match, token, waitSeq);
+    if (bufferedHit) return bufferedHit.value;
     throw new WorkflowSuspended(deadline);
   }, "waitForEvent");
   const task = /* @__PURE__ */ __name(async (name, dispatch, options) => {
@@ -1918,6 +1969,7 @@ var WorkflowEngine = class {
   maxRecoveryAttempts;
   remoteAdvanceSilenceMs;
   reconcileMs;
+  eventBufferTtlMs;
   remoteRedispatchMs;
   remoteRedispatchMax;
   webhookUrl;
@@ -1991,6 +2043,7 @@ var WorkflowEngine = class {
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
     this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
+    this.eventBufferTtlMs = deps.eventBufferTtlMs || void 0;
     this.remoteRedispatchMs = deps.remoteRedispatchMs || void 0;
     this.remoteRedispatchMax = Math.max(1, deps.remoteRedispatchMax ?? 10);
     this.webhookUrl = deps.webhookUrl;
@@ -2467,10 +2520,10 @@ var WorkflowEngine = class {
   * liveness changes between calls, exactly as {@link synthesizeRemoteChild} does.
   */
   async resolveRemoteByConvention(run) {
-    const liveGroups = await this.pool.listWorkerGroups();
     const group = tenantGroup(sanitizeQueueToken(run.workflow), run.namespace);
-    if (!liveGroups.includes(group)) return void 0;
-    const executor = new RemoteWorkflowExecutor(this.pool.primary, run.workflow, run.namespace);
+    const liveTransport = await this.pool.transportWithLiveGroup(group);
+    if (!liveTransport) return void 0;
+    const executor = new RemoteWorkflowExecutor(liveTransport, run.workflow, run.namespace);
     return {
       name: run.workflow,
       version: run.workflowVersion,
@@ -2664,14 +2717,16 @@ 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.
+  * Piggy-backs the signal/event-waiter reconcile safety net (see {@link reconcileSignalWaiter}): a
+  * crash between the waiter/buffer pairing ops on EITHER side (this run's own `putSignalWaiter` →
+  * `takeBufferedSignal`/`listBufferedEvents`, or the other side's `takeSignalWaiter`/fan-out →
+  * `bufferSignal`/`bufferEvent` → re-check — see `signal`'s interleaving proof, which `publishEvent`
+  * mirrors for events) can leave both rows stranded with nothing left to pair them: the waiter's turn
+  * already suspended, the other side 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 (and, for events, also
+  * where an `eventBufferTtlMs` prune piggy-backs — see {@link reconcileBufferedEvent}). One bulk waiter
+  * scan, filtered to just this tick's batch, keeps it cheap regardless of store size.
   */
   async resumeDueTimers(nowMs = this.clock()) {
     const due = await this.store.listDueTimers(nowMs, this.namespace);
@@ -2681,11 +2736,15 @@ var WorkflowEngine = class {
   }
   /**
   * 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.
+  * a registered signal OR event waiter and a matching payload is already buffered, pair and deliver
+  * them directly instead of falling through to a full replay. Child/breakpoint waiter tokens are
+  * never buffered (a child/breakpoint notifies via `signal` only once its counterpart is already
+  * registered) — `takeBufferedSignal` on those is a guaranteed miss, so this only ever does real work
+  * for a plain signal or an event waiter (classified via {@link isEventToken}).
+  *
+  * Also opportunistically prunes expired buffered EVENTS for this waiter's name when
+  * {@link eventBufferTtlMs} is set (see its doc — scoped to names a registered waiter references in
+  * this tick's batch, piggy-backing the SAME scan rather than a separate pass), even on a miss.
   *
   * 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
@@ -2695,6 +2754,7 @@ var WorkflowEngine = class {
   */
   async reconcileSignalWaiter(run, waiter) {
     if (!waiter) return void 0;
+    if (isEventToken(waiter.token)) return this.reconcileBufferedEvent(run, waiter);
     const buffered = await this.store.takeBufferedSignal(waiter.token);
     if (!buffered) return void 0;
     await this.store.removeSignalWaiter(waiter);
@@ -2705,6 +2765,34 @@ var WorkflowEngine = class {
     };
   }
   /**
+  * The EVENT half of {@link reconcileSignalWaiter}: scan this waiter's name for a matching buffered
+  * event (same list+evaluate+claim shape as `waitForEvent`'s own consumption — the match predicate
+  * belongs to the waiter, never the store), pruning any expired candidates it encounters along the
+  * way when {@link eventBufferTtlMs} is configured. A pruned-but-non-matching candidate does not stop
+  * the scan; only a MATCHING hit (or exhausting the scan window) does.
+  */
+  async reconcileBufferedEvent(run, waiter) {
+    const name = eventNameOf(waiter.token);
+    const match = eventMatchOf(waiter.token);
+    const candidates = await this.store.listBufferedEvents(name, EVENT_BUFFER_SCAN_LIMIT);
+    const nowMs = this.clock();
+    for (const candidate of candidates) {
+      if (this.eventBufferTtlMs != null && nowMs - candidate.publishedAt > this.eventBufferTtlMs) {
+        await this.store.removeBufferedEvent(candidate.id);
+        continue;
+      }
+      if (!eventMatches(candidate.payload, match)) continue;
+      if (!await this.store.removeBufferedEvent(candidate.id)) continue;
+      await this.store.removeSignalWaiter(waiter);
+      const settled = await this.deliverSignal(waiter, candidate.payload);
+      return settled ?? {
+        runId: run.id,
+        status: run.status
+      };
+    }
+    return void 0;
+  }
+  /**
   * Lease and execute one run by id — the worker side of dispatch. Acquires the recovery lease (so
   * exactly one instance runs it), then resumes the body. Returns the result, or null if another
   * instance holds the lease or the engine is draining. The default in-process dispatcher calls this;
@@ -2892,6 +2980,21 @@ var WorkflowEngine = class {
   *  2. **Starts** a fresh run of every workflow registered with `onEvent: [name]`, passing the
   *     payload as input. Idempotent by `evt:<id>:<workflow>` — pass `opts.id` to dedupe redeliveries
   *     of the same logical event (default: a fresh uuid, so each publish triggers once).
+  *
+  * Semantics (deliberate — mirrors `signalWithStart`'s reliability contract, so document it exactly):
+  * a publish that resumes ≥1 live waiter, OR routes into an `eventBatch` accumulator / starts ≥1
+  * subscriber, behaves exactly as above and is NOT buffered — fan-out stays live-only, same as
+  * today. A publish that touches NEITHER — no live waiter matched, no subscriber exists/started —
+  * buffers ONE copy (via {@link StateStore.bufferEvent}) unless `opts.buffer === false`, so it isn't
+  * silently dropped just because nobody happened to be listening yet. That buffered copy is consumed
+  * by the FIRST future `ctx.waitForEvent(name, { match })` whose match accepts its payload —
+  * point-to-point on redelivery, by design (only one waiter ever gets it, even though the LIVE path
+  * above is fan-out) — never by a second, later-registered onEvent subscriber (subscriber starts stay
+  * live-only; `opts.id` dedupe applies to those only, unchanged). Right after buffering, this re-checks
+  * `listSignalWaiters` ONCE — sandwich parity with `signal`'s own take → buffer → re-check — so a
+  * waiter that registers in the sliver between the initial miss and the buffer write is still paired
+  * instead of leaving both rows stranded (see `signal`'s interleaving proof; `waitForEvent`'s own
+  * post-registration buffer scan is the mirror-image half of this same race).
   */
   async publishEvent(name, payload, opts) {
     let touched = 0;
@@ -2918,6 +3021,23 @@ var WorkflowEngine = class {
         }
       }
     }
+    if (touched > 0 || opts?.buffer === false) return touched;
+    const bufferedId = globalThis.crypto.randomUUID();
+    await this.store.bufferEvent({
+      name,
+      payload,
+      id: bufferedId,
+      publishedAt: this.clock()
+    });
+    const lateWaiters = await this.store.listSignalWaiters(eventPrefix(name));
+    const lateWaiter = lateWaiters.find((w) => eventMatches(payload, eventMatchOf(w.token)));
+    if (!lateWaiter) return touched;
+    if (!await this.store.removeBufferedEvent(bufferedId)) return touched;
+    const waiter = await this.store.takeSignalWaiter(lateWaiter.token);
+    if (waiter) {
+      const settled = await this.deliverSignal(waiter, payload);
+      if (settled) touched += 1;
+    }
     return touched;
   }
   /**
@@ -3022,6 +3142,27 @@ var WorkflowEngine = class {
     void this.signal(`child:${runId}`, completion).catch(() => void 0);
   }
   /**
+  * Deferred child start shared by the in-process ctx host and the remote `startChild` command.
+  * Deferred (microtask) so a fast child can't reentrantly resume a still-suspending parent. A start
+  * that THROWS (unregistered/unroutable workflow, input validation, singleton back-pressure, store
+  * failure) must NOT be swallowed: the parent is already suspended on `child:<childId>` (the waiter
+  * is put BEFORE start on every path), so a silent drop parks it in suspended-forever, invisibly
+  * re-attempting on every recovery wake — a misconfigured remote child looks exactly like a healthy
+  * long wait. Instead the failure is delivered to that waiter like a failed child (notifyParent):
+  * the parent resumes and fails loudly with the cause. For a fire-and-forget `ctx.startChild`
+  * (spawn — no waiter) the completion is buffered; a later join by the same id consumes it and
+  * correctly observes the failed start.
+  */
+  startChildDeferred(workflow, input, childId, opts) {
+    queueMicrotask(() => void this.start(workflow, input, childId, opts).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      this.notifyParent(childId, {
+        ok: false,
+        error: `child workflow "${workflow}" failed to start: ${message}`
+      });
+    }));
+  }
+  /**
   * Cancel a run (e.g. from the dashboard). Returns null if the run does not exist. Pass
   * `{ compensate: true }` to undo the saga first: the suspended run is resumed so its completed
   * steps' compensations run in reverse (visible as `compensate:<step>` events), then it's marked
@@ -3845,9 +3986,9 @@ var WorkflowEngine = class {
           parallelGroup: cmd.parallelGroup
         });
         if (!await this.store.getRun(childId)) {
-          queueMicrotask(() => void this.start(cmd.workflow, cmd.input, childId, {
+          this.startChildDeferred(cmd.workflow, cmd.input, childId, {
             namespace: run.namespace
-          }).catch(() => void 0));
+          });
         }
       } else {
         throw new Error(`remote workflow command '${cmd.kind}' is not supported yet`);
@@ -4226,10 +4367,10 @@ var WorkflowEngine = class {
       // `davi-local` pipeline would stamp its `processing` child `default` and it would leak off the
       // tenant's worker pool onto the shared/dev workers.
       startChild: /* @__PURE__ */ __name((workflow, input, id, priority) => {
-        queueMicrotask(() => void this.start(workflow, input, id, {
+        this.startChildDeferred(workflow, input, id, {
           priority,
           namespace: parentNamespace
-        }).catch(() => void 0));
+        });
       }, "startChild"),
       // Deferred for the same reentrancy reason as `startChild` above. `cancel()` is already
       // idempotent on a terminal/cancelled run (returns its existing status without side effects), so
@@ -4809,6 +4950,22 @@ var CodecStateStore = class {
       payload: this.dec(buffered.payload)
     };
   }
+  bufferEvent(input) {
+    return this.inner.bufferEvent({
+      ...input,
+      payload: this.enc(input.payload)
+    });
+  }
+  async listBufferedEvents(name, limit) {
+    const events = await this.inner.listBufferedEvents(name, limit);
+    return events.map((e) => ({
+      ...e,
+      payload: this.dec(e.payload)
+    }));
+  }
+  removeBufferedEvent(id) {
+    return this.inner.removeBufferedEvent(id);
+  }
   async listRuns(query) {
     return (await this.inner.listRuns(query)).map((r) => this.decRun(r));
   }
@@ -5281,6 +5438,28 @@ var InMemoryStateStore = class {
       payload
     };
   }
+  /** `id -> row`, so {@link removeBufferedEvent} can delete an exact row regardless of iteration
+  *  order — mirrors the SQL stores' PK-by-id delete. */
+  bufferedEvents = /* @__PURE__ */ new Map();
+  async bufferEvent(input) {
+    this.bufferedEvents.set(input.id, {
+      name: input.name,
+      payload: input.payload,
+      publishedAt: input.publishedAt
+    });
+  }
+  async listBufferedEvents(name, limit) {
+    return [
+      ...this.bufferedEvents.entries()
+    ].filter(([, e]) => e.name === name).sort((a, b) => a[1].publishedAt - b[1].publishedAt).slice(0, limit).map(([id, e]) => ({
+      id,
+      payload: e.payload,
+      publishedAt: e.publishedAt
+    }));
+  }
+  async removeBufferedEvent(id) {
+    return this.bufferedEvents.delete(id);
+  }
   /**
   * Candidate run ids satisfying ONE attribute predicate, served from {@link attributeIndex} — the
   * pushdown step. Numeric predicates scan only `numValue` rows under the key; string/boolean ones
@@ -5440,6 +5619,8 @@ var InMemoryTransport = class {
   DURABLE_STEP_CONFIG,
   DURABLE_STEP_NAME,
   DurableWorkflow,
+  EVENT_BUFFER_SCAN_LIMIT,
+  EVENT_TOKEN_PREFIX,
   Entities,
   EventAccumulators,
   FatalError,
@@ -5478,6 +5659,7 @@ var InMemoryTransport = class {
   eventPrefix,
   eventToken,
   indexWaitersByRun,
+  isEventToken,
   isWorkflowControlFlowSignal,
   matchesAttributes,
   normalizeAttributeRows,