nuxt-cf-jobs 0.0.2

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

@@ -0,0 +1,220 @@
+import type { DispatchableJob, DispatchResult, JobContext, JobControlResult, JobDefinition, JobHandler, QueueMessage } from './types.js';
+import type { SendBackpressureOptions } from './queue.js';
+import type { QueueSendOptions } from './types.js';
+import type { AnyJobDefinition, JobNameOf, JobPayloadByName, JobQueueByName } from './registry.js';
+export interface DurableJobRoute<Queue extends string = string> {
+    queue: Queue;
+    jobType: string;
+}
+export interface DurableJobRecord<Queue extends string = string> {
+    id: string;
+    queue: Queue;
+    jobType: string;
+    batchId?: string;
+    userId?: number;
+    siteId?: string;
+    partnerId?: string;
+    traceId: string;
+    uniqueKey?: string;
+    payload: string;
+    attempts: number;
+    maxAttempts: number;
+    availableAt: number;
+    createdAt: number;
+}
+export interface QueueJobMessage<Queue extends string = string> {
+    jobId: string;
+    queue: Queue;
+}
+export type DurableJobContinuationStage = 'then' | 'catch' | 'finally';
+export interface DurableJobContinuation<Name extends string = string, Payload extends object = Record<string, unknown>, Queue extends string = string> {
+    name: Name;
+    payload: Payload;
+    queue?: Queue;
+    delaySeconds?: number;
+}
+export type DurableJobContinuations<Name extends string = string, Payload extends object = Record<string, unknown>, Queue extends string = string> = Partial<Record<DurableJobContinuationStage, Array<DurableJobContinuation<Name, Payload, Queue>>>>;
+export interface DurableJobRepository<Queue extends string = string, Record extends DurableJobRecord<Queue> = DurableJobRecord<Queue>> {
+    insertJob: (record: Record) => Promise<boolean>;
+    /**
+     * Optional batched insert. When implemented, callers can persist many records in chunks
+     * (chunked at the D1 100-statement limit by D1-backed implementations).
+     */
+    insertJobs?: (records: readonly Record[], opts?: {
+        batchSize?: number;
+    }) => Promise<{
+        inserted: Record[];
+        chunks: Array<{
+            ok: boolean;
+            ids: string[];
+            changes: number;
+            error?: unknown;
+        }>;
+    }>;
+}
+export interface RecordDurableJobFailureInput<Queue extends string = string> {
+    id?: string;
+    queue: Queue | string;
+    jobType: string;
+    batchId?: string | null;
+    userId?: number | null;
+    siteId?: string | null;
+    partnerId?: string | null;
+    traceId?: string | null;
+    uniqueKey?: string | null;
+    payload: string;
+    exception: string;
+    attempts: number;
+    maxAttempts?: number;
+}
+/**
+ * Persists a failure record without claiming or deleting a `jobs` row.
+ * Used by the DLQ helper to log exhausted messages whose original job rows may not exist
+ * (e.g. lightweight queue path) or whose lifecycle has already been finalized.
+ */
+export interface DurableJobFailureRepository {
+    recordFailure: (input: RecordDurableJobFailureInput) => Promise<void>;
+}
+export interface DurableJobRegistryLike<Env = unknown, Db = unknown, Logger = unknown> {
+    getHandler?: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined;
+    getJobDefinition?: (name: string) => JobDefinition<string, unknown, string, Env, Db, Logger> | undefined;
+    getJobRoute?: (name: string) => DurableJobRoute<string> | undefined;
+}
+export interface TypedDurableJobRegistryLike<Jobs extends readonly AnyJobDefinition[]> extends DurableJobRegistryLike {
+    jobs: Jobs;
+}
+export type DurableJobClaimMiss = 'already-resolved' | 'in-flight' | 'not-found';
+export type DurableJobClaimResult<Job> = {
+    status: 'claimed';
+    job: Job;
+} | {
+    status: DurableJobClaimMiss;
+};
+export interface ReleaseDurableJobOptions {
+    delaySeconds?: number;
+    availableAt?: number;
+    error?: string;
+}
+export interface DurableJobLifecycle<Job, CompleteResult = void, FailOptions = unknown, ReleaseResult = void> {
+    claimJob: (id: string) => Promise<Job | null>;
+    resolveClaimMiss?: (id: string) => Promise<DurableJobClaimMiss>;
+    completeJob: (job: Job, result?: unknown) => Promise<CompleteResult>;
+    failJob: (job: Job, error: string, opts?: FailOptions) => Promise<void>;
+    releaseJob?: (job: Job, opts?: ReleaseDurableJobOptions) => Promise<ReleaseResult>;
+}
+export interface QueuePublisher<Queue extends string = string, Message extends QueueJobMessage<Queue> = QueueJobMessage<Queue>> {
+    send: (queue: Queue, message: Message, opts?: QueueSendOptions & SendBackpressureOptions) => Promise<boolean>;
+    sendBatch: (queue: Queue, messages: Message[], opts?: QueueSendOptions & SendBackpressureOptions) => Promise<boolean>;
+}
+export interface DurableJobRecoveryQuery {
+    now?: number;
+    limit?: number;
+}
+export interface DurableJobStaleRecoveryQuery extends DurableJobRecoveryQuery {
+    staleBefore: number;
+    availableAt?: number;
+    error?: string;
+}
+export interface DurableJobRecoveryRepository<Queue extends string = string, Record extends Pick<DurableJobRecord<Queue>, 'id' | 'queue'> = Pick<DurableJobRecord<Queue>, 'id' | 'queue'>> {
+    findDispatchableJobs?: (query?: DurableJobRecoveryQuery) => Promise<Record[]>;
+    findStaleReservedJobs?: (query: DurableJobStaleRecoveryQuery) => Promise<Record[]>;
+    releaseStaleReservedJobs?: (query: DurableJobStaleRecoveryQuery) => Promise<number>;
+}
+export interface PrepareDurableJobOptions<Name extends string, Payload extends object, Queue extends string> {
+    name: Name;
+    payload: Payload;
+    route?: DurableJobRoute<Queue>;
+    registry?: DurableJobRegistryLike;
+    definition?: Pick<JobDefinition<Name, Payload, Queue, unknown, unknown, unknown>, 'name' | 'queue' | 'jobType' | 'input' | 'tries' | 'maxAttempts' | 'unique' | 'uniqueId'>;
+    id?: string;
+    batchId?: string;
+    userId?: number;
+    siteId?: string;
+    partnerId?: string;
+    delaySeconds?: number;
+    now?: number;
+    traceId?: string;
+    defaultMaxAttempts?: number;
+    continuations?: DurableJobContinuations<string, Record<string, unknown>, Queue>;
+}
+export declare function prepareDurableJob<const Name extends string, Payload extends object, Queue extends string>(opts: PrepareDurableJobOptions<Name, Payload, Queue>): Promise<DurableJobRecord<Queue>>;
+export declare function prepareRegisteredDurableJob<const Jobs extends readonly AnyJobDefinition[], const Name extends JobNameOf<Jobs>>(registry: TypedDurableJobRegistryLike<Jobs>, opts: PrepareRegisteredDurableJobOptions<Jobs, Name>): Promise<DurableJobRecord<JobQueueByName<Jobs, Name>>>;
+export type PrepareRegisteredDurableJobOptions<Jobs extends readonly AnyJobDefinition[], Name extends JobNameOf<Jobs>> = Omit<PrepareDurableJobOptions<Name, JobPayloadByName<Jobs, Name> & object, JobQueueByName<Jobs, Name>>, 'registry' | 'definition' | 'route' | 'name' | 'payload'> & {
+    name: Name;
+    payload: JobPayloadByName<Jobs, Name> & object;
+    route?: DurableJobRoute<JobQueueByName<Jobs, Name>>;
+};
+export declare function normalizeDurableJobContinuations<Name extends string = string, Payload extends object = Record<string, unknown>, Queue extends string = string>(continuations?: DurableJobContinuations<Name, Payload, Queue>): DurableJobContinuations<Name, Payload, Queue> | undefined;
+export declare function validateDurableJobContinuations(registry: DurableJobRegistryLike | undefined, continuations: DurableJobContinuations<string, Record<string, unknown>, string> | undefined): void;
+export declare function getDurableJobContinuations<Name extends string = string, Payload extends object = Record<string, unknown>, Queue extends string = string>(payload: unknown): DurableJobContinuations<Name, Payload, Queue> | undefined;
+export declare function getDurableJobContinuationsForStage<Name extends string = string, Payload extends object = Record<string, unknown>, Queue extends string = string>(payload: unknown, stage: DurableJobContinuationStage): Array<DurableJobContinuation<Name, Payload, Queue>>;
+export declare function serializeDurableJobContinuation<Name extends string, Payload extends object, Queue extends string = string>(continuation: DurableJobContinuation<Name, Payload, Queue>): string;
+export declare function parseDurableJobContinuation<Name extends string = string, Payload extends object = Record<string, unknown>, Queue extends string = string>(value: string): DurableJobContinuation<Name, Payload, Queue>;
+export declare function dispatchDurableJobContinuations<Name extends string, Payload extends object, Queue extends string = string>(continuations: Array<DurableJobContinuation<Name, Payload, Queue>>, dispatch: (continuation: DurableJobContinuation<Name, Payload, Queue>) => Promise<void>): Promise<void>;
+export declare function toQueueJobMessage<Queue extends string>(record: Pick<DurableJobRecord<Queue>, 'id' | 'queue'>): QueueJobMessage<Queue>;
+export declare function groupQueueJobMessagesByQueue<Queue extends string>(records: Array<Pick<DurableJobRecord<Queue>, 'id' | 'queue'>>): Map<Queue, Array<QueueJobMessage<Queue>>>;
+export declare function createQueuePublisher<Env extends Record<string, unknown>, Queue extends string, Message extends QueueJobMessage<Queue> = QueueJobMessage<Queue>>(env: Env, resolveBinding: (queue: Queue) => string | undefined, opts?: {
+    onMissingBinding?: (queue: Queue, count: number) => void | Promise<void>;
+}): QueuePublisher<Queue, Message>;
+export declare function claimDurableJob<Job>(lifecycle: Pick<DurableJobLifecycle<Job>, 'claimJob' | 'resolveClaimMiss'>, id: string): Promise<DurableJobClaimResult<Job>>;
+export declare function completeDurableJob<Job, CompleteResult>(lifecycle: Pick<DurableJobLifecycle<Job, CompleteResult>, 'completeJob'>, job: Job, result?: unknown): Promise<CompleteResult>;
+export declare function failDurableJob<Job, FailOptions>(lifecycle: Pick<DurableJobLifecycle<Job, unknown, FailOptions>, 'failJob'>, job: Job, error: string, opts?: FailOptions): Promise<void>;
+export declare function releaseDurableJob<Job, ReleaseResult>(lifecycle: Pick<DurableJobLifecycle<Job, unknown, unknown, ReleaseResult>, 'releaseJob'>, job: Job, opts?: ReleaseDurableJobOptions): Promise<ReleaseResult | undefined>;
+export declare function findDispatchableDurableJobs<Queue extends string, Record extends Pick<DurableJobRecord<Queue>, 'id' | 'queue'>>(repository: Pick<DurableJobRecoveryRepository<Queue, Record>, 'findDispatchableJobs'>, query?: DurableJobRecoveryQuery): Promise<Record[]>;
+export declare function releaseStaleReservedDurableJobs<Queue extends string, Record extends Pick<DurableJobRecord<Queue>, 'id' | 'queue'>>(repository: Pick<DurableJobRecoveryRepository<Queue, Record>, 'releaseStaleReservedJobs'>, query: DurableJobStaleRecoveryQuery): Promise<number>;
+export declare function enqueueDurableJob<Queue extends string, Record extends DurableJobRecord<Queue>>(repository: Pick<DurableJobRepository<Queue, Record>, 'insertJob'>, publisher: Pick<QueuePublisher<Queue>, 'send'>, record: Record, opts?: {
+    delaySeconds?: number;
+}): Promise<{
+    inserted: boolean;
+    dispatched: boolean;
+    error?: unknown;
+}>;
+export interface SweepDurableJobsResult<Queue extends string> {
+    swept: number;
+    dispatched: Array<{
+        queue: Queue;
+        dispatched: boolean;
+        error?: unknown;
+    }>;
+}
+export declare function sweepDispatchableDurableJobs<Queue extends string>(repository: Pick<DurableJobRecoveryRepository<Queue, Pick<DurableJobRecord<Queue>, 'id' | 'queue'>>, 'findDispatchableJobs'>, publisher: Pick<QueuePublisher<Queue>, 'sendBatch'>, query?: DurableJobRecoveryQuery): Promise<SweepDurableJobsResult<Queue>>;
+export declare function dispatchDurableJobBatch<Queue extends string>(publisher: Pick<QueuePublisher<Queue>, 'sendBatch'>, records: Array<Pick<DurableJobRecord<Queue>, 'id' | 'queue'>>, opts?: {
+    delaySeconds?: number;
+}): Promise<Array<{
+    queue: Queue;
+    dispatched: boolean;
+    error?: unknown;
+}>>;
+export type DurableJobMessageStatus = 'invalid-message' | DurableJobClaimMiss | 'dispatch-failed' | 'released' | 'failed' | 'completed';
+export interface RunDurableJobMessageOptions<StoredJob, Job extends DispatchableJob, Message extends QueueJobMessage = QueueJobMessage, Env = unknown, Db = unknown, Logger = unknown, CompleteResult = unknown, FailOptions = unknown> {
+    message: Pick<QueueMessage<Message>, 'body' | 'ack' | 'retry'>;
+    lifecycle: Pick<DurableJobLifecycle<StoredJob, CompleteResult, FailOptions>, 'claimJob' | 'resolveClaimMiss' | 'completeJob' | 'failJob' | 'releaseJob'>;
+    registry: {
+        getHandler: (name: string) => JobHandler<unknown, Env, Db, Logger> | undefined;
+        getJobDefinition?: (name: string) => JobDefinition<string, unknown, string, Env, Db, Logger> | undefined;
+    };
+    toDispatchableJob: (job: StoredJob) => Job;
+    createJobContext: (input: {
+        job: Job;
+        storedJob: StoredJob;
+        taskName: string;
+        payload: Record<string, unknown>;
+        control: JobControlResult;
+    }) => JobContext<Env, Db, Logger> | Promise<JobContext<Env, Db, Logger>>;
+    getJobId?: (message: Message) => string | undefined;
+    retryDelaySeconds?: number | ((input: {
+        error: unknown;
+        job: StoredJob;
+    }) => number);
+    failDispatchFailure?: boolean;
+    completeResult?: (input: {
+        job: StoredJob;
+        dispatch: DispatchResult;
+    }) => unknown | Promise<unknown>;
+}
+export interface RunDurableJobMessageResult {
+    status: DurableJobMessageStatus;
+    dispatch?: DispatchResult;
+    error?: unknown;
+}
+export declare function runDurableJobMessage<StoredJob, Job extends DispatchableJob, Message extends QueueJobMessage = QueueJobMessage, Env = unknown, Db = unknown, Logger = unknown, CompleteResult = unknown, FailOptions = unknown>(opts: RunDurableJobMessageOptions<StoredJob, Job, Message, Env, Db, Logger, CompleteResult, FailOptions>): Promise<RunDurableJobMessageResult>;

package/dist/runtime/server/outbox.js

@@ -0,0 +1,246 @@
+import { buildJobPayload } from "./payload.js";
+import { createJobTraceId, createJobUniqueKey, resolveJobMaxAttempts } from "./policy.js";
+import { dispatchRegisteredJob } from "./dispatch.js";
+import { CF_QUEUE_MAX_MESSAGE_BYTES, sendBatchChunked, withSendBackpressure } from "./queue.js";
+import { parseJobInput } from "./registry.js";
+function byteLength(value) {
+  return typeof Buffer !== "undefined" ? Buffer.byteLength(value, "utf8") : new TextEncoder().encode(value).byteLength;
+}
+export async function prepareDurableJob(opts) {
+  const now = opts.now ?? Math.floor(Date.now() / 1e3);
+  const definition = opts.definition ?? opts.registry?.getJobDefinition?.(opts.name);
+  const route = resolveDurableJobRoute(opts.name, opts.route, definition, opts.registry);
+  const parsedPayload = parseJobInput(definition, opts.payload);
+  if (!parsedPayload.success)
+    throw new Error(`Invalid payload for task: ${opts.name}`);
+  const continuations = normalizeDurableJobContinuations(opts.continuations);
+  validateDurableJobContinuations(opts.registry, continuations);
+  const uniqueKey = definition?.unique ? await createJobUniqueKey(opts.name, parsedPayload.data, definition.uniqueId) : void 0;
+  const payload = buildJobPayload(opts.name, parsedPayload.data);
+  const serialized = JSON.stringify(continuations ? { ...payload, _continuations: continuations } : payload);
+  if (byteLength(serialized) > CF_QUEUE_MAX_MESSAGE_BYTES)
+    throw new Error(`Job payload exceeds Cloudflare Queue limit of ${CF_QUEUE_MAX_MESSAGE_BYTES} bytes for task: ${opts.name}`);
+  return {
+    id: opts.id ?? crypto.randomUUID(),
+    queue: route.queue,
+    jobType: route.jobType,
+    batchId: opts.batchId,
+    userId: opts.userId,
+    siteId: opts.siteId,
+    partnerId: opts.partnerId,
+    traceId: opts.traceId ?? createJobTraceId(),
+    uniqueKey,
+    payload: serialized,
+    attempts: 0,
+    maxAttempts: resolveJobMaxAttempts(definition) ?? opts.defaultMaxAttempts ?? 3,
+    availableAt: now + (opts.delaySeconds ?? 0),
+    createdAt: now
+  };
+}
+export async function prepareRegisteredDurableJob(registry, opts) {
+  return prepareDurableJob({
+    ...opts,
+    registry
+  });
+}
+function resolveDurableJobRoute(name, route, definition, registry) {
+  if (route)
+    return route;
+  const registeredRoute = registry?.getJobRoute?.(name);
+  if (registeredRoute)
+    return registeredRoute;
+  if (definition)
+    return { queue: definition.queue, jobType: definition.jobType ?? definition.name };
+  throw new Error(`No route for task: ${name}`);
+}
+export function normalizeDurableJobContinuations(continuations) {
+  if (!continuations)
+    return void 0;
+  const normalized = {};
+  for (const stage of ["then", "catch", "finally"]) {
+    const entries = continuations[stage]?.filter(Boolean);
+    if (entries?.length)
+      normalized[stage] = entries;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : void 0;
+}
+export function validateDurableJobContinuations(registry, continuations) {
+  if (!registry || !continuations)
+    return;
+  for (const stage of ["then", "catch", "finally"]) {
+    for (const continuation of continuations[stage] ?? []) {
+      const definition = registry.getJobDefinition?.(continuation.name);
+      if (!definition)
+        throw new Error(`No handler for continuation task: ${continuation.name}`);
+      const parsed = parseJobInput(definition, continuation.payload);
+      if (!parsed.success)
+        throw new Error(`Invalid payload for continuation task: ${continuation.name}`);
+      if (continuation.queue && definition.queue !== continuation.queue)
+        throw new Error(`Continuation task "${continuation.name}" is registered on queue "${definition.queue}", not "${continuation.queue}"`);
+    }
+  }
+}
+export function getDurableJobContinuations(payload) {
+  if (!payload || typeof payload !== "object")
+    return void 0;
+  return normalizeDurableJobContinuations(
+    payload._continuations
+  );
+}
+export function getDurableJobContinuationsForStage(payload, stage) {
+  return getDurableJobContinuations(payload)?.[stage] ?? [];
+}
+export function serializeDurableJobContinuation(continuation) {
+  return JSON.stringify(continuation);
+}
+export function parseDurableJobContinuation(value) {
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed.name !== "string" || !parsed.payload || typeof parsed.payload !== "object")
+    throw new Error("Invalid durable job continuation");
+  return parsed;
+}
+export async function dispatchDurableJobContinuations(continuations, dispatch) {
+  await Promise.all(continuations.map((continuation) => dispatch(continuation)));
+}
+export function toQueueJobMessage(record) {
+  return { jobId: record.id, queue: record.queue };
+}
+export function groupQueueJobMessagesByQueue(records) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const messages = groups.get(record.queue) ?? [];
+    messages.push(toQueueJobMessage(record));
+    groups.set(record.queue, messages);
+  }
+  return groups;
+}
+export function createQueuePublisher(env, resolveBinding, opts = {}) {
+  function getBinding(queue) {
+    const binding = resolveBinding(queue);
+    if (!binding)
+      return void 0;
+    const cfQueue = env[binding];
+    return cfQueue && typeof cfQueue.send === "function" ? cfQueue : void 0;
+  }
+  return {
+    async send(queue, message, sendOpts) {
+      const cfQueue = getBinding(queue);
+      if (!cfQueue) {
+        await opts.onMissingBinding?.(queue, 1);
+        return false;
+      }
+      await withSendBackpressure(() => cfQueue.send(message, sendOpts), sendOpts);
+      return true;
+    },
+    async sendBatch(queue, messages, sendOpts) {
+      if (messages.length === 0)
+        return true;
+      const cfQueue = getBinding(queue);
+      if (!cfQueue) {
+        await opts.onMissingBinding?.(queue, messages.length);
+        return false;
+      }
+      await sendBatchChunked(cfQueue, messages, sendOpts);
+      return true;
+    }
+  };
+}
+export async function claimDurableJob(lifecycle, id) {
+  const job = await lifecycle.claimJob(id);
+  if (job)
+    return { status: "claimed", job };
+  return {
+    status: lifecycle.resolveClaimMiss ? await lifecycle.resolveClaimMiss(id) : "not-found"
+  };
+}
+export async function completeDurableJob(lifecycle, job, result) {
+  return await lifecycle.completeJob(job, result);
+}
+export async function failDurableJob(lifecycle, job, error, opts) {
+  await lifecycle.failJob(job, error, opts);
+}
+export async function releaseDurableJob(lifecycle, job, opts) {
+  return await lifecycle.releaseJob?.(job, opts);
+}
+export async function findDispatchableDurableJobs(repository, query) {
+  return await repository.findDispatchableJobs?.(query) ?? [];
+}
+export async function releaseStaleReservedDurableJobs(repository, query) {
+  return await repository.releaseStaleReservedJobs?.(query) ?? 0;
+}
+export async function enqueueDurableJob(repository, publisher, record, opts) {
+  const inserted = await repository.insertJob(record);
+  if (!inserted)
+    return { inserted: false, dispatched: false };
+  const dispatched = await publisher.send(record.queue, toQueueJobMessage(record), opts).catch((error) => ({ error }));
+  if (typeof dispatched === "object" && dispatched && "error" in dispatched)
+    return { inserted: true, dispatched: false, error: dispatched.error };
+  return { inserted: true, dispatched };
+}
+export async function sweepDispatchableDurableJobs(repository, publisher, query) {
+  const records = await findDispatchableDurableJobs(repository, query);
+  if (records.length === 0)
+    return { swept: 0, dispatched: [] };
+  const dispatched = await dispatchDurableJobBatch(publisher, records);
+  return { swept: records.length, dispatched };
+}
+export async function dispatchDurableJobBatch(publisher, records, opts) {
+  const groups = groupQueueJobMessagesByQueue(records);
+  return await Promise.all(
+    [...groups].map(async ([queue, messages]) => {
+      try {
+        return {
+          queue,
+          dispatched: await publisher.sendBatch(queue, messages, opts)
+        };
+      } catch (error) {
+        return { queue, dispatched: false, error };
+      }
+    })
+  );
+}
+export async function runDurableJobMessage(opts) {
+  const jobId = opts.getJobId?.(opts.message.body) ?? opts.message.body.jobId;
+  if (!jobId) {
+    opts.message.ack();
+    return { status: "invalid-message" };
+  }
+  const claimed = await claimDurableJob(opts.lifecycle, jobId);
+  if (claimed.status !== "claimed") {
+    if (claimed.status === "in-flight")
+      opts.message.retry({ delaySeconds: 60 });
+    else
+      opts.message.ack();
+    return { status: claimed.status };
+  }
+  const storedJob = claimed.job;
+  const job = opts.toDispatchableJob(storedJob);
+  try {
+    const dispatch = await dispatchRegisteredJob({
+      registry: opts.registry,
+      job,
+      createContext: (input) => opts.createJobContext({ ...input, storedJob })
+    });
+    if (!dispatch.success) {
+      if (opts.failDispatchFailure !== false)
+        await failDurableJob(opts.lifecycle, storedJob, dispatch.error ?? "Job dispatch failed");
+      opts.message.ack();
+      return { status: "dispatch-failed", dispatch };
+    }
+    if (dispatch.control?.handled) {
+      opts.message.ack();
+      return { status: dispatch.control.action === "failed" ? "failed" : "released", dispatch };
+    }
+    await completeDurableJob(opts.lifecycle, storedJob, await opts.completeResult?.({ job: storedJob, dispatch }));
+    opts.message.ack();
+    return { status: "completed", dispatch };
+  } catch (error) {
+    const delaySeconds = typeof opts.retryDelaySeconds === "function" ? opts.retryDelaySeconds({ error, job: storedJob }) : opts.retryDelaySeconds ?? 0;
+    await releaseDurableJob(opts.lifecycle, storedJob, {
+      delaySeconds,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    opts.message.retry({ delaySeconds });
+    return { status: "released", error };
+  }
+}

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

@@ -0,0 +1,3 @@
+export declare function buildJobPayload<const Name extends string, Payload extends object>(name: Name, payload: Payload): {
+    _task: Name;
+} & Payload;

package/dist/runtime/server/payload.js

@@ -0,0 +1,3 @@
+export function buildJobPayload(name, payload) {
+  return { _task: name, ...payload };
+}

package/dist/runtime/server/plugins/dev-queues.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,25 @@
+import { defineNitroPlugin, useRuntimeConfig } from "nitropack/runtime";
+import { createDevQueueRuntime } from "../dev.js";
+export default defineNitroPlugin((nitroApp) => {
+  const config = useRuntimeConfig().cfJobs;
+  const queues = config?.queues ?? {};
+  if (!Object.keys(queues).length)
+    return;
+  const runtime = createDevQueueRuntime({
+    queues,
+    onBatch: async (payload) => {
+      await nitroApp.hooks.callHook("cloudflare:queue", payload);
+    },
+    onError(error) {
+      console.error("[nuxt-cf-jobs] dev queue error:", error);
+    }
+  });
+  nitroApp.hooks.hook("request", (event) => {
+    const existing = event.context.cloudflare?.env;
+    event.context.cloudflare = {
+      ...event.context.cloudflare ?? {},
+      env: existing ? { ...runtime.env, ...existing } : runtime.env
+    };
+  });
+  nitroApp.hooks.hook("close", () => runtime.dispose());
+});

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

@@ -0,0 +1,10 @@
+import type { JobBackoff, JobDefinition } from './types.js';
+export declare function clampDelay(seconds: number | undefined): number | undefined;
+export declare function resolveJobMaxAttempts(definition: Pick<JobDefinition<string, unknown, string, unknown, unknown, unknown>, 'tries' | 'maxAttempts'> | undefined): number | undefined;
+export declare function resolveJobBackoff(backoff: JobBackoff | undefined, attempt: number): number | undefined;
+export declare function resolveJobRetryDelay(definition: Pick<JobDefinition<string, unknown, string, unknown, unknown, unknown>, 'backoff'> | undefined, attempt: number, opts?: {
+    baseSeconds?: number;
+    maxSeconds?: number;
+}): number;
+export declare function createJobTraceId(prefix?: string): string;
+export declare function createJobUniqueKey(name: string, payload: unknown, uniqueId?: (payload: never) => string): Promise<string>;

package/dist/runtime/server/policy.js

@@ -0,0 +1,49 @@
+const CF_QUEUE_MAX_DELAY_SECONDS = 43200;
+export function clampDelay(seconds) {
+  if (seconds === void 0)
+    return void 0;
+  if (seconds < 0)
+    return 0;
+  return Math.min(seconds, CF_QUEUE_MAX_DELAY_SECONDS);
+}
+export function resolveJobMaxAttempts(definition) {
+  return definition?.tries ?? definition?.maxAttempts;
+}
+export function resolveJobBackoff(backoff, attempt) {
+  if (typeof backoff === "function")
+    return clampDelay(backoff(attempt));
+  if (Array.isArray(backoff))
+    return clampDelay(backoff[Math.min(Math.max(attempt - 1, 0), backoff.length - 1)]);
+  return clampDelay(backoff);
+}
+export function resolveJobRetryDelay(definition, attempt, opts = {}) {
+  const configured = resolveJobBackoff(definition?.backoff, attempt);
+  if (configured !== void 0)
+    return configured;
+  const base = opts.baseSeconds ?? 10;
+  const max = Math.min(opts.maxSeconds ?? 300, CF_QUEUE_MAX_DELAY_SECONDS);
+  return Math.min(base * 2 ** Math.max(0, attempt - 1), max);
+}
+export function createJobTraceId(prefix = "job") {
+  return `${prefix}_${crypto.randomUUID()}`;
+}
+export async function createJobUniqueKey(name, payload, uniqueId) {
+  const source = uniqueId ? `${name}:${uniqueId(payload)}` : `${name}:${stableStringify(payload)}`;
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(source));
+  return `job_unique_${toHex(digest)}`;
+}
+function toHex(buffer) {
+  return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function stableStringify(value) {
+  if (typeof value === "bigint")
+    return `"@bigint:${value.toString()}"`;
+  if (value instanceof Date)
+    return `"@date:${value.toISOString()}"`;
+  if (Array.isArray(value))
+    return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => `${JSON.stringify(key)}:${stableStringify(nested)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}