@multiplier-labs/stepflow 0.3.6 → 0.3.8

package/dist/index.js

@@ -2,17 +2,19 @@ import {
   MemoryStorageAdapter,
   PostgresStorageAdapter,
   SQLiteStorageAdapter
-} from "./chunk-JUPZEBR3.js";
+} from "./chunk-4IDPWWGS.js";
 import {
   MemoryEventTransport,
   SocketIOEventTransport,
-  WebhookEventTransport
-} from "./chunk-D5HW7VEG.js";
+  WebhookEventTransport,
+  signWebhookPayload,
+  verifyWebhookSignature
+} from "./chunk-T6GAZBTQ.js";
 import {
   CronScheduler,
   PostgresSchedulePersistence,
   SQLiteSchedulePersistence
-} from "./chunk-FMPJBK2N.js";
+} from "./chunk-TVSADUYU.js";
 import {
   ConsoleLogger,
   SilentLogger,
@@ -300,6 +302,7 @@ async function executeStep(step, context, options) {
       await definition.hooks.beforeStep(context, step);
     }
     try {
+      throwIfCanceled(abortController, context.runId);
       const result = await runStepHandler(step, context, abortController);
       await completeStepAttempt(
         storage,
@@ -450,6 +453,7 @@ async function handleRetryAction(storage, events, logger, abortController, conte
   }
 }
 async function executeWithTimeout(fn, timeoutMs, signal, stepKey) {
+  if (signal.aborted) throw new WorkflowCanceledError("run");
   let timeoutId;
   let onAbort;
   try {
@@ -583,7 +587,12 @@ async function executeWorkflow(options) {
     checkpointResults: checkpoint?.results
   });
   const timeoutHandle = setupWorkflowTimeout(runId, definition, abortController);
+  const checkCancellation = () => {
+    if (abortController.signal.aborted) throw new WorkflowCanceledError(runId);
+  };
+  let afterRunCalled = false;
   try {
+    checkCancellation();
     if (definition.hooks?.beforeRun) {
       await definition.hooks.beforeRun(context);
     }
@@ -629,7 +638,7 @@ async function executeWorkflow(options) {
       completedSteps.push(step.key);
       await saveCheckpoint(storage, runId, context.results, completedSteps);
     }
-    timeoutHandle.clear();
+    checkCancellation();
     const duration = Date.now() - startTime;
     const runResult = {
       status: "succeeded",
@@ -637,8 +646,11 @@ async function executeWorkflow(options) {
       duration
     };
     if (definition.hooks?.afterRun) {
+      afterRunCalled = true;
       await definition.hooks.afterRun(context, runResult);
     }
+    checkCancellation();
+    timeoutHandle.clear();
     await markRunSucceeded(storage, runId, context.results);
     safeEmitEvent(events, logger, {
       runId,
@@ -660,7 +672,7 @@ async function executeWorkflow(options) {
       error: workflowError,
       duration
     };
-    if (definition.hooks?.afterRun) {
+    if (definition.hooks?.afterRun && !afterRunCalled) {
       try {
         await definition.hooks.afterRun(context, runResult);
       } catch (hookError) {
@@ -683,7 +695,9 @@ async function executeWorkflow(options) {
 var ConcurrencyManager = class {
   activeRuns = /* @__PURE__ */ new Map();
   runQueue = [];
-  timerHandles = /* @__PURE__ */ new Set();
+  timerHandles = /* @__PURE__ */ new Map();
+  pendingOperations = /* @__PURE__ */ new Set();
+  stopping = false;
   storage;
   events;
   logger;
@@ -695,6 +709,7 @@ var ConcurrencyManager = class {
     this.maxConcurrency = deps.maxConcurrency;
   }
   hasCapacity() {
+    if (this.stopping) return false;
     if (this.maxConcurrency === void 0 || this.maxConcurrency <= 0) {
       return true;
     }
@@ -709,8 +724,47 @@ var ConcurrencyManager = class {
   isActive(runId) {
     return this.activeRuns.has(runId);
   }
+  isQueued(runId) {
+    return this.runQueue.some((run) => run.runId === runId);
+  }
+  assertAccepting() {
+    if (this.stopping) throw new Error("Workflow engine is shutting down");
+  }
+  /** Track execution and admission I/O so adapters stay open until it settles. */
+  track(operation) {
+    this.pendingOperations.add(operation);
+    const cleanup = () => {
+      this.pendingOperations.delete(operation);
+    };
+    operation.then(cleanup, cleanup);
+    return operation;
+  }
+  beginShutdown() {
+    this.stopping = true;
+    this.clearTimers();
+    this.runQueue.length = 0;
+  }
+  /** Resolves true once tracked work settles, or false if `timeoutMs` elapses first. */
+  async waitForIdle(timeoutMs) {
+    let timeoutId;
+    const deadline = timeoutMs === void 0 ? void 0 : new Promise((resolve) => {
+      timeoutId = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const drain = (async () => {
+      while (this.pendingOperations.size > 0) {
+        await Promise.allSettled([...this.pendingOperations]);
+      }
+      return true;
+    })();
+    try {
+      return await (deadline ? Promise.race([drain, deadline]) : drain);
+    } finally {
+      if (timeoutId) clearTimeout(timeoutId);
+    }
+  }
   /** Insert a run in priority order (higher priority first, FIFO within same). */
   enqueue(run) {
+    this.assertAccepting();
     let inserted = false;
     for (let i = 0; i < this.runQueue.length; i++) {
       if (run.priority > this.runQueue[i].priority) {
@@ -731,6 +785,7 @@ var ConcurrencyManager = class {
     return true;
   }
   registerActive(runId, controller) {
+    this.assertAccepting();
     this.activeRuns.set(runId, controller);
   }
   unregisterActive(runId) {
@@ -761,22 +816,23 @@ var ConcurrencyManager = class {
    * (otherwise). Tracks the handle so it can be cleared during shutdown.
    */
   scheduleLaunch(fn, delay) {
+    this.assertAccepting();
     if (delay) {
-      const handle = setTimeout(fn, delay);
-      this.timerHandles.add(handle);
+      const handle = setTimeout(() => {
+        this.timerHandles.delete(handle);
+        fn();
+      }, delay);
+      this.timerHandles.set(handle, () => clearTimeout(handle));
     } else {
-      const handle = setImmediate(fn);
-      this.timerHandles.add(handle);
+      const handle = setImmediate(() => {
+        this.timerHandles.delete(handle);
+        fn();
+      });
+      this.timerHandles.set(handle, () => clearImmediate(handle));
     }
   }
   clearTimers() {
-    for (const handle of this.timerHandles) {
-      if (typeof handle === "object" && "ref" in handle) {
-        clearImmediate(handle);
-      } else {
-        clearTimeout(handle);
-      }
-    }
+    for (const cancel of this.timerHandles.values()) cancel();
     this.timerHandles.clear();
   }
   /**
@@ -826,17 +882,18 @@ var ConcurrencyManager = class {
     } catch (emitErr) {
       this.logger.error(`Failed to emit dispatch-failure event for ${queued.runId}`, emitErr);
     }
-    this.storage.updateRun(queued.runId, {
+    this.track(this.storage.updateRun(queued.runId, {
       status: "failed",
       finishedAt: /* @__PURE__ */ new Date(),
       error: { code: "QUEUE_DISPATCH_FAILED", message }
     }).catch((updateErr) => {
       this.logger.error(`Failed to record dispatch failure for ${queued.runId}`, updateErr);
-    });
+    }));
   }
 };
 
 // src/core/engine/lifecycle.ts
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 3e4;
 var LifecycleManager = class {
   storage;
   events;
@@ -844,6 +901,8 @@ var LifecycleManager = class {
   registry;
   concurrency;
   launchRun;
+  shutdownTimeout;
+  shutdownPromise;
   constructor(deps) {
     this.storage = deps.storage;
     this.events = deps.events;
@@ -851,6 +910,7 @@ var LifecycleManager = class {
     this.registry = deps.registry;
     this.concurrency = deps.concurrency;
     this.launchRun = deps.launchRun;
+    this.shutdownTimeout = deps.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
   }
   /**
    * Initialize the engine's storage adapter if it requires it.
@@ -863,18 +923,26 @@ var LifecycleManager = class {
   }
   /**
    * Shutdown the engine gracefully:
-   *   1. clear pending timer handles (so no further launches fire)
+   *   1. stop admission/dispatch and clear pending launch timers
    *   2. abort all in-flight runs
-   *   3. close the event transport
-   *   4. close the storage adapter
-   *   5. drop active-run bookkeeping
+   *   3. await tracked execution and admission I/O
+   *   4. close event and storage adapters, then drop active bookkeeping
    */
-  async shutdown() {
+  shutdown() {
+    return this.shutdownPromise ??= this.performShutdown();
+  }
+  async performShutdown() {
     this.logger.info("Shutting down workflow engine...");
-    this.concurrency.clearTimers();
+    this.concurrency.beginShutdown();
     this.concurrency.abortAllActive((runId) => {
       this.logger.debug(`Canceling active run: ${runId}`);
     });
+    const drained = await this.concurrency.waitForIdle(this.shutdownTimeout);
+    if (!drained) {
+      this.logger.warn(
+        `Shutdown timed out after ${this.shutdownTimeout}ms waiting for in-flight work; closing adapters anyway`
+      );
+    }
     if (this.events.close) {
       this.events.close();
     }
@@ -889,7 +957,9 @@ var LifecycleManager = class {
    * The run must be in 'queued' or 'running' status.
    */
   async resumeRun(runId) {
+    this.concurrency.assertAccepting();
     const run = await this.storage.getRun(runId);
+    this.concurrency.assertAccepting();
     if (!run) {
       throw new RunNotFoundError(runId);
     }
@@ -900,16 +970,29 @@ var LifecycleManager = class {
     if (!definition) {
       throw new WorkflowNotFoundError(run.kind);
     }
-    if (this.concurrency.isActive(runId)) {
-      this.logger.warn(`Run ${runId} is already active, skipping resume`);
+    if (this.concurrency.isActive(runId) || this.concurrency.isQueued(runId)) {
+      this.logger.warn(`Run ${runId} is already active or queued, skipping resume`);
       return runId;
     }
     this.logger.info(`Resuming run ${runId} from checkpoint`);
     const completedStepKeys = new Set(run.completedSteps ?? []);
-    this.launchRun(runId, definition, run.input, run.metadata, void 0, {
+    const checkpoint = {
       completedStepKeys,
       results: run.context
-    });
+    };
+    if (this.concurrency.hasCapacity()) {
+      this.launchRun(runId, definition, run.input, run.metadata, void 0, checkpoint);
+    } else {
+      this.concurrency.enqueue({
+        runId,
+        definition,
+        input: run.input,
+        metadata: run.metadata,
+        priority: run.priority ?? 0,
+        queuedAt: run.createdAt,
+        checkpoint
+      });
+    }
     return runId;
   }
   /**
@@ -917,10 +1000,17 @@ var LifecycleManager = class {
    * Returns runs with status 'queued' or 'running'.
    */
   async getResumableRuns() {
-    const result = await this.storage.listRuns({
-      status: ["queued", "running"]
-    });
-    return result.items;
+    const runs = [];
+    for (let offset = 0; ; ) {
+      const result = await this.storage.listRuns({
+        status: ["queued", "running"],
+        limit: 100,
+        offset
+      });
+      runs.push(...result.items);
+      offset += result.items.length;
+      if (result.items.length === 0 || offset >= result.total) return runs;
+    }
   }
   /**
    * Resume every interrupted run whose workflow kind is currently registered.
@@ -971,6 +1061,7 @@ var WorkflowEngine = class _WorkflowEngine {
       logger: this.logger,
       registry: this.registry,
       concurrency: this.concurrency,
+      shutdownTimeout: this.settings.shutdownTimeout,
       launchRun: (runId, def, input, metadata, delay, checkpoint) => this.launchRun(runId, def, input, metadata, delay, checkpoint)
     });
   }
@@ -1052,6 +1143,11 @@ var WorkflowEngine = class _WorkflowEngine {
    * @throws WorkflowNotFoundError if the workflow kind is not registered
    */
   async startRun(options) {
+    this.concurrency.assertAccepting();
+    return this.concurrency.track(this.createAndStartRun(options));
+  }
+  async createAndStartRun(options) {
+    const notBefore = Date.now() + (options.delay ?? 0);
     const definition = this.registry.get(options.kind);
     if (!definition) {
       throw new WorkflowNotFoundError(options.kind);
@@ -1065,7 +1161,8 @@ var WorkflowEngine = class _WorkflowEngine {
       context: {}
     });
     const runId = run.id;
-    this.events.emit({
+    this.concurrency.assertAccepting();
+    safeEmitEvent(this.events, this.logger, {
       runId,
       kind: options.kind,
       eventType: "run.created",
@@ -1078,7 +1175,7 @@ var WorkflowEngine = class _WorkflowEngine {
         definition,
         options.input ?? {},
         options.metadata,
-        options.delay
+        Math.max(0, notBefore - Date.now())
       );
     } else {
       this.concurrency.enqueue({
@@ -1087,10 +1184,11 @@ var WorkflowEngine = class _WorkflowEngine {
         input: options.input ?? {},
         metadata: options.metadata,
         priority: options.priority ?? 0,
-        queuedAt: /* @__PURE__ */ new Date()
+        queuedAt: /* @__PURE__ */ new Date(),
+        notBefore
       });
       this.logger.debug(`Run ${runId} queued (${this.concurrency.getQueuedCount()} in queue)`);
-      this.events.emit({
+      safeEmitEvent(this.events, this.logger, {
         runId,
         kind: options.kind,
         eventType: "run.queued",
@@ -1117,7 +1215,7 @@ var WorkflowEngine = class _WorkflowEngine {
       try {
         await executeWorkflow({
           runId,
-          definition,
+          definition: { ...definition, timeout: definition.timeout ?? this.settings.defaultTimeout },
           input,
           metadata,
           storage: this.storage,
@@ -1133,10 +1231,10 @@ var WorkflowEngine = class _WorkflowEngine {
       }
     };
     const guarded = () => {
-      execute().catch((err) => {
+      this.concurrency.track(execute().catch((err) => {
         this.concurrency.unregisterActive(runId);
         this.logger.error(`Unhandled error launching run ${runId}`, err);
-      });
+      }));
     };
     this.concurrency.scheduleLaunch(guarded, delay);
   }
@@ -1146,7 +1244,14 @@ var WorkflowEngine = class _WorkflowEngine {
    */
   processQueue() {
     this.concurrency.processQueue((next) => {
-      this.executeRun(next.runId, next.definition, next.input, next.metadata);
+      this.launchRun(
+        next.runId,
+        next.definition,
+        next.input,
+        next.metadata,
+        Math.max(0, (next.notBefore ?? 0) - Date.now()),
+        next.checkpoint
+      );
     });
   }
   /**
@@ -1169,6 +1274,10 @@ var WorkflowEngine = class _WorkflowEngine {
    * @throws {RunNotFoundError} If no run with the given ID exists
    */
   async cancelRun(runId) {
+    this.concurrency.assertAccepting();
+    return this.concurrency.track(this.cancelTrackedRun(runId));
+  }
+  async cancelTrackedRun(runId) {
     const run = await this.storage.getRun(runId);
     if (!run) {
       throw new RunNotFoundError(runId);
@@ -1182,7 +1291,7 @@ var WorkflowEngine = class _WorkflowEngine {
       status: "canceled",
       finishedAt: /* @__PURE__ */ new Date()
     });
-    this.events.emit({
+    safeEmitEvent(this.events, this.logger, {
       runId,
       kind: run.kind,
       eventType: "run.canceled",
@@ -1273,14 +1382,15 @@ var WorkflowEngine = class _WorkflowEngine {
    * @throws {WorkflowNotFoundError} If the workflow kind is not registered
    */
   async resumeRun(runId) {
-    return this.lifecycle.resumeRun(runId);
+    return this.concurrency.track(this.lifecycle.resumeRun(runId));
   }
   /**
    * Get all runs that were interrupted and can be resumed.
    * Returns runs with status 'queued' or 'running'.
    */
   async getResumableRuns() {
-    return this.lifecycle.getResumableRuns();
+    this.concurrency.assertAccepting();
+    return this.concurrency.track(this.lifecycle.getResumableRuns());
   }
   /**
    * Resume all interrupted runs.
@@ -1289,7 +1399,8 @@ var WorkflowEngine = class _WorkflowEngine {
    * @returns Array of resumed run IDs
    */
   async resumeAllInterrupted() {
-    return this.lifecycle.resumeAllInterrupted();
+    this.concurrency.assertAccepting();
+    return this.concurrency.track(this.lifecycle.resumeAllInterrupted());
   }
   // ============================================================================
   // Event Subscription
@@ -1938,7 +2049,9 @@ export {
   createScopedLogger,
   generateId,
   sanitizeErrorForStorage,
+  signWebhookPayload,
   sleep,
+  verifyWebhookSignature,
   withRetry
 };
 //# sourceMappingURL=index.js.map