@zintrust/redis-rpc 2.4.2 → 2.4.4

package/README.md

@@ -56,6 +56,43 @@ The server and client read these variables:
 | `REDIS_RPC_RETRY_MAX`      | `2`                                  | Client-side retry count used by integrations.                   |
 | `REDIS_RPC_RETRY_DELAY_MS` | `500`                                | Client-side retry delay used by integrations.                   |
 
+### Custom request headers
+
+The client supports injecting extra HTTP headers into every outgoing RPC request. This uses the same environment-variable convention as all other ZinTrust proxy adapters (`REDIS_PROXY_HEADERS_*` for the redis-proxy, `MYSQL_PROXY_HEADERS_*` for MySQL, and so on).
+
+**Pattern:** `REDIS_RPC_PROXY_HEADERS_{HEADER_NAME}=value`
+
+Underscores in `HEADER_NAME` are converted to hyphens to form the actual header name.
+
+| Environment variable | HTTP header sent |
+| --- | --- |
+| `REDIS_RPC_PROXY_HEADERS_X_Tenant_Id=abc` | `x-tenant-id: abc` |
+| `REDIS_RPC_PROXY_HEADERS_Authorization=Bearer t` | `authorization: Bearer t` |
+| `REDIS_RPC_PROXY_HEADERS_X_Trace_Id=xyz` | `x-trace-id: xyz` |
+| `REDIS_RPC_PROXY_HEADERS_X_Custom_Header=foo` | `x-custom-header: foo` |
+
+These headers are read once when `createRedisRpcClient()` is called and are sent on every request. They are merged after `x-redis-rpc-secret`, so they cannot accidentally overwrite authentication.
+
+You can also pass headers directly in code. Programmatic headers take priority over env-sourced ones when a key collides:
+
+```ts
+const client = createRedisRpcClient({
+  baseUrl: process.env.REDIS_RPC_URL,
+  secret: process.env.REDIS_RPC_SECRET,
+  headers: {
+    'x-tenant-id': 'abc',
+    'x-trace-id': '123',
+  },
+});
+```
+
+Both sources are combined: `{ ...rpcClientHeaders(), ...options.headers }`. To inspect what headers were auto-detected from env, call the exported helper directly:
+
+```ts
+import { rpcClientHeaders } from '@zintrust/redis-rpc';
+console.log(rpcClientHeaders()); // { 'x-tenant-id': 'abc', ... } or undefined
+```
+
 Set both `USE_REDIS_PROXY=true` and `REDIS_RPC_URL` to make supported ZinTrust packages select Redis RPC automatically. `USE_REDIS_PROXY=true` by itself does not enable Redis RPC; it only says the process is allowed to use a Redis proxy transport.
 
 ## Running the server

package/dist/client.js

@@ -2,7 +2,7 @@ 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';
+import { rpcClientHeaders, rpcServerOptions } from './env.js';
 const requestJson = (url, body, headers) => {
     return new Promise((resolve, reject) => {
         const transport = url.protocol === 'https:' ? https : http;
@@ -48,6 +48,8 @@ export const createRedisRpcClient = (options = {}) => {
     const settings = rpcServerOptions();
     const baseUrl = options.baseUrl || `http://${settings.host}:${settings.port}`;
     const secret = options.secret ?? settings.secret;
+    // Env-sourced headers are the baseline; options.headers merges on top (wins on collision).
+    const resolvedHeaders = { ...rpcClientHeaders(), ...options.headers };
     const client = Object.freeze({
         call: async (service, method, payload = {}) => {
             const url = new URL('/rpc', baseUrl);
@@ -61,6 +63,7 @@ export const createRedisRpcClient = (options = {}) => {
                 'content-type': 'application/json',
                 connection: 'close',
                 ...(secret ? { 'x-redis-rpc-secret': secret } : {}),
+                ...resolvedHeaders,
             });
             const parsed = response.body;
             if (!response.ok || parsed.ok !== true) {

package/dist/env.d.ts

@@ -15,3 +15,18 @@ 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;
+/**
+ * Reads custom HTTP headers from environment variables using the same convention
+ * as all other ZinTrust proxies (SqlProxyAdapterUtils.parseCustomHeadersFromEnv).
+ *
+ * Pattern: REDIS_RPC_PROXY_HEADERS_{HEADER_NAME}=value
+ *   Underscores in HEADER_NAME are converted to hyphens.
+ *
+ * Examples:
+ *   REDIS_RPC_PROXY_HEADERS_X_Tenant_Id=abc        → x-tenant-id: abc
+ *   REDIS_RPC_PROXY_HEADERS_Authorization=Bearer t  → authorization: Bearer t
+ *   REDIS_RPC_PROXY_HEADERS_X_Trace_Id=xyz          → x-trace-id: xyz
+ *
+ * Returns undefined when no matching env vars are set (no overhead).
+ */
+export declare const rpcClientHeaders: () => Record<string, string> | undefined;

package/dist/env.js

@@ -1,9 +1,12 @@
-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;
+    if (typeof value !== 'string') {
+        return fallback;
+    }
+    const trimmed = value.trim();
+    return trimmed === '' ? fallback : trimmed;
 };
 export const readInt = (key, fallback) => {
     const parsed = Number.parseInt(readString(key, String(fallback)), 10);
@@ -22,3 +25,27 @@ export const rpcServerOptions = () => ({
     secret: readString('REDIS_RPC_SECRET', readString('REDIS_PROXY_SECRET', readString('APP_KEY', ''))),
     prefix: readString('REDIS_RPC_BULLMQ_PREFIX', readString('BULLMQ_PREFIX', 'bull')),
 });
+/**
+ * Reads custom HTTP headers from environment variables using the same convention
+ * as all other ZinTrust proxies (SqlProxyAdapterUtils.parseCustomHeadersFromEnv).
+ *
+ * Pattern: REDIS_RPC_PROXY_HEADERS_{HEADER_NAME}=value
+ *   Underscores in HEADER_NAME are converted to hyphens.
+ *
+ * Examples:
+ *   REDIS_RPC_PROXY_HEADERS_X_Tenant_Id=abc        → x-tenant-id: abc
+ *   REDIS_RPC_PROXY_HEADERS_Authorization=Bearer t  → authorization: Bearer t
+ *   REDIS_RPC_PROXY_HEADERS_X_Trace_Id=xyz          → x-trace-id: xyz
+ *
+ * Returns undefined when no matching env vars are set (no overhead).
+ */
+export const rpcClientHeaders = () => {
+    const PREFIX = 'REDIS_RPC_PROXY_HEADERS_';
+    const headers = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith(PREFIX) && typeof value === 'string' && value.trim() !== '') {
+            headers[key.slice(PREFIX.length).replaceAll('_', '-')] = value.trim();
+        }
+    }
+    return Object.keys(headers).length > 0 ? headers : undefined;
+};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createRedisRpcServer, listenRedisRpcServer } from './server';
 export { createRedisRpcClient } from './client';
+export { rpcClientHeaders, rpcServerOptions, redisConnectionOptions } from './env';
 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/dist/index.js

@@ -1,5 +1,6 @@
 export { createRedisRpcServer, listenRedisRpcServer } from './server.js';
 export { createRedisRpcClient } from './client.js';
+export { rpcClientHeaders, rpcServerOptions, redisConnectionOptions } from './env.js';
 export { createBullMqRpcQueue, createWorkerRpcRuntime, createQueueMonitorRpcDriver, createRedisRpcService, } from './adapters.js';
 export { createRedisRpcBackend } from './backend.js';
 /**

package/dist/server.js

@@ -18,33 +18,169 @@ const json = (response, status, payload) => {
     });
     response.end(JSON.stringify(payload));
 };
+const getHeaderSecret = (request) => {
+    const raw = request.headers['x-redis-rpc-secret'];
+    if (Array.isArray(raw)) {
+        return raw[0] ?? '';
+    }
+    return typeof raw === 'string' ? raw : '';
+};
+const previewSecret = (value) => value.slice(0, 5);
+const logStep = (step, details) => {
+    Logger.debug(`[redis-rpc][server] ${step}`, details);
+};
+const getRequestContext = (request, settings) => {
+    const method = request.method ?? '';
+    const url = new URL(request.url || '/', `http://${request.headers.host || 'localhost'}`);
+    const headerSecret = getHeaderSecret(request);
+    const settingsSecret = settings.secret || '';
+    return {
+        method,
+        url,
+        headerSecret,
+        settingsSecret,
+    };
+};
+const logRequestReceived = (context) => {
+    logStep('request.received', {
+        method: context.method,
+        path: context.url.pathname,
+        host: context.url.host,
+        headerSecretPreview: previewSecret(context.headerSecret),
+        settingsSecretPreview: previewSecret(context.settingsSecret),
+    });
+};
+const isHealthRoute = (context) => context.method === 'GET' && context.url.pathname === '/health';
+const isRpcRoute = (context) => context.method === 'POST' && context.url.pathname === '/rpc';
+const logHealthRoute = (prefix, path) => {
+    logStep('route.health', {
+        path,
+        prefix,
+    });
+};
+const logRouteCheck = (context) => {
+    logStep('route.check', {
+        method: context.method,
+        path: context.url.pathname,
+        isRpcRoute: isRpcRoute(context),
+    });
+};
+const logRouteNotFound = (context) => {
+    logStep('route.notFound', {
+        method: context.method,
+        path: context.url.pathname,
+    });
+};
+const validateRequestSecret = (context) => {
+    logStep('secret.validate.start', {
+        headerSecretPreview: previewSecret(context.headerSecret),
+        settingsSecretPreview: previewSecret(context.settingsSecret),
+    });
+    const secretMatches = context.settingsSecret !== '' && context.headerSecret === context.settingsSecret;
+    logStep('secret.validate.result', {
+        headerSecretPreview: previewSecret(context.headerSecret),
+        settingsSecretPreview: previewSecret(context.settingsSecret),
+        secretMatches,
+    });
+    return secretMatches;
+};
+const logSecretValidationFailure = (context) => {
+    logStep('secret.validate.failed', {
+        headerSecretPreview: previewSecret(context.headerSecret),
+        settingsSecretPreview: previewSecret(context.settingsSecret),
+    });
+};
+const readRpcBody = async (request) => {
+    logStep('body.read.start', {});
+    const bodyText = await readBody(request);
+    logStep('body.read.complete', {
+        length: bodyText.length,
+        isEmpty: bodyText.trim().length === 0,
+    });
+    try {
+        const body = (bodyText.trim().length === 0 ? {} : JSON.parse(bodyText));
+        logStep('body.parse.complete', {
+            requestId: body.requestId ?? null,
+            service: String(body.service || ''),
+            method: String(body.method || ''),
+            hasPayload: body.payload !== undefined,
+        });
+        return body;
+    }
+    catch (error) {
+        logStep('body.parse.failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+};
+const dispatchRpcRequest = async (backend, body) => {
+    logStep('dispatch.start', {
+        requestId: body.requestId ?? null,
+        service: String(body.service || ''),
+        method: String(body.method || ''),
+    });
+    const result = await backend.dispatch(String(body.service || ''), String(body.method || ''), body.payload ?? {});
+    logStep('dispatch.complete', {
+        requestId: body.requestId ?? null,
+        service: String(body.service || ''),
+        method: String(body.method || ''),
+    });
+    return result;
+};
+const sendRpcSuccess = (response, requestId, result) => {
+    json(response, 200, { ok: true, requestId, result, error: null });
+    logStep('response.sent', {
+        status: 200,
+        requestId,
+    });
+};
+const handleRequestError = (response, error) => {
+    const payload = toErrorPayload(error);
+    logStep('request.error', {
+        status: payload.status,
+        message: payload.body && typeof payload.body === 'object' && 'message' in payload.body
+            ? String(payload.body.message ?? '')
+            : '',
+    });
+    json(response, payload.status, payload.body);
+};
+const handleRpcRequest = async (request, response, context, backend) => {
+    logRouteCheck(context);
+    if (!isRpcRoute(context)) {
+        logRouteNotFound(context);
+        throw createRpcNotFoundError('Unknown Redis RPC route');
+    }
+    if (!validateRequestSecret(context)) {
+        logSecretValidationFailure(context);
+        throw createRpcUnauthorizedError('Invalid Redis RPC secret');
+    }
+    const body = await readRpcBody(request);
+    const result = await dispatchRpcRequest(backend, body);
+    sendRpcSuccess(response, body.requestId ?? null, result);
+};
+const handleHealthRequest = (response, backend) => {
+    logHealthRoute(backend.prefix, '/health');
+    json(response, 200, { ok: true, service: 'redis-rpc', prefix: backend.prefix });
+};
+const handleIncomingRequest = async (request, response, settings, backend) => {
+    const context = getRequestContext(request, settings);
+    logRequestReceived(context);
+    if (isHealthRoute(context)) {
+        handleHealthRequest(response, backend);
+        return;
+    }
+    await handleRpcRequest(request, response, context, backend);
+};
 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);
-        }
+    const server = http.createServer((request, response) => {
+        void handleIncomingRequest(request, response, settings, backend).catch((error) => {
+            handleRequestError(response, error);
+        });
     });
     return { server, backend, settings };
 };

package/dist/types.d.ts

@@ -49,6 +49,8 @@ export type CreateRedisRpcBackendOptions = Partial<RedisRpcServerOptions> & Read
 export type RedisRpcClientOptions = Partial<RedisRpcServerOptions> & Readonly<{
     baseUrl?: string;
     secret?: string;
+    /** Extra HTTP headers merged into every request (same pattern as redis-proxy customHeaders). */
+    headers?: Record<string, string>;
 }>;
 export type RedisRpcClient = Readonly<{
     call: <T = unknown>(service: string, method: string, payload?: RpcPayload) => Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/redis-rpc",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "description": "Redis RPC backend for BullMQ queue operations in ZinTrust.",
   "private": false,
   "type": "module",

package/dist/build-manifest.json

@@ -1,98 +0,0 @@
-{
-  "name": "@zintrust/redis-rpc",
-  "version": "2.4.1",
-  "buildDate": "2026-05-31T11:45:34.243Z",
-  "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"
-    },
-    "build-manifest.json": {
-      "size": 2714,
-      "sha256": "7b981cbb55c59a29db94c6f110f360299e33e36ed26d54a5f4aef9af54e3a324"
-    },
-    "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": "554f195a0480b8fddb7778d656aae9d528398b15b1f95748d5ccf77c58884dc4"
-    },
-    "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"
-    }
-  }
-}