@zintrust/queue-redis 2.1.3 → 2.4.1

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

@@ -13,8 +13,6 @@ interface IBullMQRedisQueue extends IQueueDriver {
     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

@@ -1,29 +1,13 @@
 import { Cloudflare } from '@zintrust/core/cloudflare';
 import { Env, queueConfig } from '@zintrust/core/config';
 import { ErrorFactory } from '@zintrust/core/errors';
+import { isNullish, isUndefinedOrNull } from '@zintrust/core/helper';
 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';
 /**
  * BullMQ Redis Queue Driver
  *
@@ -36,44 +20,38 @@ 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.');
+    const resolveQueueRedisConfig = () => {
+        let workersHost = Cloudflare.getWorkersVar('WORKERS_REDIS_HOST');
+        let workersPortRaw = Cloudflare.getWorkersVar('WORKERS_REDIS_PORT');
+        let workersPassword = Cloudflare.getWorkersVar('WORKERS_REDIS_PASSWORD');
+        let workersDbRaw = Cloudflare.getWorkersVar('WORKERS_REDIS_QUEUE_DB');
+        if (isUndefinedOrNull(workersPassword) || isNullish(workersPassword)) {
+            workersPassword = Env.get('REDIS_PASSWORD', '');
         }
-        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.');
+        if (isUndefinedOrNull(workersPortRaw) || isNullish(workersPortRaw)) {
+            workersPortRaw = Env.get('REDIS_PORT', '6379');
+        }
+        if (isUndefinedOrNull(workersHost) || isNullish(workersHost)) {
+            workersHost = Env.get('REDIS_HOST', '127.0.0.1');
+        }
+        if (isUndefinedOrNull(workersDbRaw) || isNullish(workersDbRaw)) {
+            workersDbRaw = Env.get('REDIS_QUEUE_DB', '0');
         }
-    };
-    const resolveQueueRedisConfig = () => {
-        const workersHost = Cloudflare.getWorkersVar('WORKERS_REDIS_HOST');
-        const workersPortRaw = Cloudflare.getWorkersVar('WORKERS_REDIS_PORT');
-        const workersPassword = Cloudflare.getWorkersVar('WORKERS_REDIS_PASSWORD');
-        const workersDbRaw = Cloudflare.getWorkersVar('WORKERS_REDIS_QUEUE_DB');
         return {
-            host: workersHost !== null && workersHost.trim() !== '' ? workersHost.trim() : Env.REDIS_HOST,
-            port: workersPortRaw !== null && Number.isFinite(Number.parseInt(workersPortRaw, 10))
-                ? Number.parseInt(workersPortRaw, 10)
-                : Env.REDIS_PORT,
-            password: workersPassword !== null && workersPassword.trim() !== ''
-                ? workersPassword
-                : Env.REDIS_PASSWORD,
-            database: workersDbRaw !== null && Number.isFinite(Number.parseInt(workersDbRaw, 10))
-                ? Number.parseInt(workersDbRaw, 10)
-                : Env.getInt('REDIS_QUEUE_DB', 0),
+            host: workersHost,
+            port: Number(workersPortRaw),
+            password: workersPassword,
+            database: Number(workersDbRaw),
         };
     };
     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({
@@ -201,9 +179,6 @@ export const BullMQRedisQueue = (() => {
         }
     };
     const getQueue = (queueName) => {
-        if (shouldUseHttpProxyDriver()) {
-            throw ErrorFactory.createConfigError('BullMQ queue instance is not available when QUEUE_HTTP_PROXY mode is active.');
-        }
         // Check if queue exists in cache
         if (queues.has(queueName)) {
             const existingQueue = queues.get(queueName);
@@ -405,8 +380,8 @@ 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 {
@@ -443,8 +418,8 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async dequeue(queue) {
-            if (shouldUseHttpProxyDriver()) {
-                return HttpQueueDriver.dequeue(queue);
+            if (shouldUseRedisRpcQueueDriver()) {
+                return RedisRpcQueueDriver.dequeue(queue);
             }
             try {
                 const q = getQueue(queue);
@@ -474,8 +449,8 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async ack(queue, id) {
-            if (shouldUseHttpProxyDriver()) {
-                await HttpQueueDriver.ack(queue, id);
+            if (shouldUseRedisRpcQueueDriver()) {
+                await RedisRpcQueueDriver.ack(queue, id);
                 return;
             }
             try {
@@ -494,8 +469,8 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async length(queue) {
-            if (shouldUseHttpProxyDriver()) {
-                return HttpQueueDriver.length(queue);
+            if (shouldUseRedisRpcQueueDriver()) {
+                return RedisRpcQueueDriver.length(queue);
             }
             try {
                 const q = getQueue(queue);
@@ -508,8 +483,8 @@ export const BullMQRedisQueue = (() => {
             }
         },
         async drain(queue) {
-            if (shouldUseHttpProxyDriver()) {
-                await HttpQueueDriver.drain(queue);
+            if (shouldUseRedisRpcQueueDriver()) {
+                await RedisRpcQueueDriver.drain(queue);
                 return;
             }
             try {

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/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/build-manifest.json

@@ -1,14 +1,14 @@
 {
   "name": "@zintrust/queue-redis",
-  "version": "2.1.3",
-  "buildDate": "2026-05-27T04:07:37.277Z",
+  "version": "2.4.1",
+  "buildDate": "2026-05-31T11:38:17.470Z",
   "buildEnvironment": {
     "node": "v22.22.1",
     "platform": "darwin",
     "arch": "arm64"
   },
   "git": {
-    "commit": "c82f6263",
+    "commit": "e97b7b3d",
     "branch": "release"
   },
   "package": {
@@ -20,17 +20,18 @@
       "redis"
     ],
     "peerDependencies": [
-      "@zintrust/core"
+      "@zintrust/core",
+      "@zintrust/redis-rpc"
     ]
   },
   "files": {
     "BullMQRedisQueue.d.ts": {
-      "size": 1068,
-      "sha256": "548d76f2c5aee51a3a16139be99a8d1ac8d15895a5610ccdb28b110c5bfbbcb5"
+      "size": 918,
+      "sha256": "fdcd271e7aa241cc3af89c979a4ee2538541d1442024bd6dda91c8b12f712c6f"
     },
     "BullMQRedisQueue.js": {
-      "size": 23383,
-      "sha256": "d27a28debec574a4c0beba6b10c0a0b36b682ce0b0549a85330ce31d72e393d5"
+      "size": 21906,
+      "sha256": "87fd1eb1a320ea85b4cffde44e6f86ec487332cf8cd7052b11fd1b89caf8a1e5"
     },
     "HttpQueueDriver.d.ts": {
       "size": 841,
@@ -42,11 +43,11 @@
     },
     "QueueHttpGateway.d.ts": {
       "size": 437,
-      "sha256": "590488c877c66989f3904334178ed8c5c288e87379e6b67c5d228a5c053375aa"
+      "sha256": "9c45a8643136415b248828322442aac16cd4b2e0d22355c3b8ecf6188973ffe7"
     },
     "QueueHttpGateway.js": {
-      "size": 8233,
-      "sha256": "748a9b7fe3ce5806514988dd169618b8c2e71fdc5b1de74352ed3b43155943ef"
+      "size": 7665,
+      "sha256": "352a1c2de6bbbaf7cd684bb428454bdd3293aff070956b3ee912403fe1394992"
     },
     "RedisPublishClient.d.ts": {
       "size": 451,
@@ -56,25 +57,25 @@
       "size": 5589,
       "sha256": "aed9cee5023addfdbbf1026d0a45c86d29a8f3e65ffbd01637c1e0e7f994213b"
     },
-    "RedisQueue.d.ts": {
-      "size": 438,
-      "sha256": "eefad366ae71d63044b23038265bf3eb60a0277e41ac70f57c5973d79f2af5ce"
+    "RedisRpcQueueDriver.d.ts": {
+      "size": 549,
+      "sha256": "19dc10ffc29e813a241a9c69184e988d94d1c16ffc82010c75cadc29a4833a93"
     },
-    "RedisQueue.js": {
-      "size": 3593,
-      "sha256": "dc8b2c28b2e288e048423067f90ffbe0389ac813086246a1c8fafeeeab5c142d"
+    "RedisRpcQueueDriver.js": {
+      "size": 5357,
+      "sha256": "24bb11e1a9f8a163ec79b08dc326e0c337297f312d393347dad91d38b692a9ea"
     },
     "build-manifest.json": {
-      "size": 2512,
-      "sha256": "ae0f16869176a1fc869c638f74f9d04d82da5157d31ebee60f3c935c89c419df"
+      "size": 2273,
+      "sha256": "774ebf83d6b9fc3222555c6ace7c7318e4cdeba9e4f439bce38cfc99cef9cf66"
     },
     "index.d.ts": {
-      "size": 571,
-      "sha256": "077ab82bfa8c1b11dc7d832d17d3dfaf9913e3b9905670f01e22cfd3e0640b63"
+      "size": 609,
+      "sha256": "c74e26117ad588f7d28dda0c71fdd17588e6f58a0c68ede56af2fb2795352726"
     },
     "index.js": {
-      "size": 676,
-      "sha256": "a8ddd4949863c9182479ae4b993edd04ea563b0e8810ce9bd842d6180bcd32e0"
+      "size": 714,
+      "sha256": "ea00335dbb0386bc3863d61def64aebcc330f8dcef348a663bae51055d1bcc20"
     },
     "register.d.ts": {
       "size": 170,

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.3",
+  "version": "2.4.1",
   "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/RedisQueue.d.ts

@@ -1,10 +0,0 @@
-import type { QueueMessage } from '@zintrust/core';
-interface IQueueDriver {
-    enqueue<T = unknown>(queue: string, payload: T): 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 RedisQueue: IQueueDriver;
-export default RedisQueue;

package/dist/RedisQueue.js

@@ -1,92 +0,0 @@
-import { ErrorFactory, generateUuid, getRedisUrl, Logger } from '@zintrust/core';
-export const RedisQueue = (() => {
-    let client = null;
-    let connected = false;
-    const ensureClient = async () => {
-        if (connected && client !== null)
-            return client;
-        const url = getRedisUrl();
-        if (url === null)
-            throw ErrorFactory.createConfigError('Redis queue driver requires REDIS_URL');
-        // Import lazily so package is optional for environments that don't use Redis
-        try {
-            // Prefer the redis package when available
-            try {
-                const mod = (await import('redis'));
-                const createClient = mod.createClient;
-                client = createClient({ url });
-                if (typeof client.connect === 'function') {
-                    try {
-                        await client.connect();
-                        connected = true;
-                    }
-                    catch (connectionError) {
-                        connected = false;
-                        Logger.warn('Redis client connect failed:', String(connectionError));
-                    }
-                }
-                else {
-                    connected = true;
-                }
-            }
-            catch {
-                // Fallback to ioredis when available (used by queue-monitor)
-                const mod = (await import('ioredis'));
-                const redis = mod.default(url);
-                client = {
-                    rPush: (queue, value) => redis.rpush(queue, value),
-                    lPop: (queue) => redis.lpop(queue),
-                    lLen: (queue) => redis.llen(queue),
-                    del: (queue) => redis.del(queue),
-                };
-                connected = true;
-            }
-        }
-        catch (error) {
-            const globalFake = globalThis
-                .__fakeRedisClient;
-            if (globalFake === undefined) {
-                throw ErrorFactory.createConfigError("Redis queue driver requires the 'redis' or 'ioredis' package (run `zin add queue:redis` / `zin plugin install queue:redis`, or `npm install redis` / `npm install ioredis`) or a test fake client set in globalThis.__fakeRedisClient", error);
-            }
-            client = globalFake;
-            connected = true;
-        }
-        if (client === null)
-            throw ErrorFactory.createConfigError('Redis client could not be initialized');
-        return client;
-    };
-    return {
-        async enqueue(queue, payload) {
-            const cli = await ensureClient();
-            const id = generateUuid();
-            const msg = JSON.stringify({ id, payload, attempts: 0 });
-            await cli.rPush(queue, msg);
-            return id;
-        },
-        async dequeue(queue) {
-            const cli = await ensureClient();
-            const raw = await cli.lPop(queue);
-            if (raw === null)
-                return undefined;
-            try {
-                const parsed = JSON.parse(raw);
-                return parsed;
-            }
-            catch (err) {
-                throw ErrorFactory.createTryCatchError('Failed to parse queue message', err);
-            }
-        },
-        async ack(_queue, _id) {
-            return Promise.resolve(); // NOSONAR
-        },
-        async length(queue) {
-            const cli = await ensureClient();
-            return cli.lLen(queue);
-        },
-        async drain(queue) {
-            const cli = await ensureClient();
-            await cli.del(queue);
-        },
-    };
-})();
-export default RedisQueue;