@dudousxd/nestjs-durable-testing 0.19.1 → 0.21.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AdmissionBackend, StateStore, RunStatus, WorkflowEngine, InMemoryStateStore, InMemoryTransport, RunResult, WorkflowRef, StartOptions, WorkflowRun, StepCheckpoint, Transport } from '@dudousxd/nestjs-durable-core';
+export { RUN_HISTORY_FIXTURE_VERSION } from '@dudousxd/nestjs-durable-core';
 
 /**
  * Builds an {@link AdmissionBackend} bound to the given test clock. Implementations that hold their
@@ -184,6 +185,34 @@ interface RunHistory {
     run: WorkflowRun;
     checkpoints: StepCheckpoint[];
 }
+
+/**
+ * Capture a run's replayable history (the run row + its full checkpoint timeline) from anything with
+ * the read API: a `WorkflowEngine`, or a bare `StateStore` (the CLI's `durable export` uses the
+ * store). The fixture half of the {@link assertReplayable} loop: capture a representative run,
+ * commit it with {@link serializeRunHistory}, and assert it in CI via {@link parseRunHistory}.
+ * Returns `null` for an unknown run.
+ */
+declare function captureHistory(source: {
+    getRun(runId: string): Promise<WorkflowRun | null | undefined>;
+    listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+}, runId: string): Promise<RunHistory | null>;
+/**
+ * Serialize a captured history as a pretty-printed JSON fixture (with a trailing newline, so it
+ * commits cleanly). Read it back with {@link parseRunHistory}.
+ */
+declare function serializeRunHistory(history: RunHistory): string;
+/**
+ * Parse a committed fixture (what {@link serializeRunHistory} / `durable export` writes) back into a
+ * {@link RunHistory}, reviving the `Date` fields JSON flattened to ISO strings, so
+ * `assertReplayable(register, parseRunHistory(readFileSync('fixture.json', 'utf8')))` just works.
+ *
+ * Throws on a fixture whose `version` is not {@link RUN_HISTORY_FIXTURE_VERSION}: a fixture written
+ * in another format would otherwise replay against the wrong shape. A fixture with NO `version` (a
+ * hand-built `{ run, checkpoints }`, the shape these docs showed before the marker existed) is read
+ * as version 1.
+ */
+declare function parseRunHistory(json: string): RunHistory;
 /**
  * Replay a recorded run's history against the CURRENT workflow code and throw if they diverged.
  *
@@ -288,4 +317,4 @@ declare function aggregationFixture(): StepCheckpoint[];
  */
 declare function registerCheckpointAggregationCases(t: (label: string, fn: () => Promise<void>) => void, getStore: () => StateStore, run: (over?: Partial<WorkflowRun>) => WorkflowRun): void;
 
-export { type AdmissionBackendFactory, DURABLE_CANONICAL_COLUMNS, type DurableColumnMap, type DurableColumnMismatch, type HandleableTransport, MutableClock, type RunHistory, type StateStoreContext, type StateStoreFactory, StateStoreUnavailableError, type TestEngine, aggregationFixture, assertDurableColumns, assertOutput, assertReplayable, assertRunStatus, assertStepAttempts, assertStepsRan, assertTransportConformance, createTestEngine, failOnce, failTimes, preserveColumnExpectation, recordedSteps, registerCheckpointAggregationCases, runAdmissionBackendContract, runStateStoreContract };
+export { type AdmissionBackendFactory, DURABLE_CANONICAL_COLUMNS, type DurableColumnMap, type DurableColumnMismatch, type HandleableTransport, MutableClock, type RunHistory, type StateStoreContext, type StateStoreFactory, StateStoreUnavailableError, type TestEngine, aggregationFixture, assertDurableColumns, assertOutput, assertReplayable, assertRunStatus, assertStepAttempts, assertStepsRan, assertTransportConformance, captureHistory, createTestEngine, failOnce, failTimes, parseRunHistory, preserveColumnExpectation, recordedSteps, registerCheckpointAggregationCases, runAdmissionBackendContract, runStateStoreContract, serializeRunHistory };

package/dist/index.js

@@ -375,7 +375,50 @@ function createTestEngine() {
 __name(createTestEngine, "createTestEngine");
 
 // src/replay.ts
-import { InMemoryStateStore as InMemoryStateStore2, WorkflowEngine as WorkflowEngine2 } from "@dudousxd/nestjs-durable-core";
+import { InMemoryStateStore as InMemoryStateStore2, RUN_HISTORY_FIXTURE_VERSION, WorkflowEngine as WorkflowEngine2 } from "@dudousxd/nestjs-durable-core";
+async function captureHistory(source, runId) {
+  const run2 = await source.getRun(runId);
+  if (!run2) return null;
+  return {
+    run: run2,
+    checkpoints: await source.listCheckpoints(runId)
+  };
+}
+__name(captureHistory, "captureHistory");
+function serializeRunHistory(history) {
+  return `${JSON.stringify({
+    version: RUN_HISTORY_FIXTURE_VERSION,
+    ...history
+  }, null, 2)}
+`;
+}
+__name(serializeRunHistory, "serializeRunHistory");
+function parseRunHistory(json) {
+  const raw = JSON.parse(json);
+  if (!raw || typeof raw !== "object" || !raw.run || !Array.isArray(raw.checkpoints)) {
+    throw new Error("not a run history fixture: expected { run, checkpoints }");
+  }
+  if (raw.version !== void 0 && raw.version !== RUN_HISTORY_FIXTURE_VERSION) {
+    throw new Error(`unsupported run history fixture version ${JSON.stringify(raw.version)} (this kit reads version ${RUN_HISTORY_FIXTURE_VERSION}); re-export the fixture or upgrade @dudousxd/nestjs-durable-testing`);
+  }
+  const date = /* @__PURE__ */ __name((v) => new Date(v), "date");
+  const run2 = {
+    ...raw.run,
+    createdAt: date(raw.run.createdAt),
+    updatedAt: date(raw.run.updatedAt)
+  };
+  const checkpoints = raw.checkpoints.map((cp2) => ({
+    ...cp2,
+    enqueuedAt: date(cp2.enqueuedAt),
+    startedAt: date(cp2.startedAt),
+    finishedAt: date(cp2.finishedAt)
+  }));
+  return {
+    run: run2,
+    checkpoints
+  };
+}
+__name(parseRunHistory, "parseRunHistory");
 async function assertReplayable(register, history) {
   const store = new InMemoryStateStore2();
   await store.createRun({
@@ -399,7 +442,7 @@ async function assertReplayable(register, history) {
 __name(assertReplayable, "assertReplayable");
 
 // src/state-store-conformance.ts
-import { SINGLETON_ADMITTED_TAG, WorkflowEngine as WorkflowEngine3 } from "@dudousxd/nestjs-durable-core";
+import { SINGLETON_ADMITTED_TAG, SINGLETON_TRACKED_TAG, WorkflowEngine as WorkflowEngine3 } from "@dudousxd/nestjs-durable-core";
 import { beforeEach, describe as describe2, expect as expect3, it as it2 } from "vitest";
 
 // src/checkpoint-aggregation-contract.ts
@@ -932,7 +975,8 @@ function runStateStoreContract(name, makeStore) {
         await store.createRun(run({
           id,
           tags: [
-            "singleton:k"
+            "singleton:k",
+            SINGLETON_TRACKED_TAG
           ]
         }));
       }
@@ -1021,6 +1065,134 @@ function runStateStoreContract(name, makeStore) {
       }));
       expect3(await claim("other-workflow", "singleton:k", "other")).toBe(true);
     });
+    const created = /* @__PURE__ */ __name((offset) => new Date(at.getTime() + offset * 1e3), "created");
+    t("singleton admission counts an untagged pre-0.73 holder (rolling upgrade)", async () => {
+      const claim = /* @__PURE__ */ __name((id, wakeAt) => store.tryAdmitSingleton?.(id, "singleton:k", "checkout", 1, wakeAt), "claim");
+      await store.createRun(run({
+        id: "legacy",
+        tags: [
+          "singleton:k"
+        ],
+        createdAt: created(1)
+      }));
+      await store.createRun(run({
+        id: "new",
+        tags: [
+          "singleton:k",
+          SINGLETON_TRACKED_TAG
+        ],
+        createdAt: created(0)
+      }));
+      expect3(await claim("new", 12e3)).toBe(false);
+      expect3(await store.getRun("new")).toMatchObject({
+        status: "suspended",
+        wakeAt: 12e3
+      });
+      expect3((await store.getRun("new"))?.tags).toContain(SINGLETON_TRACKED_TAG);
+      await store.updateRun("legacy", {
+        status: "suspended",
+        wakeAt: 2e4
+      });
+      expect3(await claim("new")).toBe(false);
+      await store.updateRun("legacy", {
+        status: "completed"
+      });
+      expect3(await claim("new")).toBe(true);
+      expect3((await store.getRun("new"))?.tags).toEqual([
+        "singleton:k",
+        SINGLETON_ADMITTED_TAG
+      ]);
+      await store.updateRun("new", {
+        status: "completed"
+      });
+      expect3((await store.getRun("new"))?.tags).toEqual([
+        "singleton:k"
+      ]);
+    });
+    t("legacy singleton waiters keep their FIFO place across the upgrade", async () => {
+      const claim = /* @__PURE__ */ __name((id) => store.tryAdmitSingleton?.(id, "singleton:k", "checkout", 1), "claim");
+      await store.createRun(run({
+        id: "holder",
+        tags: [
+          "singleton:k"
+        ],
+        createdAt: created(0)
+      }));
+      await store.createRun(run({
+        id: "old-waiter",
+        status: "suspended",
+        wakeAt: 5e3,
+        tags: [
+          "singleton:k"
+        ],
+        createdAt: created(1)
+      }));
+      await store.createRun(run({
+        id: "new-run",
+        tags: [
+          "singleton:k",
+          SINGLETON_TRACKED_TAG
+        ],
+        createdAt: created(2)
+      }));
+      expect3(await claim("new-run")).toBe(false);
+      expect3(await claim("old-waiter")).toBe(false);
+      expect3(await store.tryAdmitSingleton?.("old-waiter", "singleton:k", "checkout", 1, 6e3)).toBe(false);
+      expect3((await store.getRun("old-waiter"))?.tags).toContain(SINGLETON_TRACKED_TAG);
+      await store.updateRun("holder", {
+        status: "completed"
+      });
+      expect3(await claim("new-run")).toBe(false);
+      expect3(await claim("old-waiter")).toBe(true);
+      expect3(await claim("new-run")).toBe(false);
+      await store.updateRun("old-waiter", {
+        status: "completed"
+      });
+      expect3(await claim("new-run")).toBe(true);
+    });
+    t("concurrent claims never over-admit beside an untagged legacy holder", async () => {
+      await store.createRun(run({
+        id: "legacy",
+        tags: [
+          "singleton:k"
+        ],
+        createdAt: created(0)
+      }));
+      const ids2 = [
+        "c1",
+        "c2",
+        "c3",
+        "c4"
+      ];
+      for (const [i, id] of ids2.entries()) {
+        await store.createRun(run({
+          id,
+          tags: [
+            "singleton:k",
+            SINGLETON_TRACKED_TAG
+          ],
+          createdAt: created(i + 1)
+        }));
+      }
+      const results = await Promise.all([
+        ...ids2
+      ].reverse().map((id, i) => (i % 2 ? peerStore : store).tryAdmitSingleton?.(id, "singleton:k", "checkout", 2)));
+      expect3(results).toEqual([
+        false,
+        false,
+        false,
+        true
+      ]);
+      const active = await store.listRuns({
+        workflow: "checkout",
+        statuses: [
+          "running"
+        ]
+      });
+      expect3(active.filter((r) => r.tags?.includes(SINGLETON_ADMITTED_TAG)).map((r) => r.id)).toEqual([
+        "c1"
+      ]);
+    });
     t("creates a run and reads it back with its JSON input", async () => {
       await store.createRun(run());
       const loaded = await store.getRun("r1");
@@ -1501,40 +1673,40 @@ function runStateStoreContract(name, makeStore) {
     t("listOrphanedRuns returns incomplete runs with a free or expired lease, oldest first", async () => {
       expect3(store.listOrphanedRuns).toBeDefined();
       if (!store.listOrphanedRuns) return;
-      const created = /* @__PURE__ */ __name((offset) => new Date(at.getTime() + offset * 1e3), "created");
+      const created2 = /* @__PURE__ */ __name((offset) => new Date(at.getTime() + offset * 1e3), "created");
       await store.createRun(run({
         id: "held",
-        createdAt: created(1)
+        createdAt: created2(1)
       }));
       expect3(await store.tryLockRun("held", "live", NOW + 3e4, NOW)).toBe(true);
       await store.createRun(run({
         id: "expired",
-        createdAt: created(3)
+        createdAt: created2(3)
       }));
       expect3(await store.tryLockRun("expired", "dead", NOW, NOW - 1)).toBe(true);
       await store.createRun(run({
         id: "free",
-        createdAt: created(2)
+        createdAt: created2(2)
       }));
       await store.createRun(run({
         id: "compensating",
         status: "cancelling",
-        createdAt: created(4)
+        createdAt: created2(4)
       }));
       await store.createRun(run({
         id: "parked",
         status: "suspended",
-        createdAt: created(0)
+        createdAt: created2(0)
       }));
       await store.createRun(run({
         id: "done",
         status: "completed",
-        createdAt: created(0)
+        createdAt: created2(0)
       }));
       await store.createRun(run({
         id: "tenant",
         namespace: "beta",
-        createdAt: created(5)
+        createdAt: created2(5)
       }));
       expect3((await store.listOrphanedRuns(NOW, 10)).map((r) => r.id)).toEqual([
         "free",
@@ -1552,6 +1724,50 @@ function runStateStoreContract(name, makeStore) {
       expect3((await store.listOrphanedRuns(NOW + 3e4, 10)).map((r) => r.id)).toContain("held");
       expect3(await store.listOrphanedRuns(NOW, 0)).toEqual([]);
     });
+    t("listOrphanedRuns also returns the owner's live leases taken before its cutoff", async () => {
+      if (!store.listOrphanedRuns) return;
+      const created2 = /* @__PURE__ */ __name((offset) => new Date(at.getTime() + offset * 1e3), "created");
+      await store.createRun(run({
+        id: "own-old",
+        createdAt: created2(1)
+      }));
+      expect3(await store.tryLockRun("own-old", "pod-a", NOW + 1e4, NOW)).toBe(true);
+      await store.createRun(run({
+        id: "own-new",
+        createdAt: created2(2)
+      }));
+      expect3(await store.tryLockRun("own-new", "pod-a", NOW + 3e4, NOW)).toBe(true);
+      await store.createRun(run({
+        id: "foreign",
+        createdAt: created2(3)
+      }));
+      expect3(await store.tryLockRun("foreign", "pod-b", NOW + 1e4, NOW)).toBe(true);
+      await store.createRun(run({
+        id: "own-parked",
+        status: "suspended",
+        createdAt: created2(4)
+      }));
+      expect3(await store.tryLockRun("own-parked", "pod-a", NOW + 1e4, NOW)).toBe(true);
+      await store.createRun(run({
+        id: "free",
+        createdAt: created2(5)
+      }));
+      const ownedBy = {
+        owner: "pod-a",
+        lockedBefore: NOW + 3e4
+      };
+      expect3((await store.listOrphanedRuns(NOW, 10)).map((r) => r.id)).toEqual([
+        "free"
+      ]);
+      expect3((await store.listOrphanedRuns(NOW, 10, void 0, ownedBy)).map((r) => r.id)).toEqual([
+        "own-old",
+        "free"
+      ]);
+      expect3((await store.listOrphanedRuns(NOW, 1, void 0, ownedBy)).map((r) => r.id)).toEqual([
+        "own-old"
+      ]);
+      expect3((await store.listOrphanedRuns(NOW, 10, "beta", ownedBy)).map((r) => r.id)).toEqual([]);
+    });
     t("updateRunIf writes only over an expected status", async () => {
       expect3(store.updateRunIf).toBeDefined();
       if (!store.updateRunIf) return;
@@ -2141,6 +2357,18 @@ function runStateStoreContract(name, makeStore) {
       await store.releaseRunLock("r1");
       expect3(await store.tryLockRun("r1", "C", 9e3, 2600)).toBe(true);
     });
+    t("releaseRunLock with an owner clears only a lease that owner still holds", async () => {
+      await store.createRun(run({
+        id: "r1"
+      }));
+      expect3(await store.tryLockRun("r1", "A", 2e3, 1e3)).toBe(true);
+      expect3(await store.tryLockRun("r1", "B", 4e3, 2500)).toBe(true);
+      await store.releaseRunLock("r1", "A");
+      expect3(await store.tryLockRun("r1", "C", 9e3, 3e3)).toBe(false);
+      expect3((await store.getRun("r1"))?.lockedBy).toBe("B");
+      await store.releaseRunLock("r1", "B");
+      expect3(await store.tryLockRun("r1", "C", 9e3, 3e3)).toBe(true);
+    });
     t("renewRunLock only succeeds for the current owner", async () => {
       await store.createRun(run({
         id: "r1"
@@ -3894,6 +4122,77 @@ function runStateStoreContract(name, makeStore) {
       })).rejects.toThrow(/vwf@9 is not registered/);
       expect3(await store.getRun("ghost-run")).toBeNull();
     });
+    t("times out every unfinished run of its workflow and namespace, except one compensating", async () => {
+      const engine = new WorkflowEngine3({
+        store,
+        namespace: "alpha"
+      });
+      engine.register("t-capped", "1", async () => void 0, {
+        executionTimeout: "1h"
+      });
+      const old = {
+        workflow: "t-capped",
+        namespace: "alpha",
+        createdAt: /* @__PURE__ */ new Date(1e3)
+      };
+      await store.createRun(run({
+        ...old,
+        id: "tc-pending",
+        status: "pending"
+      }));
+      await store.createRun(run({
+        ...old,
+        id: "tc-running",
+        status: "running"
+      }));
+      await store.createRun(run({
+        ...old,
+        id: "tc-suspended",
+        status: "suspended"
+      }));
+      await store.createRun(run({
+        ...old,
+        id: "tc-blocked",
+        status: "blocked"
+      }));
+      await store.createRun(run({
+        ...old,
+        id: "tc-cancelling",
+        status: "cancelling"
+      }));
+      await store.createRun(run({
+        ...old,
+        id: "tc-done",
+        status: "completed"
+      }));
+      await store.createRun(run({
+        ...old,
+        id: "tc-other-tenant",
+        status: "pending",
+        namespace: "beta"
+      }));
+      await store.createRun(run({
+        ...old,
+        id: "tc-other-workflow",
+        status: "pending",
+        workflow: "t-uncapped"
+      }));
+      await engine.sweepTimeouts(1e3 + 37e5);
+      for (const id of [
+        "tc-pending",
+        "tc-running",
+        "tc-suspended",
+        "tc-blocked"
+      ]) {
+        const swept = await store.getRun(id);
+        expect3(swept?.status, id).toBe("cancelled");
+        expect3(swept?.error?.code, id).toBe("execution_timeout");
+      }
+      expect3((await store.getRun("tc-cancelling"))?.status).toBe("cancelling");
+      expect3((await store.getRun("tc-done"))?.status).toBe("completed");
+      expect3((await store.getRun("tc-other-tenant"))?.status).toBe("pending");
+      expect3((await store.getRun("tc-other-workflow"))?.status).toBe("pending");
+    });
     t("cancels a timed-out run\u2019s live child subtree, not just the run itself", async () => {
       const engine = new WorkflowEngine3({
         store
@@ -3995,6 +4294,7 @@ __name(assertTransportConformance, "assertTransportConformance");
 export {
   DURABLE_CANONICAL_COLUMNS,
   MutableClock,
+  RUN_HISTORY_FIXTURE_VERSION,
   StateStoreUnavailableError,
   aggregationFixture,
   assertDurableColumns,
@@ -4004,13 +4304,16 @@ export {
   assertStepAttempts,
   assertStepsRan,
   assertTransportConformance,
+  captureHistory,
   createTestEngine,
   failOnce,
   failTimes,
+  parseRunHistory,
   preserveColumnExpectation,
   recordedSteps,
   registerCheckpointAggregationCases,
   runAdmissionBackendContract,
-  runStateStoreContract
+  runStateStoreContract,
+  serializeRunHistory
 };
 //# sourceMappingURL=index.js.map