nuxt-cf-jobs 0.6.0 → 0.6.2

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-cf-jobs",
   "configKey": "cfJobs",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/server/outbox.d.ts

@@ -308,6 +308,47 @@ export interface RunDurableJobMessageOptions<StoredJob, Job extends Dispatchable
      * Omit to keep retrying every throw (the transport/DLQ then decides terminal).
      */
     maxAttemptsOf?: (job: StoredJob) => number | undefined;
+    /**
+     * Per-job scope created right after claim: `wrapDispatch` wraps the handler run
+     * (e.g. AsyncLocalStorage telemetry), `onSettled` observes every terminal/
+     * released outcome (e.g. write a run-log row). Both close over the same scope so
+     * the wrapper's collected data is available to the observer.
+     */
+    createJobScope?: (storedJob: StoredJob) => DurableJobScope<StoredJob>;
+    /**
+     * Decide whether a THROWN error is terminal (→ `failed_jobs`) vs released for
+     * retry. Overrides the default `attempts >= maxAttemptsOf` so callers can, e.g.,
+     * never fail on transient infra errors. `maxAttempts` is `maxAttemptsOf`'s value.
+     */
+    isPermanentFailure?: (input: {
+        error: unknown;
+        storedJob: StoredJob;
+        attempts: number;
+        maxAttempts: number | undefined;
+    }) => boolean;
+    /**
+     * Dispatch the job payload's `then`/`catch`/`finally` continuations after a
+     * terminal outcome: `then`+`finally` on success, `catch`+`finally` on terminal
+     * failure, none on a release/retry.
+     */
+    dispatchContinuations?: (input: {
+        storedJob: StoredJob;
+        stage: DurableJobContinuationStage;
+    }) => void | Promise<void>;
+}
+export interface DurableJobSettlement<StoredJob> {
+    storedJob: StoredJob;
+    status: RunDurableJobMessageResult['status'];
+    /** Wall-clock ms from claim to settle. */
+    durationMs: number;
+    /** True when the job reached a terminal failure (not a release/retry). */
+    permanent: boolean;
+    /** The error for failed/released/exhausted outcomes (raw, for the caller to classify). */
+    error?: unknown;
+}
+export interface DurableJobScope<StoredJob> {
+    wrapDispatch?: (run: () => Promise<DispatchResult>) => Promise<DispatchResult>;
+    onSettled?: (settlement: DurableJobSettlement<StoredJob>) => void | Promise<void>;
 }
 /**
  * Outcome of {@link runDurableJobMessage}, discriminated on `status` so each

package/dist/runtime/server/outbox.js

@@ -234,26 +234,41 @@ export async function runDurableJobMessage(opts) {
         reportedStats[k] = (reportedStats[k] ?? 0) + s[k];
     }
   };
+  const scope = opts.createJobScope?.(storedJob);
+  const startedMs = Date.now();
+  const settle = async (status, permanent, error) => {
+    await scope?.onSettled?.({ storedJob, status, durationMs: Date.now() - startedMs, permanent, error });
+  };
+  const continuations = async (...stages) => {
+    for (const stage of stages)
+      await opts.dispatchContinuations?.({ storedJob, stage });
+  };
   try {
-    const dispatch = await dispatchRegisteredJob({
+    const runOnce = () => dispatchRegisteredJob({
       registry: opts.registry,
       job,
       createContext: async (input) => ({ ...await opts.createJobContext({ ...input, storedJob }), reportStats })
     });
+    const dispatch = await (scope?.wrapDispatch ? scope.wrapDispatch(runOnce) : runOnce());
     if (!dispatch.success) {
       if (opts.failDispatchFailure !== false)
         await failDurableJob(opts.lifecycle, storedJob, dispatch.error ? formatJobError(dispatch.error) : "Job dispatch failed");
+      await settle("dispatch-failed", true, dispatch.error);
+      await continuations("catch", "finally");
       opts.message.ack();
       return { status: "dispatch-failed", dispatch, error: dispatch.error };
     }
     if (dispatch.control?.handled) {
       if (dispatch.control.action === "failed") {
         await failDurableJob(opts.lifecycle, storedJob, dispatch.control.error ?? "Job failed via ctx.fail()");
+        await settle("failed", true, dispatch.control.error);
+        await continuations("catch", "finally");
         opts.message.ack();
         return { status: "failed", dispatch };
       }
       const delaySeconds = dispatch.control.delaySeconds ?? 0;
       await releaseDurableJob(opts.lifecycle, storedJob, { delaySeconds, error: dispatch.control.error });
+      await settle("released", false, dispatch.control.error);
       opts.message.retry({ delaySeconds });
       return { status: "released", dispatch };
     }
@@ -261,12 +276,17 @@ export async function runDurableJobMessage(opts) {
     const hasStats = Object.keys(reportedStats).length > 0;
     const completeWith = hasStats ? { ...result && typeof result === "object" ? result : {}, ...reportedStats } : result;
     await completeDurableJob(opts.lifecycle, storedJob, completeWith);
+    await settle("completed", false);
+    await continuations("then", "finally");
     opts.message.ack();
     return { status: "completed", dispatch };
   } catch (error) {
     const maxAttempts = opts.maxAttemptsOf?.(storedJob);
-    if (typeof maxAttempts === "number" && job.attempts >= maxAttempts) {
+    const permanent = opts.isPermanentFailure ? opts.isPermanentFailure({ error, storedJob, attempts: job.attempts, maxAttempts }) : typeof maxAttempts === "number" && job.attempts >= maxAttempts;
+    if (permanent) {
       await failDurableJob(opts.lifecycle, storedJob, describeCause(error));
+      await settle("exhausted", true, error);
+      await continuations("catch", "finally");
       opts.message.ack();
       return { status: "exhausted", error: jobErrors.handlerThrew(error) };
     }
@@ -275,6 +295,7 @@ export async function runDurableJobMessage(opts) {
       delaySeconds,
       error: describeCause(error)
     });
+    await settle("errored", false, error);
     opts.message.retry({ delaySeconds });
     return { status: "errored", error: jobErrors.handlerThrew(error) };
   }

package/dist/runtime/server/plugins/dev-queues.js

@@ -18,14 +18,16 @@ export default defineNitroPlugin((nitroApp) => {
       console.error("[nuxt-cf-jobs] dev queue error:", error);
     }
   });
+  const taskEnvHost = globalThis;
+  taskEnvHost.__env__ = { ...runtime.env, ...taskEnvHost.__env__ ?? {} };
   nitroApp.hooks.hook("request", (event) => {
     const existing = event.context.cloudflare?.env;
     event.context.cloudflare = {
       ...event.context.cloudflare ?? {},
       env: existing ? { ...runtime.env, ...existing } : runtime.env
     };
+    if (existing)
+      taskEnvHost.__env__ = { ...taskEnvHost.__env__, ...existing, ...runtime.env };
   });
-  const taskEnvHost = globalThis;
-  taskEnvHost.__env__ = { ...runtime.env, ...taskEnvHost.__env__ ?? {} };
   nitroApp.hooks.hook("close", () => runtime.dispose());
 });

package/dist/runtime/server/runtime.d.ts

@@ -1,7 +1,7 @@
 import type { BatchProgress, DurableBatchStore, SettleBatchMemberOptions, SettleBatchMemberResult } from './batch.js';
-import type { D1DatabaseLike, D1DurableJobRepository } from './d1.js';
+import type { D1DatabaseLike, D1DurableJobRecord, D1DurableJobRepository } from './d1.js';
 import type { JobMetricsSink } from './metrics.js';
-import type { CreateJobBatchOptions, CreateJobBatchResult, DurableJobRecord, EnqueueDurableJobResult, PruneDurableJobsOptions, PruneDurableJobsResult, QueuePublisher, RunDurableJobMessageOptions, RunDurableJobMessageResult } from './outbox.js';
+import type { CreateJobBatchOptions, CreateJobBatchResult, DurableJobContinuationStage, DurableJobRecord, DurableJobScope, EnqueueDurableJobResult, PruneDurableJobsOptions, PruneDurableJobsResult, QueuePublisher, RunDurableJobMessageOptions, RunDurableJobMessageResult } from './outbox.js';
 import type { DispatchableJob, JobDefinition, JobHandler, QueueBatch, QueueMessage } from './types.js';
 export interface RunDurableJobBatchMessageOptions<StoredJob, Job extends DispatchableJob, Message extends {
     jobId: string;
@@ -70,6 +70,25 @@ export interface ConsumeQueueBatchOptions<Queue extends string, Env, Db, Logger>
         jobId?: string;
         error?: string;
     }) => void;
+    createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
+    isPermanentFailure?: (input: {
+        error: unknown;
+        storedJob: D1DurableJobRecord<Queue>;
+        attempts: number;
+        maxAttempts: number | undefined;
+    }) => boolean;
+    dispatchContinuations?: (input: {
+        storedJob: D1DurableJobRecord<Queue>;
+        stage: DurableJobContinuationStage;
+    }) => void | Promise<void>;
+    /**
+     * Soft batch CPU budget (ms). Before each message, if the batch has run longer
+     * than this, the remaining messages are retried instead of processed — so a
+     * heavy batch can't blow the Worker CPU limit mid-message.
+     */
+    maxBatchCpuMs?: number;
+    /** Delay (s) for messages deferred by the CPU guard. Default 5. */
+    cpuGuardRetryDelaySeconds?: number;
 }
 /**
  * Process one CF queue batch end-to-end — the loop both apps hand-roll:
@@ -109,6 +128,8 @@ export interface CreateDurableJobsRuntimeOptions<Queue extends string = string,
     metricsSink?: JobMetricsSink;
     /** Notified after each batch settle. */
     onBatchProgress?: (progress: BatchProgress) => void | Promise<void>;
+    /** Override how a batch's onFinish continuation runs (default: durable enqueue). */
+    dispatchOnFinish?: SettleBatchMemberOptions['dispatchOnFinish'];
     /** Per-throw retry backoff for the consumer. */
     retryDelaySeconds?: RunDurableJobMessageOptions<unknown, DispatchableJob>['retryDelaySeconds'];
     onMissingBinding?: (queue: Queue, count: number) => void | Promise<void>;
@@ -128,6 +149,24 @@ export interface CreateDurableJobsRuntimeOptions<Queue extends string = string,
         jobId?: string;
         error?: string;
     }) => void;
+    /** Per-job scope: wrap dispatch (e.g. telemetry) + observe each settlement. */
+    createJobScope?: (storedJob: D1DurableJobRecord<Queue>) => DurableJobScope<D1DurableJobRecord<Queue>>;
+    /** Decide whether a thrown error is terminal (default: attempts >= max). */
+    isPermanentFailure?: (input: {
+        error: unknown;
+        storedJob: D1DurableJobRecord<Queue>;
+        attempts: number;
+        maxAttempts: number | undefined;
+    }) => boolean;
+    /** Dispatch then/catch/finally payload continuations after a terminal outcome. */
+    dispatchContinuations?: (input: {
+        storedJob: D1DurableJobRecord<Queue>;
+        stage: DurableJobContinuationStage;
+    }) => void | Promise<void>;
+    /** Soft per-batch CPU budget (ms); remaining messages are deferred once exceeded. */
+    maxBatchCpuMs?: number;
+    /** Delay (s) for CPU-guard-deferred messages. Default 5. */
+    cpuGuardRetryDelaySeconds?: number;
 }
 export interface DurableJobsRuntime<Queue extends string = string> {
     repository: D1DurableJobRepository<Queue>;

package/dist/runtime/server/runtime.js

@@ -93,7 +93,13 @@ export async function consumeQueueBatch(opts) {
     }
     return;
   }
+  const batchStartedMs = Date.now();
+  const cpuBudget = opts.maxBatchCpuMs;
   for (const message of opts.batch.messages) {
+    if (cpuBudget != null && Date.now() - batchStartedMs > cpuBudget) {
+      message.retry({ delaySeconds: opts.cpuGuardRetryDelaySeconds ?? 5 });
+      continue;
+    }
     const body = message.body ?? {};
     const jobId = typeof body.jobId === "string" ? body.jobId : void 0;
     if (jobId) {
@@ -107,6 +113,9 @@ export async function consumeQueueBatch(opts) {
         retryDelaySeconds: opts.retryDelaySeconds,
         // Honour the stored job's attempt cap (Laravel worker model).
         maxAttemptsOf: (stored) => stored.max_attempts,
+        createJobScope: opts.createJobScope,
+        isPermanentFailure: opts.isPermanentFailure,
+        dispatchContinuations: opts.dispatchContinuations,
         dispatchOnFinish: opts.dispatchOnFinish,
         onBatchProgress: opts.onBatchProgress
       });
@@ -150,7 +159,7 @@ export function createDurableJobsRuntime(opts) {
     opts.resolveQueueBinding,
     { onMissingBinding: opts.onMissingBinding }
   );
-  const dispatchOnFinish = async ({ continuation, batch }) => {
+  const dispatchOnFinish = opts.dispatchOnFinish ?? (async ({ continuation, batch }) => {
     const c = continuation;
     try {
       const record = await prepareDurableJob({ name: c.name, payload: c.payload, registry: opts.registry });
@@ -158,7 +167,7 @@ export function createDurableJobsRuntime(opts) {
     } catch (error) {
       opts.onLog?.({ stage: "onfinish-failed", taskName: c.name, jobId: batch.id, error: error instanceof Error ? error.message : String(error) });
     }
-  };
+  });
   const isDuplicate = makeIsDuplicate(opts.dedup);
   return {
     repository,
@@ -180,6 +189,9 @@ export function createDurableJobsRuntime(opts) {
       createJobContext: opts.createJobContext,
       retryDelaySeconds: opts.retryDelaySeconds,
       maxAttemptsOf: (stored) => stored.max_attempts,
+      createJobScope: opts.createJobScope,
+      isPermanentFailure: opts.isPermanentFailure,
+      dispatchContinuations: opts.dispatchContinuations,
       dispatchOnFinish,
       onBatchProgress: opts.onBatchProgress
     }),
@@ -194,7 +206,12 @@ export function createDurableJobsRuntime(opts) {
       retryDelaySeconds: opts.retryDelaySeconds,
       isDlqQueue: opts.isDlqQueue,
       isDuplicate,
-      onLog: opts.onLog
+      onLog: opts.onLog,
+      createJobScope: opts.createJobScope,
+      isPermanentFailure: opts.isPermanentFailure,
+      dispatchContinuations: opts.dispatchContinuations,
+      maxBatchCpuMs: opts.maxBatchCpuMs,
+      cpuGuardRetryDelaySeconds: opts.cpuGuardRetryDelaySeconds
     }),
     prune: (pruneOpts) => pruneDurableJobs(repository, pruneOpts)
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-cf-jobs",
   "type": "module",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Nuxt module for typed Cloudflare queue jobs.",
   "author": {
     "name": "Harlan Wilton",