@trigger.dev/redis-worker 4.3.1 → 4.3.2

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Callback, Result, RedisOptions, Redis } from '@internal/redis';
 import { Logger } from '@trigger.dev/core/logger';
 import { z } from 'zod';
-import { Tracer, Meter, Counter, Histogram, ObservableGauge, Span, SpanKind, Attributes } from '@internal/tracing';
+import { Tracer, Meter, Counter, Histogram, ObservableGauge, Span, SpanKind, Attributes, Context } from '@internal/tracing';
 import { RetryOptions as RetryOptions$1 } from '@trigger.dev/core/v3/schemas';
 
 interface MessageCatalogSchema {
@@ -229,6 +229,15 @@ declare class Worker<TCatalog extends WorkerCatalog> {
     stop(): Promise<void>;
 }
 
+/**
+ * Check if an error is an AbortError.
+ *
+ * This handles both:
+ * - Custom abort errors created with `new Error("AbortError")` (sets .message)
+ * - Native Node.js AbortError from timers/promises (sets .name)
+ */
+declare function isAbortError(error: unknown): boolean;
+
 /**
  * RetryStrategy interface for pluggable retry logic.
  */
@@ -481,6 +490,12 @@ interface FairScheduler {
      * Optional - not all schedulers need to track state.
      */
     recordProcessed?(tenantId: string, queueId: string): Promise<void>;
+    /**
+     * Called after processing multiple messages to update scheduler state.
+     * Batch variant for efficiency - reduces Redis calls when processing multiple messages.
+     * Optional - falls back to calling recordProcessed multiple times if not implemented.
+     */
+    recordProcessedBatch?(tenantId: string, queueId: string, count: number): Promise<void>;
     /**
      * Initialize the scheduler (called once on startup).
      */
@@ -544,14 +559,15 @@ interface FairQueueKeyProducer {
 }
 /**
  * Worker queue configuration options.
+ * Worker queues are always enabled - FairQueue routes messages to worker queues,
+ * and external consumers are responsible for consuming from those queues.
  */
 interface WorkerQueueOptions<TPayload = unknown> {
-    /** Whether to enable worker queues (default: false for backwards compatibility) */
-    enabled: boolean;
-    /** Blocking pop timeout in seconds (default: 10) */
-    blockingTimeoutSeconds?: number;
-    /** Function to resolve which worker queue a message should go to */
-    resolveWorkerQueue?: (message: StoredMessage<TPayload>) => string;
+    /**
+     * Function to resolve which worker queue a message should go to.
+     * This is called during the claim-and-push phase to determine the target queue.
+     */
+    resolveWorkerQueue: (message: StoredMessage<TPayload>) => string;
 }
 /**
  * Retry and dead letter queue configuration.
@@ -572,6 +588,8 @@ interface CooloffOptions {
     threshold?: number;
     /** Duration of cooloff period in milliseconds (default: 10000) */
     periodMs?: number;
+    /** Maximum number of cooloff state entries before triggering cleanup (default: 1000) */
+    maxStatesSize?: number;
 }
 /**
  * Options for creating a FairQueue instance.
@@ -593,8 +611,11 @@ interface FairQueueOptions<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     shardCount?: number;
     /** Concurrency group configurations */
     concurrencyGroups?: ConcurrencyGroupConfig[];
-    /** Worker queue configuration */
-    workerQueue?: WorkerQueueOptions<z.infer<TPayloadSchema>>;
+    /**
+     * Worker queue configuration.
+     * FairQueue routes messages to worker queues; external consumers handle consumption.
+     */
+    workerQueue: WorkerQueueOptions<z.infer<TPayloadSchema>>;
     /** Retry and dead letter queue configuration */
     retry?: RetryOptions;
     /** Visibility timeout in milliseconds (default: 30000) */
@@ -609,6 +630,12 @@ interface FairQueueOptions<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     consumerIntervalMs?: number;
     /** Whether to start consumers on initialization (default: true) */
     startConsumers?: boolean;
+    /** Maximum number of messages to claim in a single batch operation (default: 10) */
+    batchClaimSize?: number;
+    /** Maximum iterations before starting a new trace span (default: 500) */
+    consumerTraceMaxIterations?: number;
+    /** Maximum seconds before starting a new trace span (default: 60) */
+    consumerTraceTimeoutSeconds?: number;
     /** Queue cooloff configuration */
     cooloff?: CooloffOptions;
     /** Logger instance */
@@ -718,6 +745,8 @@ interface DRRSchedulerConfig {
     quantum: number;
     /** Maximum accumulated deficit (prevents starvation) */
     maxDeficit: number;
+    /** Maximum queues to fetch from master queue (default: 1000) */
+    masterQueueLimit?: number;
     /** Redis options for state storage */
     redis: RedisOptions;
     /** Key producer */
@@ -969,6 +998,11 @@ declare class ConcurrencyManager {
      * Get current concurrency for a specific group.
      */
     getCurrentConcurrency(groupName: string, groupId: string): Promise<number>;
+    /**
+     * Get available capacity for a queue across all concurrency groups.
+     * Returns the minimum available capacity across all groups.
+     */
+    getAvailableCapacity(queue: QueueDescriptor): Promise<number>;
     /**
      * Get concurrency limit for a specific group.
      */
@@ -1054,6 +1088,19 @@ declare class VisibilityManager {
      * @returns Claim result with the message if successful
      */
     claim<TPayload = unknown>(queueId: string, queueKey: string, queueItemsKey: string, consumerId: string, timeoutMs?: number): Promise<ClaimResult<TPayload>>;
+    /**
+     * Claim multiple messages for processing (batch claim).
+     * Moves up to maxCount messages from the queue to the in-flight set.
+     *
+     * @param queueId - The queue to claim from
+     * @param queueKey - The Redis key for the queue sorted set
+     * @param queueItemsKey - The Redis key for the queue items hash
+     * @param consumerId - ID of the consumer claiming the messages
+     * @param maxCount - Maximum number of messages to claim
+     * @param timeoutMs - Visibility timeout in milliseconds
+     * @returns Array of claimed messages
+     */
+    claimBatch<TPayload = unknown>(queueId: string, queueKey: string, queueItemsKey: string, consumerId: string, maxCount: number, timeoutMs?: number): Promise<Array<InFlightMessage<TPayload>>>;
     /**
      * Extend the visibility timeout for a message (heartbeat).
      *
@@ -1079,9 +1126,25 @@ declare class VisibilityManager {
      * @param queueId - The queue ID
      * @param queueKey - The Redis key for the queue
      * @param queueItemsKey - The Redis key for the queue items hash
+     * @param masterQueueKey - The Redis key for the master queue
      * @param score - Optional score for the message (defaults to now)
      */
-    release<TPayload = unknown>(messageId: string, queueId: string, queueKey: string, queueItemsKey: string, score?: number): Promise<void>;
+    release<TPayload = unknown>(messageId: string, queueId: string, queueKey: string, queueItemsKey: string, masterQueueKey: string, score?: number): Promise<void>;
+    /**
+     * Release multiple messages back to their queue in a single operation.
+     * Used when processing fails or consumer wants to retry later.
+     * All messages must belong to the same queue.
+     *
+     * @param messages - Array of messages to release (must all have same queueId)
+     * @param queueId - The queue ID
+     * @param queueKey - The Redis key for the queue
+     * @param queueItemsKey - The Redis key for the queue items hash
+     * @param masterQueueKey - The Redis key for the master queue
+     * @param score - Optional score for the messages (defaults to now)
+     */
+    releaseBatch(messages: Array<{
+        messageId: string;
+    }>, queueId: string, queueKey: string, queueItemsKey: string, masterQueueKey: string, score?: number): Promise<void>;
     /**
      * Reclaim timed-out messages from a shard.
      * Returns messages to their original queues.
@@ -1093,6 +1156,7 @@ declare class VisibilityManager {
     reclaimTimedOut(shardId: number, getQueueKeys: (queueId: string) => {
         queueKey: string;
         queueItemsKey: string;
+        masterQueueKey: string;
     }): Promise<number>;
     /**
      * Get all in-flight messages for a shard.
@@ -1118,7 +1182,9 @@ declare class VisibilityManager {
 declare module "@internal/redis" {
     interface RedisCommander<Context> {
         claimMessage(queueKey: string, queueItemsKey: string, inflightKey: string, inflightDataKey: string, queueId: string, consumerId: string, deadline: string): Promise<[string, string] | null>;
-        releaseMessage(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, member: string, messageId: string, score: string): Promise<number>;
+        claimMessageBatch(queueKey: string, queueItemsKey: string, inflightKey: string, inflightDataKey: string, queueId: string, deadline: string, maxCount: string): Promise<string[]>;
+        releaseMessage(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, masterQueueKey: string, member: string, messageId: string, score: string, queueId: string): Promise<number>;
+        releaseMessageBatch(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, masterQueueKey: string, score: string, queueId: string, ...membersAndMessageIds: string[]): Promise<number>;
         heartbeatMessage(inflightKey: string, member: string, newDeadline: string): Promise<number>;
     }
 }
@@ -1239,6 +1305,12 @@ declare abstract class BaseScheduler implements FairScheduler {
      * Default implementation does nothing.
      */
     recordProcessed(_tenantId: string, _queueId: string): Promise<void>;
+    /**
+     * Called after processing multiple messages to update scheduler state.
+     * Batch variant for efficiency - reduces Redis calls when processing multiple messages.
+     * Default implementation does nothing.
+     */
+    recordProcessedBatch(_tenantId: string, _queueId: string, _count: number): Promise<void>;
     /**
      * Initialize the scheduler.
      * Default implementation does nothing.
@@ -1294,6 +1366,7 @@ declare class DRRScheduler extends BaseScheduler {
     private keys;
     private quantum;
     private maxDeficit;
+    private masterQueueLimit;
     private logger;
     constructor(config: DRRSchedulerConfig);
     /**
@@ -1313,6 +1386,11 @@ declare class DRRScheduler extends BaseScheduler {
      * Decrements the tenant's deficit.
      */
     recordProcessed(tenantId: string, _queueId: string): Promise<void>;
+    /**
+     * Record that multiple messages were processed from a tenant.
+     * Decrements the tenant's deficit by count atomically.
+     */
+    recordProcessedBatch(tenantId: string, _queueId: string, count: number): Promise<void>;
     close(): Promise<void>;
     /**
      * Get the current deficit for a tenant.
@@ -1332,6 +1410,7 @@ declare module "@internal/redis" {
     interface RedisCommander<Context> {
         drrAddQuantum(deficitKey: string, quantum: string, maxDeficit: string, ...tenantIds: string[]): Promise<string[]>;
         drrDecrementDeficit(deficitKey: string, tenantId: string): Promise<string>;
+        drrDecrementDeficitBatch(deficitKey: string, tenantId: string, count: string): Promise<string>;
     }
 }
 
@@ -1522,7 +1601,8 @@ declare class FairQueueTelemetry {
         observedTenants?: string[];
     }): void;
     /**
-     * Create standard attributes for a message operation.
+     * Create standard attributes for a message operation (for spans/traces).
+     * Use this for span attributes where high cardinality is acceptable.
      */
     messageAttributes(params: {
         queueId?: string;
@@ -1545,23 +1625,124 @@ declare class FairQueueTelemetry {
      */
     get hasMetrics(): boolean;
 }
+/**
+ * State for tracking a consumer loop's batched span.
+ */
+interface ConsumerLoopState {
+    /** Countdown of iterations before starting a new span */
+    perTraceCountdown: number;
+    /** When the current trace started */
+    traceStartedAt: Date;
+    /** The current batched span */
+    currentSpan?: Span;
+    /** The context for the current batched span */
+    currentSpanContext?: Context;
+    /** Number of iterations in the current span */
+    iterationsCount: number;
+    /** Total iterations across all spans */
+    totalIterationsCount: number;
+    /** Running duration in milliseconds for the current span */
+    runningDurationInMs: number;
+    /** Stats counters for the current span */
+    stats: Record<string, number>;
+    /** Flag to force span end on next iteration */
+    endSpanInNextIteration: boolean;
+}
+/**
+ * Configuration for the BatchedSpanManager.
+ */
+interface BatchedSpanManagerOptions {
+    /** The tracer to use for creating spans */
+    tracer?: Tracer;
+    /** Name prefix for spans */
+    name: string;
+    /** Maximum iterations before rotating the span */
+    maxIterations: number;
+    /** Maximum seconds before rotating the span */
+    timeoutSeconds: number;
+    /** Optional callback to get dynamic attributes when starting a new batched span */
+    getDynamicAttributes?: () => Attributes;
+}
+/**
+ * Manages batched spans for consumer loops.
+ *
+ * This allows multiple iterations to be grouped into a single parent span,
+ * reducing the volume of spans while maintaining observability.
+ */
+declare class BatchedSpanManager {
+    private tracer?;
+    private name;
+    private maxIterations;
+    private timeoutSeconds;
+    private loopStates;
+    private getDynamicAttributes?;
+    constructor(options: BatchedSpanManagerOptions);
+    /**
+     * Initialize state for a consumer loop.
+     */
+    initializeLoop(loopId: string): void;
+    /**
+     * Get the state for a consumer loop.
+     */
+    getState(loopId: string): ConsumerLoopState | undefined;
+    /**
+     * Increment a stat counter for a loop.
+     */
+    incrementStat(loopId: string, statName: string, value?: number): void;
+    /**
+     * Mark that the span should end on the next iteration.
+     */
+    markForRotation(loopId: string): void;
+    /**
+     * Check if the span should be rotated (ended and a new one started).
+     */
+    shouldRotate(loopId: string): boolean;
+    /**
+     * End the current span for a loop and record stats.
+     */
+    endCurrentSpan(loopId: string): void;
+    /**
+     * Start a new batched span for a loop.
+     */
+    startNewSpan(loopId: string, attributes?: Attributes): void;
+    /**
+     * Execute a function within the batched span context.
+     * Automatically handles span rotation and iteration tracking.
+     */
+    withBatchedSpan<T>(loopId: string, fn: (span: Span) => Promise<T>, options?: {
+        iterationSpanName?: string;
+        attributes?: Attributes;
+    }): Promise<T>;
+    /**
+     * Clean up state for a loop when it's stopped.
+     */
+    cleanup(loopId: string): void;
+    /**
+     * Clean up all loop states.
+     */
+    cleanupAll(): void;
+}
 /**
  * No-op telemetry instance for when telemetry is disabled.
  */
 declare const noopTelemetry: FairQueueTelemetry;
 
 /**
- * FairQueue is the main orchestrator for fair queue processing.
+ * FairQueue is the main orchestrator for fair queue message routing.
  *
- * It coordinates:
+ * FairQueue handles:
  * - Master queue with sharding (using jump consistent hash)
  * - Fair scheduling via pluggable schedulers
  * - Multi-level concurrency limiting
  * - Visibility timeouts with heartbeats
- * - Worker queues with blocking pop
+ * - Routing messages to worker queues
  * - Retry strategies with dead letter queue
  * - OpenTelemetry tracing and metrics
  *
+ * External consumers are responsible for:
+ * - Running their own worker queue consumer loops
+ * - Calling complete/release/fail APIs after processing
+ *
  * @typeParam TPayloadSchema - Zod schema for message payload validation
  */
 declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
@@ -1573,7 +1754,7 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     private masterQueue;
     private concurrencyManager?;
     private visibilityManager;
-    private workerQueueManager?;
+    private workerQueueManager;
     private telemetry;
     private logger;
     private payloadSchema?;
@@ -1586,19 +1767,20 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     private visibilityTimeoutMs;
     private heartbeatIntervalMs;
     private reclaimIntervalMs;
-    private workerQueueEnabled;
-    private workerQueueBlockingTimeoutSeconds;
-    private workerQueueResolver?;
+    private workerQueueResolver;
+    private batchClaimSize;
     private cooloffEnabled;
     private cooloffThreshold;
     private cooloffPeriodMs;
+    private maxCooloffStatesSize;
     private queueCooloffStates;
     private globalRateLimiter?;
-    private messageHandler?;
+    private consumerTraceMaxIterations;
+    private consumerTraceTimeoutSeconds;
+    private batchedSpanManager;
     private isRunning;
     private abortController;
     private masterQueueConsumerLoops;
-    private workerQueueConsumerLoops;
     private reclaimLoop?;
     private queueDescriptorCache;
     constructor(options: FairQueueOptions<TPayloadSchema>);
@@ -1611,10 +1793,6 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     registerTelemetryGauges(options?: {
         observedTenants?: string[];
     }): void;
-    /**
-     * Set the message handler for processing dequeued messages.
-     */
-    onMessage(handler: MessageHandler<z.infer<TPayloadSchema>>): void;
     /**
      * Enqueue a single message to a queue.
      */
@@ -1644,7 +1822,29 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
      */
     getDeadLetterQueueLength(tenantId: string): Promise<number>;
     /**
-     * Start the consumer loops and reclaim loop.
+     * Get the size of the in-memory queue descriptor cache.
+     * This cache stores metadata for queues that have been enqueued.
+     * The cache is cleaned up when queues are fully processed.
+     */
+    getQueueDescriptorCacheSize(): number;
+    /**
+     * Get the size of the in-memory cooloff states cache.
+     * This cache tracks queues that are in cooloff due to repeated failures.
+     * The cache is cleaned up when queues are fully processed or cooloff expires.
+     */
+    getQueueCooloffStatesSize(): number;
+    /**
+     * Get all in-memory cache sizes for monitoring.
+     * Useful for adding as span attributes.
+     */
+    getCacheSizes(): {
+        descriptorCacheSize: number;
+        cooloffStatesSize: number;
+    };
+    /**
+     * Start the master queue consumer loops and reclaim loop.
+     * FairQueue claims messages and pushes them to worker queues.
+     * External consumers are responsible for consuming from worker queues.
      */
     start(): void;
     /**
@@ -1671,6 +1871,49 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
      * Get the shard ID for a queue.
      */
     getShardForQueue(queueId: string): number;
+    /**
+     * Get message data from in-flight storage.
+     * External consumers use this to retrieve the stored message after popping from worker queue.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     * @returns The stored message or null if not found
+     */
+    getMessageData(messageId: string, queueId: string): Promise<StoredMessage<z.infer<TPayloadSchema>> | null>;
+    /**
+     * Extend the visibility timeout for a message.
+     * External consumers should call this periodically during long-running processing.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     * @returns true if heartbeat was successful
+     */
+    heartbeatMessage(messageId: string, queueId: string): Promise<boolean>;
+    /**
+     * Mark a message as successfully processed.
+     * This removes the message from in-flight and releases concurrency.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     */
+    completeMessage(messageId: string, queueId: string): Promise<void>;
+    /**
+     * Release a message back to the queue for processing by another consumer.
+     * The message is placed at the back of the queue.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     */
+    releaseMessage(messageId: string, queueId: string): Promise<void>;
+    /**
+     * Mark a message as failed. This will trigger retry logic if configured,
+     * or move the message to the dead letter queue.
+     *
+     * @param messageId - The ID of the message
+     * @param queueId - The queue ID the message belongs to
+     * @param error - Optional error that caused the failure
+     */
+    failMessage(messageId: string, queueId: string, error?: Error): Promise<void>;
 }
 declare module "@internal/redis" {
     interface RedisCommander<Context> {
@@ -1680,4 +1923,4 @@ declare module "@internal/redis" {
     }
 }
 
-export { type AnyMessageCatalog, type AnyQueueItem, BaseScheduler, CallbackFairQueueKeyProducer, type ClaimResult, type ConcurrencyCheckResult, type ConcurrencyGroupConfig, ConcurrencyManager, type ConcurrencyManagerOptions, type ConcurrencyState, type CooloffOptions, CronSchema, CustomRetry, DRRScheduler, type DRRSchedulerConfig, type DeadLetterMessage, DefaultFairQueueKeyProducer, type EnqueueBatchOptions, type EnqueueOptions, ExponentialBackoffRetry, FairQueue, FairQueueAttributes, type FairQueueKeyProducer, type FairQueueMetrics, type FairQueueOptions, FairQueueTelemetry, type FairScheduler, FixedDelayRetry, type GlobalRateLimiter, ImmediateRetry, type InFlightMessage, type JobHandler, type JobHandlerParams, LinearBackoffRetry, MasterQueue, type MasterQueueOptions, type MessageCatalogKey, type MessageCatalogSchema, type MessageCatalogValue, type MessageHandler, type MessageHandlerContext, MessagingAttributes, NoRetry, NoopScheduler, type QueueCooloffState, type QueueDescriptor, type QueueItem, type QueueMessage, type QueueWithScore, type RetryOptions, type RetryStrategy, RoundRobinScheduler, type SchedulerContext, SimpleQueue, type StoredMessage, type TelemetryOptions, type TenantQueues, VisibilityManager, type VisibilityManagerOptions, WeightedScheduler, type WeightedSchedulerBiases, type WeightedSchedulerConfig, Worker, type WorkerCatalog, type WorkerConcurrencyOptions, WorkerQueueManager, type WorkerQueueManagerOptions, type WorkerQueueOptions, createDefaultRetryStrategy, defaultRetryOptions, noopTelemetry };
+export { type AnyMessageCatalog, type AnyQueueItem, BaseScheduler, BatchedSpanManager, type BatchedSpanManagerOptions, CallbackFairQueueKeyProducer, type ClaimResult, type ConcurrencyCheckResult, type ConcurrencyGroupConfig, ConcurrencyManager, type ConcurrencyManagerOptions, type ConcurrencyState, type ConsumerLoopState, type CooloffOptions, CronSchema, CustomRetry, DRRScheduler, type DRRSchedulerConfig, type DeadLetterMessage, DefaultFairQueueKeyProducer, type EnqueueBatchOptions, type EnqueueOptions, ExponentialBackoffRetry, FairQueue, FairQueueAttributes, type FairQueueKeyProducer, type FairQueueMetrics, type FairQueueOptions, FairQueueTelemetry, type FairScheduler, FixedDelayRetry, type GlobalRateLimiter, ImmediateRetry, type InFlightMessage, type JobHandler, type JobHandlerParams, LinearBackoffRetry, MasterQueue, type MasterQueueOptions, type MessageCatalogKey, type MessageCatalogSchema, type MessageCatalogValue, type MessageHandler, type MessageHandlerContext, MessagingAttributes, NoRetry, NoopScheduler, type QueueCooloffState, type QueueDescriptor, type QueueItem, type QueueMessage, type QueueWithScore, type RetryOptions, type RetryStrategy, RoundRobinScheduler, type SchedulerContext, SimpleQueue, type StoredMessage, type TelemetryOptions, type TenantQueues, VisibilityManager, type VisibilityManagerOptions, WeightedScheduler, type WeightedSchedulerBiases, type WeightedSchedulerConfig, Worker, type WorkerCatalog, type WorkerConcurrencyOptions, WorkerQueueManager, type WorkerQueueManagerOptions, type WorkerQueueOptions, createDefaultRetryStrategy, defaultRetryOptions, isAbortError, noopTelemetry };