@taicode/common-server 3.7.7 → 3.7.8

package/output/redis-queue/redis-queue-consumer.js

@@ -0,0 +1,327 @@
+import { catchIt } from '@taicode/common-base';
+import { logger } from '@taicode/common-base';
+import { RedisQueueCommon } from './redis-queue-common.js';
+/**
+ * Redis 队列消费者
+ *
+ * 只负责消费任务,不包含入队逻辑
+ *
+ * @template R Registry 类型,默认为 RedisQueueRegistry
+ * @template K 队列键名类型
+ *
+ * @example
+ * ```ts
+ * // 方式 1: 使用默认 RedisQueueRegistry
+ * const consumer = new RedisQueueConsumer('email-queue', {
+ *   redisUrl: 'redis://localhost:6379',
+ *   concurrency: 5,
+ *   handler: async (data) => {
+ *     await sendEmail(data.to, data.subject)
+ *     return catchIt(() => {})
+ *   }
+ * })
+ *
+ * // 方式 2: 使用自定义 Registry
+ * interface MyRegistry {
+ *   'order-queue': { orderId: string; amount: number }
+ * }
+ *
+ * const consumer = new RedisQueueConsumer<MyRegistry, 'order-queue'>(
+ *   'order-queue',
+ *   {
+ *     redisUrl: 'redis://localhost:6379',
+ *     handler: async (data) => {
+ *       logger.info(data.orderId, data.amount)
+ *       return catchIt(() => {})
+ *     }
+ *   }
+ * )
+ *
+ * await consumer.connect() // 自动开始消费
+ *
+ * // 获取统计信息
+ * const stats = await consumer.statistics()
+ *
+ * // 停止消费
+ * consumer.disconnect()
+ * ```
+ */
+export class RedisQueueConsumer extends RedisQueueCommon {
+    consumerRunning = false;
+    consumerInterval = null;
+    recoveryInterval = null;
+    processingTasks = 0; // 当前正在处理的任务数
+    processingPromises = new Set(); // 跟踪所有正在处理的任务
+    config;
+    constructor(queueKey, config) {
+        // 验证必填参数
+        if (!config.handler) {
+            throw new Error('[RedisQueueConsumer] handler is required');
+        }
+        // 调用父类构造函数
+        super(queueKey, {
+            redisUrl: config.redisUrl,
+            redisClient: config.redisClient,
+            cleanupDelay: config.cleanupDelay ?? 86400,
+        });
+        this.config = {
+            handler: config.handler,
+            maxRetries: config.maxRetries ?? 3,
+            concurrency: config.concurrency ?? 1,
+            consumerInterval: config.consumerInterval ?? 1000,
+            processingTimeout: config.processingTimeout ?? 60000,
+            cleanupDelay: config.cleanupDelay ?? 86400,
+        };
+    }
+    getLogPrefix() {
+        return 'RedisQueueConsumer';
+    }
+    /**
+     * 连接 Redis 并自动启动消费者
+     */
+    async connect() {
+        await super.connect();
+        // 连接成功后启动消费者和恢复机制
+        this.startConsumer();
+        this.startRecovery();
+    }
+    /**
+     * 断开 Redis 连接并停止消费者
+     * 会等待所有正在处理的任务完成后再断开连接
+     */
+    async disconnect() {
+        // 先停止消费者和恢复机制，不再接受新任务
+        this.stopConsumer();
+        this.stopRecovery();
+        // 等待所有正在处理的任务完成
+        if (this.processingPromises.size > 0) {
+            logger.info(`[RedisQueueConsumer] Waiting for ${this.processingPromises.size} tasks to complete...`);
+            await Promise.allSettled(this.processingPromises);
+            logger.info(`[RedisQueueConsumer] All tasks completed`);
+        }
+        // 最后断开 Redis 连接
+        super.disconnect();
+    }
+    /**
+     * 处理单个任务
+     */
+    async processTask(taskId) {
+        this.processingTasks++;
+        // 创建一个 Promise 来跟踪这个任务的处理过程
+        const taskPromise = (async () => {
+            try {
+                const task = await this.getTask(taskId);
+                if (!task) {
+                    logger.warn(`[RedisQueueConsumer] Task not found: ${taskId}`);
+                    return;
+                }
+                // 任务应该是 pending 状态(Lua 脚本已确保延迟检查)
+                if (task.status !== 'pending') {
+                    logger.info(`[RedisQueueConsumer] Task ${taskId} has invalid status (${task.status}), marking as failed`);
+                    await this.applyStatus(taskId, task.status, 'failed');
+                    return;
+                }
+                try {
+                    // 任务已在 processing 队列中(由 Lua 脚本完成),只需更新状态和开始时间
+                    task.status = 'processing';
+                    task.processingStartTime = Date.now();
+                    const taskKey = `${this.queueKey}:task:${taskId}`;
+                    await this.redis.setEx(taskKey, this.config.cleanupDelay, JSON.stringify(task));
+                    // 执行任务处理器
+                    await this.config.handler(task.data);
+                    // 更新状态为完成
+                    await this.applyStatus(taskId, 'processing', 'completed');
+                    logger.info(`[RedisQueueConsumer] Task completed: ${taskId}`);
+                }
+                catch (error) {
+                    logger.error(`[RedisQueueConsumer] Task failed: ${taskId}`, error);
+                    // 检查是否需要重试
+                    if (task.retryCount < task.maxRetries) {
+                        task.retryCount++;
+                        task.status = 'pending';
+                        task.processingStartTime = undefined;
+                        const taskKey = `${this.queueKey}:task:${taskId}`;
+                        // 使用 Lua 脚本确保原子性
+                        const script = `
+            redis.call('SETEX', KEYS[1], ARGV[1], ARGV[2])
+            redis.call('LREM', KEYS[2], 0, ARGV[3])
+            redis.call('RPUSH', KEYS[3], ARGV[3])
+            return 1
+          `;
+                        await this.redis.eval(script, {
+                            keys: [taskKey, this.processingQueue, this.pendingQueue],
+                            arguments: [this.config.cleanupDelay.toString(), JSON.stringify(task), taskId],
+                        });
+                        logger.info(`[RedisQueueConsumer] Task ${taskId} will retry (${task.retryCount}/${task.maxRetries})`);
+                    }
+                    else {
+                        task.status = 'failed';
+                        task.processingStartTime = undefined;
+                        const taskKey = `${this.queueKey}:task:${taskId}`;
+                        // 使用 Lua 脚本确保原子性
+                        const script = `
+            redis.call('SETEX', KEYS[1], ARGV[1], ARGV[2])
+            redis.call('LREM', KEYS[2], 0, ARGV[3])
+            redis.call('RPUSH', KEYS[3], ARGV[3])
+            return 1
+          `;
+                        await this.redis.eval(script, {
+                            keys: [taskKey, this.processingQueue, this.failedQueue],
+                            arguments: [this.config.cleanupDelay.toString(), JSON.stringify(task), taskId],
+                        });
+                        logger.error(`[RedisQueueConsumer] Task ${taskId} failed after ${task.maxRetries} retries`);
+                    }
+                }
+            }
+            finally {
+                this.processingTasks--;
+            }
+        })();
+        // 将任务 Promise 添加到集合中
+        this.processingPromises.add(taskPromise);
+        // 任务完成后从集合中移除
+        taskPromise.finally(() => {
+            this.processingPromises.delete(taskPromise);
+        });
+        // 返回任务 Promise
+        return taskPromise;
+    }
+    /**
+     * 启动恢复机制（内部方法，自动调用）
+     */
+    startRecovery() {
+        if (this.recoveryInterval || !this.redis) {
+            return;
+        }
+        // 立即执行一次恢复
+        this.recoverStalled(this.config.processingTimeout).catch(error => {
+            logger.error('[RedisQueueConsumer] Initial recovery error:', error);
+        });
+        // 定期检查（每 10 秒检查一次）
+        this.recoveryInterval = setInterval(() => {
+            this.recoverStalled(this.config.processingTimeout).catch(error => {
+                logger.error('[RedisQueueConsumer] Recovery error:', error);
+            });
+        }, 10000);
+        logger.info('[RedisQueueConsumer] Recovery mechanism started');
+    }
+    /**
+     * 停止恢复机制（内部方法，自动调用）
+     */
+    stopRecovery() {
+        if (this.recoveryInterval) {
+            clearInterval(this.recoveryInterval);
+            this.recoveryInterval = null;
+            logger.info('[RedisQueueConsumer] Recovery mechanism stopped');
+        }
+    }
+    /**
+     * 启动消费者（内部方法，自动调用）
+     */
+    startConsumer() {
+        if (this.consumerRunning || !this.redis) {
+            return;
+        }
+        this.consumerRunning = true;
+        logger.info(`[RedisQueueConsumer] Consumer started with concurrency: ${this.config.concurrency}`);
+        // Lua 脚本: 原子化从 pending 取出任务并移到 processing(只取已到延迟时间的任务)
+        const popAndMoveScript = `
+      local pendingQueue = KEYS[1]
+      local processingQueue = KEYS[2]
+      local queueKeyPrefix = KEYS[3]
+      local count = tonumber(ARGV[1])
+      local currentTime = tonumber(ARGV[2])
+      
+      local taskIds = {}
+      local checkedCount = 0
+      local maxCheck = count * 3  -- 最多检查 count*3 个任务,避免无限循环
+      
+      while #taskIds < count and checkedCount < maxCheck do
+        local taskId = redis.call('LPOP', pendingQueue)
+        if not taskId then
+          break
+        end
+        
+        checkedCount = checkedCount + 1
+        
+        -- 获取任务详情检查延迟时间
+        local taskKey = queueKeyPrefix .. ':task:' .. taskId
+        local taskData = redis.call('GET', taskKey)
+        
+        if taskData then
+          local task = cjson.decode(taskData)
+          local delayUntil = task.delayUntil
+          
+          -- 如果没有延迟或已到延迟时间,则移到 processing
+          if not delayUntil or delayUntil <= currentTime then
+            redis.call('RPUSH', processingQueue, taskId)
+            table.insert(taskIds, taskId)
+          else
+            -- 未到延迟时间,放回队列尾部
+            redis.call('RPUSH', pendingQueue, taskId)
+          end
+        end
+      end
+      
+      return taskIds
+    `;
+        this.consumerInterval = setInterval(async () => {
+            try {
+                // 检查当前是否有可用的并发槽位
+                const availableSlots = this.config.concurrency - this.processingTasks;
+                if (availableSlots <= 0) {
+                    return; // 已达到并发限制，等待下一次轮询
+                }
+                // 使用 Lua 脚本原子化取出任务并移到 processing 队列
+                const taskIds = await this.redis.eval(popAndMoveScript, {
+                    keys: [this.pendingQueue, this.processingQueue, this.queueKey],
+                    arguments: [availableSlots.toString(), Date.now().toString()],
+                });
+                // 并发处理所有任务（不等待完成）
+                taskIds.forEach(taskId => {
+                    this.processTask(taskId).catch(error => {
+                        logger.error(`[RedisQueueConsumer] Unhandled error in processTask: ${taskId}`, error);
+                    });
+                });
+            }
+            catch (error) {
+                logger.error('[RedisQueueConsumer] Consumer error:', error);
+            }
+        }, this.config.consumerInterval);
+    }
+    /**
+     * 停止消费者（内部方法，自动调用）
+     */
+    stopConsumer() {
+        if (this.consumerInterval) {
+            clearInterval(this.consumerInterval);
+            this.consumerInterval = null;
+        }
+        this.consumerRunning = false;
+        logger.info('[RedisQueueConsumer] Consumer stopped');
+    }
+    /**
+     * 获取队列统计信息（O(1) 时间复杂度）
+     */
+    async statistics() {
+        if (!this.redis) {
+            return { pending: 0, processing: 0, completed: 0, failed: 0 };
+        }
+        const [pending, processing, completed, failed] = await Promise.all([
+            this.redis.lLen(this.pendingQueue),
+            this.redis.lLen(this.processingQueue),
+            this.redis.lLen(this.completedQueue),
+            this.redis.lLen(this.failedQueue),
+        ]);
+        return { pending, processing, completed, failed };
+    }
+    /**
+     * 健康检查
+     */
+    async health() {
+        if (!this.redis)
+            return false;
+        const result = await catchIt(() => this.redis.ping());
+        return !result.isError() && result.value === 'PONG';
+    }
+}

package/output/redis-queue/redis-queue-consumer.test.d.ts

@@ -0,0 +1,26 @@
+type TestTaskData = {
+    id?: string;
+    value?: number | string;
+    test?: boolean | string;
+    index?: number;
+    payload?: string;
+    order?: number;
+    taskId?: number;
+    message?: string;
+    name?: string;
+    shouldFail?: boolean;
+    step?: number;
+    real?: boolean;
+    nested?: {
+        value: number;
+    };
+    example?: string;
+    data?: any;
+};
+declare module './types.js' {
+    interface RedisQueueRegistry {
+        [key: `test:queue:${string}`]: TestTaskData;
+    }
+}
+export {};
+//# sourceMappingURL=redis-queue-consumer.test.d.ts.map

package/output/redis-queue/redis-queue-consumer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-queue-consumer.test.d.ts","sourceRoot":"","sources":["../../source/redis-queue/redis-queue-consumer.test.ts"],"names":[],"mappings":"AAQA,KAAK,YAAY,GAAG;IAClB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,GAAG,CAAA;CACX,CAAA;AAGD,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,kBAAkB;QAC1B,CAAC,GAAG,EAAE,cAAc,MAAM,EAAE,GAAG,YAAY,CAAA;KAC5C;CACF"}

package/output/redis-queue/redis-queue-consumer.test.js

@@ -0,0 +1,316 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { catchIt } from '@taicode/common-base';
+import { RedisQueueProvider } from './redis-queue-provider.js';
+import { RedisQueueConsumer } from './redis-queue-consumer.js';
+import { dispatchQueueTask, waitQueueCompletion, clearQueue, getQueueTasks } from './test-helpers.js';
+const REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379';
+describe('RedisQueueConsumer', () => {
+    const providers = [];
+    const consumers = [];
+    afterEach(async () => {
+        for (const consumer of consumers) {
+            await clearQueue(consumer);
+            await consumer.disconnect();
+        }
+        for (const provider of providers) {
+            provider.disconnect();
+        }
+        providers.length = 0;
+        consumers.length = 0;
+    });
+    const createQueue = (handler, options) => {
+        const uniqueKey = `test:queue:${Date.now()}:${Math.random()}`;
+        const provider = new RedisQueueProvider(uniqueKey, {
+            redisUrl: REDIS_URL,
+        });
+        const consumer = new RedisQueueConsumer(uniqueKey, {
+            redisUrl: REDIS_URL,
+            consumerInterval: 100,
+            maxRetries: 2,
+            ...options,
+            handler,
+        });
+        providers.push(provider);
+        consumers.push(consumer);
+        return { provider, consumer };
+    };
+    describe('连接管理', () => {
+        it('应该成功连接到 Redis', async () => {
+            const { consumer } = createQueue(async () => catchIt(() => { }));
+            await consumer.connect();
+            const health = await consumer.health();
+            expect(health).toBe(true);
+        });
+        it('连接后应该自动启动消费者', async () => {
+            let processed = false;
+            const { provider, consumer } = createQueue(async () => {
+                processed = true;
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue({ test: true });
+            await new Promise(resolve => setTimeout(resolve, 300));
+            expect(processed).toBe(true);
+        });
+    });
+    describe('任务处理', () => {
+        it('应该成功处理任务', async () => {
+            const processedData = [];
+            const { provider, consumer } = createQueue(async (data) => {
+                processedData.push(data);
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue({ value: 'test' });
+            await new Promise(resolve => setTimeout(resolve, 500));
+            expect(processedData).toHaveLength(1);
+            expect(processedData[0]).toEqual({ value: 'test' });
+            const stats = await consumer.statistics();
+            expect(stats.completed).toBe(1);
+        });
+        it('应该能够使用 dispatchQueueTask 立即处理任务', async () => {
+            const processedData = [];
+            const { provider, consumer } = createQueue(async (data) => {
+                processedData.push(data);
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            const taskIds = await provider.enqueue([{ value: 1 }, { value: 2 }, { value: 3 }]);
+            // 使用 dispatchQueueTask 立即处理任务
+            await dispatchQueueTask(consumer, taskIds);
+            expect(processedData).toHaveLength(3);
+            expect(processedData.map(d => d.value)).toEqual([1, 2, 3]);
+            const stats = await consumer.statistics();
+            expect(stats.completed).toBe(3);
+        });
+        it('应该按 FIFO 顺序处理任务', async () => {
+            const processOrder = [];
+            const { provider, consumer } = createQueue(async (data) => {
+                if (data.order !== undefined) {
+                    processOrder.push(data.order);
+                }
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue([{ order: 1 }, { order: 2 }, { order: 3 }]);
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            expect(processOrder).toEqual([1, 2, 3]);
+        });
+        it('应该能够使用 waitQueueCompletion 等待队列完成', async () => {
+            const { provider, consumer } = createQueue(async () => {
+                await new Promise(resolve => setTimeout(resolve, 100));
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue([{ test: 1 }, { test: 2 }, { test: 3 }]);
+            // 等待所有任务完成
+            await waitQueueCompletion(consumer, stats => stats.pending === 0 && stats.processing === 0 && stats.completed === 3);
+            const stats = await consumer.statistics();
+            expect(stats.completed).toBe(3);
+        });
+        it('应该能够使用 getQueueTasks 获取任务详情', async () => {
+            const { provider, consumer } = createQueue(async () => catchIt(() => { }));
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue([{ name: 'task1' }, { name: 'task2' }]);
+            // 获取待处理任务
+            const pendingTasks = await getQueueTasks(provider, 'pending');
+            expect(pendingTasks).toHaveLength(2);
+            expect(pendingTasks.map(t => t.data.name).sort()).toEqual(['task1', 'task2']);
+            // 等待任务完成
+            await waitQueueCompletion(consumer, stats => stats.completed === 2);
+            // 获取已完成任务
+            const completedTasks = await getQueueTasks(provider, 'completed');
+            expect(completedTasks).toHaveLength(2);
+            expect(completedTasks.every(t => t.status === 'completed')).toBe(true);
+        });
+    });
+    describe('重试机制', () => {
+        it('失败的任务应该自动重试', async () => {
+            let attemptCount = 0;
+            const { provider, consumer } = createQueue(async () => {
+                attemptCount++;
+                throw new Error('Task failed');
+            }, { maxRetries: 2 });
+            await provider.connect();
+            await consumer.connect();
+            const taskId = await provider.enqueue({ test: 1 });
+            await new Promise(resolve => setTimeout(resolve, 3000));
+            // 最多 1 次初始 + 2 次重试 = 3 次,但允许恢复机制导致的额外尝试
+            expect(attemptCount).toBeGreaterThanOrEqual(3);
+            expect(attemptCount).toBeLessThanOrEqual(4);
+            const stats = await consumer.statistics();
+            expect(stats.failed).toBe(1);
+        });
+    });
+    describe('消费者管理', () => {
+        it('断开连接后消费者应该停止', async () => {
+            let processCount = 0;
+            const { provider, consumer } = createQueue(async () => {
+                processCount++;
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue({ test: 1 });
+            await new Promise(resolve => setTimeout(resolve, 300));
+            expect(processCount).toBe(1);
+            await consumer.disconnect();
+            await provider.connect();
+            await provider.enqueue({ test: 2 });
+            await new Promise(resolve => setTimeout(resolve, 300));
+            expect(processCount).toBe(1); // 没有增加
+        });
+        it('disconnect 应该等待正在处理的任务完成', async () => {
+            const processedTasks = [];
+            let processingTask = null;
+            const { provider, consumer } = createQueue(async (data) => {
+                processingTask = data.taskId || 0;
+                await new Promise(resolve => setTimeout(resolve, 500)); // 模拟长时间处理
+                processedTasks.push(data.taskId || 0);
+                processingTask = null;
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            // 添加一个任务
+            await provider.enqueue({ taskId: 1 });
+            // 等待任务开始处理
+            await new Promise(resolve => setTimeout(resolve, 200));
+            expect(processingTask).toBe(1);
+            expect(processedTasks).toHaveLength(0);
+            // 调用 disconnect，应该等待任务完成
+            const disconnectPromise = consumer.disconnect();
+            // 此时任务应该还在处理中
+            expect(processingTask).toBe(1);
+            // 等待 disconnect 完成
+            await disconnectPromise;
+            // disconnect 完成后，任务应该已经处理完成
+            expect(processingTask).toBe(null);
+            expect(processedTasks).toHaveLength(1);
+            expect(processedTasks[0]).toBe(1);
+        });
+    });
+    describe('队列统计', () => {
+        it('应该正确返回队列统计信息', async () => {
+            const { provider, consumer } = createQueue(async () => {
+                await new Promise(resolve => setTimeout(resolve, 100));
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue([{ data: 1 }, { data: 2 }, { data: 3 }]);
+            await new Promise(resolve => setTimeout(resolve, 50));
+            const stats = await consumer.statistics();
+            expect(stats.pending + stats.processing).toBeGreaterThan(0);
+        });
+    });
+    describe('并发处理', () => {
+        it('应该支持并发处理多个任务', async () => {
+            const processing = [];
+            const completed = [];
+            const { provider, consumer } = createQueue(async (data) => {
+                if (data.taskId !== undefined) {
+                    processing.push(data.taskId);
+                }
+                await new Promise(resolve => setTimeout(resolve, 200));
+                if (data.taskId !== undefined) {
+                    completed.push(data.taskId);
+                }
+                return catchIt(() => { });
+            }, { concurrency: 3 });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue([
+                { taskId: 1 }, { taskId: 2 }, { taskId: 3 }, { taskId: 4 }, { taskId: 5 },
+            ]);
+            await new Promise(resolve => setTimeout(resolve, 250));
+            expect(processing.length).toBeGreaterThanOrEqual(2);
+            await new Promise(resolve => setTimeout(resolve, 1500));
+            expect(completed.length).toBe(5);
+        });
+    });
+    describe('幂等性', () => {
+        it('应该支持在 data 中指定 id 来实现幂等性', async () => {
+            let processCount = 0;
+            const { provider, consumer } = createQueue(async () => {
+                processCount++;
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue({ id: 'unique-1', value: 1 });
+            await provider.enqueue({ id: 'unique-1', value: 2 });
+            await provider.enqueue({ id: 'unique-2', value: 3 });
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            expect(processCount).toBe(2); // 只处理 unique-1 和 unique-2
+        });
+    });
+    describe('延迟处理', () => {
+        it('应该支持延迟处理任务', async () => {
+            const startTime = Date.now();
+            let processTime = 0;
+            const { provider, consumer } = createQueue(async () => {
+                processTime = Date.now() - startTime;
+                return catchIt(() => { });
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue({ test: true });
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            expect(processTime).toBeGreaterThan(0);
+        });
+    });
+    describe('超时恢复', () => {
+        it('超时的任务应该直接标记为失败', { timeout: 15000 }, async () => {
+            let processCount = 0;
+            const { provider, consumer } = createQueue(async () => {
+                processCount++;
+                // 模拟处理卡住，永远不完成 (但超时机制会检测到)
+                await new Promise(resolve => setTimeout(resolve, 20000));
+                return catchIt(() => { });
+            }, {
+                processingTimeout: 500, // 500ms 超时
+                consumerInterval: 100,
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue({ value: 1 });
+            // 等待任务被处理和超时恢复 (需要等待至少2个恢复周期: 10秒)
+            await new Promise(resolve => setTimeout(resolve, 12000));
+            const stats = await consumer.statistics();
+            // 超时后直接标记为失败,不应该重试
+            expect(stats.failed).toBe(1);
+            expect(stats.pending).toBe(0);
+            expect(stats.processing).toBe(0);
+            expect(stats.completed).toBe(0);
+            // 应该只处理一次,不会重试
+            expect(processCount).toBe(1);
+        });
+        it('未超时的失败任务应该正常重试', async () => {
+            let attemptCount = 0;
+            const { provider, consumer } = createQueue(async () => {
+                attemptCount++;
+                throw new Error('Task failed');
+            }, {
+                maxRetries: 3,
+                processingTimeout: 5000, // 5秒超时,足够长不会触发
+                consumerInterval: 100,
+            });
+            await provider.connect();
+            await consumer.connect();
+            await provider.enqueue({ value: 1 });
+            // 等待所有重试完成
+            await new Promise(resolve => setTimeout(resolve, 3000));
+            const stats = await consumer.statistics();
+            // 应该重试 3 次后失败
+            expect(stats.failed).toBe(1);
+            expect(attemptCount).toBe(4); // 初始 1 次 + 3 次重试
+        });
+    });
+});