@veryfront/ext-redis 0.1.1185

package/esm/event-publisher.js

@@ -0,0 +1,356 @@
+import { logger as baseLogger } from "veryfront/utils/logger";
+import { requireRedisUrl } from "./connection-config.js";
+const logger = baseLogger.component("redis-event-publisher");
+const CONFIG_KEYS = new Set(["url", "channelPrefix", "debug"]);
+const MAX_CHANNEL_PREFIX_CODE_UNITS = 1_024;
+function readOwnDataProperty(value, key) {
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(value, key);
+    }
+    catch (cause) {
+        throw new TypeError(`Redis event publisher config ${key} could not be inspected`, { cause });
+    }
+    if (!descriptor)
+        return undefined;
+    if (!("value" in descriptor)) {
+        throw new TypeError(`Redis event publisher config ${key} must be a data property`);
+    }
+    return descriptor.value;
+}
+function captureConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("Redis event publisher config must be an object");
+    }
+    let prototype;
+    let keys;
+    try {
+        prototype = Object.getPrototypeOf(value);
+        keys = Reflect.ownKeys(value);
+    }
+    catch (cause) {
+        throw new TypeError("Redis event publisher config could not be inspected", { cause });
+    }
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError("Redis event publisher config must be a plain object");
+    }
+    if (keys.some((key) => typeof key !== "string" || !CONFIG_KEYS.has(key))) {
+        throw new TypeError("Redis event publisher config contains an unknown option");
+    }
+    const url = requireRedisUrl(readOwnDataProperty(value, "url"));
+    const channelPrefixValue = readOwnDataProperty(value, "channelPrefix");
+    const channelPrefix = channelPrefixValue ?? "claude-code";
+    if (typeof channelPrefix !== "string" || channelPrefix.length === 0 ||
+        channelPrefix.length > MAX_CHANNEL_PREFIX_CODE_UNITS ||
+        channelPrefix.trim() !== channelPrefix || /\p{Cc}/u.test(channelPrefix)) {
+        throw new TypeError("Redis event publisher channelPrefix must be a bounded canonical string");
+    }
+    const debugValue = readOwnDataProperty(value, "debug");
+    if (debugValue !== undefined && typeof debugValue !== "boolean") {
+        throw new TypeError("Redis event publisher debug must be a boolean");
+    }
+    return Object.freeze({ url, channelPrefix, debug: debugValue ?? false });
+}
+function safeLogInfo(target, message, ...args) {
+    try {
+        target.info(message, ...args);
+    }
+    catch {
+        // Diagnostics must not own transport lifecycle.
+    }
+}
+function safeLogError(target, message, ...args) {
+    try {
+        target.error(message, ...args);
+    }
+    catch {
+        // Diagnostics must not own transport lifecycle.
+    }
+}
+function publisherClosedError(state) {
+    return new Error(`Redis event publisher is ${state}`);
+}
+function raceWithAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+class InternalRedisEventPublisher {
+    config;
+    createClient;
+    diagnosticLogger;
+    resources = new Set();
+    closeAttempts = new Map();
+    retirements = new Set();
+    clients = null;
+    initialization = null;
+    initializationAbortController = null;
+    closePromise = null;
+    state = "open";
+    constructor(config, createClient, diagnosticLogger) {
+        this.config = config;
+        this.createClient = createClient;
+        this.diagnosticLogger = diagnosticLogger;
+    }
+    registerErrorListener(client, role) {
+        client.on("error", (error) => {
+            safeLogError(this.diagnosticLogger, "Redis event publisher client error", error, { role });
+        });
+    }
+    createClientPair() {
+        const publishClient = this.createClient(this.config.url);
+        this.resources.add(publishClient);
+        this.registerErrorListener(publishClient, "publish");
+        const subscribeClient = this.createClient(this.config.url);
+        if (subscribeClient === publishClient) {
+            throw new TypeError("Redis event publisher requires distinct publish and subscribe clients");
+        }
+        this.resources.add(subscribeClient);
+        this.registerErrorListener(subscribeClient, "subscribe");
+        return Object.freeze({ publish: publishClient, subscribe: subscribeClient });
+    }
+    ensureInitialized() {
+        if (this.state !== "open")
+            return Promise.reject(publisherClosedError(this.state));
+        if (this.clients)
+            return Promise.resolve(this.clients);
+        if (this.initialization)
+            return this.initialization;
+        const abortController = new AbortController();
+        this.initializationAbortController = abortController;
+        const initialization = (async () => {
+            let clients;
+            let connectAttempts = [];
+            try {
+                // A failed prior setup must be fully retired before replacement.
+                await raceWithAbort(this.waitForRetirements(), abortController.signal);
+                await raceWithAbort(this.closeClients([...this.resources]), abortController.signal);
+                if (this.state !== "open")
+                    throw publisherClosedError(this.state);
+                const nextClients = this.createClientPair();
+                clients = nextClients;
+                connectAttempts = [
+                    this.startConnect(nextClients.publish),
+                    this.startConnect(nextClients.subscribe),
+                ];
+                await raceWithAbort(Promise.all(connectAttempts.map(({ promise }) => promise)).then(() => undefined), abortController.signal);
+                if (this.state !== "open")
+                    throw publisherClosedError(this.state);
+            }
+            catch (error) {
+                const cleanupTargets = clients ? [clients.publish, clients.subscribe] : [...this.resources];
+                const immediateCleanup = this.closeClients(cleanupTargets);
+                for (const attempt of connectAttempts) {
+                    if (!attempt.settled)
+                        this.scheduleFinalClose(attempt, immediateCleanup);
+                }
+                try {
+                    await immediateCleanup;
+                }
+                catch (closeError) {
+                    throw new AggregateError([error, closeError], "Redis event publisher setup and cleanup failed");
+                }
+                throw error;
+            }
+            if (!clients)
+                throw new Error("Redis event publisher clients were not initialized");
+            this.clients = clients;
+            return clients;
+        })().finally(() => {
+            if (this.initialization === initialization)
+                this.initialization = null;
+            if (this.initializationAbortController === abortController) {
+                this.initializationAbortController = null;
+            }
+        });
+        this.initialization = initialization;
+        return initialization;
+    }
+    startConnect(client) {
+        const attempt = {
+            client,
+            promise: Promise.resolve().then(() => client.connect()),
+            settled: false,
+        };
+        void attempt.promise.then(() => {
+            attempt.settled = true;
+        }, () => {
+            attempt.settled = true;
+        });
+        return attempt;
+    }
+    waitForRetirements() {
+        return Promise.all([...this.retirements]).then(() => undefined);
+    }
+    scheduleFinalClose(attempt, immediateCleanup) {
+        const connectionSettled = attempt.promise.then(() => undefined, () => undefined);
+        const retirement = connectionSettled
+            .then(() => immediateCleanup.catch(() => undefined))
+            .then(() => this.closeClient(attempt.client, true));
+        const tracked = retirement.finally(() => {
+            this.retirements.delete(tracked);
+        });
+        this.retirements.add(tracked);
+        void tracked.catch((error) => {
+            safeLogError(this.diagnosticLogger, "Redis event publisher late-connect cleanup failed", error);
+        });
+    }
+    closeClient(client, force = false) {
+        if (force)
+            this.resources.add(client);
+        else if (!this.resources.has(client))
+            return Promise.resolve();
+        const existing = this.closeAttempts.get(client);
+        if (existing) {
+            if (!force)
+                return existing;
+            return existing.catch(() => undefined).then(() => this.closeClient(client, true));
+        }
+        const attempt = Promise.resolve()
+            .then(() => client.isOpen === false ? undefined : client.close())
+            .then(() => {
+            this.resources.delete(client);
+            if (this.clients?.publish === client || this.clients?.subscribe === client) {
+                this.clients = null;
+            }
+            this.closeAttempts.delete(client);
+        }, (error) => {
+            this.closeAttempts.delete(client);
+            throw error;
+        });
+        this.closeAttempts.set(client, attempt);
+        return attempt;
+    }
+    closeClients(clients) {
+        return Promise.all([...new Set(clients)].map((client) => this.closeClient(client))).then(() => undefined);
+    }
+    getChannel(runId) {
+        return `${this.config.channelPrefix}:events:${runId}`;
+    }
+    async publish(event) {
+        const clients = await this.ensureInitialized();
+        if (this.state !== "open")
+            throw publisherClosedError(this.state);
+        const channel = event.runId
+            ? this.getChannel(event.runId)
+            : `${this.config.channelPrefix}:events:global`;
+        await clients.publish.publish(channel, JSON.stringify(event));
+        if (this.config.debug) {
+            safeLogInfo(this.diagnosticLogger, "Published event", {
+                channel,
+                eventType: event.type,
+            });
+        }
+    }
+    async subscribe(runId, handler) {
+        const clients = await this.ensureInitialized();
+        if (this.state !== "open")
+            throw publisherClosedError(this.state);
+        const channel = this.getChannel(runId);
+        let deliveryActive = true;
+        const listener = (message) => {
+            if (!deliveryActive || this.state !== "open")
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(message);
+            }
+            catch (error) {
+                safeLogError(this.diagnosticLogger, "Failed to parse Redis event", error);
+                return;
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                return;
+            try {
+                const handled = handler(parsed);
+                void Promise.resolve(handled).catch((error) => {
+                    safeLogError(this.diagnosticLogger, "Redis event handler failed", error);
+                });
+            }
+            catch (error) {
+                safeLogError(this.diagnosticLogger, "Redis event handler failed", error);
+            }
+        };
+        await clients.subscribe.subscribe(channel, listener);
+        if (this.state !== "open") {
+            this.startBackgroundUnsubscribe(clients.subscribe, channel, listener);
+            throw publisherClosedError(this.state);
+        }
+        if (this.config.debug) {
+            safeLogInfo(this.diagnosticLogger, "Subscribed to channel", { channel });
+        }
+        let disposed = false;
+        let disposal = null;
+        return () => {
+            deliveryActive = false;
+            if (disposed || disposal || this.state === "closed")
+                return;
+            const attempt = Promise.resolve()
+                .then(async () => {
+                if (this.state === "closing" && this.closePromise)
+                    return false;
+                await clients.subscribe.unsubscribe(channel, listener);
+                return true;
+            })
+                .then((unsubscribed) => {
+                if (unsubscribed)
+                    disposed = true;
+                else if (disposal === attempt)
+                    disposal = null;
+            }, (error) => {
+                if (disposal === attempt)
+                    disposal = null;
+                safeLogError(this.diagnosticLogger, "Failed to unsubscribe Redis event listener", error, { channel });
+            });
+            disposal = attempt;
+        };
+    }
+    startBackgroundUnsubscribe(client, channel, listener) {
+        void Promise.resolve()
+            .then(() => client.unsubscribe(channel, listener))
+            .catch((error) => {
+            safeLogError(this.diagnosticLogger, "Failed to unsubscribe Redis event listener", error, { channel });
+        });
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        if (this.state === "closed" && this.resources.size === 0)
+            return Promise.resolve();
+        this.state = "closing";
+        this.initializationAbortController?.abort(publisherClosedError("closing"));
+        const closePromise = this.closeClients([...this.resources]).then(() => {
+            this.state = "closed";
+        }, (error) => {
+            throw error;
+        }).finally(() => {
+            if (this.closePromise === closePromise)
+                this.closePromise = null;
+        });
+        this.closePromise = closePromise;
+        return closePromise;
+    }
+}
+/** Construct a validated Redis Pub/Sub implementation. */
+export function createRedisEventPublisher(config, dependencies) {
+    if (typeof dependencies.createClient !== "function") {
+        throw new TypeError("Redis event publisher client factory must be a function");
+    }
+    const diagnosticLogger = dependencies.logger ?? logger;
+    if (!diagnosticLogger || typeof diagnosticLogger !== "object" ||
+        typeof diagnosticLogger.info !== "function" ||
+        typeof diagnosticLogger.error !== "function") {
+        throw new TypeError("Redis event publisher logger is invalid");
+    }
+    return new InternalRedisEventPublisher(captureConfig(config), dependencies.createClient, diagnosticLogger);
+}

package/esm/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ext-redis: third-party Redis runtime implementation for Veryfront.
+ *
+ * @module extensions/ext-redis
+ */
+import type { ExtensionFactory } from "veryfront/extensions/types";
+declare const extRedis: ExtensionFactory;
+export default extRedis;
+export { createRedisRuntimeProvider } from "./redis-runtime-provider.js";
+export type { RedisClient, RedisClientOptions, RedisEventPublisherConfig, RedisEventPublisherImplementation, RedisRuntimeProvider, } from "veryfront/extensions/distributed";
+//# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAOnE,QAAA,MAAM,QAAQ,EAAE,gBAqCf,CAAC;AAEF,eAAe,QAAQ,CAAC;AACxB,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,yBAAyB,EACzB,iCAAiC,EACjC,oBAAoB,GACrB,MAAM,kCAAkC,CAAC"}

package/esm/index.js

@@ -0,0 +1,51 @@
+/**
+ * ext-redis: third-party Redis runtime implementation for Veryfront.
+ *
+ * @module extensions/ext-redis
+ */
+import { RedisRuntimeProviderName, } from "veryfront/extensions/distributed";
+import { createRedisRuntimeProvider } from "./redis-runtime-provider.js";
+const extRedis = () => {
+    let provider;
+    return {
+        name: "ext-redis",
+        version: "0.1.0",
+        contracts: { provides: [RedisRuntimeProviderName] },
+        capabilities: [
+            { type: "net:outbound", hosts: ["*"] },
+            {
+                type: "env:read",
+                keys: ["NODE_ENV", "REDIS_PASSWORD", "REDIS_URL", "REDIS_USERNAME"],
+            },
+        ],
+        async setup(ctx) {
+            if (provider)
+                throw new Error("ext-redis is already active");
+            const nextProvider = createRedisRuntimeProvider();
+            try {
+                ctx.provide(RedisRuntimeProviderName, nextProvider);
+            }
+            catch (error) {
+                await nextProvider.close();
+                throw error;
+            }
+            provider = nextProvider;
+            try {
+                ctx.logger.info(`[ext-redis] ${RedisRuntimeProviderName} registered`);
+            }
+            catch {
+                // Diagnostics must not invalidate a successfully registered provider.
+            }
+        },
+        async teardown() {
+            if (!provider)
+                return;
+            const retiring = provider;
+            await retiring.close();
+            if (provider === retiring)
+                provider = undefined;
+        },
+    };
+};
+export default extRedis;
+export { createRedisRuntimeProvider } from "./redis-runtime-provider.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/redis-client-manager.d.ts

@@ -0,0 +1,33 @@
+import type { RedisClient, RedisClientOptions } from "veryfront/extensions/distributed";
+/** Minimal `@redis/client` factory options used by this extension. */
+export interface RedisClientFactoryOptions {
+    url?: string;
+    socket?: {
+        tls?: boolean;
+        connectTimeout?: number;
+        reconnectStrategy?: false;
+    };
+    password?: string;
+    username?: string;
+}
+export type RedisClientFactory = (options: RedisClientFactoryOptions) => RedisClient;
+export interface RedisClientManagerDependencies {
+    getEnv?: (key: string) => string | undefined;
+    loadFactory?: () => Promise<RedisClientFactory>;
+    now?: () => number;
+}
+export interface RedisClientOpenLifecycle {
+    signal?: AbortSignal;
+    onClientCreated?(client: RedisClient): (() => Promise<void>) | void;
+}
+export interface RedisClientManager {
+    getClient(options?: RedisClientOptions): Promise<RedisClient>;
+    disconnect(): Promise<void>;
+}
+/** Internal handoff of a provisional client that still requires cleanup. */
+export declare function takeRedisClientSetupCleanupClient(error: unknown): RedisClient | undefined;
+/** Open one independently owned Redis connection. */
+export declare function openRedisClient(options?: RedisClientOptions, dependencies?: RedisClientManagerDependencies, lifecycle?: RedisClientOpenLifecycle): Promise<RedisClient>;
+/** Create an isolated, concurrency-safe Redis client manager. */
+export declare function createRedisClientManager(dependencies?: RedisClientManagerDependencies): RedisClientManager;
+//# sourceMappingURL=redis-client-manager.d.ts.map

package/esm/redis-client-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-client-manager.d.ts","sourceRoot":"","sources":["../src/redis-client-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAyBxF,sEAAsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE;QACP,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,iBAAiB,CAAC,EAAE,KAAK,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,yBAAyB,KAAK,WAAW,CAAC;AAErF,MAAM,WAAW,8BAA8B;IAC7C,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,eAAe,CAAC,CAAC,MAAM,EAAE,WAAW,GAAG,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;CACrE;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAeD,4EAA4E;AAC5E,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAKzF;AAuOD,qDAAqD;AACrD,wBAAsB,eAAe,CACnC,OAAO,GAAE,kBAAuB,EAChC,YAAY,GAAE,8BAAmC,EACjD,SAAS,GAAE,wBAA6B,GACvC,OAAO,CAAC,WAAW,CAAC,CA4DtB;AAOD,iEAAiE;AACjE,wBAAgB,wBAAwB,CACtC,YAAY,GAAE,8BAAmC,GAChD,kBAAkB,CA6QpB"}