@zintrust/queue-redis 2.1.4 → 2.4.2

package/README.md

@@ -16,9 +16,16 @@ npm i @zintrust/queue-redis
 import '@zintrust/queue-redis/register';
 ```
 
-Then set `QUEUE_DRIVER=redis` and configure `REDIS_URL`.
+Then set `QUEUE_DRIVER=redis` and configure your Redis connection.
 
-For Cloudflare Workers, set `ENABLE_CLOUDFLARE_SOCKETS=true` and use a TCP-accessible Redis endpoint.
+For Cloudflare Workers or any runtime without Redis TCP access, run Redis RPC from a Node.js backend and configure the Worker with both flags:
+
+```bash
+USE_REDIS_PROXY=true
+REDIS_RPC_URL=https://queues.example.com
+```
+
+Start the backend with `zin redis-rpc` or `zin s redis-rpc`. See [`@zintrust/redis-rpc`](https://www.npmjs.com/package/@zintrust/redis-rpc).
 
 ## When to use
 

package/dist/BullMQRedisQueue.d.ts

@@ -1,5 +1,5 @@
 import type { BullMQPayload, QueueMessage } from '@zintrust/core/queue';
-import { Queue } from 'bullmq';
+import type { Queue } from 'bullmq';
 interface IQueueDriver {
     enqueue(queue: string, payload: BullMQPayload): Promise<string>;
     dequeue<T = unknown>(queue: string): Promise<QueueMessage<T> | undefined>;
@@ -8,13 +8,11 @@ interface IQueueDriver {
     drain(queue: string): Promise<void>;
 }
 interface IBullMQRedisQueue extends IQueueDriver {
-    getQueue(queueName: string): Queue;
+    getQueue(queueName: string): Promise<Queue>;
     shutdown(): Promise<void>;
     closeQueue(queueName: string): Promise<void>;
     getQueueNames(): string[];
 }
-export declare const shouldUseHttpProxyDriver: () => boolean;
-export declare const runWithDirectQueueDriver: <T>(fn: () => Promise<T>) => Promise<T>;
 /**
  * BullMQ Redis Queue Driver
  *

package/dist/BullMQRedisQueue.js

@@ -6,24 +6,19 @@ import { Logger } from '@zintrust/core/logger';
 import { createLockProvider, getLockProvider, registerLockProvider, resolveDeduplicationLockKey, resolveLockPrefix, } from '@zintrust/core/queue';
 import { createRedisConnection, getBullMQSafeQueueName } from '@zintrust/core/redis';
 import { generateUuid, ZintrustLang } from '@zintrust/core/utils';
-import { Queue } from 'bullmq';
-import { HttpQueueDriver } from './HttpQueueDriver.js';
-export const shouldUseHttpProxyDriver = () => {
-    if (directModeDepth > 0)
-        return false;
-    const isCloudFlareWorkers = Cloudflare.getWorkersEnv() !== null;
-    const isProxy = isCloudFlareWorkers || Env.getBool('QUEUE_HTTP_PROXY_ENABLED', false);
-    return isProxy;
-};
-let directModeDepth = 0;
-export const runWithDirectQueueDriver = async (fn) => {
-    directModeDepth += 1;
-    try {
-        return await fn();
-    }
-    finally {
-        directModeDepth = Math.max(0, directModeDepth - 1);
-    }
+import { RedisRpcQueueDriver, shouldUseRedisRpcQueueDriver } from './RedisRpcQueueDriver.js';
+// Lazy BullMQ loader keyed on a variable specifier so bundlers (esbuild/wrangler)
+// do not inline bullmq/ioredis into the Workers bundle. Every public method routes
+// through RedisRpcQueueDriver first when shouldUseRedisRpcQueueDriver() is true
+// (always, on Workers), so this loader never runs there.
+let QueueCtor;
+const ensureBullmqLoaded = async () => {
+    if (QueueCtor !== undefined)
+        return QueueCtor;
+    const bullmqPkg = 'bullmq';
+    const loaded = (await import(bullmqPkg)).Queue;
+    QueueCtor = loaded;
+    return loaded;
 };
 /**
  * BullMQ Redis Queue Driver
@@ -37,17 +32,6 @@ export const BullMQRedisQueue = (() => {
     let lockProviderCache = null;
     const PULL_WORKER_TOKEN = 'pull-worker';
     const SHARED_CONNECTION_SHUTDOWN_TIMEOUT_MS = 100;
-    const isRedisProxyEnabled = () => {
-        return Env.USE_REDIS_PROXY === true || Env.get('REDIS_PROXY_URL', '').trim() !== '';
-    };
-    const assertProxyAndWorkersCompatibility = (isWorkersRuntime) => {
-        if (isRedisProxyEnabled() && shouldUseHttpProxyDriver() === false) {
-            throw ErrorFactory.createConfigError('BullMQ Redis driver does not support REDIS proxy transport directly. Enable QUEUE_HTTP_PROXY_ENABLED=true for queue proxy mode, or disable REDIS proxy mode for direct BullMQ access.');
-        }
-        if (isWorkersRuntime && Cloudflare.isCloudflareSocketsEnabled() === false) {
-            throw ErrorFactory.createConfigError('BullMQ Redis driver requires ENABLE_CLOUDFLARE_SOCKETS=true in Cloudflare Workers. To use HTTP queue proxy mode, set QUEUE_HTTP_PROXY_ENABLED=true and QUEUE_HTTP_PROXY_URL.');
-        }
-    };
     const resolveQueueRedisConfig = () => {
         let workersHost = Cloudflare.getWorkersVar('WORKERS_REDIS_HOST');
         let workersPortRaw = Cloudflare.getWorkersVar('WORKERS_REDIS_PORT');
@@ -75,12 +59,11 @@ export const BullMQRedisQueue = (() => {
     const assertWorkersHostIsReachable = (isWorkersRuntime, redisConfig) => {
         if (isWorkersRuntime &&
             (redisConfig.host === 'localhost' || redisConfig.host === '127.0.0.1')) {
-            throw ErrorFactory.createConfigError('Redis host cannot be localhost in Cloudflare Workers. Use a public Redis host, or enable queue HTTP proxy mode with QUEUE_HTTP_PROXY_ENABLED=true and QUEUE_HTTP_PROXY_URL.');
+            throw ErrorFactory.createConfigError('Redis host cannot be localhost in Cloudflare Workers. Use a public Redis host.');
         }
     };
     const createSharedBullMqConnection = () => {
         const isWorkersRuntime = Cloudflare.getWorkersEnv() !== null;
-        assertProxyAndWorkersCompatibility(isWorkersRuntime);
         const redisConfig = resolveQueueRedisConfig();
         assertWorkersHostIsReachable(isWorkersRuntime, redisConfig);
         return createRedisConnection({
@@ -207,10 +190,8 @@ export const BullMQRedisQueue = (() => {
             await closeSharedConnection(sharedConnection);
         }
     };
-    const getQueue = (queueName) => {
-        if (shouldUseHttpProxyDriver()) {
-            throw ErrorFactory.createConfigError('BullMQ queue instance is not available when QUEUE_HTTP_PROXY mode is active.');
-        }
+    const getQueue = async (queueName) => {
+        const QueueCtor = await ensureBullmqLoaded();
         // Check if queue exists in cache
         if (queues.has(queueName)) {
             const existingQueue = queues.get(queueName);
@@ -242,7 +223,7 @@ export const BullMQRedisQueue = (() => {
         const backoffDelay = Env.getInt('BULLMQ_BACKOFF_DELAY', 2000);
         const backoffType = Env.get('BULLMQ_BACKOFF_TYPE', 'exponential');
         const prefix = getBullMQSafeQueueName();
-        const queue = new Queue(queueName, {
+        const queue = new QueueCtor(queueName, {
             connection: connection,
             prefix,
             defaultJobOptions: {
@@ -412,12 +393,12 @@ export const BullMQRedisQueue = (() => {
         closeQueue,
         getQueueNames,
         async enqueue(queue, payload) {
-            if (shouldUseHttpProxyDriver()) {
-                return HttpQueueDriver.enqueue(queue, payload);
+            if (shouldUseRedisRpcQueueDriver()) {
+                return RedisRpcQueueDriver.enqueue(queue, payload);
             }
             let requestedJobId;
             try {
-                const q = getQueue(queue);
+                const q = await getQueue(queue);
                 // Extract BullMQ options from payload with proper typing
                 const payloadData = payload;
                 const jobOptions = createJobOptions(payloadData);
@@ -450,11 +431,11 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async dequeue(queue) {
-            if (shouldUseHttpProxyDriver()) {
-                return HttpQueueDriver.dequeue(queue);
+            if (shouldUseRedisRpcQueueDriver()) {
+                return RedisRpcQueueDriver.dequeue(queue);
             }
             try {
-                const q = getQueue(queue);
+                const q = await getQueue(queue);
                 const jobs = await q.getJobs(['waiting'], 0, 1);
                 if (jobs.length === 0)
                     return undefined;
@@ -481,12 +462,12 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async ack(queue, id) {
-            if (shouldUseHttpProxyDriver()) {
-                await HttpQueueDriver.ack(queue, id);
+            if (shouldUseRedisRpcQueueDriver()) {
+                await RedisRpcQueueDriver.ack(queue, id);
                 return;
             }
             try {
-                const q = getQueue(queue);
+                const q = await getQueue(queue);
                 const job = await q.getJob(id);
                 if (job) {
                     await job.moveToCompleted('acknowledged', PULL_WORKER_TOKEN, false);
@@ -501,11 +482,11 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async length(queue) {
-            if (shouldUseHttpProxyDriver()) {
-                return HttpQueueDriver.length(queue);
+            if (shouldUseRedisRpcQueueDriver()) {
+                return RedisRpcQueueDriver.length(queue);
             }
             try {
-                const q = getQueue(queue);
+                const q = await getQueue(queue);
                 const counts = await q.getJobCounts();
                 return counts['waiting'] || 0;
             }
@@ -515,12 +496,12 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async drain(queue) {
-            if (shouldUseHttpProxyDriver()) {
-                await HttpQueueDriver.drain(queue);
+            if (shouldUseRedisRpcQueueDriver()) {
+                await RedisRpcQueueDriver.drain(queue);
                 return;
             }
             try {
-                const q = getQueue(queue);
+                const q = await getQueue(queue);
                 await q.drain();
                 Logger.debug(`BullMQ: Queue ${queue} drained`);
             }

package/dist/QueueHttpGateway.d.ts

@@ -1,4 +1,4 @@
-import type { IRouter } from '@zintrust/core/http';
+import { type IRouter } from '@zintrust/core/http';
 type QueueGatewaySettings = {
     basePath: string;
     keyId: string;

package/dist/QueueHttpGateway.js

@@ -3,7 +3,7 @@ import { ErrorFactory } from '@zintrust/core/errors';
 import { Router } from '@zintrust/core/http';
 import { Logger } from '@zintrust/core/logger';
 import { SignedRequest } from '@zintrust/core/security';
-import BullMQRedisQueue, { runWithDirectQueueDriver } from './BullMQRedisQueue.js';
+import BullMQRedisQueue from './BullMQRedisQueue.js';
 const nonces = new Map();
 const nowMs = () => Date.now();
 const normalizePath = (value) => {
@@ -31,9 +31,8 @@ const readSettings = () => {
 const cleanupExpiredNonces = () => {
     const current = nowMs();
     for (const [nonceKey, expiresAt] of nonces.entries()) {
-        if (expiresAt <= current) {
+        if (expiresAt <= current)
             nonces.delete(nonceKey);
-        }
     }
 };
 const storeNonce = async (keyId, nonce, ttlMs) => {
@@ -52,18 +51,14 @@ const getBodyRecord = (req) => {
     return {};
 };
 const getRawBody = (req) => {
-    const rawText = req.context['rawBodyText'];
+    const rawText = req.context?.['rawBodyText'];
     if (typeof rawText === 'string')
         return rawText;
     return JSON.stringify(getBodyRecord(req));
 };
 const toIncomingHeaders = (req) => {
     const headers = req.getHeaders();
-    const normalize = (value) => {
-        if (Array.isArray(value))
-            return value.join(',');
-        return value;
-    };
+    const normalize = (value) => Array.isArray(value) ? value.join(',') : value;
     return {
         'x-zt-key-id': normalize(headers['x-zt-key-id']),
         'x-zt-timestamp': normalize(headers['x-zt-timestamp']),
@@ -73,63 +68,51 @@ const toIncomingHeaders = (req) => {
     };
 };
 const sendFailure = (res, requestId, status, code, message, details) => {
-    const payload = {
+    res.status(status).json({
         ok: false,
         requestId,
         result: null,
         error: { code, message, details },
-    };
-    res.status(status).json(payload);
+    });
 };
 const sendSuccess = (res, requestId, result) => {
-    const payload = {
-        ok: true,
-        requestId,
-        result,
-        error: null,
-    };
-    res.status(200).json(payload);
+    res.status(200).json({ ok: true, requestId, result, error: null });
 };
 const readQueueName = (payload) => {
-    const value = payload.queue;
-    if (typeof value !== 'string')
-        return null;
-    const normalized = value.trim();
-    return normalized === '' ? null : normalized;
+    const value = payload['queue'];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw ErrorFactory.createValidationError('payload.queue is required');
+    }
+    return value.trim();
 };
 const executeAction = async (request) => {
-    return runWithDirectQueueDriver(async () => {
-        const queueName = readQueueName(request.payload);
-        if (!queueName) {
-            throw ErrorFactory.createValidationError('payload.queue is required');
-        }
-        switch (request.action) {
-            case 'enqueue': {
-                const payload = request.payload.payload;
-                if (!payload || typeof payload !== 'object') {
-                    throw ErrorFactory.createValidationError('payload.payload is required for enqueue');
-                }
-                return BullMQRedisQueue.enqueue(queueName, payload);
+    const queueName = readQueueName(request.payload);
+    switch (request.action) {
+        case 'enqueue': {
+            const payload = request.payload['payload'];
+            if (!payload || typeof payload !== 'object') {
+                throw ErrorFactory.createValidationError('payload.payload is required for enqueue');
             }
-            case 'dequeue':
-                return BullMQRedisQueue.dequeue(queueName);
-            case 'ack': {
-                const id = request.payload.id;
-                if (typeof id !== 'string' || id.trim() === '') {
-                    throw ErrorFactory.createValidationError('payload.id is required for ack');
-                }
-                await BullMQRedisQueue.ack(queueName, id);
-                return null;
+            return BullMQRedisQueue.enqueue(queueName, payload);
+        }
+        case 'dequeue':
+            return BullMQRedisQueue.dequeue(queueName);
+        case 'ack': {
+            const id = request.payload['id'];
+            if (typeof id !== 'string' || id.trim() === '') {
+                throw ErrorFactory.createValidationError('payload.id is required for ack');
             }
-            case 'length':
-                return BullMQRedisQueue.length(queueName);
-            case 'drain':
-                await BullMQRedisQueue.drain(queueName);
-                return null;
-            default:
-                throw ErrorFactory.createValidationError(`Unsupported action: ${String(request.action)}`);
+            await BullMQRedisQueue.ack(queueName, id);
+            return null;
         }
-    });
+        case 'length':
+            return BullMQRedisQueue.length(queueName);
+        case 'drain':
+            await BullMQRedisQueue.drain(queueName);
+            return null;
+        default:
+            throw ErrorFactory.createValidationError(`Unsupported action: ${String(request.action)}`);
+    }
 };
 const verifyRequest = async (req, bodyText, settings) => {
     if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
@@ -140,30 +123,25 @@ const verifyRequest = async (req, bodyText, settings) => {
             message: 'Queue HTTP gateway signing credentials are not configured',
         };
     }
-    const url = new URL(req.getPath(), 'http://localhost');
     const verifyResult = await SignedRequest.verify({
         method: req.getMethod(),
-        url,
+        url: new URL(req.getPath(), 'http://localhost'),
         body: bodyText,
         headers: toIncomingHeaders(req),
         nowMs: nowMs(),
         windowMs: settings.signingWindowMs,
         verifyNonce: async (keyId, nonce) => storeNonce(keyId, nonce, settings.nonceTtlMs),
-        getSecretForKeyId: async (keyId) => {
-            if (keyId === settings.keyId)
-                return settings.secret;
-            return undefined;
-        },
+        getSecretForKeyId: async (keyId) => (keyId === settings.keyId ? settings.secret : undefined),
     });
     if (verifyResult.ok === true)
         return { ok: true };
-    const errorCode = 'code' in verifyResult ? verifyResult.code : 'INVALID_SIGNATURE';
-    const errorMessage = 'message' in verifyResult ? verifyResult.message : 'Invalid signature';
+    const code = 'code' in verifyResult ? verifyResult.code : 'INVALID_SIGNATURE';
+    const message = 'message' in verifyResult ? verifyResult.message : 'Invalid signature';
     return {
         ok: false,
-        code: errorCode,
-        status: errorCode === 'EXPIRED' || errorCode === 'REPLAYED' ? 401 : 403,
-        message: errorMessage,
+        code,
+        status: code === 'EXPIRED' || code === 'REPLAYED' ? 401 : 403,
+        message,
     };
 };
 const createHandler = (settings) => {
@@ -178,37 +156,37 @@ const createHandler = (settings) => {
             sendFailure(res, requestId, auth.status, auth.code, auth.message);
             return;
         }
-        const action = body['action'];
-        const payload = body['payload'];
-        if (typeof action !== 'string') {
+        if (typeof body['action'] !== 'string') {
             sendFailure(res, requestId, 400, 'VALIDATION_ERROR', 'action is required');
             return;
         }
-        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        if (!body['payload'] || typeof body['payload'] !== 'object' || Array.isArray(body['payload'])) {
             sendFailure(res, requestId, 400, 'VALIDATION_ERROR', 'payload must be an object');
             return;
         }
-        const normalizedRequest = {
-            action: action,
-            requestId,
-            payload: payload,
-        };
         try {
-            const result = await executeAction(normalizedRequest);
+            const result = await executeAction({
+                action: body['action'],
+                requestId,
+                payload: body['payload'],
+            });
             sendSuccess(res, requestId, result);
         }
         catch (error) {
             Logger.error('Queue HTTP gateway action failed', error);
-            sendFailure(res, requestId, 500, 'QUEUE_ERROR', 'Queue operation failed', error instanceof Error ? { message: error.message } : error);
+            sendFailure(res, requestId, 500, 'QUEUE_ERROR', 'Queue operation failed', {
+                message: error instanceof Error ? error.message : String(error),
+            });
         }
     };
 };
 export const QueueHttpGateway = Object.freeze({
     create(config) {
+        const defaults = readSettings();
         const settings = {
-            ...readSettings(),
+            ...defaults,
             ...config,
-            basePath: normalizePath(config?.basePath ?? readSettings().basePath),
+            basePath: normalizePath(config?.basePath ?? defaults.basePath),
         };
         const routeOptions = settings.middleware.length > 0 ? { middleware: settings.middleware } : undefined;
         return {

package/dist/RedisPublishClient.js

@@ -83,7 +83,10 @@ export const createRedisPublishClient = async () => {
  */
 const tryCreateRedisClient = async (url) => {
     try {
-        const mod = (await import('redis'));
+        // Variable specifier so bundlers (esbuild/wrangler) do not inline node-redis
+        // into the Workers bundle — this path never runs on Workers (RPC proxy is used).
+        const redisPkg = 'redis';
+        const mod = (await import(redisPkg));
         const client = mod.createClient({ url });
         if (typeof client.connect === 'function') {
             await connectClient(client, 'Redis publish client failed to connect');
@@ -99,7 +102,9 @@ const tryCreateRedisClient = async (url) => {
  */
 const tryCreateIoRedisClient = async (url) => {
     try {
-        const mod = (await import('ioredis'));
+        // Variable specifier so bundlers do not inline ioredis into the Workers bundle.
+        const ioredisPkg = 'ioredis';
+        const mod = (await import(ioredisPkg));
         const redis = mod.default(url);
         const client = {
             publish: (channel, message) => redis.publish(channel, message),

package/dist/RedisRpcQueueDriver.d.ts

@@ -0,0 +1,11 @@
+import type { BullMQPayload, QueueMessage } from '@zintrust/core/queue';
+export interface IQueueDriver {
+    enqueue(queue: string, payload: BullMQPayload): Promise<string>;
+    dequeue<T = unknown>(queue: string): Promise<QueueMessage<T> | undefined>;
+    ack(queue: string, id: string): Promise<void>;
+    length(queue: string): Promise<number>;
+    drain(queue: string): Promise<void>;
+}
+export declare const shouldUseRedisRpcQueueDriver: () => boolean;
+export declare const RedisRpcQueueDriver: IQueueDriver;
+export default RedisRpcQueueDriver;

package/dist/RedisRpcQueueDriver.js

@@ -0,0 +1,131 @@
+import { Env } from '@zintrust/core/config';
+import { ErrorFactory } from '@zintrust/core/errors';
+import { JobStateTracker, TimeoutManager } from '@zintrust/core/queue';
+import { generateUuid } from '@zintrust/core/utils';
+const REDIS_RPC_PACKAGE = '@zintrust/redis-rpc';
+export const shouldUseRedisRpcQueueDriver = () => {
+    return Env.USE_REDIS_PROXY === true && Env.get('REDIS_RPC_URL', '').trim() !== '';
+};
+const resolveRpcBaseUrl = () => {
+    const configured = Env.get('REDIS_RPC_URL', '').trim();
+    if (configured.length > 0)
+        return configured;
+    const host = Env.get('REDIS_RPC_HOST', '127.0.0.1').trim() || '127.0.0.1';
+    const port = Env.getInt('REDIS_RPC_PORT', 8794);
+    return `http://${host}:${port}`;
+};
+const createRpcClient = async () => {
+    try {
+        const mod = (await import(REDIS_RPC_PACKAGE));
+        return mod.createRedisRpcClient({
+            baseUrl: resolveRpcBaseUrl(),
+            secret: Env.get('REDIS_RPC_SECRET', Env.get('REDIS_PROXY_SECRET', Env.APP_KEY)),
+        });
+    }
+    catch (error) {
+        throw ErrorFactory.createConfigError('@zintrust/redis-rpc is required when USE_REDIS_PROXY=true and REDIS_RPC_URL is configured', error);
+    }
+};
+const resolveRequestedJobId = (payloadData) => {
+    if (typeof payloadData?.jobId === 'string' && payloadData.jobId.trim().length > 0) {
+        return payloadData.jobId.trim();
+    }
+    return generateUuid();
+};
+const createJobOptions = (payloadData) => ({
+    jobId: resolveRequestedJobId(payloadData),
+    delay: payloadData.delay,
+    attempts: payloadData.attempts,
+    priority: payloadData.priority,
+    removeOnComplete: payloadData.removeOnComplete || 100,
+    removeOnFail: payloadData.removeOnFail || 50,
+    backoff: payloadData.backoff || {
+        type: 'exponential',
+        delay: 2000,
+    },
+    repeat: payloadData.repeat,
+    lifo: payloadData.lifo ?? false,
+});
+const resolveJobId = (result, fallback) => {
+    if (typeof result === 'object' && result !== null) {
+        const id = result.id;
+        if (typeof id === 'string' && id.trim().length > 0)
+            return id;
+        if (typeof id === 'number' && Number.isFinite(id))
+            return String(id);
+    }
+    return fallback;
+};
+const markPendingRecoveryFallback = async (input) => {
+    const payload = input.payload;
+    const currentAttempts = typeof payload['_currentAttempts'] === 'number' && Number.isFinite(payload['_currentAttempts'])
+        ? Math.max(0, Math.floor(payload['_currentAttempts']))
+        : 0;
+    const maxAttempts = typeof payload['attempts'] === 'number' && Number.isFinite(payload['attempts'])
+        ? Math.max(1, Math.floor(payload['attempts']))
+        : undefined;
+    const idempotencyKey = typeof payload['uniqueId'] === 'string' && payload['uniqueId'].trim().length > 0
+        ? payload['uniqueId'].trim()
+        : undefined;
+    await JobStateTracker.enqueued({
+        queueName: input.queue,
+        jobId: input.fallbackJobId,
+        payload: input.payload,
+        attempts: currentAttempts,
+        maxAttempts,
+        idempotencyKey,
+    });
+    const pendingRecoveryApi = JobStateTracker;
+    await pendingRecoveryApi.pendingRecovery?.({
+        queueName: input.queue,
+        jobId: input.fallbackJobId,
+        reason: 'Redis RPC enqueue failed; marked pending recovery',
+        error: input.error,
+    });
+};
+export const RedisRpcQueueDriver = Object.freeze({
+    async enqueue(queue, payload) {
+        const fallbackJobId = resolveRequestedJobId(payload);
+        const timeoutMs = Env.getInt('REDIS_RPC_TIMEOUT_MS', Env.getInt('QUEUE_HTTP_PROXY_TIMEOUT_MS', 10000));
+        const options = createJobOptions({ ...payload, jobId: fallbackJobId });
+        try {
+            return await TimeoutManager.withTimeoutRetry(async () => {
+                const client = await createRpcClient();
+                const result = await client.queue('add', {
+                    target: queue,
+                    args: [`${queue}-job`, payload, options],
+                });
+                return resolveJobId(result, fallbackJobId);
+            }, {
+                timeoutMs,
+                maxRetries: Math.max(0, Env.getInt('REDIS_RPC_RETRY_MAX', Env.getInt('QUEUE_HTTP_PROXY_RETRY_MAX', 2))),
+                retryDelayMs: Math.max(0, Env.getInt('REDIS_RPC_RETRY_DELAY_MS', Env.getInt('QUEUE_HTTP_PROXY_RETRY_DELAY_MS', 500))),
+                operationName: `redis-rpc-queue-enqueue:${queue}`,
+            });
+        }
+        catch (error) {
+            await markPendingRecoveryFallback({ queue, fallbackJobId, payload, error });
+            return fallbackJobId;
+        }
+    },
+    async dequeue(queue) {
+        const client = await createRpcClient();
+        return client.queue('dequeue', {
+            target: queue,
+            visibilityTimeoutMs: Env.getInt('QUEUE_REDIS_VISIBILITY_TIMEOUT_MS', 30_000),
+        });
+    },
+    async ack(queue, id) {
+        const client = await createRpcClient();
+        await client.queue('ack', { target: queue, args: [id] });
+    },
+    async length(queue) {
+        const client = await createRpcClient();
+        return client.queue('length', { target: queue });
+    },
+    async drain(queue) {
+        const client = await createRpcClient();
+        await client.queue('drain', { target: queue });
+    },
+});
+export default RedisRpcQueueDriver;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { BullMQRedisQueue } from './BullMQRedisQueue';
-export { HttpQueueDriver } from './HttpQueueDriver';
 export { QueueHttpGateway } from './QueueHttpGateway';
+export { RedisRpcQueueDriver, shouldUseRedisRpcQueueDriver } from './RedisRpcQueueDriver';
 export { createRedisPublishClient, resetPublishClient, type RedisPublishClient, } from './RedisPublishClient';
 export type { QueueMessage } from '@zintrust/core/queue';
 /**

package/dist/index.js

@@ -1,6 +1,6 @@
 export { BullMQRedisQueue } from './BullMQRedisQueue.js';
-export { HttpQueueDriver } from './HttpQueueDriver.js';
 export { QueueHttpGateway } from './QueueHttpGateway.js';
+export { RedisRpcQueueDriver, shouldUseRedisRpcQueueDriver } from './RedisRpcQueueDriver.js';
 export { createRedisPublishClient, resetPublishClient, } from './RedisPublishClient.js';
 /**
  * Package version and build metadata

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/queue-redis",
-  "version": "2.1.4",
+  "version": "2.4.2",
   "description": "Redis queue driver for ZinTrust.",
   "private": false,
   "type": "module",
@@ -23,7 +23,13 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "*"
+    "@zintrust/core": "*",
+    "@zintrust/redis-rpc": "*"
+  },
+  "peerDependenciesMeta": {
+    "@zintrust/redis-rpc": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -40,7 +46,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "ioredis": "^5.10.1",
+    "ioredis": "^5.11.0",
     "redis": "^5.12.1"
   }
 }

package/dist/HttpQueueDriver.d.ts

@@ -1,17 +0,0 @@
-import type { BullMQPayload, QueueMessage } from '@zintrust/core/queue';
-export type QueueRpcAction = 'enqueue' | 'dequeue' | 'ack' | 'length' | 'drain';
-export interface IQueueDriver {
-    enqueue(queue: string, payload: BullMQPayload): Promise<string>;
-    dequeue<T = unknown>(queue: string): Promise<QueueMessage<T> | undefined>;
-    ack(queue: string, id: string): Promise<void>;
-    length(queue: string): Promise<number>;
-    drain(queue: string): Promise<void>;
-}
-export declare const HttpQueueDriver: Readonly<{
-    enqueue(queue: string, payload: BullMQPayload): Promise<string>;
-    dequeue<T = unknown>(queue: string): Promise<QueueMessage<T> | undefined>;
-    ack(queue: string, id: string): Promise<void>;
-    length(queue: string): Promise<number>;
-    drain(queue: string): Promise<void>;
-}>;
-export default HttpQueueDriver;

package/dist/HttpQueueDriver.js

@@ -1,258 +0,0 @@
-import { Env } from '@zintrust/core/config';
-import { ErrorFactory } from '@zintrust/core/errors';
-import { Logger } from '@zintrust/core/logger';
-import { JobStateTracker, TimeoutManager } from '@zintrust/core/queue';
-import { SignedRequest } from '@zintrust/core/security';
-import { generateUuid } from '@zintrust/core/utils';
-const DEFAULT_PROXY_URL = 'http://127.0.0.1:7772';
-const DEFAULT_ROUTE_PATH = '/api/_sys/queue/rpc';
-const createTimeoutSignal = (timeoutMs) => {
-    if (timeoutMs <= 0)
-        return undefined;
-    const timeout = AbortSignal.timeout;
-    return typeof timeout === 'function' ? timeout(timeoutMs) : undefined;
-};
-const toBodyText = (payload) => JSON.stringify(payload);
-const normalizeBaseUrl = (value) => {
-    const raw = value.trim();
-    return raw === '' ? DEFAULT_PROXY_URL : raw;
-};
-const normalizeRoutePath = (value) => {
-    const trimmed = value.trim();
-    if (trimmed === '')
-        return DEFAULT_ROUTE_PATH;
-    if (trimmed.startsWith('/'))
-        return trimmed;
-    return `/${trimmed}`;
-};
-const resolveSigningPrefix = (baseUrl) => {
-    try {
-        const parsed = new URL(baseUrl);
-        const path = parsed.pathname.endsWith('/') ? parsed.pathname.slice(0, -1) : parsed.pathname;
-        if (path === '' || path === '/')
-            return undefined;
-        return path;
-    }
-    catch {
-        return undefined;
-    }
-};
-const buildSigningUrl = (requestUrl, baseUrl) => {
-    const prefix = resolveSigningPrefix(baseUrl);
-    if (!prefix)
-        return requestUrl;
-    if (requestUrl.pathname === prefix || requestUrl.pathname.startsWith(`${prefix}/`)) {
-        const signingUrl = new URL(requestUrl.toString());
-        const stripped = requestUrl.pathname.slice(prefix.length);
-        signingUrl.pathname = stripped.startsWith('/') ? stripped : `/${stripped}`;
-        return signingUrl;
-    }
-    return requestUrl;
-};
-const resolveSettings = () => {
-    const baseUrl = normalizeBaseUrl(Env.get('QUEUE_HTTP_PROXY_URL', DEFAULT_PROXY_URL));
-    const routePath = normalizeRoutePath(Env.get('QUEUE_HTTP_PROXY_PATH', DEFAULT_ROUTE_PATH));
-    const keyId = Env.get('QUEUE_HTTP_PROXY_KEY_ID', Env.APP_NAME || 'zintrust').trim();
-    const configuredSecret = Env.get('QUEUE_HTTP_PROXY_KEY', '').trim();
-    const secret = configuredSecret === '' ? Env.APP_KEY : configuredSecret;
-    const timeoutMs = Env.getInt('QUEUE_HTTP_PROXY_TIMEOUT_MS', 10000);
-    if (secret.trim() === '') {
-        throw ErrorFactory.createConfigError('QUEUE_HTTP_PROXY_KEY or APP_KEY is required');
-    }
-    return {
-        baseUrl,
-        routePath,
-        keyId,
-        secret,
-        timeoutMs,
-    };
-};
-const buildRpcUrl = (settings) => {
-    const url = new URL(settings.baseUrl);
-    const basePath = url.pathname.endsWith('/') ? url.pathname.slice(0, -1) : url.pathname;
-    const routePath = settings.routePath.startsWith('/')
-        ? settings.routePath
-        : `/${settings.routePath}`;
-    url.pathname = `${basePath}${routePath}`;
-    url.search = '';
-    return url;
-};
-const parseJsonResponse = async (response) => {
-    const text = await response.text();
-    if (text.trim() === '') {
-        return {
-            ok: false,
-            error: { code: 'EMPTY_RESPONSE', message: 'Empty response from queue gateway' },
-        };
-    }
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return {
-            ok: false,
-            error: { code: 'INVALID_JSON', message: text },
-        };
-    }
-};
-const ensureSuccessfulResponse = (response, requestId) => {
-    if (!response.ok) {
-        const code = response.error?.code || 'QUEUE_HTTP_PROXY_ERROR';
-        const message = response.error?.message || 'Queue gateway returned an error';
-        const details = {
-            code,
-            requestId,
-            gatewayRequestId: response.requestId,
-            details: response.error?.details,
-        };
-        throw ErrorFactory.createTryCatchError(message, details);
-    }
-    return response.result;
-};
-const callGateway = async (action, payload) => {
-    const settings = resolveSettings();
-    const url = buildRpcUrl(settings);
-    const requestId = generateUuid();
-    const requestBody = {
-        action,
-        requestId,
-        payload,
-    };
-    const bodyText = toBodyText(requestBody);
-    const signingUrl = buildSigningUrl(url, settings.baseUrl);
-    const params = {
-        method: 'POST',
-        url: signingUrl,
-        body: bodyText,
-        keyId: settings.keyId,
-        secret: settings.secret,
-    };
-    const signedHeaders = await SignedRequest.createHeaders(params);
-    try {
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...signedHeaders,
-            },
-            body: bodyText,
-            signal: createTimeoutSignal(settings.timeoutMs),
-        });
-        const parsed = await parseJsonResponse(response);
-        if (!response.ok && parsed.ok === false) {
-            throw ErrorFactory.createConnectionError(parsed.error?.message || `Queue gateway HTTP error (${response.status})`, {
-                status: response.status,
-                requestId,
-                error: parsed.error,
-            });
-        }
-        return ensureSuccessfulResponse(parsed, requestId);
-    }
-    catch (error) {
-        if (error instanceof Error && error.name === 'AbortError') {
-            throw ErrorFactory.createConnectionError('Queue gateway request timed out', {
-                timeoutMs: settings.timeoutMs,
-                requestId,
-            });
-        }
-        throw error;
-    }
-};
-const resolveFallbackJobId = (payload) => {
-    if (typeof payload.jobId === 'string' && payload.jobId.trim().length > 0) {
-        return payload.jobId.trim();
-    }
-    return generateUuid();
-};
-const resolveCurrentAttempts = (payload) => {
-    const raw = payload['_currentAttempts'];
-    if (typeof raw !== 'number' || Number.isFinite(raw) === false)
-        return 0;
-    return Math.max(0, Math.floor(raw));
-};
-const resolveMaxAttempts = (payload) => {
-    if (typeof payload.attempts === 'number' && Number.isFinite(payload.attempts)) {
-        return Math.max(1, Math.floor(payload.attempts));
-    }
-    return undefined;
-};
-const resolveIdempotencyKey = (payload) => {
-    if (typeof payload.uniqueId !== 'string')
-        return undefined;
-    const trimmed = payload.uniqueId.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-};
-const markPendingRecoveryFallback = async (input) => {
-    const currentAttempts = resolveCurrentAttempts(input.payload);
-    const maxAttempts = resolveMaxAttempts(input.payload);
-    const idempotencyKey = resolveIdempotencyKey(input.payload);
-    // Compatibility shim: consumers of `@zintrust/core` may have a narrower
-    // `JobStateTracker.enqueued` type than the runtime implementation.
-    const enqueuedApi = JobStateTracker;
-    await enqueuedApi.enqueued({
-        queueName: input.queue,
-        jobId: input.fallbackJobId,
-        payload: input.payload,
-        attempts: currentAttempts,
-        maxAttempts,
-        idempotencyKey,
-    });
-    const pendingRecoveryApi = JobStateTracker;
-    if (typeof pendingRecoveryApi.pendingRecovery === 'function') {
-        await pendingRecoveryApi.pendingRecovery({
-            queueName: input.queue,
-            jobId: input.fallbackJobId,
-            reason: 'HTTP queue proxy enqueue failed; marked pending recovery',
-            error: input.error,
-        });
-    }
-};
-export const HttpQueueDriver = Object.freeze({
-    async enqueue(queue, payload) {
-        const fallbackJobId = resolveFallbackJobId(payload);
-        const timeoutMs = Env.getInt('QUEUE_HTTP_PROXY_TIMEOUT_MS', 10000);
-        try {
-            return await TimeoutManager.withTimeoutRetry(async () => callGateway('enqueue', { queue, payload }), {
-                timeoutMs,
-                maxRetries: Math.max(0, Env.getInt('QUEUE_HTTP_PROXY_RETRY_MAX', 2)),
-                retryDelayMs: Math.max(0, Env.getInt('QUEUE_HTTP_PROXY_RETRY_DELAY_MS', 500)),
-                operationName: `http-queue-enqueue:${queue}`,
-            });
-        }
-        catch (error) {
-            Logger.warn('HTTP queue enqueue failed; storing tracker fallback in memory', {
-                ...Logger.withTraceSkipContext({
-                    queue,
-                    fallbackJobId,
-                    error: error instanceof Error ? error.message : String(error),
-                }),
-            });
-            await markPendingRecoveryFallback({
-                queue,
-                fallbackJobId,
-                payload,
-                error,
-            });
-            Logger.warn('Job marked pending recovery in tracker', {
-                ...Logger.withTraceSkipContext({
-                    queue,
-                    jobId: fallbackJobId,
-                }),
-            });
-            return fallbackJobId;
-        }
-    },
-    async dequeue(queue) {
-        return callGateway('dequeue', { queue });
-    },
-    async ack(queue, id) {
-        await callGateway('ack', { queue, id });
-    },
-    async length(queue) {
-        return callGateway('length', { queue });
-    },
-    async drain(queue) {
-        await callGateway('drain', { queue });
-    },
-});
-export default HttpQueueDriver;