@zintrust/redis-rpc 2.4.1

package/dist/backend.js

@@ -0,0 +1,557 @@
+import { ErrorFactory } from '@zintrust/core/errors';
+import { isArray, isNonEmptyString, isObject, isUndefinedOrNull } from '@zintrust/core/helper';
+import { Logger } from '@zintrust/core/logger';
+import { Sanitizer } from '@zintrust/core/security';
+import { Queue, QueueEvents, Worker, } from 'bullmq';
+import IORedis from 'ioredis';
+import { redisConnectionOptions, rpcServerOptions } from './env.js';
+import { createRpcValidationError } from './errors.js';
+const DEFAULT_JOB_STATES = [
+    'waiting',
+    'active',
+    'completed',
+    'failed',
+    'delayed',
+    'paused',
+    'prioritized',
+    'waiting-children',
+];
+const CLEAN_JOB_TYPES = new Set([
+    'completed',
+    'failed',
+    'active',
+    'delayed',
+    'prioritized',
+    'waiting',
+    'paused',
+    'wait',
+]);
+const EVENT_NAMES = [
+    'added',
+    'waiting',
+    'active',
+    'completed',
+    'failed',
+    'delayed',
+    'removed',
+    'drained',
+    'paused',
+    'resumed',
+];
+const PULL_WORKER_TOKEN = 'pull-worker';
+const isRecord = (value) => isObject(value) && !isArray(value);
+const sanitizeKey = (value) => {
+    const sanitized = Sanitizer.keyLike(value);
+    return sanitized.length > 0 ? sanitized : value.trim();
+};
+const requireRecord = (value, name) => {
+    if (!isRecord(value)) {
+        throw createRpcValidationError(`${name} must be an object`);
+    }
+    return value;
+};
+const requireString = (value, name) => {
+    if (!isNonEmptyString(value)) {
+        throw createRpcValidationError(`${name} is required`);
+    }
+    return sanitizeKey(value);
+};
+const asArgs = (payload) => (isArray(payload.args) ? payload.args : []);
+const firstDefined = (...values) => values.find((value) => !isUndefinedOrNull(value));
+const redisCommandArgs = (values) => values.flatMap((value) => {
+    if (!isRecord(value))
+        return [Buffer.isBuffer(value) ? value : String(value)];
+    return Object.entries(value).flatMap(([key, entry]) => {
+        if (typeof entry !== 'boolean')
+            return [key, String(entry)];
+        return entry ? [key] : [];
+    });
+});
+const redisPipelineCommands = (payload) => {
+    const commands = payload.commands;
+    if (!isArray(commands)) {
+        throw createRpcValidationError('commands must be an array');
+    }
+    return commands.map((command) => {
+        if (!isRecord(command)) {
+            throw createRpcValidationError('commands entries must be objects');
+        }
+        return command;
+    });
+};
+const queuePipelineCommand = (pipeline, command, args) => {
+    const lower = command.toLowerCase();
+    const candidate = pipeline[lower];
+    if (typeof candidate === 'function') {
+        candidate.apply(pipeline, args);
+        return;
+    }
+    if (typeof pipeline.call === 'function') {
+        pipeline.call(command, ...args);
+        return;
+    }
+    throw createRpcValidationError(`Unsupported redis command: ${command}`);
+};
+const serializePipelineResults = (results) => results.map(([error, result]) => [error === null ? null : error.message, result]);
+const queueNameFromPayload = (payload) => {
+    return requireString(firstDefined(payload.queueName, payload.queue, payload.target), 'queueName');
+};
+const numberFrom = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+const boolFrom = (value, fallback = false) => typeof value === 'boolean' ? value : fallback;
+const normalizeStates = (value) => {
+    if (!isArray(value)) {
+        return DEFAULT_JOB_STATES;
+    }
+    const states = value.map((state) => String(state).trim()).filter(Boolean);
+    return states.length > 0 ? states : DEFAULT_JOB_STATES;
+};
+const withTimeout = async (operation, timeoutMs = 5000) => {
+    let timeout;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((_, reject) => {
+                timeout = globalThis.setTimeout(() => reject(ErrorFactory.createTryCatchError('Redis RPC close timed out')), timeoutMs);
+                timeout.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+};
+const serializeJob = async (job) => {
+    if (!job)
+        return null;
+    let state;
+    try {
+        state = await job.getState();
+    }
+    catch (error) {
+        Logger.warn('Redis RPC failed to read job state', { error });
+    }
+    return {
+        id: isUndefinedOrNull(job.id) ? undefined : String(job.id),
+        name: job.name,
+        queueName: job.queueName,
+        data: job.data,
+        opts: job.opts,
+        progress: job.progress,
+        attemptsMade: job.attemptsMade,
+        failedReason: job.failedReason,
+        stacktrace: job.stacktrace,
+        returnvalue: job.returnvalue,
+        timestamp: job.timestamp,
+        processedOn: job.processedOn,
+        finishedOn: job.finishedOn,
+        delay: job.delay,
+        priority: job.priority,
+        state,
+    };
+};
+const createConnection = (state, extra = {}) => {
+    const connection = new IORedis({ ...state.connectionOptions, ...extra });
+    state.connections.add(connection);
+    connection.once('end', () => state.connections.delete(connection));
+    return connection;
+};
+const queueOptions = (state) => ({
+    connection: createConnection(state),
+    prefix: state.prefix,
+});
+const getQueue = (state, queueName) => {
+    const name = requireString(queueName, 'queueName');
+    const existing = state.queues.get(name);
+    if (existing)
+        return existing;
+    const queue = new Queue(name, queueOptions(state));
+    state.queues.set(name, queue);
+    return queue;
+};
+const getQueueEvents = (state, queueName) => {
+    const name = requireString(queueName, 'queueName');
+    const existing = state.queueEvents.get(name);
+    if (existing)
+        return existing;
+    const events = new QueueEvents(name, queueOptions(state));
+    const log = [];
+    state.eventLogs.set(name, log);
+    for (const eventName of EVENT_NAMES) {
+        events.on(eventName, (payload) => {
+            log.push({ event: eventName, payload, at: Date.now() });
+            if (log.length > 200)
+                log.shift();
+        });
+    }
+    state.queueEvents.set(name, events);
+    return events;
+};
+const getJob = async (state, queueName, jobId) => {
+    const queue = getQueue(state, queueName);
+    return queue.getJob(requireString(jobId, 'jobId'));
+};
+const addJob = async (state, payload) => {
+    const queue = getQueue(state, queueNameFromPayload(payload));
+    const args = asArgs(payload);
+    let name = 'default';
+    if (isNonEmptyString(args[0])) {
+        name = args[0].trim();
+    }
+    else if (isNonEmptyString(payload.name)) {
+        name = payload.name.trim();
+    }
+    const data = args.length > 1 ? args[1] : firstDefined(payload.data, payload.payload, {});
+    let opts = {};
+    if (isRecord(args[2])) {
+        opts = args[2];
+    }
+    else if (isRecord(payload.opts)) {
+        opts = payload.opts;
+    }
+    return serializeJob(await queue.add(name, data, opts));
+};
+const getQueueJob = async (state, queueName, payload) => {
+    const args = asArgs(payload);
+    return serializeJob(await getJob(state, queueName, firstDefined(args[0], payload.jobId, payload.id)));
+};
+const listQueueJobs = async (state, queueName, payload) => {
+    const args = asArgs(payload);
+    const queue = getQueue(state, queueName);
+    const jobs = await queue.getJobs(normalizeStates(firstDefined(args[0], payload.states)), numberFrom(firstDefined(args[1], payload.start), 0), numberFrom(firstDefined(args[2], payload.end), 99), boolFrom(firstDefined(args[3], payload.asc), false));
+    return Promise.all(jobs.map((job) => serializeJob(job)));
+};
+const getQueueJobCounts = async (state, queueName, payload) => {
+    const args = asArgs(payload);
+    const queue = getQueue(state, queueName);
+    let types = [];
+    if (args.length > 0) {
+        types = args.map(String);
+    }
+    else if (isArray(payload.types)) {
+        types = payload.types.map(String);
+    }
+    return types.length > 0 ? queue.getJobCounts(...types) : queue.getJobCounts();
+};
+const closeQueue = async (state, queueName) => {
+    await state.queues.get(queueName)?.close();
+    await state.queueEvents.get(queueName)?.close();
+    state.queues.delete(queueName);
+    state.queueEvents.delete(queueName);
+    state.eventLogs.delete(queueName);
+    return true;
+};
+const getObliterateOptions = (payload) => {
+    const args = asArgs(payload);
+    const options = args[0];
+    return isRecord(options) ? options : { force: payload.force !== false };
+};
+const getQueueJobById = async (state, queueName, payload) => {
+    const args = asArgs(payload);
+    return getJob(state, queueName, firstDefined(args[0], payload.jobId, payload.id));
+};
+const dequeueQueueJob = async (state, queueName, payload) => {
+    const queue = getQueue(state, queueName);
+    const jobs = await queue.getJobs(['waiting'], 0, 0);
+    const job = jobs[0];
+    if (!job)
+        return undefined;
+    const visibilityTimeoutMs = numberFrom(payload.visibilityTimeoutMs, 30_000);
+    await job.moveToDelayed(Date.now() + Math.max(1, visibilityTimeoutMs), PULL_WORKER_TOKEN);
+    return {
+        id: isUndefinedOrNull(job.id) ? undefined : String(job.id),
+        payload: job.data,
+        attempts: job.attemptsMade || 0,
+    };
+};
+const ackQueueJob = async (state, queueName, payload) => {
+    const job = await getQueueJobById(state, queueName, payload);
+    if (!job)
+        return false;
+    await job.moveToCompleted('acknowledged', PULL_WORKER_TOKEN, false);
+    return true;
+};
+const removeQueueJob = async (state, queueName, payload) => {
+    const job = await getQueueJobById(state, queueName, payload);
+    if (!job)
+        return false;
+    await job.remove();
+    return true;
+};
+const retryQueueJob = async (state, queueName, payload) => {
+    const args = asArgs(payload);
+    const job = await getQueueJobById(state, queueName, payload);
+    if (!job)
+        return { ok: false, status: 'missing' };
+    await job.retry(firstDefined(args[1], payload.state));
+    return { ok: true, status: 'retried' };
+};
+const promoteQueueJob = async (state, queueName, payload) => {
+    const job = await getQueueJobById(state, queueName, payload);
+    if (!job)
+        return { ok: false, status: 'missing' };
+    await job.promote();
+    return { ok: true, status: 'promoted' };
+};
+/* eslint-disable complexity */
+const dispatchQueue = async (state, method, payload) => {
+    const queueName = queueNameFromPayload(payload);
+    switch (method) {
+        case 'add':
+        case 'enqueue':
+            return addJob(state, payload);
+        case 'get':
+        case 'getJob':
+            return getQueueJob(state, queueName, payload);
+        case 'getJobs':
+            return listQueueJobs(state, queueName, payload);
+        case 'getJobCounts':
+        case 'counts':
+            return getQueueJobCounts(state, queueName, payload);
+        case 'count':
+        case 'length':
+            return getQueue(state, queueName).count();
+        case 'dequeue':
+            return dequeueQueueJob(state, queueName, payload);
+        case 'ack':
+            return ackQueueJob(state, queueName, payload);
+        case 'pause':
+            await getQueue(state, queueName).pause();
+            return true;
+        case 'resume':
+            await getQueue(state, queueName).resume();
+            return true;
+        case 'drain':
+            await getQueue(state, queueName).drain(Boolean(firstDefined(asArgs(payload)[0], payload.delayed)));
+            return true;
+        case 'obliterate':
+            await getQueue(state, queueName).obliterate(getObliterateOptions(payload));
+            return true;
+        case 'clean': {
+            const args = asArgs(payload);
+            const cleanType = String(firstDefined(args[2], payload.type, 'completed'));
+            return getQueue(state, queueName).clean(numberFrom(firstDefined(args[0], payload.grace), 0), numberFrom(firstDefined(args[1], payload.limit), 1000), (CLEAN_JOB_TYPES.has(cleanType) ? cleanType : 'completed'));
+        }
+        case 'removeJob':
+            return removeQueueJob(state, queueName, payload);
+        case 'retryJob':
+            return retryQueueJob(state, queueName, payload);
+        case 'promoteJob':
+            return promoteQueueJob(state, queueName, payload);
+        case 'closeQueue':
+            return closeQueue(state, queueName);
+        default:
+            throw createRpcValidationError(`Unsupported queue method: ${method}`);
+    }
+};
+/* eslint-enable complexity */
+const createProcessor = (kind) => {
+    switch (kind) {
+        case 'echo':
+        case undefined:
+        case null:
+            return async (job) => ({ echo: job.data, jobId: job.id, name: job.name });
+        case 'sum':
+            return async (job) => {
+                const data = job.data;
+                const values = isArray(data.values) ? data.values : [];
+                return values.reduce((total, value) => total + Number(value || 0), 0);
+            };
+        case 'fail':
+            return async () => {
+                throw ErrorFactory.createWorkerError('redis-rpc test processor failure');
+            };
+        default:
+            throw createRpcValidationError(`Unsupported worker processor: ${String(kind)}`);
+    }
+};
+const dispatchWorker = async (state, method, payload) => {
+    const args = asArgs(payload);
+    switch (method) {
+        case 'start':
+        case 'startWorker': {
+            const queueName = requireString(firstDefined(args[0], payload.queueName, payload.queue), 'queueName');
+            const defaultWorkerName = `${queueName}:${String(payload.processor || 'echo')}`;
+            const workerName = requireString(firstDefined(args[1], payload.workerName, payload.name, defaultWorkerName), 'workerName');
+            if (state.workers.has(workerName))
+                return { workerName, queueName, status: 'already-running' };
+            const options = isRecord(args[2]) ? args[2] : payload;
+            const worker = new Worker(queueName, createProcessor(options.processor), {
+                connection: createConnection(state),
+                prefix: state.prefix,
+                concurrency: numberFrom(options.concurrency, 1),
+            });
+            state.workers.set(workerName, { queueName, worker });
+            await worker.waitUntilReady();
+            return { workerName, queueName, status: 'running' };
+        }
+        case 'stop':
+        case 'stopWorker': {
+            const workerName = requireString(firstDefined(args[0], payload.workerName, payload.name), 'workerName');
+            const entry = state.workers.get(workerName);
+            if (!entry)
+                return false;
+            await entry.worker.close(true);
+            state.workers.delete(workerName);
+            return true;
+        }
+        case 'list':
+            return Array.from(state.workers.entries()).map(([workerName, entry]) => ({
+                workerName,
+                queueName: entry.queueName,
+            }));
+        default:
+            throw createRpcValidationError(`Unsupported worker method: ${method}`);
+    }
+};
+const dispatchMonitor = async (state, method, payload) => {
+    const args = asArgs(payload);
+    switch (method) {
+        case 'snapshot':
+        case 'getSnapshot': {
+            let queueNames;
+            if (isArray(args[0])) {
+                queueNames = args[0];
+            }
+            else if (isArray(payload.queueNames)) {
+                queueNames = payload.queueNames;
+            }
+            else {
+                queueNames = Array.from(state.queues.keys());
+            }
+            const queues = await Promise.all(queueNames.map(async (name) => {
+                const queueName = requireString(name, 'queueName');
+                return { name: queueName, counts: await getQueue(state, queueName).getJobCounts() };
+            }));
+            return { status: 'ok', startedAt: new Date().toISOString(), queues };
+        }
+        case 'events':
+        case 'getEvents': {
+            const queueName = requireString(firstDefined(args[0], payload.queueName, payload.queue), 'queueName');
+            getQueueEvents(state, queueName);
+            return state.eventLogs.get(queueName) ?? [];
+        }
+        case 'getRecentJobsForQueue': {
+            const queueName = requireString(firstDefined(args[0], payload.queueName, payload.queue), 'queueName');
+            return dispatchQueue(state, 'getJobs', {
+                ...payload,
+                args: [],
+                queueName,
+                states: DEFAULT_JOB_STATES,
+                start: 0,
+                end: firstDefined(args[1], payload.limit, 99),
+            });
+        }
+        default:
+            throw createRpcValidationError(`Unsupported queue-monitor method: ${method}`);
+    }
+};
+const dispatchRedis = async (state, method, payload) => {
+    const args = asArgs(payload);
+    const connection = createConnection(state, { maxRetriesPerRequest: 1 });
+    try {
+        if (method === 'ping')
+            return await connection.ping();
+        if (method === 'call') {
+            const command = requireString(firstDefined(args[0], payload.command), 'command');
+            const rawCommandArgs = args.length > 0 ? args.slice(1) : asArgs(payload);
+            const commandArgs = redisCommandArgs(rawCommandArgs);
+            return await connection.call(command, ...commandArgs);
+        }
+        if (method === 'pipeline' || method === 'multi') {
+            const commands = redisPipelineCommands(payload);
+            const transaction = method === 'multi' || boolFrom(payload.transaction, false);
+            const pipeline = (transaction
+                ? connection.multi()
+                : connection.pipeline());
+            for (const entry of commands) {
+                const command = requireString(entry.command, 'command');
+                queuePipelineCommand(pipeline, command, redisCommandArgs(isArray(entry.args) ? entry.args : []));
+            }
+            return serializePipelineResults(await pipeline.exec());
+        }
+        throw createRpcValidationError(`Unsupported redis method: ${method}`);
+    }
+    finally {
+        connection.disconnect();
+    }
+};
+const dispatchCustom = async (backend, state, service, method, payload) => {
+    const handler = state.services.get(service);
+    if (!handler) {
+        throw createRpcValidationError(`Unsupported Redis RPC service: ${service}`);
+    }
+    return handler({ method, payload, backend });
+};
+const closeBackend = async (state) => {
+    await Promise.allSettled(Array.from(state.workers.values()).map(async ({ worker }) => {
+        try {
+            await withTimeout(() => worker.close(true));
+        }
+        catch {
+            await worker.disconnect();
+        }
+    }));
+    await Promise.allSettled(Array.from(state.queueEvents.values()).map(async (events) => {
+        try {
+            await withTimeout(() => events.close());
+        }
+        catch {
+            await events.disconnect();
+        }
+    }));
+    await Promise.allSettled(Array.from(state.queues.values()).map(async (queue) => {
+        try {
+            await withTimeout(() => queue.close());
+        }
+        catch {
+            await queue.disconnect();
+        }
+    }));
+    for (const connection of state.connections) {
+        connection.disconnect();
+    }
+    state.workers.clear();
+    state.queues.clear();
+    state.queueEvents.clear();
+    state.eventLogs.clear();
+    state.connections.clear();
+};
+export const createRedisRpcBackend = (options = {}) => {
+    const serverOptions = rpcServerOptions();
+    const state = {
+        prefix: options.prefix || serverOptions.prefix,
+        connectionOptions: options.redis || redisConnectionOptions(),
+        queues: new Map(),
+        queueEvents: new Map(),
+        workers: new Map(),
+        eventLogs: new Map(),
+        connections: new Set(),
+        services: new Map(Object.entries(options.services ?? {})),
+    };
+    const backend = Object.freeze({
+        prefix: state.prefix,
+        dispatch: async (service, method, payload = {}) => {
+            const normalizedService = requireString(service, 'service');
+            const normalizedMethod = requireString(method, 'method');
+            const body = requireRecord(payload, 'payload');
+            if (normalizedService === 'queue' || normalizedService === 'bullmq')
+                return dispatchQueue(state, normalizedMethod, body);
+            if (normalizedService === 'worker')
+                return dispatchWorker(state, normalizedMethod, body);
+            if (normalizedService === 'queue-monitor')
+                return dispatchMonitor(state, normalizedMethod, body);
+            if (normalizedService === 'redis')
+                return dispatchRedis(state, normalizedMethod, body);
+            return dispatchCustom(backend, state, normalizedService, normalizedMethod, body);
+        },
+        registerService: (service, handler) => {
+            state.services.set(requireString(service, 'service'), handler);
+        },
+        close: () => closeBackend(state),
+    });
+    return backend;
+};

package/dist/build-manifest.json

@@ -0,0 +1,94 @@
+{
+  "name": "@zintrust/redis-rpc",
+  "version": "2.4.1",
+  "buildDate": "2026-05-31T11:41:49.490Z",
+  "buildEnvironment": {
+    "node": "v22.22.1",
+    "platform": "darwin",
+    "arch": "arm64"
+  },
+  "git": {
+    "commit": "e97b7b3d",
+    "branch": "release"
+  },
+  "package": {
+    "engines": {
+      "node": ">=20.0.0"
+    },
+    "dependencies": [
+      "@zintrust/core",
+      "bullmq",
+      "dotenv",
+      "ioredis"
+    ],
+    "peerDependencies": [
+      "@zintrust/core"
+    ]
+  },
+  "files": {
+    "adapters.d.ts": {
+      "size": 2331,
+      "sha256": "4080a5f54655beac7aa22f271aae61e03611230abf75491cd269d83278ea07c7"
+    },
+    "adapters.js": {
+      "size": 2817,
+      "sha256": "f7a732072fa8b1c0a288cdea9e6304f0e884179ed924eb1530a2dbd57e5bb087"
+    },
+    "backend.d.ts": {
+      "size": 183,
+      "sha256": "c2f1dd71fe2c5a1dc73a7fba855b5e8f8b1700c9f05baeab2c5d9aa8f31f4c60"
+    },
+    "backend.js": {
+      "size": 21160,
+      "sha256": "85777d42545d97624a0973fccc33b91a0f8e6a6345c940a8581845a4670cce2e"
+    },
+    "client.d.ts": {
+      "size": 166,
+      "sha256": "f58e91ca403a526864cca16eba5caa34a947835d403a20fe9e02e7cdd7ec55ca"
+    },
+    "client.js": {
+      "size": 3528,
+      "sha256": "79322c1c1265d34a02260f0d51b99e0e549e02978a40208faaf4e6fdf56e92e3"
+    },
+    "env.d.ts": {
+      "size": 575,
+      "sha256": "640907189918c080ac4bdce3f9a09771ab417ab266d9d5096071ce03e95f36a0"
+    },
+    "env.js": {
+      "size": 1282,
+      "sha256": "4612b16a360e9a0644718f533c94dd80f2f4e1134c396348cf86814f54387ba7"
+    },
+    "errors.d.ts": {
+      "size": 484,
+      "sha256": "178c171224b78c62b2347f58922906fa6903cdff27731db14b4f9c88af4e86d1"
+    },
+    "errors.js": {
+      "size": 1202,
+      "sha256": "eea48bcb9a1fe0f4f065835b9ce517087a5216bd9f78816378c17fac432d7dce"
+    },
+    "index.d.ts": {
+      "size": 775,
+      "sha256": "69ade1c65e33274c5a4aef0ddddd02a2ad4b8436da40fdb918e352f17a038230"
+    },
+    "index.js": {
+      "size": 745,
+      "sha256": "b5bb2ade3e202388d2ea9606e279c849796227d8ca43c28082cde0feddad2f5a"
+    },
+    "server.d.ts": {
+      "size": 276,
+      "sha256": "3f9453082da4e8bdef61c904a4e6a8f2c5c24ef6ae8c785ec6671ee57739256c"
+    },
+    "server.js": {
+      "size": 3027,
+      "sha256": "843b4cb91e438003d474d1f145d30cdc0627f8e099fb90bfe02597eb469be192"
+    },
+    "types.d.ts": {
+      "size": 2348,
+      "sha256": "90ab4f7122923b219e51cd333688e90a1152def08b6e86891dd066c36f185157"
+    },
+    "types.js": {
+      "size": 11,
+      "sha256": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881"
+    }
+  }
+}

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import type { RedisRpcClient, RedisRpcClientOptions } from './types';
+export declare const createRedisRpcClient: (options?: RedisRpcClientOptions) => RedisRpcClient;