@dudousxd/nestjs-durable-core 0.72.1 → 0.73.0

package/dist/index.cjs

@@ -56,6 +56,8 @@ __export(index_exports, {
   RemoteWorkflowExecutor: () => RemoteWorkflowExecutor,
   RemoteWorkflowTimeout: () => RemoteWorkflowTimeout,
   RunGateway: () => RunGateway,
+  SINGLETON_ACTIVE_STATUSES: () => SINGLETON_ACTIVE_STATUSES,
+  SINGLETON_ADMITTED_TAG: () => SINGLETON_ADMITTED_TAG,
   STATE_STORE: () => STATE_STORE,
   STATE_STORE_CANONICAL: () => STATE_STORE_CANONICAL,
   ScheduleAlreadyExistsError: () => ScheduleAlreadyExistsError,
@@ -86,6 +88,7 @@ __export(index_exports, {
   capableWorkers: () => capableWorkers,
   classifyWaiterToken: () => classifyWaiterToken,
   clearDurableExecutionWrappers: () => clearDurableExecutionWrappers,
+  clearTerminalSingletonAdmission: () => clearTerminalSingletonAdmission,
   collectMetrics: () => collectMetrics,
   concurrencyTag: () => concurrencyTag,
   controlPlaneDescriptor: () => controlPlaneDescriptor,
@@ -143,6 +146,8 @@ __export(index_exports, {
   runValueFacetsFromRuns: () => runValueFacetsFromRuns,
   sanitizeQueueToken: () => sanitizeQueueToken,
   scheduledRunId: () => scheduledRunId,
+  singletonAdmissionDenialPatch: () => singletonAdmissionDenialPatch,
+  singletonAdmissionTags: () => singletonAdmissionTags,
   sqlComparator: () => sqlComparator,
   stepConfigOf: () => stepConfigOf,
   stepId: () => stepId,
@@ -2444,6 +2449,54 @@ function errorMessage(error2) {
 }
 __name(errorMessage, "errorMessage");
 
+// src/singleton-admission.ts
+var SINGLETON_ADMITTED_TAG = "durable:singleton:admitted";
+var SINGLETON_ACTIVE_STATUSES = [
+  "pending",
+  "running",
+  "suspended",
+  "blocked",
+  "cancelling"
+];
+function singletonAdmissionTags(runs, runId, tag, workflow, limit) {
+  if (!Number.isInteger(limit) || limit < 1) throw new Error("singleton limit must be a positive integer");
+  const active = runs.filter((run) => run.workflow === workflow && SINGLETON_ACTIVE_STATUSES.includes(run.status) && run.tags?.includes(tag));
+  const candidate = active.find((run) => run.id === runId);
+  if (!candidate) return null;
+  if (candidate.tags?.includes(SINGLETON_ADMITTED_TAG)) return candidate.tags;
+  if (candidate.status === "cancelling") return null;
+  const holders = active.filter((run) => run.tags?.includes(SINGLETON_ADMITTED_TAG));
+  const remaining = limit - holders.length;
+  if (remaining <= 0) return null;
+  const waiters = active.filter((run) => !run.tags?.includes(SINGLETON_ADMITTED_TAG)).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
+  if (!waiters.slice(0, remaining).some((run) => run.id === runId)) return null;
+  return [
+    ...candidate.tags ?? [],
+    SINGLETON_ADMITTED_TAG
+  ];
+}
+__name(singletonAdmissionTags, "singletonAdmissionTags");
+async function clearTerminalSingletonAdmission(runId, patch, getRun) {
+  if (!patch.status || !TERMINAL_RUN_STATUSES.includes(patch.status)) return patch;
+  const tags = "tags" in patch ? patch.tags : (await getRun(runId))?.tags;
+  return {
+    ...patch,
+    tags: tags?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG)
+  };
+}
+__name(clearTerminalSingletonAdmission, "clearTerminalSingletonAdmission");
+function singletonAdmissionDenialPatch(runs, runId, tag, workflow, retryWakeAt) {
+  if (retryWakeAt === void 0) return void 0;
+  const candidate = runs.find((run) => run.id === runId && run.workflow === workflow && run.tags?.includes(tag) && SINGLETON_ACTIVE_STATUSES.includes(run.status));
+  if (!candidate || candidate.status === "cancelling") return void 0;
+  return {
+    status: "suspended",
+    wakeAt: retryWakeAt,
+    updatedAt: /* @__PURE__ */ new Date()
+  };
+}
+__name(singletonAdmissionDenialPatch, "singletonAdmissionDenialPatch");
+
 // src/singleton-gate.ts
 var SINGLETON_RETRY_MS = 1e3;
 var SINGLETON_RETRY_JITTER_MS = 250;
@@ -2457,6 +2510,9 @@ var SingletonGate = class {
   }
   /** The tag a singleton run carries, so the gate can find others sharing its key. */
   tag(cfg, input) {
+    if (!this.deps.store.tryAdmitSingleton) {
+      throw new Error("Singleton workflows require StateStore.tryAdmitSingleton for atomic durable admission");
+    }
     return `singleton:${cfg.key(input)}`;
   }
   /** Next wake time for a gated run: the base retry delay jittered to avoid a wakeup stampede. */
@@ -2465,7 +2521,7 @@ var SingletonGate = class {
   }
   /**
   * Reject a start that would grow the same-key backlog past `limit + maxQueueDepth` (counting
-  * `pending`/`running`/`suspended` runs sharing the key in one scan). No-op when no `maxQueueDepth`
+  * `pending`/`running`/`suspended`/`blocked`/`cancelling` runs sharing the key in one scan). No-op when no `maxQueueDepth`
   * is configured.
   */
   async assertCapacity(workflow, cfg, input) {
@@ -2474,34 +2530,25 @@ var SingletonGate = class {
     const queued = await this.deps.store.listRuns({
       tag: this.tag(cfg, input),
       workflow,
-      statuses: [
-        "pending",
-        "running",
-        "suspended",
-        "cancelling"
-      ]
+      statuses: SINGLETON_ACTIVE_STATUSES
     });
     if (queued.length >= cap) {
       throw new SingletonQueueFullError(workflow, cfg.key(input), cfg.maxQueueDepth);
     }
   }
-  /**
-  * Whether `run` may run now under its key: it's among the `limit` oldest in-flight (running or
-  * suspended) runs sharing the key, by `(createdAt, id)` order. A consistent store gives every
-  * instance the same ordering, so admission is race-free + FIFO.
-  */
+  /** Preserve durable holders and atomically claim one of the remaining slots. */
   async admit(run, cfg) {
-    const inflight = (await this.deps.store.listRuns({
-      tag: this.tag(cfg, run.input),
-      workflow: run.workflow,
-      statuses: [
-        "running",
-        "suspended",
-        "cancelling"
-      ]
-    })).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id));
-    const idx = inflight.findIndex((r) => r.id === run.id);
-    return idx >= 0 && idx < (cfg.limit ?? 1);
+    if (!this.deps.store.tryAdmitSingleton) {
+      throw new Error("Singleton workflows require StateStore.tryAdmitSingleton for atomic durable admission");
+    }
+    const admitted = await this.deps.store.tryAdmitSingleton(run.id, this.tag(cfg, run.input), run.workflow, cfg.limit ?? 1, this.retryWakeAt());
+    if (admitted && !run.tags?.includes(SINGLETON_ADMITTED_TAG)) {
+      run.tags = [
+        ...run.tags ?? [],
+        SINGLETON_ADMITTED_TAG
+      ];
+    }
+    return admitted;
   }
   /**
   * Notify-on-release: a singleton run settled (freeing a slot), so dispatch the oldest gated
@@ -4018,7 +4065,7 @@ var WorkflowEngine = class {
         VERSION_UNDECLARED_TAG
       ] : []
     ];
-    const tags = mergeTags(registered.tags, stampedTags);
+    const tags = mergeTags(registered.tags, stampedTags)?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG);
     if (registered.singleton) {
       await this.singletons.assertCapacity(name, registered.singleton, input);
     }
@@ -4093,6 +4140,12 @@ var WorkflowEngine = class {
       await this.store.releaseRunLock(runId);
       throw new NamespaceMismatch();
     }
+    if (run.status === "failed" && run.tags?.includes(SINGLETON_ADMITTED_TAG)) {
+      run.tags = run.tags.filter((tag) => tag !== SINGLETON_ADMITTED_TAG);
+      await this.store.updateRun(run.id, {
+        tags: run.tags
+      });
+    }
     const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run) ?? await this.resolveRemoteByConvention(run);
     if (!registered) {
       throw new Error(`workflow ${run.workflow}@${run.workflowVersion} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
@@ -4242,7 +4295,10 @@ var WorkflowEngine = class {
   /** Track an in-flight execution so {@link drain} can wait for it. */
   track(p) {
     this.inflight.add(p);
-    void p.finally(() => this.inflight.delete(p));
+    const done = /* @__PURE__ */ __name(() => {
+      this.inflight.delete(p);
+    }, "done");
+    void p.then(done, done);
     return p;
   }
   /**
@@ -4593,7 +4649,8 @@ var WorkflowEngine = class {
       status: "pending",
       error: void 0,
       ...resurrecting ? {
-        recoveryAttempts: 0
+        recoveryAttempts: 0,
+        tags: run.tags?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG)
       } : {},
       updatedAt: /* @__PURE__ */ new Date()
     });
@@ -4712,10 +4769,19 @@ var WorkflowEngine = class {
         off();
         resolve(toResult(run));
       }, "finish");
+      const fail = /* @__PURE__ */ __name((error2) => {
+        if (done) return;
+        done = true;
+        if (timer) clearTimeout(timer);
+        if (poller) clearInterval(poller);
+        off();
+        reject(error2);
+      }, "fail");
       const check = /* @__PURE__ */ __name(() => {
+        if (done) return;
         void this.store.getRun(runId).then((run) => {
           if (run && isSettled(run)) finish(run);
-        });
+        }, fail);
       }, "check");
       const poller = opts?.until === "terminal" ? (() => {
         const interval = setInterval(check, 250);
@@ -5498,6 +5564,26 @@ var WorkflowEngine = class {
       durationMs: Date.now() - step.startedAt.getTime()
     });
   }
+  /** Admission persists the wait atomically; never overwrite a cancellation after it returns. */
+  async singletonWaitResult(run) {
+    const current = await this.store.getRun(run.id);
+    await this.store.releaseRunLock(run.id);
+    if (!current) throw new Error(`run ${run.id} was deleted during singleton admission`);
+    if (current.status === "suspended") {
+      this.emit({
+        type: "run.suspended",
+        runId: current.id,
+        workflow: current.workflow,
+        namespace: current.namespace
+      });
+    }
+    return {
+      runId: current.id,
+      status: current.status,
+      output: current.output,
+      error: current.error
+    };
+  }
   async execute(run, fn) {
     const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run) ?? await this.resolveRemoteByConvention(run);
     const lockNow = this.clock();
@@ -5667,23 +5753,7 @@ var WorkflowEngine = class {
       });
     }
     if (registered.singleton && !await this.singletons.admit(run, registered.singleton)) {
-      const wakeAt = this.singletons.retryWakeAt();
-      await this.store.updateRun(run.id, {
-        status: "suspended",
-        wakeAt,
-        updatedAt: /* @__PURE__ */ new Date()
-      });
-      this.emit({
-        type: "run.suspended",
-        runId: run.id,
-        workflow: run.workflow,
-        namespace: run.namespace
-      });
-      await this.store.releaseRunLock(run.id);
-      return {
-        runId: run.id,
-        status: "suspended"
-      };
+      return this.singletonWaitResult(run);
     }
     const wfPlan = await this.planRoute(tenantGroup(sanitizeQueueToken(remote.group), void 0), registered.requires);
     if (wfPlan?.status === "blocked") return this.parkBlocked(run, wfPlan);
@@ -6297,23 +6367,7 @@ var WorkflowEngine = class {
       });
     }
     if (run.status !== "cancelling" && registered?.singleton && !await this.singletons.admit(run, registered.singleton)) {
-      const wakeAt = this.singletons.retryWakeAt();
-      await this.store.updateRun(run.id, {
-        status: "suspended",
-        wakeAt,
-        updatedAt: /* @__PURE__ */ new Date()
-      });
-      this.emit({
-        type: "run.suspended",
-        runId: run.id,
-        workflow: run.workflow,
-        namespace: run.namespace
-      });
-      await this.store.releaseRunLock(run.id);
-      return {
-        runId: run.id,
-        status: "suspended"
-      };
+      return this.singletonWaitResult(run);
     }
     const compensations = [];
     const snapshot = await this.store.listCheckpoints(run.id);
@@ -7332,6 +7386,8 @@ var CodecStateStore = class {
   }
   inner;
   codec;
+  /** Atomic claims touch only searchable metadata and bypass payload encoding. */
+  tryAdmitSingleton;
   /**
   * Forwarded verbatim — a facet cell counts `status`/`origin`, neither of which the codec touches
   * (it encodes payloads: input/output/error). Bound as a PROPERTY, and only when the inner store
@@ -7364,6 +7420,7 @@ var CodecStateStore = class {
   constructor(inner, codec) {
     this.inner = inner;
     this.codec = codec;
+    if (inner.tryAdmitSingleton) this.tryAdmitSingleton = inner.tryAdmitSingleton.bind(inner);
     const deleteRuns = inner.deleteRuns;
     if (deleteRuns) this.deleteRuns = (ids) => deleteRuns.call(inner, ids);
     const prune = inner.pruneTerminalRuns;
@@ -7816,6 +7873,28 @@ var InMemoryStateStore = class {
       byRun.set(runId, row);
     }
   }
+  async tryAdmitSingleton(runId, tag, workflow, limit, retryWakeAt) {
+    const runs = [
+      ...this.runs.values()
+    ];
+    const tags = singletonAdmissionTags(runs, runId, tag, workflow, limit);
+    if (!tags) {
+      const patch = singletonAdmissionDenialPatch(runs, runId, tag, workflow, retryWakeAt);
+      const candidate = this.runs.get(runId);
+      if (patch && candidate) this.runs.set(runId, {
+        ...candidate,
+        ...patch
+      });
+      return false;
+    }
+    const run = this.runs.get(runId);
+    if (!run) return false;
+    this.runs.set(runId, {
+      ...run,
+      tags
+    });
+    return true;
+  }
   async createRun(run) {
     this.runs.set(run.id, {
       ...run,
@@ -7823,7 +7902,11 @@ var InMemoryStateStore = class {
     });
     this.reindexAttributes(run.id, run.searchAttributes);
   }
-  async updateRun(runId, patch) {
+  async updateRun(runId, inputPatch) {
+    const patch = inputPatch.status && TERMINAL_RUN_STATUSES.includes(inputPatch.status) ? {
+      ...inputPatch,
+      tags: ("tags" in inputPatch ? inputPatch.tags : this.runs.get(runId)?.tags)?.filter((tag) => tag !== SINGLETON_ADMITTED_TAG)
+    } : inputPatch;
     const existing = this.runs.get(runId);
     if (!existing) throw new Error(`run ${runId} not found`);
     const next = {
@@ -8248,6 +8331,8 @@ var InMemoryTransport = class {
   RemoteWorkflowExecutor,
   RemoteWorkflowTimeout,
   RunGateway,
+  SINGLETON_ACTIVE_STATUSES,
+  SINGLETON_ADMITTED_TAG,
   STATE_STORE,
   STATE_STORE_CANONICAL,
   ScheduleAlreadyExistsError,
@@ -8278,6 +8363,7 @@ var InMemoryTransport = class {
   capableWorkers,
   classifyWaiterToken,
   clearDurableExecutionWrappers,
+  clearTerminalSingletonAdmission,
   collectMetrics,
   concurrencyTag,
   controlPlaneDescriptor,
@@ -8335,6 +8421,8 @@ var InMemoryTransport = class {
   runValueFacetsFromRuns,
   sanitizeQueueToken,
   scheduledRunId,
+  singletonAdmissionDenialPatch,
+  singletonAdmissionTags,
   sqlComparator,
   stepConfigOf,
   stepId,