@trigger.dev/redis-worker 4.4.1 → 4.4.3

package/dist/index.d.cts

@@ -97,6 +97,10 @@ declare const CronSchema: z.ZodObject<{
     lastTimestamp?: number | undefined;
 }>;
 type CronSchema = z.infer<typeof CronSchema>;
+type BatchConfig = {
+    maxSize: number;
+    maxWaitMs: number;
+};
 type WorkerCatalog = {
     [key: string]: {
         schema: z.ZodFirstPartySchemaTypes | z.ZodDiscriminatedUnion<any, any>;
@@ -106,6 +110,8 @@ type WorkerCatalog = {
         jitterInMs?: number;
         /** Defaults to true. If false, errors will not be logged. */
         logErrors?: boolean;
+        /** When set, items are accumulated and delivered in batches to the handler. */
+        batch?: BatchConfig;
     };
 };
 type QueueCatalogFromWorkerCatalog<Catalog extends WorkerCatalog> = {
@@ -119,6 +125,9 @@ type JobHandlerParams<Catalog extends WorkerCatalog, K extends keyof Catalog> =
     deduplicationKey?: string;
 };
 type JobHandler<Catalog extends WorkerCatalog, K extends keyof Catalog> = (params: JobHandlerParams<Catalog, K>) => Promise<void>;
+type JobHandlerFor<Catalog extends WorkerCatalog, K extends keyof Catalog> = Catalog[K] extends {
+    batch: BatchConfig;
+} ? (items: Array<JobHandlerParams<Catalog, K>>) => Promise<void> : (params: JobHandlerParams<Catalog, K>) => Promise<void>;
 type WorkerConcurrencyOptions = {
     workers?: number;
     tasksPerWorker?: number;
@@ -129,7 +138,7 @@ type WorkerOptions<TCatalog extends WorkerCatalog> = {
     redisOptions: RedisOptions;
     catalog: TCatalog;
     jobs: {
-        [K in keyof TCatalog]: JobHandler<TCatalog, K>;
+        [K in keyof TCatalog]: JobHandlerFor<TCatalog, K>;
     };
     concurrency?: WorkerConcurrencyOptions;
     pollIntervalMs?: number;
@@ -154,6 +163,7 @@ declare class Worker<TCatalog extends WorkerCatalog> {
     private concurrency;
     private shutdownTimeoutMs;
     private limiters;
+    private batchAccumulators;
     constructor(options: WorkerOptions<TCatalog>);
     start(): this;
     /**
@@ -206,11 +216,45 @@ declare class Worker<TCatalog extends WorkerCatalog> {
     cancel(cancellationKey: string): Promise<void>;
     ack(id: string): Promise<void>;
     getJob(id: string): Promise<QueueItem<QueueCatalogFromWorkerCatalog<TCatalog>> | null>;
+    /**
+     * Returns true if the given job type has batch config in the catalog.
+     */
+    private isBatchJob;
+    /**
+     * Returns the batch config for a job type, or undefined if not batch-enabled.
+     */
+    private getBatchConfig;
+    /**
+     * The max dequeue count: the largest batch maxSize across catalog entries,
+     * falling back to tasksPerWorker for non-batch catalogs.
+     */
+    private get maxDequeueCount();
     /**
      * The main loop that each worker runs. It repeatedly polls for items,
      * processes them, and then waits before the next iteration.
      */
     private runWorkerLoop;
+    /**
+     * Adds an item to the batch accumulator for its job type.
+     */
+    private addToAccumulator;
+    /**
+     * Flushes any batch accumulators that have exceeded their maxWaitMs.
+     */
+    private flushTimedOutBatches;
+    /**
+     * Flushes all batch accumulators (used during shutdown).
+     */
+    private flushAllBatches;
+    /**
+     * Flushes the batch accumulator for a specific job type.
+     * Removes items from the accumulator and submits them to the limiter as a single batch.
+     */
+    private flushBatch;
+    /**
+     * Processes a batch of items for a batch-enabled job type.
+     */
+    private processBatch;
     /**
      * Processes a single item.
      */
@@ -485,6 +529,13 @@ interface SchedulerContext {
     /** Get queue descriptor by ID */
     getQueueDescriptor(queueId: string): QueueDescriptor;
 }
+/**
+ * Extended context for two-level dispatch scheduling.
+ */
+interface DispatchSchedulerContext extends SchedulerContext {
+    /** Get queues for a specific tenant from the per-tenant queue index (Level 2) */
+    getQueuesForTenant(tenantId: string, limit?: number): Promise<QueueWithScore[]>;
+}
 /**
  * Pluggable scheduler interface for fair queue selection.
  */
@@ -499,6 +550,13 @@ interface FairScheduler {
      * @returns Queues grouped by tenant in priority order
      */
     selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
+    /**
+     * Select queues using the two-level tenant dispatch index.
+     * Level 1: reads tenantIds from dispatch shard.
+     * Level 2: reads queueIds from per-tenant index.
+     * Optional - falls back to selectQueues with flat queue list if not implemented.
+     */
+    selectQueuesFromDispatch?(dispatchShardKey: string, consumerId: string, context: DispatchSchedulerContext): Promise<TenantQueues[]>;
     /**
      * Called after processing a message to update scheduler state.
      * Optional - not all schedulers need to track state.
@@ -566,6 +624,10 @@ interface FairQueueKeyProducer {
     deadLetterQueueKey(tenantId: string): string;
     /** Get the dead letter queue data hash key for a tenant */
     deadLetterQueueDataKey(tenantId: string): string;
+    /** Get the dispatch index key for a shard (Level 1: tenantIds with capacity) */
+    dispatchKey(shardId: number): string;
+    /** Get the per-tenant queue index key (Level 2: queueIds for a tenant) */
+    tenantQueueIndexKey(tenantId: string): string;
     /** Extract tenant ID from a queue ID */
     extractTenantId(queueId: string): string;
     /** Extract a specific group ID from a queue ID */
@@ -660,8 +722,22 @@ interface FairQueueOptions<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     meter?: Meter;
     /** Name for metrics/tracing (default: "fairqueue") */
     name?: string;
-    /** Optional global rate limiter to limit processing across all consumers */
-    globalRateLimiter?: GlobalRateLimiter;
+    /**
+     * Maximum number of items allowed in a worker queue before claiming pauses.
+     * When set, the claim phase checks worker queue depth and skips claiming if
+     * the queue is at or above this limit. This prevents unbounded worker queue
+     * growth which could cause visibility timeouts (claimed messages have a
+     * visibility timeout that ticks while they sit in the worker queue).
+     * Requires `workerQueueDepthCheckId` to know which queue to check.
+     * Disabled by default (0 = no limit).
+     */
+    workerQueueMaxDepth?: number;
+    /**
+     * The worker queue ID to check depth against when workerQueueMaxDepth is set.
+     * Required when workerQueueMaxDepth > 0 and the system uses a single shared worker queue.
+     * If not set, depth checking is disabled even if workerQueueMaxDepth is set.
+     */
+    workerQueueDepthCheckId?: string;
 }
 /**
  * Context passed to the message handler.
@@ -822,7 +898,9 @@ interface WeightedSchedulerConfig {
  * Uses a configurable prefix and standard key structure.
  *
  * Key structure:
- * - Master queue: {prefix}:master:{shardId}
+ * - Master queue: {prefix}:master:{shardId} (legacy, drain-only)
+ * - Dispatch index: {prefix}:dispatch:{shardId} (Level 1: tenantIds)
+ * - Tenant queue index: {prefix}:tenantq:{tenantId} (Level 2: queueIds)
  * - Queue: {prefix}:queue:{queueId}
  * - Queue items: {prefix}:queue:{queueId}:items
  * - Concurrency: {prefix}:concurrency:{groupName}:{groupId}
@@ -845,6 +923,8 @@ declare class DefaultFairQueueKeyProducer implements FairQueueKeyProducer {
     inflightKey(shardId: number): string;
     inflightDataKey(shardId: number): string;
     workerQueueKey(consumerId: string): string;
+    dispatchKey(shardId: number): string;
+    tenantQueueIndexKey(tenantId: string): string;
     deadLetterQueueKey(tenantId: string): string;
     deadLetterQueueDataKey(tenantId: string): string;
     /**
@@ -1148,10 +1228,12 @@ 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 tenantQueueIndexKey - The Redis key for the tenant queue index (Level 2)
+     * @param dispatchKey - The Redis key for the dispatch index (Level 1)
+     * @param tenantId - The tenant ID
      * @param score - Optional score for the message (defaults to now)
      */
-    release<TPayload = unknown>(messageId: string, queueId: string, queueKey: string, queueItemsKey: string, masterQueueKey: string, score?: number): Promise<void>;
+    release<TPayload = unknown>(messageId: string, queueId: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, tenantId: string, score?: number, updatedData?: string): Promise<void>;
     /**
      * Release multiple messages back to their queue in a single operation.
      * Used when processing fails or consumer wants to retry later.
@@ -1161,12 +1243,14 @@ 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 tenantQueueIndexKey - The Redis key for the tenant queue index (Level 2)
+     * @param dispatchKey - The Redis key for the dispatch index (Level 1)
+     * @param tenantId - The tenant ID
      * @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>;
+    }>, queueId: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, tenantId: string, score?: number): Promise<void>;
     /**
      * Reclaim timed-out messages from a shard.
      * Returns messages to their original queues.
@@ -1178,7 +1262,9 @@ declare class VisibilityManager {
     reclaimTimedOut(shardId: number, getQueueKeys: (queueId: string) => {
         queueKey: string;
         queueItemsKey: string;
-        masterQueueKey: string;
+        tenantQueueIndexKey: string;
+        dispatchKey: string;
+        tenantId: string;
     }): Promise<ReclaimedMessageInfo[]>;
     /**
      * Get all in-flight messages for a shard.
@@ -1205,8 +1291,8 @@ 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>;
         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>;
+        releaseMessage(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, member: string, messageId: string, score: string, queueId: string, updatedData: string, tenantId: string): Promise<number>;
+        releaseMessageBatch(inflightKey: string, inflightDataKey: string, queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, score: string, queueId: string, tenantId: string, ...membersAndMessageIds: string[]): Promise<number>;
         heartbeatMessage(inflightKey: string, member: string, newDeadline: string): Promise<number>;
     }
 }
@@ -1403,6 +1489,17 @@ declare class DRRScheduler extends BaseScheduler {
      * 6. Order tenants by deficit (highest first for fairness)
      */
     selectQueues(masterQueueShard: string, consumerId: string, context: SchedulerContext): Promise<TenantQueues[]>;
+    /**
+     * Select queues using the two-level tenant dispatch index.
+     *
+     * Algorithm:
+     * 1. ZRANGEBYSCORE on dispatch index (gets only tenants with queues - much smaller)
+     * 2. Add quantum to each tenant's deficit (atomically)
+     * 3. Check capacity as safety net (dispatch should only have tenants with capacity)
+     * 4. Select tenants with deficit >= 1, sorted by deficit (highest first)
+     * 5. For each tenant, fetch their queues from Level 2 index
+     */
+    selectQueuesFromDispatch(dispatchShardKey: string, consumerId: string, context: DispatchSchedulerContext): Promise<TenantQueues[]>;
     /**
      * Record that a message was processed from a tenant.
      * Decrements the tenant's deficit.
@@ -1531,6 +1628,7 @@ interface FairQueueMetrics {
     queueTime: Histogram;
     queueLength: ObservableGauge;
     masterQueueLength: ObservableGauge;
+    dispatchLength: ObservableGauge;
     inflightCount: ObservableGauge;
     dlqLength: ObservableGauge;
 }
@@ -1616,6 +1714,7 @@ declare class FairQueueTelemetry {
     registerGaugeCallbacks(callbacks: {
         getQueueLength?: (queueId: string) => Promise<number>;
         getMasterQueueLength?: (shardId: number) => Promise<number>;
+        getDispatchLength?: (shardId: number) => Promise<number>;
         getInflightCount?: (shardId: number) => Promise<number>;
         getDLQLength?: (tenantId: string) => Promise<number>;
         shardCount?: number;
@@ -1749,6 +1848,83 @@ declare class BatchedSpanManager {
  */
 declare const noopTelemetry: FairQueueTelemetry;
 
+interface TenantDispatchOptions {
+    redis: RedisOptions;
+    keys: FairQueueKeyProducer;
+    shardCount: number;
+}
+interface TenantWithScore {
+    tenantId: string;
+    score: number;
+}
+/**
+ * TenantDispatch manages the two-level tenant dispatch index.
+ *
+ * Level 1 - Dispatch Index (per shard):
+ *   Key: {prefix}:dispatch:{shardId}
+ *   ZSET of tenantIds scored by oldest message timestamp across their queues.
+ *   Only tenants with queues containing messages appear here.
+ *
+ * Level 2 - Per-Tenant Queue Index:
+ *   Key: {prefix}:tenantq:{tenantId}
+ *   ZSET of queueIds scored by oldest message timestamp in that queue.
+ *
+ * This replaces the flat master queue for new enqueues, isolating each tenant's
+ * queue backlog so the scheduler iterates tenants (not queues) at Level 1.
+ */
+declare class TenantDispatch {
+    private options;
+    private redis;
+    private keys;
+    private shardCount;
+    constructor(options: TenantDispatchOptions);
+    /**
+     * Get the dispatch shard ID for a tenant.
+     * Uses jump consistent hash on the tenant ID so each tenant
+     * always maps to exactly one dispatch shard.
+     */
+    getShardForTenant(tenantId: string): number;
+    /**
+     * Get eligible tenants from a dispatch shard (Level 1).
+     * Returns tenants ordered by oldest message (lowest score first).
+     */
+    getTenantsFromShard(shardId: number, limit?: number, maxScore?: number): Promise<TenantWithScore[]>;
+    /**
+     * Get queues for a specific tenant (Level 2).
+     * Returns queues ordered by oldest message (lowest score first).
+     */
+    getQueuesForTenant(tenantId: string, limit?: number, maxScore?: number): Promise<QueueWithScore[]>;
+    /**
+     * Get the number of tenants in a dispatch shard.
+     */
+    getShardTenantCount(shardId: number): Promise<number>;
+    /**
+     * Get total tenant count across all dispatch shards.
+     * Note: tenants may appear in multiple shards, so this may overcount.
+     */
+    getTotalTenantCount(): Promise<number>;
+    /**
+     * Get the number of queues for a tenant.
+     */
+    getTenantQueueCount(tenantId: string): Promise<number>;
+    /**
+     * Remove a tenant from a specific dispatch shard.
+     */
+    removeTenantFromShard(shardId: number, tenantId: string): Promise<void>;
+    /**
+     * Add a tenant to a dispatch shard with the given score.
+     */
+    addTenantToShard(shardId: number, tenantId: string, score: number): Promise<void>;
+    /**
+     * Remove a queue from a tenant's queue index.
+     */
+    removeQueueFromTenant(tenantId: string, queueId: string): Promise<void>;
+    /**
+     * Close the Redis connection.
+     */
+    close(): Promise<void>;
+}
+
 /**
  * FairQueue is the main orchestrator for fair queue message routing.
  *
@@ -1796,7 +1972,8 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     private cooloffPeriodMs;
     private maxCooloffStatesSize;
     private queueCooloffStates;
-    private globalRateLimiter?;
+    private workerQueueMaxDepth;
+    private workerQueueDepthCheckId?;
     private consumerTraceMaxIterations;
     private consumerTraceTimeoutSeconds;
     private batchedSpanManager;
@@ -1805,6 +1982,7 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
     private masterQueueConsumerLoops;
     private reclaimLoop?;
     private queueDescriptorCache;
+    private tenantDispatch;
     constructor(options: FairQueueOptions<TPayloadSchema>);
     /**
      * Register observable gauge callbacks for telemetry.
@@ -1882,7 +2060,7 @@ declare class FairQueue<TPayloadSchema extends z.ZodTypeAny = z.ZodUnknown> {
      */
     getQueueLength(queueId: string): Promise<number>;
     /**
-     * Get total queue count across all shards.
+     * Get total tenant count across dispatch shards plus any legacy queues still draining.
      */
     getTotalQueueCount(): Promise<number>;
     /**
@@ -1942,7 +2120,10 @@ declare module "@internal/redis" {
         enqueueMessageAtomic(queueKey: string, queueItemsKey: string, masterQueueKey: string, queueId: string, messageId: string, timestamp: string, payload: string): Promise<number>;
         enqueueBatchAtomic(queueKey: string, queueItemsKey: string, masterQueueKey: string, queueId: string, ...args: string[]): Promise<number>;
         updateMasterQueueIfEmpty(masterQueueKey: string, queueKey: string, queueId: string): Promise<number>;
+        enqueueMessageAtomicV2(queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, queueId: string, messageId: string, timestamp: string, payload: string, tenantId: string): Promise<number>;
+        enqueueBatchAtomicV2(queueKey: string, queueItemsKey: string, tenantQueueIndexKey: string, dispatchKey: string, queueId: string, tenantId: string, ...args: string[]): Promise<number>;
+        updateDispatchIndexes(queueKey: string, tenantQueueIndexKey: string, dispatchKey: string, queueId: string, tenantId: string): Promise<number>;
     }
 }
 
-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 ReclaimedMessageInfo, 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 };
+export { type AnyMessageCatalog, type AnyQueueItem, BaseScheduler, type BatchConfig, 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 DispatchSchedulerContext, 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 ReclaimedMessageInfo, type RetryOptions, type RetryStrategy, RoundRobinScheduler, type SchedulerContext, SimpleQueue, type StoredMessage, type TelemetryOptions, TenantDispatch, type TenantDispatchOptions, type TenantQueues, type TenantWithScore, VisibilityManager, type VisibilityManagerOptions, WeightedScheduler, type WeightedSchedulerBiases, type WeightedSchedulerConfig, Worker, type WorkerCatalog, type WorkerConcurrencyOptions, WorkerQueueManager, type WorkerQueueManagerOptions, type WorkerQueueOptions, createDefaultRetryStrategy, defaultRetryOptions, isAbortError, noopTelemetry };