@kubun/plugin-workflow 0.14.1 → 0.15.1

package/lib/engine.d.ts

@@ -10,11 +10,12 @@ export type WorkflowEngineDeps = {
     now?: () => number;
     getRandomID?: GetRandomID;
     tickMs?: number;
+    disposeTimeoutMs?: number;
 };
 export type WorkflowEngine = {
     api: WorkflowAPI;
     recover(): Promise<Array<string>>;
     tick(): Promise<void>;
-    dispose(): void;
+    dispose(): Promise<void>;
 };
 export declare function createWorkflowEngine(deps: WorkflowEngineDeps): WorkflowEngine;

package/lib/engine.js

@@ -6,6 +6,8 @@ import { computeNextDelay, validateAdaptivePolicy } from './adaptive.js';
 const LEASE_MS = 30_000;
 // Default scheduler cadence; injectable via deps so tests drive `tick()` directly.
 const DEFAULT_TICK_MS = 1_000;
+// Default upper bound for dispose()'s best-effort drain of in-flight drives.
+const DEFAULT_DISPOSE_TIMEOUT_MS = 5_000;
 // Backoff for a failed attempt (1-based). `fixed` returns `baseMs`; `exponential`
 // doubles per attempt, capped at `maxMs`. Pure so it is unit-testable.
 export function backoff(attempts, policy) {
@@ -86,6 +88,9 @@ export function createWorkflowEngine(deps) {
     const running = new Map();
     // In-flight drives, tracked so nudges are not lost and errors are logged.
     const inflight = new Set();
+    // Set by dispose(): stops the scheduler from claiming/driving new work while
+    // the existing in-flight drives are drained.
+    let disposed = false;
     let storePromise;
     function store() {
         storePromise ??= deps.getStore();
@@ -342,13 +347,24 @@ export function createWorkflowEngine(deps) {
         }
     }
     async function tick() {
+        // After dispose() no new work is claimed: a straggler tick (a queued nudge
+        // or the interval firing before it was cleared) must not start fresh drives
+        // while shutdown drains the in-flight ones.
+        if (disposed) return;
         try {
             const s = await store();
+            // Re-check after every await that precedes a claim: dispose() may have run
+            // during the gap. Bailing here — rather than only at entry — is what keeps
+            // a tick that was already in-flight when dispose() fired from claiming and
+            // driving fresh work after shutdown began.
+            if (disposed) return;
             const at = now();
             // Promote due schedules first so their instances are claimable this pass.
             await promoteSchedules(s, at);
+            if (disposed) return;
             const lanes = await s.listRunnableQueues(at);
             for (const lane of lanes){
+                if (disposed) return;
                 const cap = laneConcurrency(lane) - await s.countRunning(lane, at);
                 if (cap <= 0) continue;
                 // Clamp to available tokens; consume only for rows actually claimed
@@ -357,6 +373,9 @@ export function createWorkflowEngine(deps) {
                 if (grant <= 0) continue;
                 const rows = await s.claimDue(lane, grant, bootID, LEASE_MS, at);
                 consumeTokens(lane, rows.length);
+                // If dispose() fired during claimDue, leave the just-claimed rows for
+                // crash-reclaim rather than starting drives no abort sweep will cancel.
+                if (disposed) return;
                 for (const row of rows)track(run(row));
             }
         } catch (cause) {
@@ -378,8 +397,12 @@ export function createWorkflowEngine(deps) {
         });
     }
     const tickMs = deps.tickMs ?? DEFAULT_TICK_MS;
+    const disposeTimeoutMs = deps.disposeTimeoutMs ?? DEFAULT_DISPOSE_TIMEOUT_MS;
     let interval = setInterval(()=>{
-        void tick();
+        // Tracked, not fire-and-forget: dispose()'s drain must be able to await an
+        // interval tick that is mid-pass, or its claim/promote writes could land
+        // after dispose() resolves and the store closes.
+        track(tick());
     }, tickMs);
     // Allow the process to exit even while the scheduler interval is pending.
     const intervalHandle = interval;
@@ -606,17 +629,68 @@ export function createWorkflowEngine(deps) {
             // resumes them. The returned ids are the pre-tick stranded set.
             const s = await store();
             const stranded = await s.listRecoverable(now());
-            await tick();
+            // Tracked like every other tick so a concurrent dispose() drains this
+            // pass's store writes rather than resolving out from under them.
+            const p = tick();
+            track(p);
+            await p;
             return stranded.map((r)=>r.instance_id);
         },
-        tick,
-        dispose () {
+        // Tracked so dispose()'s drain awaits a manual tick that is mid-pass; an
+        // untracked one could issue promote/claim writes after dispose() resolved.
+        tick: ()=>{
+            const p = tick();
+            track(p);
+            return p;
+        },
+        async dispose () {
+            disposed = true;
             if (interval != null) {
                 clearInterval(interval);
                 interval = null;
             }
+            // Abort every live drive, then drain to quiescence: an aborted run still
+            // issues its `cancelled` terminal write, and aborting frees a lane so a
+            // straggler drive may appear — so loop until nothing is in flight rather
+            // than awaiting a single snapshot. `disposed` keeps tick() from adding new
+            // work, so a cooperative drive set terminates. When the drain wins the
+            // race below, no scheduled write is still in flight and the caller can
+            // safely close the store.
             for (const controller of running.values())controller.abort();
             running.clear();
+            let drainedDone = false;
+            const drained = (async ()=>{
+                while(inflight.size > 0)await Promise.allSettled([
+                    ...inflight
+                ]);
+                drainedDone = true;
+            })();
+            // Bound the wait: a handler that never observes its abort signal leaves an
+            // un-settling drive in `inflight`, and an unbounded drain would wedge
+            // shutdown forever. Resolve best-effort on the deadline instead; the timer
+            // is unref'd so it never itself holds the process open. NOTE: on timeout,
+            // genuine writes may still be in flight, so a caller that then closes the
+            // store can race them — the deadline trades that residual for a bounded
+            // shutdown. It only fires when a drive is not settling, which is logged.
+            let timer;
+            const deadline = new Promise((resolve)=>{
+                timer = setTimeout(resolve, disposeTimeoutMs);
+                timer.unref?.();
+            });
+            try {
+                await Promise.race([
+                    drained,
+                    deadline
+                ]);
+            } finally{
+                if (timer != null) clearTimeout(timer);
+            }
+            if (!drainedDone) {
+                logger.warn('workflow dispose timed out draining in-flight drives', {
+                    inflight: inflight.size,
+                    disposeTimeoutMs
+                });
+            }
         }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/plugin-workflow",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,21 +15,21 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/db": "^0.14.0",
-    "@kubun/engine": "^0.14.1",
-    "@kubun/graphql": "^0.14.1",
-    "@kubun/id": "^0.14.0",
-    "@kubun/logger": "^0.14.0",
-    "@kubun/plugin-workflow-api": "^0.14.1",
-    "@kubun/store-workflow": "^0.14.1",
+    "@kubun/db": "^0.15.0",
+    "@kubun/engine": "^0.15.0",
+    "@kubun/graphql": "^0.15.0",
+    "@kubun/id": "^0.15.0",
+    "@kubun/logger": "^0.15.0",
+    "@kubun/plugin-workflow-api": "^0.15.0",
+    "@kubun/store-workflow": "^0.15.0",
     "@sozai/event": "^0.1.3",
     "@sozai/flow": "^0.3.1",
     "@sozai/runtime": "^0.1.0",
     "@sozai/schema": "^0.1.2"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.14.0",
-    "@kubun/db-postgres": "^0.14.0",
+    "@kubun/db-better-sqlite": "^0.15.0",
+    "@kubun/db-postgres": "^0.15.0",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {