@dudousxd/nestjs-durable-core 0.49.3 → 0.50.0

package/dist/index.cjs

@@ -71,6 +71,7 @@ __export(index_exports, {
   normalizeAttributeRows: () => normalizeAttributeRows,
   parseDuration: () => parseDuration,
   prevCronFireMs: () => prevCronFireMs,
+  readSearchAttributes: () => readSearchAttributes,
   resolveRunWaiting: () => resolveRunWaiting,
   runInWorkflowCtx: () => runInWorkflowCtx,
   runSchedules: () => runSchedules,
@@ -1185,6 +1186,11 @@ function normalizeChildOptions(options) {
   } : options ?? {};
 }
 __name(normalizeChildOptions, "normalizeChildOptions");
+function formatIssuePath(path) {
+  if (!path || path.length === 0) return "(root)";
+  return path.map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
+}
+__name(formatIssuePath, "formatIssuePath");
 function resolveStepPolicy(config, opts) {
   const policy = {};
   const retries = opts?.retries ?? config?.retries;
@@ -1215,7 +1221,7 @@ var Position = class Position2 {
     this.seq -= 1;
   }
 };
-function createWorkflowCtx(host, runId, compensations, workflow = "") {
+function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttributesSchema) {
   const { store, replay } = host;
   const pos = new Position();
   const readCheckpoint = /* @__PURE__ */ __name((seq) => {
@@ -1684,6 +1690,24 @@ function createWorkflowCtx(host, runId, compensations, workflow = "") {
       }
       return;
     }
+    if (searchAttributesSchema) {
+      const run = await store.getRun(runId);
+      const merged = {
+        ...run?.searchAttributes ?? {},
+        ...attrs
+      };
+      const result = searchAttributesSchema["~standard"].validate(merged);
+      if (result instanceof Promise) {
+        throw new Error(`workflow "${workflow}": ctx.upsertSearchAttributes schema validation must be synchronous (the searchAttributes schema's \`~standard.validate\` returned a Promise) \u2014 replay-determinism requires a sync validator; drop any async refinement from the schema passed to @Workflow({ searchAttributes }).`);
+      }
+      if (result.issues) {
+        const offendingKeys = [
+          ...new Set(result.issues.map((issue) => formatIssuePath(issue.path)))
+        ];
+        const details = result.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`).join("; ");
+        throw new Error(`workflow "${workflow}": ctx.upsertSearchAttributes rejected by its searchAttributes schema \u2014 offending key(s) ${offendingKeys.join(", ")} \u2014 ${details}`);
+      }
+    }
     await host.upsertSearchAttributes(runId, attrs);
     await writeCheckpoint(instantCheckpoint({
       runId,
@@ -1814,6 +1838,8 @@ var WorkflowEngine = class {
   maxRecoveryAttempts;
   remoteAdvanceSilenceMs;
   reconcileMs;
+  remoteRedispatchMs;
+  remoteRedispatchMax;
   webhookUrl;
   traceparent;
   context;
@@ -1885,6 +1911,8 @@ var WorkflowEngine = class {
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
     this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
+    this.remoteRedispatchMs = deps.remoteRedispatchMs || void 0;
+    this.remoteRedispatchMax = Math.max(1, deps.remoteRedispatchMax ?? 10);
     this.webhookUrl = deps.webhookUrl;
     this.traceparent = deps.traceparent;
     this.context = deps.context;
@@ -2035,6 +2063,7 @@ var WorkflowEngine = class {
       singleton: opts?.singleton,
       executionTimeoutMs: opts?.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
       validateInput: opts?.validateInput,
+      searchAttributesSchema: opts?.searchAttributesSchema,
       onEvent: opts?.onEvent,
       eventBatch: opts?.eventBatch,
       // A real, retained in-process body — so `workflowBody` can hand it to an in-app worker, and so
@@ -2596,6 +2625,49 @@ var WorkflowEngine = class {
     };
   }
   /**
+  * Explicitly re-dispatch every remote step of `runId` stuck `pending` — the OPERATOR escape hatch for
+  * a run whose dispatched step job was LOST (worker crashed with no result, or a transport that dropped
+  * the job). No automatic recovery re-drives these: a reconcile re-drive re-suspends a still-pending
+  * step by design (unless `remoteRedispatchMs` is set), `recoverIncomplete` only reclaims LEASED runs,
+  * and `requeue` just replays back to the pending guard. This re-enqueues the same `stepId` so the
+  * (idempotent) step re-runs and its result resumes the run. Safe to call on a healthy run — it re-runs
+  * only in-flight `pending` remote steps, which are idempotent by the durable contract. Returns the
+  * run's current status (with the count re-dispatched), or null if the run is unknown.
+  */
+  async redispatchPending(runId) {
+    const run = await this.store.getRun(runId);
+    if (!run) return null;
+    const pending = (await this.store.listCheckpoints(runId)).filter((cp) => cp.kind === "remote" && cp.status === "pending");
+    let redispatched = 0;
+    for (const cp of pending) {
+      if (!cp.stepId) continue;
+      const reAttempt = cp.attempts + 1;
+      const reEnqueuedAt = /* @__PURE__ */ new Date();
+      await this.store.saveCheckpoint({
+        ...cp,
+        attempts: reAttempt,
+        enqueuedAt: reEnqueuedAt,
+        startedAt: reEnqueuedAt,
+        finishedAt: reEnqueuedAt
+      });
+      await this.dispatchRemoteTask({
+        runId,
+        seq: cp.seq,
+        name: cp.name,
+        stepId: cp.stepId,
+        group: cp.workerGroup ?? sanitizeQueueToken(cp.name),
+        input: cp.input,
+        attempt: reAttempt
+      });
+      redispatched += 1;
+    }
+    return {
+      runId,
+      status: run.status,
+      redispatched
+    };
+  }
+  /**
   * **Fix-and-replay**: re-run a run (typically a `dead`/`failed` one) with a corrected `input`, as a
   * fresh run with clean history. It's a NEW run — `newRunId` defaults to `<runId>~retry~<uuid>` — so
   * the original stays inspectable. Returns the new run's id, or null if `runId` is unknown.
@@ -3691,7 +3763,7 @@ var WorkflowEngine = class {
     const snapshot = await this.store.listCheckpoints(run.id);
     const replay = /* @__PURE__ */ new Map();
     for (const cp of snapshot) replay.set(cp.seq, cp);
-    const ctx = createWorkflowCtx(this.ctxHostFor(replay, run.namespace), run.id, compensations, run.workflow);
+    const ctx = createWorkflowCtx(this.ctxHostFor(replay, run.namespace), run.id, compensations, run.workflow, registered?.searchAttributesSchema);
     try {
       const output = await runInWorkflowCtx(ctx, () => fn(ctx, run.input));
       if (this.cancelRequested.has(run.id)) {
@@ -4083,7 +4155,47 @@ var WorkflowEngine = class {
     if (existing?.status === "completed") return existing.output;
     if (this.pool.size === 0) throw new Error("remote steps require a Transport");
     if (step.timeoutMs) return this.callRemoteInMemory(runId, seq, step, input, transport);
-    if (existing?.status === "pending") throw new WorkflowSuspended();
+    if (existing?.status === "pending") {
+      if (this.remoteRedispatchMs == null) throw new WorkflowSuspended();
+      if (existing.wakeAt == null) {
+        const wakeAt = this.clock() + this.remoteRedispatchMs;
+        await this.store.saveCheckpoint({
+          ...existing,
+          wakeAt
+        });
+        throw new WorkflowSuspended(wakeAt);
+      }
+      if (this.clock() < existing.wakeAt) throw new WorkflowSuspended(existing.wakeAt);
+      if (existing.attempts >= this.remoteRedispatchMax) {
+        throw new RemoteStepError({
+          message: `remote step "${step.name}" lost \u2014 no result after ${existing.attempts} re-dispatch(es)`,
+          code: "remote_step_lost"
+        });
+      }
+      const reAttempt = existing.attempts + 1;
+      const nextDeadline = this.clock() + this.remoteRedispatchMs;
+      const reEnqueuedAt = /* @__PURE__ */ new Date();
+      await this.store.saveCheckpoint({
+        ...existing,
+        attempts: reAttempt,
+        wakeAt: nextDeadline,
+        enqueuedAt: reEnqueuedAt,
+        startedAt: reEnqueuedAt,
+        finishedAt: reEnqueuedAt
+      });
+      await this.dispatchRemoteTask({
+        runId,
+        seq,
+        name: step.name,
+        stepId: existing.stepId ?? stepId(runId, seq),
+        group: existing.workerGroup ?? tenantGroup(sanitizeQueueToken(step.name), step.partition),
+        input: existing.input,
+        priority: admission?.priority,
+        attempt: reAttempt,
+        transport
+      });
+      throw new WorkflowSuspended(nextDeadline);
+    }
     let attempt = 1;
     if (existing?.status === "failed") {
       const maxAttempts = Math.max(1, step.retries ?? 1);
@@ -4131,18 +4243,17 @@ var WorkflowEngine = class {
       startedAt: enqueuedAt,
       finishedAt: enqueuedAt
     });
-    await this.pool.dispatch({
+    await this.dispatchRemoteTask({
       runId,
       seq,
       name: step.name,
       stepId: id,
       group: tenantGroup(sanitizeQueueToken(step.name), step.partition),
       input,
-      traceparent: this.traceparent?.(),
-      context: this.context?.(),
       priority: admission?.priority,
-      attempt
-    }, transport);
+      attempt,
+      transport
+    });
     this.emit({
       type: "step.started",
       runId,
@@ -4152,6 +4263,23 @@ var WorkflowEngine = class {
     });
     throw new WorkflowSuspended();
   }
+  /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
+  *  dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
+  *  {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
+  dispatchRemoteTask(task) {
+    return this.pool.dispatch({
+      runId: task.runId,
+      seq: task.seq,
+      name: task.name,
+      stepId: task.stepId,
+      group: task.group,
+      input: task.input,
+      traceparent: this.traceparent?.(),
+      context: this.context?.(),
+      priority: task.priority,
+      attempt: task.attempt
+    }, task.transport);
+  }
   /**
   * Complete a durable remote step from its worker result and resume the run — runs on whichever
   * instance receives the result (the dispatching one may be gone), so the run is crash/scale-safe.
@@ -4391,12 +4519,17 @@ var TERMINAL_RUN_STATUSES = [
 // 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)
@@ -4817,6 +4950,19 @@ function attributeOperand(filter) {
 }
 __name(attributeOperand, "attributeOperand");
 
+// src/search-attributes-schema.ts
+function readSearchAttributes(schema, run) {
+  const result = schema["~standard"].validate(run.searchAttributes ?? {});
+  if (result instanceof Promise) {
+    throw new Error("readSearchAttributes: schema validation must be synchronous (the searchAttributes schema's `~standard.validate` returned a Promise) \u2014 async Standard Schema validators are not supported.");
+  }
+  if (result.issues) {
+    return {};
+  }
+  return result.value;
+}
+__name(readSearchAttributes, "readSearchAttributes");
+
 // src/tokens.ts
 var STATE_STORE = Symbol.for("nestjs-durable:STATE_STORE");
 var TRANSPORT = Symbol.for("nestjs-durable:TRANSPORT");
@@ -5193,6 +5339,7 @@ var InMemoryTransport = class {
   normalizeAttributeRows,
   parseDuration,
   prevCronFireMs,
+  readSearchAttributes,
   resolveRunWaiting,
   runInWorkflowCtx,
   runSchedules,