nuxt-cf-jobs 0.0.2

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

@@ -0,0 +1,211 @@
+import type { JobRegistryLike } from './dispatch.js';
+import type { DurableJobFailureRepository } from './outbox.js';
+import type { AnyJobDefinition, JobPayloadOf } from './registry.js';
+import type { CloudflareQueue, CloudflareQueueSendBatchMessage, DispatchableJob, JobContext, JobControlResult, JobDefinition, QueueBindingsConfig, QueuePayload, QueueSendOptions } from './types.js';
+export declare const CF_QUEUE_MAX_BATCH_SIZE = 100;
+export declare const CF_QUEUE_MAX_BATCH_BYTES: number;
+export declare const CF_QUEUE_MAX_MESSAGE_BYTES: number;
+export declare const CF_QUEUE_MAX_DELAY_SECONDS = 43200;
+export interface SendBackpressureOptions {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    onError?: (input: {
+        error: unknown;
+        attempt: number;
+        willRetry: boolean;
+    }) => void | Promise<void>;
+}
+export declare function withSendBackpressure<R>(fn: () => Promise<R>, opts: SendBackpressureOptions | undefined): Promise<R>;
+export declare function sendBatchChunked<T>(cfQueue: CloudflareQueue<T>, messages: T[], opts?: QueueSendOptions & SendBackpressureOptions): Promise<void>;
+export declare function sendBatchMessagesChunked<T>(cfQueue: CloudflareQueue<T>, messages: Array<CloudflareQueueSendBatchMessage<T>>, opts?: SendBackpressureOptions): Promise<void>;
+export type QueueSource = Record<string, unknown> | {
+    context?: {
+        cloudflare?: {
+            env?: Record<string, unknown>;
+        } | unknown;
+    } | unknown;
+};
+export interface JobQueuePublisher<Job extends AnyJobDefinition> {
+    send: (payload: JobPayloadOf<Job>, opts?: QueueSendOptions & SendBackpressureOptions) => Promise<boolean>;
+    sendBatch: (payloads: Array<JobPayloadOf<Job>>, opts?: QueueSendOptions & SendBackpressureOptions) => Promise<boolean>;
+    sendBatchMessages: (messages: Array<{
+        payload: JobPayloadOf<Job>;
+        delaySeconds?: number;
+        contentType?: import('./types').QueueMessageContentType;
+    }>, opts?: SendBackpressureOptions) => Promise<boolean>;
+}
+export interface QueueBindingValidationIssue {
+    jobName: string;
+    queue: string;
+    reason: 'missing-binding';
+}
+export declare function validateJobQueueBindings(queues: QueueBindingsConfig, jobs: readonly Pick<AnyJobDefinition, 'name' | 'queue'>[]): QueueBindingValidationIssue[];
+export declare function assertJobQueueBindings(queues: QueueBindingsConfig, jobs: readonly Pick<AnyJobDefinition, 'name' | 'queue'>[]): void;
+/**
+ * Resolves the Cloudflare runtime env from a Nitro task context where no `H3Event` is available.
+ *
+ * Nitro tasks (`defineTask`) run without an event, so Cloudflare bindings must be threaded through
+ * `globalThis.__env__`. This helper reads that shim and returns the env (or `undefined`).
+ */
+export declare function resolveNitroTaskEnv(): Record<string, unknown> | undefined;
+export declare function resolveQueueSourceEnv(source: QueueSource | undefined): Record<string, unknown> | undefined;
+export declare function createJobQueue<const Job extends AnyJobDefinition>(source: QueueSource | undefined, queues: QueueBindingsConfig, definition: Job): JobQueuePublisher<Job>;
+export declare function resolveQueueBindingName(queues: QueueBindingsConfig, queueName: string): string | undefined;
+export declare function resolveCloudflareQueueName(queues: QueueBindingsConfig, queueName: string): string;
+export declare function resolveLogicalQueueName(queues: QueueBindingsConfig, cloudflareQueueName: string): string | undefined;
+export declare function resolveQueueJobType(queues: QueueBindingsConfig, queueName: string): string | undefined;
+export declare function getQueueBinding<T>(env: Record<string, unknown> | undefined, binding: string | undefined): CloudflareQueue<T> | undefined;
+export declare function getQueueBindingByName<T>(env: Record<string, unknown> | undefined, queues: QueueBindingsConfig, queueName: string): CloudflareQueue<T> | undefined;
+export declare function sendQueueMessage<T>(env: Record<string, unknown> | undefined, binding: string, message: T, opts?: QueueSendOptions & SendBackpressureOptions): Promise<boolean>;
+export declare function sendQueueBatch<T>(env: Record<string, unknown> | undefined, binding: string, messages: T[], opts?: QueueSendOptions & SendBackpressureOptions): Promise<boolean>;
+export declare function sendNamedQueueMessage<T>(env: Record<string, unknown> | undefined, queues: QueueBindingsConfig, queueName: string, message: T, opts?: QueueSendOptions & SendBackpressureOptions): Promise<boolean>;
+export declare function sendNamedQueueBatch<T>(env: Record<string, unknown> | undefined, queues: QueueBindingsConfig, queueName: string, messages: T[], opts?: QueueSendOptions & SendBackpressureOptions): Promise<boolean>;
+export interface DlqPublisher<T = Record<string, unknown>> {
+    send: (message: T, opts?: QueueSendOptions & SendBackpressureOptions) => Promise<boolean>;
+}
+export declare function createDlqPublisher<T = Record<string, unknown>, Env extends Record<string, unknown> = Record<string, unknown>>(env: Env | undefined, binding: string): DlqPublisher<T>;
+export declare function shouldSendToDlq(input: {
+    attempts: number;
+    maxAttempts?: number;
+}): boolean;
+export declare function resolveDlqBinding(queues: QueueBindingsConfig, logicalQueue: string): string | undefined;
+export interface QueueConsumerConfigIssue {
+    queue: string;
+    jobName?: string;
+    reason: 'tries-exceeds-max-retries' | 'dlq-binding-missing';
+    detail: string;
+}
+export declare function validateQueueConsumerConfig(queues: QueueBindingsConfig, jobs: readonly AnyJobDefinition[]): QueueConsumerConfigIssue[];
+export interface QueueShapeIssue {
+    queue: string;
+    reason: 'missing-binding' | 'dlq-pair-incomplete' | 'duplicate-binding' | 'duplicate-cf-queue-name';
+    detail: string;
+}
+export declare function validateQueueBindingShape(queues: QueueBindingsConfig): QueueShapeIssue[];
+/**
+ * Identity helper that pins the literal types of a queues config and runs structural validation eagerly.
+ * Throws on shape issues (duplicate bindings, half-configured DLQ pairs) so misconfig fails fast.
+ *
+ * @example
+ *   export const queues = defineCfJobsQueues({
+ *     default: 'QUEUE_DEFAULT',
+ *     critical: { binding: 'QUEUE_CRITICAL', queueName: 'critical-prod', maxRetries: 5 },
+ *   } as const)
+ */
+export declare function defineCfJobsQueues<const T extends QueueBindingsConfig>(queues: T): T;
+export declare function registerQueueConsumer<T, Env extends Record<string, unknown>>(nitroApp: {
+    hooks: {
+        hook: (name: any, handler: any) => void;
+    };
+}, queueName: string, handler: (payload: QueuePayload<T, Env>) => Promise<void>, queues?: QueueBindingsConfig): void;
+export interface RegisteredQueueConsumerMessage<T = Record<string, unknown>> {
+    id?: string;
+    body: T;
+    attempts: number;
+    timestamp?: Date | number;
+    ack: () => void;
+    retry: (opts?: {
+        delaySeconds?: number;
+    }) => void;
+}
+export interface RegisteredQueueConsumerBatch<T = Record<string, unknown>> {
+    queue: string;
+    messages: Array<RegisteredQueueConsumerMessage<T>>;
+    ackAll?: () => void;
+    retryAll?: (opts?: {
+        delaySeconds?: number;
+    }) => void;
+}
+export interface RegisteredQueueConsumerPayload<Env extends Record<string, unknown>> {
+    batch: RegisteredQueueConsumerBatch;
+    env: Env;
+}
+export interface DlqMessageInput<Env extends Record<string, unknown>> {
+    env: Env;
+    batch: RegisteredQueueConsumerBatch;
+    message: RegisteredQueueConsumerMessage;
+    /** Parsed `_task` from the message body, when present. */
+    taskName?: string;
+    /** Parsed `jobId` from the message body, when present. */
+    jobId?: string;
+}
+export interface DlqQueueHandler<Env extends Record<string, unknown>> {
+    /** When true, the message is persisted via `dlqRepository.recordFailure` (if configured). */
+    persist?: boolean;
+    /** Custom per-message handler. Runs after `persist` (if enabled). Errors are propagated. */
+    onMessage?: (input: DlqMessageInput<Env>) => void | Promise<void>;
+}
+export type DlqQueuesOption<Env extends Record<string, unknown>> = readonly string[] | ((cfQueueName: string) => boolean) | Record<string, DlqQueueHandler<Env>>;
+export interface RegisteredQueueConsumerContextInput<Env extends Record<string, unknown>> {
+    env: Env;
+    batch: RegisteredQueueConsumerBatch;
+    message: RegisteredQueueConsumerMessage;
+    logicalQueue: string;
+    taskName: string;
+    definition: JobDefinition<string, unknown, string, Env, unknown, unknown>;
+    job: DispatchableJob;
+    control: JobControlResult;
+    payload: Record<string, unknown>;
+}
+export interface RegisteredQueueConsumerHookInput<Env extends Record<string, unknown>> {
+    env: Env;
+    batch: RegisteredQueueConsumerBatch;
+    message: RegisteredQueueConsumerMessage;
+    logicalQueue?: string;
+    taskName?: string;
+    definition?: AnyJobDefinition;
+    job?: DispatchableJob;
+}
+export interface RegisterRegisteredQueueConsumerOptions<Env extends Record<string, unknown>, Db, Logger> {
+    registry: JobRegistryLike<Env, Db, Logger> & {
+        jobs?: readonly AnyJobDefinition[];
+    };
+    queues: QueueBindingsConfig | (() => QueueBindingsConfig);
+    createContext: (input: RegisteredQueueConsumerContextInput<Env>) => JobContext<Env, Db, Logger> | Promise<JobContext<Env, Db, Logger>>;
+    getJobId?: (input: RegisteredQueueConsumerHookInput<Env> & {
+        payload: Record<string, unknown>;
+    }) => string;
+    getSiteId?: (payload: Record<string, unknown>) => string | null | undefined;
+    getUserId?: (payload: Record<string, unknown>) => number | null | undefined;
+    retryDelaySeconds?: (input: RegisteredQueueConsumerHookInput<Env> & {
+        error: unknown;
+    }) => number;
+    dlqQueues?: DlqQueuesOption<Env>;
+    /** Forward exhausted messages to a DLQ. If unspecified, falls back to the binding resolved from `queues[logical].deadLetterQueueBinding`/`deadLetterQueue`. */
+    dlqBinding?: string | ((input: {
+        logicalQueue: string;
+        definition?: AnyJobDefinition;
+    }) => string | undefined);
+    /**
+     * Repository used to persist exhausted DLQ messages when `dlqQueues` is set to the
+     * `Record<string, { persist: true }>` form. Cloudflare's wrangler `dead_letter_queue` directive
+     * only forwards messages CF-side; you still need a `cloudflare:queue` consumer for the DLQ to
+     * persist them, which this option provides.
+     */
+    dlqRepository?: DurableJobFailureRepository;
+    /** Delay (s) applied when unknown-queue messages are returned to the queue. Defaults to 60. */
+    unknownQueueRetryDelaySeconds?: number;
+    /** In-memory dedup cache size for the lightweight (non-durable) consumer path. Set to 0 to disable. */
+    dedupCacheSize?: number;
+    onMissingQueue?: (input: RegisteredQueueConsumerHookInput<Env>) => void | Promise<void>;
+    onInvalidPayload?: (input: RegisteredQueueConsumerHookInput<Env> & {
+        error?: string;
+        validationError?: unknown;
+    }) => void | Promise<void>;
+    onDispatchError?: (input: RegisteredQueueConsumerHookInput<Env> & {
+        error: unknown;
+    }) => void | Promise<void>;
+    onDlq?: (input: RegisteredQueueConsumerHookInput<Env>) => void | Promise<void>;
+    onDuplicate?: (input: RegisteredQueueConsumerHookInput<Env>) => void | Promise<void>;
+}
+export declare function registerRegisteredQueueConsumer<Env extends Record<string, unknown>, Db, Logger>(nitroApp: {
+    hooks: {
+        hook: (name: any, handler: any) => void;
+    };
+}, opts: RegisterRegisteredQueueConsumerOptions<Env, Db, Logger>): void;
+export declare function processRegisteredQueueBatch<Env extends Record<string, unknown>, Db, Logger>(payload: RegisteredQueueConsumerPayload<Env>, opts: RegisterRegisteredQueueConsumerOptions<Env, Db, Logger>): Promise<void>;
+export declare function exponentialBackoff(attempts: number, opts?: {
+    baseSeconds?: number;
+    maxSeconds?: number;
+}): number;