@zintrust/core 0.4.26 → 0.4.28

package/packages/queue-redis/src/HttpQueueDriver.js

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

package/packages/queue-redis/src/QueueHttpGateway.d.ts

@@ -0,0 +1,16 @@
+import type { IRouter } from '../../../src/index.js';
+type QueueGatewaySettings = {
+    basePath: string;
+    keyId: string;
+    secret: string;
+    signingWindowMs: number;
+    nonceTtlMs: number;
+    middleware: ReadonlyArray<string>;
+};
+export declare const QueueHttpGateway: Readonly<{
+    create(config?: Partial<QueueGatewaySettings>): {
+        registerRoutes: (router: IRouter) => void;
+    };
+}>;
+export default QueueHttpGateway;
+//# sourceMappingURL=QueueHttpGateway.d.ts.map

package/packages/queue-redis/src/QueueHttpGateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueHttpGateway.d.ts","sourceRoot":"","sources":["../../../../packages/queue-redis/src/QueueHttpGateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsC,OAAO,EAAgB,MAAM,gBAAgB,CAAC;AAkChG,KAAK,oBAAoB,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AA0PF,eAAO,MAAM,gBAAgB;oBACX,OAAO,CAAC,oBAAoB,CAAC,GAAG;QAC9C,cAAc,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;KAC3C;EAgBD,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/packages/queue-redis/src/QueueHttpGateway.js

@@ -0,0 +1,217 @@
+import { Env, ErrorFactory, Logger, Router, SignedRequest } from '../../../src/index.js';
+import BullMQRedisQueue, { runWithDirectQueueDriver } from './BullMQRedisQueue.js';
+const nonces = new Map();
+const nowMs = () => Date.now();
+const normalizePath = (value) => {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '/api/_sys/queue/rpc';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const parseMiddleware = (value) => value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+const readSettings = () => {
+    const configuredSecret = Env.get('QUEUE_HTTP_PROXY_KEY', '').trim();
+    const secret = configuredSecret === '' ? Env.APP_KEY : configuredSecret;
+    return {
+        basePath: normalizePath(Env.get('QUEUE_HTTP_PROXY_PATH', '/api/_sys/queue/rpc')),
+        keyId: Env.get('QUEUE_HTTP_PROXY_KEY_ID', Env.APP_NAME || 'zintrust').trim(),
+        secret,
+        signingWindowMs: Env.getInt('QUEUE_HTTP_PROXY_MAX_SKEW_MS', 60000),
+        nonceTtlMs: Env.getInt('QUEUE_HTTP_PROXY_NONCE_TTL_MS', 120000),
+        middleware: parseMiddleware(Env.get('QUEUE_HTTP_PROXY_MIDDLEWARE', '')),
+    };
+};
+const cleanupExpiredNonces = () => {
+    const current = nowMs();
+    for (const [nonceKey, expiresAt] of nonces.entries()) {
+        if (expiresAt <= current) {
+            nonces.delete(nonceKey);
+        }
+    }
+};
+const storeNonce = async (keyId, nonce, ttlMs) => {
+    cleanupExpiredNonces();
+    const nonceKey = `${keyId}:${nonce}`;
+    if (nonces.has(nonceKey))
+        return false;
+    nonces.set(nonceKey, nowMs() + Math.max(ttlMs, 1));
+    return true;
+};
+const getBodyRecord = (req) => {
+    const body = req.getBody?.() ?? req.body;
+    if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+        return body;
+    }
+    return {};
+};
+const getRawBody = (req) => {
+    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;
+    };
+    return {
+        'x-zt-key-id': normalize(headers['x-zt-key-id']),
+        'x-zt-timestamp': normalize(headers['x-zt-timestamp']),
+        'x-zt-nonce': normalize(headers['x-zt-nonce']),
+        'x-zt-body-sha256': normalize(headers['x-zt-body-sha256']),
+        'x-zt-signature': normalize(headers['x-zt-signature']),
+    };
+};
+const sendFailure = (res, requestId, status, code, message, details) => {
+    const payload = {
+        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);
+};
+const readQueueName = (payload) => {
+    const value = payload.queue;
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    return normalized === '' ? null : normalized;
+};
+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);
+            }
+            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;
+            }
+            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() === '') {
+        return {
+            ok: false,
+            code: 'CONFIG_ERROR',
+            status: 500,
+            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,
+        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;
+        },
+    });
+    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';
+    return {
+        ok: false,
+        code: errorCode,
+        status: errorCode === 'EXPIRED' || errorCode === 'REPLAYED' ? 401 : 403,
+        message: errorMessage,
+    };
+};
+const createHandler = (settings) => {
+    return async (req, res) => {
+        const rawBody = getRawBody(req);
+        const body = getBodyRecord(req);
+        const requestId = typeof body['requestId'] === 'string' && body['requestId'].trim() !== ''
+            ? body['requestId']
+            : 'unknown';
+        const auth = await verifyRequest(req, rawBody, settings);
+        if (auth.ok === false) {
+            sendFailure(res, requestId, auth.status, auth.code, auth.message);
+            return;
+        }
+        const action = body['action'];
+        const payload = body['payload'];
+        if (typeof action !== 'string') {
+            sendFailure(res, requestId, 400, 'VALIDATION_ERROR', 'action is required');
+            return;
+        }
+        if (!payload || typeof payload !== 'object' || Array.isArray(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);
+            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);
+        }
+    };
+};
+export const QueueHttpGateway = Object.freeze({
+    create(config) {
+        const settings = {
+            ...readSettings(),
+            ...config,
+            basePath: normalizePath(config?.basePath ?? readSettings().basePath),
+        };
+        const routeOptions = settings.middleware.length > 0 ? { middleware: settings.middleware } : undefined;
+        return {
+            registerRoutes(router) {
+                Router.post(router, settings.basePath, createHandler(settings), routeOptions);
+            },
+        };
+    },
+});
+export default QueueHttpGateway;

package/packages/queue-redis/src/RedisPublishClient.d.ts

@@ -0,0 +1,14 @@
+export type RedisPublishClient = {
+    connect?: () => Promise<void>;
+    publish(channel: string, message: string): Promise<number>;
+};
+/**
+ * Singleton Redis publish client factory
+ * Creates and caches a Redis publish client for broadcasting
+ */
+export declare const createRedisPublishClient: () => Promise<RedisPublishClient>;
+/**
+ * Reset the singleton publish client (useful for testing)
+ */
+export declare const resetPublishClient: () => void;
+//# sourceMappingURL=RedisPublishClient.d.ts.map

package/packages/queue-redis/src/RedisPublishClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisPublishClient.d.ts","sourceRoot":"","sources":["../../../../packages/queue-redis/src/RedisPublishClient.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5D,CAAC;AAuLF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,kBAAkB,CAkB3E,CAAC;AA6FF;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAGrC,CAAC"}