@zintrust/redis-rpc 2.4.1

package/dist/client.js

@@ -0,0 +1,82 @@
+import { ErrorFactory, isUndefinedOrNull } from '@zintrust/core/runtime';
+import { randomUUID } from 'node:crypto';
+import http from 'node:http';
+import https from 'node:https';
+import { rpcServerOptions } from './env.js';
+const requestJson = (url, body, headers) => {
+    return new Promise((resolve, reject) => {
+        const transport = url.protocol === 'https:' ? https : http;
+        const request = transport.request(url, {
+            method: 'POST',
+            agent: false,
+            headers: {
+                ...headers,
+                'content-length': String(Buffer.byteLength(body)),
+            },
+        }, (response) => {
+            const chunks = [];
+            response.setEncoding('utf8');
+            response.on('data', (chunk) => chunks.push(chunk));
+            response.on('end', () => {
+                const text = chunks.join('');
+                try {
+                    resolve({
+                        statusCode: response.statusCode || 0,
+                        ok: (response.statusCode || 0) >= 200 && (response.statusCode || 0) < 300,
+                        body: isUndefinedOrNull(text.trim()) ? {} : JSON.parse(text),
+                    });
+                }
+                catch (error) {
+                    reject(ErrorFactory.createTryCatchError('Redis RPC response parse failed', { error }));
+                }
+            });
+        });
+        request.on('error', (error) => reject(ErrorFactory.createConnectionError('Redis RPC request failed', { error })));
+        request.end(body);
+    });
+};
+const createServiceProxy = (client, service, target) => {
+    return new Proxy(Object.create(null), {
+        get(_receiver, property) {
+            if (typeof property !== 'string')
+                return undefined;
+            return (...args) => client.call(service, property, { target, args });
+        },
+    });
+};
+export const createRedisRpcClient = (options = {}) => {
+    const settings = rpcServerOptions();
+    const baseUrl = options.baseUrl || `http://${settings.host}:${settings.port}`;
+    const secret = options.secret ?? settings.secret;
+    const client = Object.freeze({
+        call: async (service, method, payload = {}) => {
+            const url = new URL('/rpc', baseUrl);
+            const body = JSON.stringify({
+                requestId: randomUUID(),
+                service,
+                method,
+                payload,
+            });
+            const response = await requestJson(url, body, {
+                'content-type': 'application/json',
+                connection: 'close',
+                ...(secret ? { 'x-redis-rpc-secret': secret } : {}),
+            });
+            const parsed = response.body;
+            if (!response.ok || parsed.ok !== true) {
+                const error = parsed.error;
+                throw ErrorFactory.createTryCatchError(error?.message || `Redis RPC failed (${response.statusCode})`, {
+                    code: error?.code,
+                    details: error?.details,
+                });
+            }
+            return parsed.result;
+        },
+        queue: (method, payload = {}) => client.call('queue', method, payload),
+        worker: (method, payload = {}) => client.call('worker', method, payload),
+        monitor: (method, payload = {}) => client.call('queue-monitor', method, payload),
+        redis: (method, payload = {}) => client.call('redis', method, payload),
+        service: (service, target) => createServiceProxy(client, service, target),
+    });
+    return client;
+};

package/dist/env.d.ts

@@ -0,0 +1,17 @@
+export type RedisRpcRedisOptions = Readonly<{
+    host: string;
+    port: number;
+    password?: string;
+    db: number;
+    maxRetriesPerRequest: null;
+}>;
+export type RedisRpcServerOptions = Readonly<{
+    host: string;
+    port: number;
+    secret: string;
+    prefix: string;
+}>;
+export declare const readString: (key: string, fallback?: string) => string;
+export declare const readInt: (key: string, fallback: number) => number;
+export declare const redisConnectionOptions: () => RedisRpcRedisOptions;
+export declare const rpcServerOptions: () => RedisRpcServerOptions;

package/dist/env.js

@@ -0,0 +1,24 @@
+import { isNull } from '@zintrust/core/helper';
+import { config as loadDotenv } from 'dotenv';
+loadDotenv({ path: process.env.REDIS_RPC_ENV_FILE || '.env' });
+export const readString = (key, fallback = '') => {
+    const value = process.env[key];
+    return typeof value === 'string' && !isNull(value.trim()) ? value.trim() : fallback;
+};
+export const readInt = (key, fallback) => {
+    const parsed = Number.parseInt(readString(key, String(fallback)), 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+export const redisConnectionOptions = () => ({
+    host: readString('REDIS_RPC_REDIS_HOST', readString('REDIS_HOST', '127.0.0.1')),
+    port: readInt('REDIS_RPC_REDIS_PORT', readInt('REDIS_PORT', 6379)),
+    password: readString('REDIS_RPC_REDIS_PASSWORD', readString('REDIS_PASSWORD', '')) || undefined,
+    db: readInt('REDIS_RPC_REDIS_DB', readInt('REDIS_QUEUE_DB', readInt('REDIS_DB', 0))),
+    maxRetriesPerRequest: null,
+});
+export const rpcServerOptions = () => ({
+    host: readString('REDIS_RPC_HOST', '127.0.0.1'),
+    port: readInt('REDIS_RPC_PORT', 8794),
+    secret: readString('REDIS_RPC_SECRET', readString('REDIS_PROXY_SECRET', readString('APP_KEY', ''))),
+    prefix: readString('REDIS_RPC_BULLMQ_PREFIX', readString('BULLMQ_PREFIX', 'bull')),
+});

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export declare const createRpcValidationError: (message: string, details?: unknown) => Error;
+export declare const createRpcUnauthorizedError: (message: string, details?: unknown) => Error;
+export declare const createRpcNotFoundError: (message: string, details?: unknown) => Error;
+export declare const createRpcFailureError: (message: string, details?: unknown) => Error;
+export declare const toErrorPayload: (error: unknown) => Readonly<{
+    status: number;
+    body: unknown;
+}>;

package/dist/errors.js

@@ -0,0 +1,30 @@
+import { ErrorFactory } from '@zintrust/core/runtime';
+export const createRpcValidationError = (message, details) => {
+    return ErrorFactory.createValidationError(message, details);
+};
+export const createRpcUnauthorizedError = (message, details) => {
+    return ErrorFactory.createUnauthorizedError(message, details);
+};
+export const createRpcNotFoundError = (message, details) => {
+    return ErrorFactory.createNotFoundError(message, details);
+};
+export const createRpcFailureError = (message, details) => {
+    return ErrorFactory.createTryCatchError(message, details);
+};
+export const toErrorPayload = (error) => {
+    const value = error;
+    const code = typeof value.code === 'string' && value.code.length > 0 ? value.code : 'REDIS_RPC_ERROR';
+    const message = typeof value.message === 'string' && value.message.length > 0 ? value.message : 'Redis RPC request failed';
+    const status = typeof value.statusCode === 'number' && value.statusCode >= 400 ? value.statusCode : 500;
+    return {
+        status,
+        body: {
+            ok: false,
+            error: {
+                code,
+                message,
+                details: value.details,
+            },
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createRedisRpcServer, listenRedisRpcServer } from './server';
+export { createRedisRpcClient } from './client';
+export { createBullMqRpcQueue, createWorkerRpcRuntime, createQueueMonitorRpcDriver, createRedisRpcService, } from './adapters';
+export { createRedisRpcBackend } from './backend';
+export type { RpcPayload, RpcRequest, RpcErrorBody, RpcSuccessBody, RedisRpcBackendState, RedisRpcServiceHandler, RedisRpcBackend, CreateRedisRpcBackendOptions, RedisRpcClientOptions, RedisRpcClient, RedisRpcServerInstance, } from './types';
+/**
+ * Package version and build metadata
+ * Available at runtime for debugging and health checks
+ */
+export declare const _ZINTRUST_REDIS_RPC_VERSION = "1.0.0";
+export declare const _ZINTRUST_REDIS_RPC_BUILD_DATE = "__BUILD_DATE__";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createRedisRpcServer, listenRedisRpcServer } from './server.js';
+export { createRedisRpcClient } from './client.js';
+export { createBullMqRpcQueue, createWorkerRpcRuntime, createQueueMonitorRpcDriver, createRedisRpcService, } from './adapters.js';
+export { createRedisRpcBackend } from './backend.js';
+/**
+ * Package version and build metadata
+ * Available at runtime for debugging and health checks
+ */
+export const _ZINTRUST_REDIS_RPC_VERSION = '1.0.0';
+export const _ZINTRUST_REDIS_RPC_BUILD_DATE = '__BUILD_DATE__';

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import type { RedisRpcServerInstance } from './types';
+export declare const createRedisRpcServer: (options?: Record<string, unknown>) => RedisRpcServerInstance;
+export declare const listenRedisRpcServer: (options?: Record<string, unknown>) => Promise<RedisRpcServerInstance>;

package/dist/server.js

@@ -0,0 +1,65 @@
+import { isObject } from '@zintrust/core/helper';
+import { Logger } from '@zintrust/core/runtime';
+import http from 'node:http';
+import { createRedisRpcBackend } from './backend.js';
+import { rpcServerOptions } from './env.js';
+import { createRpcNotFoundError, createRpcUnauthorizedError, toErrorPayload } from './errors.js';
+const readBody = async (request) => {
+    const chunks = [];
+    for await (const chunk of request) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+};
+const json = (response, status, payload) => {
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+    });
+    response.end(JSON.stringify(payload));
+};
+export const createRedisRpcServer = (options = {}) => {
+    const settings = { ...rpcServerOptions(), ...options };
+    const backend = isObject(options.backend)
+        ? options.backend
+        : createRedisRpcBackend(settings);
+    const server = http.createServer(async (request, response) => {
+        try {
+            const url = new URL(request.url || '/', `http://${request.headers.host || 'localhost'}`);
+            if (request.method === 'GET' && url.pathname === '/health') {
+                json(response, 200, { ok: true, service: 'redis-rpc', prefix: backend.prefix });
+                return;
+            }
+            if (request.method !== 'POST' || url.pathname !== '/rpc') {
+                throw createRpcNotFoundError('Unknown Redis RPC route');
+            }
+            if (!settings.secret || request.headers['x-redis-rpc-secret'] !== settings.secret) {
+                throw createRpcUnauthorizedError('Invalid Redis RPC secret');
+            }
+            const bodyText = await readBody(request);
+            const body = (bodyText.trim().length === 0 ? {} : JSON.parse(bodyText));
+            const result = await backend.dispatch(String(body.service || ''), String(body.method || ''), body.payload ?? {});
+            json(response, 200, { ok: true, requestId: body.requestId ?? null, result, error: null });
+        }
+        catch (error) {
+            const payload = toErrorPayload(error);
+            json(response, payload.status, payload.body);
+        }
+    });
+    return { server, backend, settings };
+};
+export const listenRedisRpcServer = async (options = {}) => {
+    const created = createRedisRpcServer(options);
+    await new Promise((resolve) => created.server.listen(created.settings.port, created.settings.host, resolve));
+    return created;
+};
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const created = await listenRedisRpcServer();
+    Logger.info(`redis-rpc listening on http://${created.settings.host}:${created.settings.port}`);
+    const shutdown = async () => {
+        await created.backend.close();
+        created.server.close(() => process.exit(0));
+    };
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+import type { RedisOptions } from 'ioredis';
+import type http from 'node:http';
+import type { RedisRpcRedisOptions, RedisRpcServerOptions } from './env';
+export type RpcPayload = Record<string, unknown> & Readonly<{
+    args?: unknown[];
+    target?: string;
+    queue?: string;
+    queueName?: string;
+}>;
+export type RpcRequest = Readonly<{
+    requestId?: string | null;
+    service: string;
+    method: string;
+    payload?: RpcPayload;
+}>;
+export type RpcErrorBody = Readonly<{
+    ok: false;
+    error: Readonly<{
+        code: string;
+        message: string;
+        details?: unknown;
+    }>;
+}>;
+export type RpcSuccessBody<T = unknown> = Readonly<{
+    ok: true;
+    requestId: string | null;
+    result: T;
+    error: null;
+}>;
+export type RedisRpcBackendState = {
+    prefix: string;
+    connectionOptions: RedisRpcRedisOptions | RedisOptions;
+};
+export type RedisRpcServiceHandler = (input: Readonly<{
+    method: string;
+    payload: RpcPayload;
+    backend: RedisRpcBackend;
+}>) => Promise<unknown>;
+export type RedisRpcBackend = Readonly<{
+    prefix: string;
+    dispatch: (service: string, method: string, payload?: RpcPayload) => Promise<unknown>;
+    registerService: (service: string, handler: RedisRpcServiceHandler) => void;
+    close: () => Promise<void>;
+}>;
+export type CreateRedisRpcBackendOptions = Partial<RedisRpcServerOptions> & Readonly<{
+    redis?: RedisRpcRedisOptions | RedisOptions;
+    services?: Record<string, RedisRpcServiceHandler>;
+}>;
+export type RedisRpcClientOptions = Partial<RedisRpcServerOptions> & Readonly<{
+    baseUrl?: string;
+    secret?: string;
+}>;
+export type RedisRpcClient = Readonly<{
+    call: <T = unknown>(service: string, method: string, payload?: RpcPayload) => Promise<T>;
+    queue: <T = unknown>(method: string, payload?: RpcPayload) => Promise<T>;
+    worker: <T = unknown>(method: string, payload?: RpcPayload) => Promise<T>;
+    monitor: <T = unknown>(method: string, payload?: RpcPayload) => Promise<T>;
+    redis: <T = unknown>(method: string, payload?: RpcPayload) => Promise<T>;
+    service: <TService extends object = Record<string, (...args: unknown[]) => Promise<unknown>>>(service: string, target?: string) => TService;
+}>;
+export type RedisRpcServerInstance = Readonly<{
+    server: http.Server;
+    backend: RedisRpcBackend;
+    settings: RedisRpcServerOptions;
+}>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@zintrust/redis-rpc",
+  "version": "2.4.1",
+  "description": "Redis RPC backend for BullMQ queue operations in ZinTrust.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters.d.ts",
+      "default": "./dist/adapters.js"
+    },
+    "./backend": {
+      "types": "./dist/backend.d.ts",
+      "default": "./dist/backend.js"
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@zintrust/core": "2.4.0",
+    "bullmq": "^5.77.6",
+    "dotenv": "^17.2.3",
+    "ioredis": "^5.11.0"
+  },
+  "peerDependencies": {
+    "@zintrust/core": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "zintrust",
+    "redis",
+    "rpc",
+    "bullmq",
+    "queue",
+    "proxy"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ../../scripts/fix-dist-esm-imports.mjs dist",
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx test-bullmq.mjs",
+    "prepublishOnly": "npm run build"
+  }
+}