pg-workflows 0.8.3 → 0.9.0

package/dist/index.d.ts

@@ -304,8 +304,9 @@ declare class WorkflowEngine {
 	workflows: Map<string, WorkflowInternalDefinition>;
 	private logger;
 	constructor({ workflows, logger, boss,...connectionOptions }: WorkflowEngineOptions);
-	start(asEngine?: boolean, { batchSize }?: {
+	start(asEngine?: boolean, { batchSize, heartbeatSeconds }?: {
 		batchSize?: number;
+		heartbeatSeconds?: number;
 	}): Promise<void>;
 	stop(): Promise<void>;
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
@@ -375,6 +376,14 @@ declare class WorkflowEngine {
 	*/
 	private resolveScopedResourceId;
 	private handleWorkflowRun;
+	/**
+	* Reconciles workflow runs whose retries pg-boss has exhausted (handler
+	* threw on the final attempt, or worker died and missed the heartbeat
+	* past the retry budget). The DLQ entry tells us the run is unrecoverable;
+	* we mark it FAILED with whatever error message the catch block last
+	* persisted, falling back to a worker-death message.
+	*/
+	private handleWorkflowRunDlq;
 	private getCachedStepEntry;
 	private getWaitForStepEntry;
 	private runStep;
@@ -398,6 +407,8 @@ declare class WorkflowEngine {
 	}>;
 }
 import { StandardSchemaV1 as StandardSchemaV12 } from "@standard-schema/spec";
+declare function validateWorkflowId(workflowId: string): void;
+declare function validateResourceId(resourceId: string | undefined | null): void;
 declare class WorkflowEngineError extends Error {
 	readonly workflowId?: string | undefined;
 	readonly runId?: string | undefined;
@@ -408,4 +419,4 @@ declare class WorkflowEngineError extends Error {
 declare class WorkflowRunNotFoundError extends WorkflowEngineError {
 	constructor(runId?: string, workflowId?: string);
 }
-export { workflow, parseDuration, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepType, StepInternalDefinition, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, DurationObject, Duration };
+export { workflow, validateWorkflowId, validateResourceId, parseDuration, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowInternalLoggerContext, WorkflowInternalLogger, WorkflowInternalDefinition, WorkflowFactory, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepType, StepInternalDefinition, StepBaseContext, StartWorkflowOptions, InputParameters, InferInputParameters, DurationObject, Duration };

package/dist/index.js

@@ -2,6 +2,7 @@ import {
   DEFAULT_PGBOSS_SCHEMA,
   PAUSE_EVENT_NAME,
   StepType,
+  WORKFLOW_RUN_DLQ_QUEUE_NAME,
   WORKFLOW_RUN_QUEUE_NAME,
   WorkflowClient,
   WorkflowEngineError,
@@ -13,9 +14,11 @@ import {
   insertWorkflowRun,
   runMigrations,
   updateWorkflowRun,
+  validateResourceId,
+  validateWorkflowId,
   withPostgresTransaction,
   workflow
-} from "./shared/chunk-2xy8z3xp.js";
+} from "./shared/chunk-fr76gdwj.js";
 // src/duration.ts
 import parse from "parse-duration";
 var MS_PER_SECOND = 1000;
@@ -131,6 +134,12 @@ var defaultLogger = {
   error: (message, error) => console.error(message, error)
 };
 var defaultExpireInSeconds = process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS ? Number.parseInt(process.env.WORKFLOW_RUN_EXPIRE_IN_SECONDS, 10) : 5 * 60;
+var retrySendOptions = (maxRetries) => ({
+  retryLimit: maxRetries,
+  retryBackoff: true,
+  retryDelay: 1
+});
+var defaultHeartbeatSeconds = process.env.WORKFLOW_RUN_HEARTBEAT_SECONDS ? Number.parseInt(process.env.WORKFLOW_RUN_HEARTBEAT_SECONDS, 10) : 30;
 
 class WorkflowEngine {
   boss;
@@ -164,7 +173,10 @@ class WorkflowEngine {
     }
     this.db = this.boss.getDb();
   }
-  async start(asEngine = true, { batchSize } = { batchSize: 1 }) {
+  async start(asEngine = true, {
+    batchSize = 1,
+    heartbeatSeconds = defaultHeartbeatSeconds
+  } = {}) {
     if (this._started) {
       return;
     }
@@ -175,13 +187,21 @@ class WorkflowEngine {
         await this.registerWorkflow(workflow2);
       }
     }
-    await this.boss.createQueue(WORKFLOW_RUN_QUEUE_NAME);
+    const mainQueueOptions = {
+      retryLimit: 0,
+      deadLetter: WORKFLOW_RUN_DLQ_QUEUE_NAME,
+      heartbeatSeconds
+    };
+    await this.boss.createQueue(WORKFLOW_RUN_DLQ_QUEUE_NAME, { retryLimit: 0 });
+    await this.boss.createQueue(WORKFLOW_RUN_QUEUE_NAME, mainQueueOptions);
+    await this.boss.updateQueue(WORKFLOW_RUN_QUEUE_NAME, mainQueueOptions);
     const numWorkers = +(process.env.WORKFLOW_RUN_WORKERS ?? 3);
     if (asEngine) {
-      for (let i = 0;i < numWorkers; i++) {
-        await this.boss.work(WORKFLOW_RUN_QUEUE_NAME, { pollingIntervalSeconds: 0.5, batchSize }, (job) => this.handleWorkflowRun(job));
+      await Promise.all(Array.from({ length: numWorkers }, (_, i) => this.boss.work(WORKFLOW_RUN_QUEUE_NAME, { pollingIntervalSeconds: 0.5, batchSize, includeMetadata: true }, (jobs) => this.handleWorkflowRun(jobs)).then(() => {
         this.logger.log(`Worker ${i + 1}/${numWorkers} started for queue ${WORKFLOW_RUN_QUEUE_NAME}`);
-      }
+      })));
+      await this.boss.work(WORKFLOW_RUN_DLQ_QUEUE_NAME, { pollingIntervalSeconds: 0.5, batchSize: 1 }, (jobs) => this.handleWorkflowRunDlq(jobs));
+      this.logger.log(`Worker started for queue ${WORKFLOW_RUN_DLQ_QUEUE_NAME}`);
     }
     this._started = true;
     this.logger.log("Workflow engine started!");
@@ -244,6 +264,8 @@ class WorkflowEngine {
       idempotencyKey = params.idempotencyKey;
       options = params.options;
     }
+    validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
     if (!this._started) {
       await this.start(false, { batchSize: options?.batchSize ?? 1 });
     }
@@ -284,7 +306,8 @@ class WorkflowEngine {
         };
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: new Date,
-          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+          expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+          ...retrySendOptions(insertedRun.maxRetries)
         });
       }
       return insertedRun;
@@ -415,7 +438,8 @@ class WorkflowEngine {
       }
     };
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
-      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+      ...retrySendOptions(run.maxRetries)
     });
     this.logger.log(`event ${eventName} sent for workflow run with id ${runId}`);
     return run;
@@ -494,7 +518,7 @@ class WorkflowEngine {
     return run.resourceId ?? undefined;
   }
   async handleWorkflowRun([job]) {
-    const { runId = "", resourceId, workflowId = "", input, event } = job?.data ?? {};
+    const { runId = "", resourceId, workflowId = "", event } = job?.data ?? {};
     let run;
     let scopedResourceId;
     try {
@@ -517,6 +541,14 @@ class WorkflowEngine {
         throw new WorkflowEngineError(`Workflow run ${runId} does not match job workflowId ${workflowId}`, workflowId, runId);
       }
       scopedResourceId = this.resolveScopedResourceId(resourceId, run);
+      if (job?.retryCount !== undefined && run.retryCount !== job.retryCount) {
+        await this.updateRun({
+          runId,
+          resourceId: scopedResourceId,
+          data: { retryCount: job.retryCount }
+        });
+        run = { ...run, retryCount: job.retryCount };
+      }
       if (run.status === "cancelled" /* CANCELLED */) {
         this.logger.log(`Workflow run ${runId} is cancelled, skipping`);
         return;
@@ -660,34 +692,11 @@ class WorkflowEngine {
         });
       }
     } catch (error) {
-      if (run && run.retryCount < run.maxRetries) {
-        await this.updateRun({
-          runId,
-          resourceId: scopedResourceId,
-          data: {
-            retryCount: run.retryCount + 1,
-            jobId: job?.id
-          }
-        });
-        const retryDelay = 2 ** run.retryCount * 1000;
-        const pgBossJob = {
-          runId,
-          resourceId: scopedResourceId,
-          workflowId,
-          input
-        };
-        await this.boss?.send("workflow-run", pgBossJob, {
-          startAfter: new Date(Date.now() + retryDelay),
-          expireInSeconds: defaultExpireInSeconds
-        });
-        return;
-      }
       if (runId) {
         await this.updateRun({
           runId,
           resourceId: scopedResourceId,
           data: {
-            status: "failed" /* FAILED */,
             error: error instanceof Error ? error.message : String(error),
             jobId: job?.id
           }
@@ -696,6 +705,26 @@ class WorkflowEngine {
       throw error;
     }
   }
+  async handleWorkflowRunDlq([job]) {
+    const { runId } = job?.data ?? {};
+    if (!runId)
+      return;
+    const run = await getWorkflowRun({ runId }, { db: this.db });
+    if (!run || run.status !== "running" /* RUNNING */)
+      return;
+    await this.updateRun({
+      runId,
+      resourceId: run.resourceId ?? undefined,
+      data: {
+        status: "failed" /* FAILED */,
+        error: run.error ?? "Workflow run worker died or job expired before completion"
+      }
+    });
+    this.logger.log("Marked stuck workflow run as failed", {
+      runId,
+      workflowId: run.workflowId
+    });
+  }
   getCachedStepEntry(timeline, stepId) {
     const stepEntry = timeline[stepId];
     return stepEntry && typeof stepEntry === "object" && "output" in stepEntry ? stepEntry : null;
@@ -819,7 +848,8 @@ ${error.stack}` : String(error)
         };
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: timeoutDate.getTime() <= Date.now() ? new Date : timeoutDate,
-          expireInSeconds: defaultExpireInSeconds
+          expireInSeconds: defaultExpireInSeconds,
+          ...retrySendOptions(run.maxRetries)
         });
       } catch (error) {
         await this.updateRun({
@@ -936,7 +966,8 @@ ${error.stack}` : String(error)
         event: { name: pollEvent, data: {} }
       }, {
         startAfter: new Date(Date.now() + intervalMs),
-        expireInSeconds: defaultExpireInSeconds
+        expireInSeconds: defaultExpireInSeconds,
+        ...retrySendOptions(run.maxRetries)
       });
     } catch (error) {
       await this.updateRun({
@@ -979,6 +1010,9 @@ ${error.stack}` : String(error)
     statuses,
     workflowId
   }) {
+    if (workflowId)
+      validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
     return getWorkflowRuns({
       resourceId,
       startingAfter,
@@ -991,6 +1025,8 @@ ${error.stack}` : String(error)
 }
 export {
   workflow,
+  validateWorkflowId,
+  validateResourceId,
   parseDuration,
   createWorkflowRef,
   WorkflowStatus,
@@ -1001,5 +1037,5 @@ export {
   StepType
 };
 
-//# debugId=9A3E4733F40A491264756E2164756E21
+//# debugId=FC991C83D3B1165A64756E2164756E21
 //# sourceMappingURL=index.js.map