@dudousxd/nestjs-durable-core 0.72.0 → 0.72.1

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   InMemoryTransport: () => InMemoryTransport,
   LEGACY_V1_CAPABILITIES: () => LEGACY_V1_CAPABILITIES,
   LEGACY_V1_PROTOCOL: () => LEGACY_V1_PROTOCOL,
+  NestedWorkflowCallError: () => NestedWorkflowCallError,
   NonDeterminismError: () => NonDeterminismError,
   QueueController: () => QueueController,
   RUN_VALUE_FACET_LIMIT: () => RUN_VALUE_FACET_LIMIT,
@@ -92,6 +93,7 @@ __export(index_exports, {
   coveredTokens: () => coveredTokens,
   createStepLogger: () => createStepLogger,
   currentStep: () => currentStep,
+  currentStepScope: () => currentStepScope,
   currentWorkflowCtx: () => currentWorkflowCtx,
   debug: () => debug,
   describeWorker: () => describeWorker,
@@ -133,7 +135,9 @@ __export(index_exports, {
   resolveRunWaiting: () => resolveRunWaiting,
   runDurableExecution: () => runDurableExecution,
   runInStepLogger: () => runInStepLogger,
+  runInStepScope: () => runInStepScope,
   runInWorkflowCtx: () => runInWorkflowCtx,
+  runOutsideWorkflowCtx: () => runOutsideWorkflowCtx,
   runSchedules: () => runSchedules,
   runStepHandler: () => runStepHandler,
   runValueFacetsFromRuns: () => runValueFacetsFromRuns,
@@ -324,6 +328,27 @@ function currentWorkflowCtx() {
   return storage.getStore();
 }
 __name(currentWorkflowCtx, "currentWorkflowCtx");
+var STEP_SCOPE_KEY = Symbol.for("nestjs-durable:ambient-step-scope");
+var stepScopeRef = globalThis;
+if (!stepScopeRef[STEP_SCOPE_KEY]) {
+  stepScopeRef[STEP_SCOPE_KEY] = new import_node_async_hooks.AsyncLocalStorage();
+}
+var stepScopeStorage = stepScopeRef[STEP_SCOPE_KEY];
+function runInStepScope(owner, step, fn) {
+  return stepScopeStorage.run({
+    owner,
+    step
+  }, fn);
+}
+__name(runInStepScope, "runInStepScope");
+function currentStepScope() {
+  return stepScopeStorage.getStore();
+}
+__name(currentStepScope, "currentStepScope");
+function runOutsideWorkflowCtx(fn) {
+  return storage.exit(() => stepScopeStorage.exit(fn));
+}
+__name(runOutsideWorkflowCtx, "runOutsideWorkflowCtx");
 
 // src/ambient-step.ts
 var import_node_async_hooks2 = require("async_hooks");
@@ -486,6 +511,21 @@ var NonDeterminismError = class extends Error {
     this.seq = seq;
   }
 };
+var NestedWorkflowCallError = class extends FatalError {
+  static {
+    __name(this, "NestedWorkflowCallError");
+  }
+  runId;
+  primitive;
+  step;
+  constructor(runId, primitive, step) {
+    super(`ctx.${primitive}() was called inside the body of step "${step}" (run ${runId}). Workflow primitives (child/startChild/step/sleep/signals/sideEffect/\u2026, and MyWorkflow.start()/.execute() via the ambient ctx) must be called from the workflow body, never from inside a step body: the step's checkpoint replays without re-running it, so the nested call would shift every later journal position and corrupt the run on replay. Move the call out of the step.`, "nested_workflow_call");
+    this.name = "NestedWorkflowCallError";
+    this.runId = runId;
+    this.primitive = primitive;
+    this.step = step;
+  }
+};
 var GatherError = class extends Error {
   static {
     __name(this, "GatherError");
@@ -842,14 +882,19 @@ async function runStepHandler(task, handler) {
   } : result, "withEvents");
   try {
     const logger = createStepLogger(events, Date.now);
-    const output = await runDurableExecution({
-      unit: "step",
-      runId: task.runId,
-      workflow: void 0,
-      name: task.name,
-      seq: task.seq,
-      attempt: task.attempt
-    }, async () => runInStepLogger(logger, () => handler(task.input, logger)));
+    const output = await runDurableExecution(
+      {
+        unit: "step",
+        runId: task.runId,
+        workflow: void 0,
+        name: task.name,
+        seq: task.seq,
+        attempt: task.attempt
+      },
+      // Outside any ambient workflow ctx: an in-process transport runs the handler on the parent
+      // body's async path, but a handler is not the body (see `runOutsideWorkflowCtx`).
+      async () => runOutsideWorkflowCtx(() => runInStepLogger(logger, () => handler(task.input, logger)))
+    );
     return withEvents({
       ...base,
       status: "completed",
@@ -2753,10 +2798,15 @@ var Position = class Position2 {
   rewind() {
     this.seq -= 1;
   }
+  /** The position the NEXT primitive would claim, without claiming it. */
+  peek() {
+    return this.seq + 1;
+  }
 };
 function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttributesSchema) {
   const { store, replay } = host;
   const pos = new Position();
+  const scopeOwner = {};
   const readCheckpoint = /* @__PURE__ */ __name((seq) => {
     const hit = replay?.get(seq);
     if (hit !== void 0) return hit;
@@ -2802,7 +2852,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
         };
         const body = /* @__PURE__ */ __name(() => {
           const logger = createStepLogger(events, host.clock);
-          return runInStepLogger(logger, () => fn(logger));
+          return runInStepScope(scopeOwner, name, () => runInStepLogger(logger, () => fn(logger)));
         }, "body");
         const output = host.interceptStep ? await host.interceptStep(invocation, body) : await body();
         await host.completeStep({
@@ -2855,7 +2905,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     }
     if (existing && existing.status === "completed") return existing.output;
     return store.transaction(async (tx) => {
-      const output = await fn(tx.raw);
+      const output = await runInStepScope(scopeOwner, name, () => fn(tx.raw));
       const cp = instantCheckpoint({
         runId,
         seq: current,
@@ -3364,30 +3414,49 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     });
   }
   __name(step, "step");
+  const nestedStep = /* @__PURE__ */ __name(() => {
+    const scope = currentStepScope();
+    return scope !== void 0 && scope.owner === scopeOwner ? scope.step : void 0;
+  }, "nestedStep");
+  const guard = /* @__PURE__ */ __name((primitive, fn) => (...args) => {
+    const stepName = nestedStep();
+    if (stepName === void 0) return fn(...args);
+    return (async () => {
+      if (await readCheckpoint(pos.peek())) return fn(...args);
+      throw new NestedWorkflowCallError(runId, primitive, stepName);
+    })();
+  }, "guard");
+  const guardedWebhook = /* @__PURE__ */ __name(() => {
+    const stepName = nestedStep();
+    if (stepName !== void 0 && !replay?.get(pos.peek())) {
+      throw new NestedWorkflowCallError(runId, "webhook", stepName);
+    }
+    return webhook();
+  }, "guardedWebhook");
   return {
     runId,
-    step,
-    localStep,
-    upsertSearchAttributes,
-    transaction,
-    callEntity,
-    signalEntity,
-    sleep,
-    sleepUntil,
+    step: guard("step", step),
+    localStep: guard("localStep", localStep),
+    upsertSearchAttributes: guard("upsertSearchAttributes", upsertSearchAttributes),
+    transaction: guard("transaction", transaction),
+    callEntity: guard("callEntity", callEntity),
+    signalEntity: guard("signalEntity", signalEntity),
+    sleep: guard("sleep", sleep),
+    sleepUntil: guard("sleepUntil", sleepUntil),
     continueAsNew,
-    waitForSignal,
-    waitForEvent,
-    task,
-    child,
-    all,
-    startChild,
-    breakpoint,
-    webhook,
-    setEvent,
-    onUpdate,
-    patched,
-    now,
-    sideEffect
+    waitForSignal: guard("waitForSignal", waitForSignal),
+    waitForEvent: guard("waitForEvent", waitForEvent),
+    task: guard("task", task),
+    child: guard("child", child),
+    all: guard("all", all),
+    startChild: guard("startChild", startChild),
+    breakpoint: guard("breakpoint", breakpoint),
+    webhook: guardedWebhook,
+    setEvent: guard("setEvent", setEvent),
+    onUpdate: guard("onUpdate", onUpdate),
+    patched: guard("patched", patched),
+    now: guard("now", now),
+    sideEffect: guard("sideEffect", sideEffect)
   };
 }
 __name(createWorkflowCtx, "createWorkflowCtx");
@@ -3989,10 +4058,30 @@ var WorkflowEngine = class {
   getRun(runId) {
     return this.store.getRun(runId);
   }
-  async resume(runId) {
+  /**
+  * Re-execute a run's body (replaying its checkpoints). This is the EXPLICIT entry point: besides
+  * driving a live run, it re-drives a `failed` run — the manual retry (prefer {@link requeue}, which
+  * also resets the failure state so replay re-attempts the failed parts). Completed / cancelled /
+  * dead runs are never re-executed. The engine's own implicit wake-ups (signals, step results,
+  * timers, redelivered dispatches) go through {@link resumeImplicit}, which treats `failed` as
+  * terminal too.
+  */
+  resume(runId) {
+    return this.resumeRun(runId, true);
+  }
+  /**
+  * {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
+  * result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
+  * these: only an explicit retry ({@link requeue} / {@link resume}) may re-drive it. Otherwise a
+  * stale waiter or a late result left behind by a failed run silently re-executes its body.
+  */
+  resumeImplicit(runId) {
+    return this.resumeRun(runId, false);
+  }
+  async resumeRun(runId, allowFailed) {
     const run = await this.store.getRun(runId);
     if (!run) throw new Error(`run ${runId} not found`);
-    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead") {
+    if (run.status === "cancelled" || run.status === "completed" || run.status === "dead" || run.status === "failed" && !allowFailed) {
       return {
         runId,
         status: run.status,
@@ -4441,7 +4530,7 @@ var WorkflowEngine = class {
     const nowMs = this.clock();
     const acquired = await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs);
     if (!acquired) return null;
-    return this.resume(runId).catch((err) => {
+    return this.resumeImplicit(runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -4662,7 +4751,7 @@ var WorkflowEngine = class {
       if (!acquired) continue;
       try {
         const settled = onLocked ? await onLocked(run) : void 0;
-        results.push(settled ?? await this.resume(run.id));
+        results.push(settled ?? await this.resumeImplicit(run.id));
       } catch (error2) {
         console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, error2);
       }
@@ -4759,7 +4848,7 @@ var WorkflowEngine = class {
       // for an ordinary (non-fan) signal/child await.
       parallelGroup: waiter.parallelGroup
     }));
-    return this.resume(waiter.runId).catch((err) => {
+    return this.resumeImplicit(waiter.runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -4875,7 +4964,7 @@ var WorkflowEngine = class {
   async cancel(runId, opts) {
     const run = await this.store.getRun(runId);
     if (!run) return null;
-    if (run.status === "completed" || run.status === "cancelled" || run.status === "dead") {
+    if (TERMINAL_RUN_STATUSES.includes(run.status)) {
       return {
         runId,
         status: run.status,
@@ -4904,7 +4993,7 @@ var WorkflowEngine = class {
         }).catch(() => void 0);
       }
       queueMicrotask(() => {
-        void this.resume(runId).then(() => this.notifyCancelled(runId)).catch(() => void 0);
+        void this.resumeImplicit(runId).then(() => this.notifyCancelled(runId)).catch(() => void 0);
       });
       await this.cancelChildren(runId, opts);
       return {
@@ -5739,7 +5828,7 @@ var WorkflowEngine = class {
       const checkpoint = await this.store.getCheckpoint(runId, cmd.seq);
       if (checkpoint && checkpoint.status !== "pending") {
         setTimeout(() => {
-          void this.resume(runId).catch(() => void 0);
+          void this.resumeImplicit(runId).catch(() => void 0);
         }, 0).unref?.();
         return;
       }
@@ -6081,7 +6170,7 @@ var WorkflowEngine = class {
             kind: "signal",
             output: payload
           }));
-          setTimeout(() => void this.resume(run.id).catch(() => void 0), 0);
+          setTimeout(() => void this.resumeImplicit(run.id).catch(() => void 0), 0);
         }, "deliverBuffered");
         const buffered = await this.store.takeBufferedSignal(cmd.signal);
         if (buffered) {
@@ -6895,7 +6984,7 @@ var WorkflowEngine = class {
       queueMs: startedAt.getTime() - cp.enqueuedAt.getTime(),
       durationMs: finishedAt.getTime() - startedAt.getTime()
     });
-    await this.resume(result.runId).catch((err) => {
+    await this.resumeImplicit(result.runId).catch((err) => {
       if (err instanceof NamespaceMismatch) return null;
       throw err;
     });
@@ -6996,7 +7085,7 @@ var WorkflowEngine = class {
       ...waiters
     ];
     waiters.clear();
-    for (const runId of runIds) void this.resume(runId).catch(() => void 0);
+    for (const runId of runIds) void this.resumeImplicit(runId).catch(() => void 0);
   }
   /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
   async releaseQueueSlot(id) {
@@ -8149,6 +8238,7 @@ var InMemoryTransport = class {
   InMemoryTransport,
   LEGACY_V1_CAPABILITIES,
   LEGACY_V1_PROTOCOL,
+  NestedWorkflowCallError,
   NonDeterminismError,
   QueueController,
   RUN_VALUE_FACET_LIMIT,
@@ -8195,6 +8285,7 @@ var InMemoryTransport = class {
   coveredTokens,
   createStepLogger,
   currentStep,
+  currentStepScope,
   currentWorkflowCtx,
   debug,
   describeWorker,
@@ -8236,7 +8327,9 @@ var InMemoryTransport = class {
   resolveRunWaiting,
   runDurableExecution,
   runInStepLogger,
+  runInStepScope,
   runInWorkflowCtx,
+  runOutsideWorkflowCtx,
   runSchedules,
   runStepHandler,
   runValueFacetsFromRuns,