@veryfront/ext-redis 0.1.1185

package/esm/redis-client-manager.js

@@ -0,0 +1,535 @@
+import { INITIALIZATION_ERROR } from "veryfront/errors/general";
+import { DEPENDENCY_MISSING } from "veryfront/errors/module";
+import { getEnv } from "veryfront/platform/env";
+import { logger as baseLogger } from "veryfront/utils/logger";
+import { requireRedisUrl } from "./connection-config.js";
+const logger = baseLogger.component("redis");
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const RECONNECT_DELAY_MS = 5_000;
+const CLIENT_OPTION_KEYS = new Set([
+    "url",
+    "connectTimeout",
+    "autoReconnect",
+    "tls",
+    "password",
+    "username",
+]);
+function logCleanupFailure(message, error) {
+    try {
+        logger.error(message, error);
+    }
+    catch {
+        // Diagnostics must not interrupt transport cleanup.
+    }
+}
+const setupCleanupClients = new WeakMap();
+/** Setup failed and the provisional client could not be disposed. */
+class RedisClientSetupCleanupError extends AggregateError {
+    constructor(setupError, cleanupError, client) {
+        super([setupError, cleanupError], "Redis client setup and cleanup failed");
+        setupCleanupClients.set(this, client);
+    }
+}
+/** Internal handoff of a provisional client that still requires cleanup. */
+export function takeRedisClientSetupCleanupClient(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const client = setupCleanupClients.get(error);
+    if (client)
+        setupCleanupClients.delete(error);
+    return client;
+}
+function readOwnDataProperty(value, key) {
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(value, key);
+    }
+    catch (cause) {
+        throw new TypeError(`Redis client option ${key} could not be inspected`, { cause });
+    }
+    if (!descriptor)
+        return undefined;
+    if (!("value" in descriptor)) {
+        throw new TypeError(`Redis client option ${key} must be a data property`);
+    }
+    return descriptor.value;
+}
+function captureClientOptions(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("Redis client options must be an object");
+    }
+    let prototype;
+    let keys;
+    try {
+        prototype = Object.getPrototypeOf(value);
+        keys = Reflect.ownKeys(value);
+    }
+    catch (cause) {
+        throw new TypeError("Redis client options could not be inspected", { cause });
+    }
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError("Redis client options must be a plain object");
+    }
+    if (keys.some((key) => typeof key !== "string" || !CLIENT_OPTION_KEYS.has(key))) {
+        throw new TypeError("Redis client options contain an unknown option");
+    }
+    const urlValue = readOwnDataProperty(value, "url");
+    const connectTimeout = readOwnDataProperty(value, "connectTimeout");
+    const autoReconnect = readOwnDataProperty(value, "autoReconnect");
+    const tls = readOwnDataProperty(value, "tls");
+    const password = readOwnDataProperty(value, "password");
+    const username = readOwnDataProperty(value, "username");
+    if (urlValue !== undefined)
+        requireRedisUrl(urlValue);
+    if (autoReconnect !== undefined && typeof autoReconnect !== "boolean") {
+        throw new TypeError("Redis client option autoReconnect must be a boolean");
+    }
+    if (tls !== undefined && typeof tls !== "boolean") {
+        throw new TypeError("Redis client option tls must be a boolean");
+    }
+    if (password !== undefined && typeof password !== "string") {
+        throw new TypeError("Redis client option password must be a string");
+    }
+    if (username !== undefined && typeof username !== "string") {
+        throw new TypeError("Redis client option username must be a string");
+    }
+    return Object.freeze({
+        ...(urlValue === undefined ? {} : { url: urlValue }),
+        ...(connectTimeout === undefined ? {} : { connectTimeout: connectTimeout }),
+        ...(autoReconnect === undefined ? {} : { autoReconnect }),
+        ...(tls === undefined ? {} : { tls }),
+        ...(password === undefined ? {} : { password }),
+        ...(username === undefined ? {} : { username }),
+    });
+}
+function connectionCancelledError() {
+    return INITIALIZATION_ERROR.create({
+        detail: "[Redis] Connection attempt cancelled by disconnect",
+    });
+}
+function raceWithAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? connectionCancelledError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason ?? connectionCancelledError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+function resolveClientOptions(options, readEnv) {
+    if (options.connectTimeout !== undefined &&
+        (!Number.isInteger(options.connectTimeout) || options.connectTimeout <= 0 ||
+            options.connectTimeout > MAX_TIMER_DELAY_MS)) {
+        throw new RangeError(`Redis connectTimeout must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    const configuredUrl = options.url ?? readEnv("REDIS_URL");
+    const url = configuredUrl === undefined || configuredUrl.length === 0
+        ? undefined
+        : requireRedisUrl(configuredUrl);
+    const useTls = options.tls ?? url?.startsWith("rediss://") ?? false;
+    if (!useTls && readEnv("NODE_ENV") === "production") {
+        logger.warn("Redis connection without TLS in production. Set REDIS_URL to rediss:// or pass tls: true.");
+    }
+    const password = options.password ?? readEnv("REDIS_PASSWORD");
+    const username = options.username ?? readEnv("REDIS_USERNAME");
+    const socket = useTls || options.connectTimeout !== undefined || options.autoReconnect === false
+        ? {
+            ...(useTls ? { tls: true } : {}),
+            ...(options.connectTimeout === undefined ? {} : { connectTimeout: options.connectTimeout }),
+            ...(options.autoReconnect === false ? { reconnectStrategy: false } : {}),
+        }
+        : undefined;
+    const factoryOptions = {
+        ...(url === undefined ? {} : { url }),
+        ...(socket === undefined ? {} : { socket }),
+        ...(password === undefined ? {} : { password }),
+        ...(username === undefined ? {} : { username }),
+    };
+    const key = JSON.stringify({
+        url,
+        useTls,
+        connectTimeout: options.connectTimeout,
+        autoReconnect: options.autoReconnect ?? true,
+        password,
+        username,
+    });
+    return { factoryOptions, key, useTls };
+}
+async function loadDefaultFactory() {
+    try {
+        const module = await import("@redis/client");
+        if (typeof module.createClient !== "function") {
+            throw new TypeError("@redis/client does not export createClient");
+        }
+        return module.createClient;
+    }
+    catch (error) {
+        logger.debug("Failed to load @redis/client module", { error });
+        throw DEPENDENCY_MISSING.create({
+            detail: "[Redis] Failed to load @redis/client from @veryfront/ext-redis. Reinstall the extension package.",
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+}
+function assertRedisClient(value) {
+    if (!value || typeof value !== "object") {
+        throw new TypeError("Redis client factory must return an object");
+    }
+    for (const method of [
+        "connect",
+        "disconnect",
+        "get",
+        "mGet",
+        "set",
+        "del",
+        "scan",
+        "expire",
+        "eval",
+        "incr",
+        "pExpire",
+        "pTTL",
+    ]) {
+        let owner = value;
+        const visited = new Set();
+        let found = false;
+        while (owner) {
+            if (visited.has(owner)) {
+                throw new TypeError("Redis client factory result has a cyclic prototype chain");
+            }
+            visited.add(owner);
+            let descriptor;
+            try {
+                descriptor = Object.getOwnPropertyDescriptor(owner, method);
+            }
+            catch (cause) {
+                throw new TypeError(`Redis client factory result ${method} could not be inspected`, {
+                    cause,
+                });
+            }
+            if (descriptor) {
+                if (!("value" in descriptor) || typeof descriptor.value !== "function") {
+                    throw new TypeError(`Redis client factory result ${method} must be a data method`);
+                }
+                found = true;
+                break;
+            }
+            try {
+                owner = Object.getPrototypeOf(owner);
+            }
+            catch (cause) {
+                throw new TypeError(`Redis client factory result ${method} prototype could not be inspected`, { cause });
+            }
+        }
+        if (!found) {
+            throw new TypeError(`Redis client factory result must expose ${method}`);
+        }
+    }
+}
+/** Open one independently owned Redis connection. */
+export async function openRedisClient(options = {}, dependencies = {}, lifecycle = {}) {
+    const capturedOptions = captureClientOptions(options);
+    const resolved = resolveClientOptions(capturedOptions, dependencies.getEnv ?? getEnv);
+    const factory = await raceWithAbort((dependencies.loadFactory ?? loadDefaultFactory)(), lifecycle.signal);
+    const client = factory(resolved.factoryOptions);
+    assertRedisClient(client);
+    let cleanup = () => client.disconnect();
+    let cleanupTail = Promise.resolve();
+    const enqueueCleanup = () => {
+        const attempt = cleanupTail.catch(() => undefined).then(() => cleanup());
+        cleanupTail = attempt;
+        return attempt;
+    };
+    try {
+        if (lifecycle.onClientCreated) {
+            const observedCleanup = lifecycle.onClientCreated(client);
+            if (observedCleanup)
+                cleanup = observedCleanup;
+        }
+        const connectAttempt = Promise.resolve().then(() => client.connect());
+        let connectSettled = false;
+        void connectAttempt.then(() => {
+            connectSettled = true;
+        }, () => {
+            connectSettled = true;
+        });
+        try {
+            await raceWithAbort(connectAttempt, lifecycle.signal);
+        }
+        catch (error) {
+            if (!connectSettled) {
+                void connectAttempt.then(() => enqueueCleanup(), () => enqueueCleanup()).catch((lateCleanupError) => {
+                    logCleanupFailure("Redis client late-connect cleanup failed", lateCleanupError);
+                });
+            }
+            throw error;
+        }
+        return client;
+    }
+    catch (error) {
+        try {
+            await enqueueCleanup();
+        }
+        catch (closeError) {
+            if (lifecycle.onClientCreated) {
+                throw new AggregateError([error, closeError], "Redis client setup and observed cleanup failed");
+            }
+            throw new RedisClientSetupCleanupError(error, closeError, client);
+        }
+        throw error;
+    }
+}
+async function disconnectClient(client) {
+    if (client.isOpen === false)
+        return;
+    await client.disconnect();
+}
+/** Create an isolated, concurrency-safe Redis client manager. */
+export function createRedisClientManager(dependencies = {}) {
+    const readEnv = dependencies.getEnv ?? getEnv;
+    const loadFactory = dependencies.loadFactory ?? loadDefaultFactory;
+    const now = dependencies.now ?? Date.now;
+    const states = new Map();
+    const orphanedClients = new Set();
+    const clientDisconnections = new WeakMap();
+    let disconnectVersion = 0;
+    let disconnecting = null;
+    function disconnectTrackedClient(client) {
+        const existing = clientDisconnections.get(client);
+        if (existing)
+            return existing;
+        const pending = disconnectClient(client).then(() => {
+            orphanedClients.delete(client);
+        }, (error) => {
+            orphanedClients.add(client);
+            throw error;
+        });
+        const tracked = pending.finally(() => {
+            if (clientDisconnections.get(client) === tracked)
+                clientDisconnections.delete(client);
+        });
+        clientDisconnections.set(client, tracked);
+        return tracked;
+    }
+    function sweepExpiredFailures() {
+        const currentTime = now();
+        for (const [key, state] of states) {
+            if (!state.client && !state.connecting && state.failedAt !== undefined &&
+                currentTime - state.failedAt >= RECONNECT_DELAY_MS) {
+                states.delete(key);
+            }
+        }
+    }
+    function getClient(options = {}) {
+        let capturedOptions;
+        try {
+            capturedOptions = captureClientOptions(options);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        if (disconnecting) {
+            return disconnecting.then(() => getClient(capturedOptions));
+        }
+        if (orphanedClients.size > 0) {
+            return disconnect().then(() => getClient(capturedOptions));
+        }
+        let resolved;
+        try {
+            resolved = resolveClientOptions(capturedOptions, readEnv);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        sweepExpiredFailures();
+        let state = states.get(resolved.key);
+        if (state?.client && state.client.isOpen !== false && state.failedAt === undefined) {
+            return Promise.resolve(state.client);
+        }
+        if (state?.connecting)
+            return state.connecting;
+        if (state?.failedAt !== undefined && now() - state.failedAt < RECONNECT_DELAY_MS) {
+            return Promise.reject(INITIALIZATION_ERROR.create({
+                detail: "[Redis] Connection recently failed, waiting before retry",
+            }));
+        }
+        if (!state) {
+            state = { generation: 0 };
+            states.set(resolved.key, state);
+        }
+        const connectionState = state;
+        const stale = connectionState.client;
+        connectionState.client = undefined;
+        const attemptGeneration = ++connectionState.generation;
+        const attemptDisconnectVersion = disconnectVersion;
+        const cancellationError = connectionCancelledError();
+        let cancelled = false;
+        let rejectCancellation;
+        const cancellation = new Promise((_resolve, reject) => {
+            rejectCancellation = reject;
+        });
+        connectionState.cancelConnecting = () => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            rejectCancellation?.(cancellationError);
+        };
+        const trackedPromise = (async () => {
+            if (stale) {
+                connectionState.provisionalClient = stale;
+                try {
+                    await Promise.race([disconnectTrackedClient(stale), cancellation]);
+                }
+                finally {
+                    if (connectionState.provisionalClient === stale) {
+                        connectionState.provisionalClient = undefined;
+                    }
+                }
+            }
+            const factory = await Promise.race([loadFactory(), cancellation]);
+            if (states.get(resolved.key) !== connectionState ||
+                connectionState.generation !== attemptGeneration ||
+                disconnectVersion !== attemptDisconnectVersion) {
+                throw connectionCancelledError();
+            }
+            const client = factory(resolved.factoryOptions);
+            connectionState.provisionalClient = client;
+            if (typeof client.on === "function") {
+                client.on("error", (error) => {
+                    if (states.get(resolved.key) !== connectionState ||
+                        connectionState.client !== client ||
+                        connectionState.generation !== attemptGeneration)
+                        return;
+                    logger.error("Client error", error);
+                    connectionState.failedAt = now();
+                });
+                client.on("reconnecting", () => {
+                    if (states.get(resolved.key) === connectionState &&
+                        connectionState.client === client &&
+                        connectionState.generation === attemptGeneration)
+                        logger.info("Reconnecting...");
+                });
+                client.on("ready", () => {
+                    if (states.get(resolved.key) !== connectionState ||
+                        connectionState.client !== client ||
+                        connectionState.generation !== attemptGeneration)
+                        return;
+                    logger.info("Ready");
+                    connectionState.failedAt = undefined;
+                });
+            }
+            const connectAttempt = Promise.resolve().then(() => client.connect());
+            let connectSettled = false;
+            void connectAttempt.then(() => {
+                connectSettled = true;
+            }, () => {
+                connectSettled = true;
+            });
+            try {
+                await Promise.race([connectAttempt, cancellation]);
+            }
+            catch (error) {
+                const immediateCleanup = disconnectTrackedClient(client);
+                if (!connectSettled) {
+                    void connectAttempt.then(async () => {
+                        await immediateCleanup.catch(() => undefined);
+                        await disconnectTrackedClient(client);
+                    }, async () => {
+                        await immediateCleanup.catch(() => undefined);
+                        await disconnectTrackedClient(client);
+                    }).catch((lateCleanupError) => {
+                        logCleanupFailure("Redis manager late-connect cleanup failed", lateCleanupError);
+                    });
+                }
+                try {
+                    await immediateCleanup;
+                }
+                catch (closeError) {
+                    throw new AggregateError([error, closeError], "Redis client connection and cleanup failed");
+                }
+                if (connectionState.provisionalClient === client) {
+                    connectionState.provisionalClient = undefined;
+                }
+                throw error;
+            }
+            if (states.get(resolved.key) !== connectionState ||
+                connectionState.generation !== attemptGeneration ||
+                disconnectVersion !== attemptDisconnectVersion) {
+                try {
+                    await disconnectTrackedClient(client);
+                }
+                catch (closeError) {
+                    throw new AggregateError([connectionCancelledError(), closeError], "Redis client cancellation cleanup failed");
+                }
+                if (connectionState.provisionalClient === client) {
+                    connectionState.provisionalClient = undefined;
+                }
+                throw connectionCancelledError();
+            }
+            connectionState.provisionalClient = undefined;
+            connectionState.client = client;
+            connectionState.failedAt = undefined;
+            logger.info("Connected successfully");
+            return client;
+        })()
+            .catch((error) => {
+            if (states.get(resolved.key) === connectionState &&
+                connectionState.generation === attemptGeneration) {
+                connectionState.failedAt = now();
+                connectionState.client = undefined;
+            }
+            throw error;
+        })
+            .finally(() => {
+            if (connectionState.connecting === trackedPromise) {
+                connectionState.connecting = undefined;
+                connectionState.cancelConnecting = undefined;
+            }
+        });
+        connectionState.connecting = trackedPromise;
+        return trackedPromise;
+    }
+    function disconnect() {
+        if (disconnecting)
+            return disconnecting;
+        disconnectVersion++;
+        const clients = new Set();
+        for (const client of orphanedClients)
+            clients.add(client);
+        for (const state of states.values()) {
+            state.generation++;
+            state.cancelConnecting?.();
+            if (state.client)
+                clients.add(state.client);
+            if (state.provisionalClient)
+                clients.add(state.provisionalClient);
+            state.client = undefined;
+            state.provisionalClient = undefined;
+        }
+        states.clear();
+        const pending = Promise.allSettled([...clients].map(disconnectTrackedClient)).then((results) => {
+            const failures = results
+                .filter((result) => result.status === "rejected")
+                .map((result) => result.reason);
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1) {
+                throw new AggregateError(failures, "Redis client manager disconnect failed");
+            }
+        });
+        const tracked = pending.finally(() => {
+            if (disconnecting === tracked)
+                disconnecting = null;
+        });
+        disconnecting = tracked;
+        return tracked;
+    }
+    return { getClient, disconnect };
+}

package/esm/redis-runtime-provider.d.ts

@@ -0,0 +1,9 @@
+import type { RedisClient, RedisClientOptions, RedisRuntimeProvider } from "veryfront/extensions/distributed";
+import { type RedisClientManagerDependencies, type RedisClientOpenLifecycle } from "./redis-client-manager.js";
+export interface RedisRuntimeProviderDependencies {
+    clientManagerDependencies?: RedisClientManagerDependencies;
+    openClient?: (options?: RedisClientOptions, lifecycle?: RedisClientOpenLifecycle) => Promise<RedisClient>;
+}
+/** Construct an isolated Redis runtime provider. */
+export declare function createRedisRuntimeProvider(dependencies?: RedisRuntimeProviderDependencies): RedisRuntimeProvider;
+//# sourceMappingURL=redis-runtime-provider.d.ts.map

package/esm/redis-runtime-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-runtime-provider.d.ts","sourceRoot":"","sources":["../src/redis-runtime-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,WAAW,EAEX,kBAAkB,EAGlB,oBAAoB,EACrB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAGL,KAAK,8BAA8B,EACnC,KAAK,wBAAwB,EAE9B,MAAM,2BAA2B,CAAC;AAoHnC,MAAM,WAAW,gCAAgC;IAC/C,yBAAyB,CAAC,EAAE,8BAA8B,CAAC;IAC3D,UAAU,CAAC,EAAE,CACX,OAAO,CAAC,EAAE,kBAAkB,EAC5B,SAAS,CAAC,EAAE,wBAAwB,KACjC,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,oDAAoD;AACpD,wBAAgB,0BAA0B,CACxC,YAAY,GAAE,gCAAqC,GAClD,oBAAoB,CA2NtB"}