@veryfront/ext-redis 0.1.1185 → 0.1.1189

package/esm/render-cache-store.js

@@ -0,0 +1,191 @@
+import { rendererLogger } from "veryfront/utils/logger";
+import { escapeCacheGlobLiteral, parseSerializedCachePayload, registerRenderDistributedCacheNamespace, requirePositiveIntegerCacheTtlSeconds, serializeCachePayload, } from "veryfront/extensions/distributed/cache-support";
+import { createRedisClientManager, } from "./redis-client-manager.js";
+const logger = rendererLogger.component("redis");
+/** Default TTL for Redis cache entries (1 hour) */
+const DEFAULT_TTL_SECONDS = 3_600;
+/** Number of keys to scan per Redis SCAN iteration */
+const REDIS_SCAN_COUNT = 100;
+/** Maximum keys passed to one DEL command. */
+const REDIS_DELETE_BATCH_SIZE = 100;
+/** Defensive bounds for untrusted/proxied SCAN implementations. */
+const REDIS_MAX_SCAN_ITERATIONS = 1_000_000;
+const REDIS_MAX_COLLECTED_KEYS = 100_000;
+export class RedisCacheStore {
+    connectionOptions;
+    keyPrefix;
+    ttlSeconds;
+    clientManager;
+    constructor(options = {}) {
+        this.connectionOptions = Object.freeze({
+            url: options.url,
+            connectTimeout: options.connectTimeoutMs,
+        });
+        this.keyPrefix = registerRenderDistributedCacheNamespace(options.keyPrefix ?? "vf:cache:render:");
+        this.clientManager = options.clientManager ?? createRedisClientManager();
+        this.ttlSeconds = requirePositiveIntegerCacheTtlSeconds(options.ttlSeconds ?? DEFAULT_TTL_SECONDS);
+    }
+    async ensureClient() {
+        return await this.clientManager.getClient(this.connectionOptions);
+    }
+    storageKey(key) {
+        return `${this.keyPrefix}${key}`;
+    }
+    async resetRedisConnection() {
+        await this.clientManager.disconnect();
+    }
+    async resetAfterFailure(error) {
+        try {
+            await this.resetRedisConnection();
+        }
+        catch (disconnectError) {
+            logger.warn("failed to reset Redis connection", { error, disconnectError });
+        }
+    }
+    async scanKeys(client, literalPrefix) {
+        let cursor = 0;
+        let iterations = 0;
+        const seenCursors = new Set();
+        const keys = new Set();
+        do {
+            iterations++;
+            if (iterations > REDIS_MAX_SCAN_ITERATIONS) {
+                throw new Error("Redis SCAN exceeded the maximum iteration count");
+            }
+            const result = await client.scan(cursor, {
+                MATCH: `${escapeCacheGlobLiteral(literalPrefix)}*`,
+                COUNT: REDIS_SCAN_COUNT,
+            });
+            if (!result ||
+                !Number.isSafeInteger(result.cursor) ||
+                result.cursor < 0 ||
+                !Array.isArray(result.keys) ||
+                !result.keys.every((key) => typeof key === "string")) {
+                throw new TypeError("Redis returned an invalid SCAN result");
+            }
+            if (result.cursor !== 0 && seenCursors.has(result.cursor)) {
+                throw new Error("Redis SCAN repeated a cursor before completing");
+            }
+            if (result.cursor !== 0)
+                seenCursors.add(result.cursor);
+            for (const key of result.keys) {
+                if (!key.startsWith(literalPrefix)) {
+                    throw new Error("Redis SCAN returned a key outside the requested cache namespace");
+                }
+                keys.add(key);
+                if (keys.size > REDIS_MAX_COLLECTED_KEYS) {
+                    throw new Error("Redis SCAN exceeded the maximum collected key count");
+                }
+            }
+            cursor = result.cursor;
+        } while (cursor !== 0);
+        return [...keys];
+    }
+    resolveRetentionTtlSeconds(value, now = Date.now()) {
+        const retainUntil = value.staleUntil ?? value.expiresAt;
+        if (retainUntil === undefined)
+            return this.ttlSeconds;
+        const remainingSeconds = Math.ceil((retainUntil - now) / 1_000);
+        if (remainingSeconds <= 0) {
+            throw new RangeError("Redis render cache payload retention has already expired");
+        }
+        return requirePositiveIntegerCacheTtlSeconds(Math.max(this.ttlSeconds, remainingSeconds));
+    }
+    async deleteKeys(client, keys) {
+        let deleted = 0;
+        for (let index = 0; index < keys.length; index += REDIS_DELETE_BATCH_SIZE) {
+            const batch = keys.slice(index, index + REDIS_DELETE_BATCH_SIZE);
+            const count = await client.del(batch);
+            if (!Number.isSafeInteger(count) || count < 0 || count > batch.length) {
+                throw new TypeError("Redis returned an invalid DEL count");
+            }
+            deleted += count;
+        }
+        return deleted;
+    }
+    async deleteRedisKey(client, key) {
+        const count = await client.del(key);
+        if (!Number.isSafeInteger(count) || count < 0 || count > 1) {
+            throw new TypeError("Redis returned an invalid DEL count");
+        }
+    }
+    async get(key) {
+        try {
+            const client = await this.ensureClient();
+            const raw = await client.get(this.storageKey(key));
+            if (!raw)
+                return undefined;
+            const payload = parseSerializedCachePayload(raw);
+            if (payload)
+                return payload;
+            await this.deleteRedisKey(client, this.storageKey(key));
+            return undefined;
+        }
+        catch (error) {
+            await this.resetAfterFailure(error);
+            logger.warn("get failed", { key, error });
+            throw error;
+        }
+    }
+    async set(key, value) {
+        const serialized = serializeCachePayload(value);
+        const retainUntil = value.staleUntil ?? value.expiresAt;
+        if (retainUntil !== undefined && retainUntil <= Date.now()) {
+            await this.delete(key);
+            return;
+        }
+        try {
+            const client = await this.ensureClient();
+            // Apply TTL to prevent unbounded Redis growth
+            const result = await client.set(this.storageKey(key), serialized, {
+                EX: this.resolveRetentionTtlSeconds(value),
+            });
+            if (result !== "OK")
+                throw new Error("Redis SET did not acknowledge the write");
+        }
+        catch (error) {
+            await this.resetAfterFailure(error);
+            logger.warn("set failed", { key, error });
+            throw error;
+        }
+    }
+    async delete(key) {
+        try {
+            const client = await this.ensureClient();
+            await this.deleteRedisKey(client, this.storageKey(key));
+        }
+        catch (error) {
+            await this.resetAfterFailure(error);
+            logger.warn("delete failed; Redis invalidation is incomplete", { key, error });
+            throw error;
+        }
+    }
+    async deleteByPrefix(prefix) {
+        try {
+            const client = await this.ensureClient();
+            const keysToDelete = await this.scanKeys(client, `${this.keyPrefix}${prefix}`);
+            const deleted = await this.deleteKeys(client, keysToDelete);
+            return deleted;
+        }
+        catch (error) {
+            await this.resetAfterFailure(error);
+            logger.warn("deleteByPrefix failed; Redis invalidation is incomplete", { prefix, error });
+            throw error;
+        }
+    }
+    async clear() {
+        try {
+            const client = await this.ensureClient();
+            const keys = await this.scanKeys(client, this.keyPrefix);
+            await this.deleteKeys(client, keys);
+        }
+        catch (error) {
+            await this.resetAfterFailure(error);
+            logger.warn("clear failed; Redis invalidation is incomplete", { error });
+            throw error;
+        }
+    }
+    async destroy() {
+        await this.clientManager.disconnect();
+    }
+}

package/esm/revisioned-cache-record.d.ts

@@ -0,0 +1,18 @@
+import { type CacheRevisionSnapshot } from "veryfront/extensions/distributed/cache-support";
+export type RedisRevisionedCacheRecord = Readonly<{
+    kind: "present";
+    revision: string;
+    value: string;
+}> | Readonly<{
+    kind: "absent";
+    revision: string;
+}>;
+/** Test whether a raw Redis string starts with the versioned CAS frame. */
+export declare function hasRevisionedCacheRecordPrefix(value: unknown): value is string;
+/** Decode one strict revisioned Redis STRING without altering its payload. */
+export declare function parseRevisionedCacheRecord(value: unknown): RedisRevisionedCacheRecord;
+/** Parse the exact two Redis Lua read result variants. */
+export declare function parseRedisRevisionReadResult(value: unknown): CacheRevisionSnapshot;
+/** Parse the exact Redis integer result used by compare-exchange. */
+export declare function parseRedisRevisionExchangeResult(value: unknown): boolean;
+//# sourceMappingURL=revisioned-cache-record.d.ts.map

package/esm/revisioned-cache-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revisioned-cache-record.d.ts","sourceRoot":"","sources":["../src/revisioned-cache-record.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,gDAAgD,CAAC;AAKxD,MAAM,MAAM,0BAA0B,GAClC,QAAQ,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9D,QAAQ,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAenD,2EAA2E;AAC3E,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9E;AAED,8EAA8E;AAC9E,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAyBrF;AAED,0DAA0D;AAC1D,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAiBlF;AAED,qEAAqE;AACrE,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKxE"}

package/esm/revisioned-cache-record.js

@@ -0,0 +1,68 @@
+import { requireCacheExchangeResult, snapshotCacheRevisionResult, } from "veryfront/extensions/distributed/cache-support";
+const RECORD_PREFIX = "\0VFCAS1\0";
+const MAX_SIGNED_REDIS_INTEGER = "9223372036854775807";
+function requireCanonicalRevision(value) {
+    if (typeof value !== "string" ||
+        !/^[1-9]\d*$/.test(value) ||
+        value.length > MAX_SIGNED_REDIS_INTEGER.length ||
+        (value.length === MAX_SIGNED_REDIS_INTEGER.length &&
+            value > MAX_SIGNED_REDIS_INTEGER)) {
+        throw new TypeError("Redis cache revision must be a canonical positive signed 64-bit integer");
+    }
+    return value;
+}
+/** Test whether a raw Redis string starts with the versioned CAS frame. */
+export function hasRevisionedCacheRecordPrefix(value) {
+    return typeof value === "string" && value.startsWith(RECORD_PREFIX);
+}
+/** Decode one strict revisioned Redis STRING without altering its payload. */
+export function parseRevisionedCacheRecord(value) {
+    if (!hasRevisionedCacheRecordPrefix(value)) {
+        throw new TypeError("Redis revisioned cache record has invalid framing");
+    }
+    const stateIndex = RECORD_PREFIX.length;
+    const state = value[stateIndex];
+    if ((state !== "p" && state !== "a") || value[stateIndex + 1] !== "\0") {
+        throw new TypeError("Redis revisioned cache record has invalid state framing");
+    }
+    const revisionStart = stateIndex + 2;
+    const revisionEnd = value.indexOf("\0", revisionStart);
+    if (revisionEnd < 0) {
+        throw new TypeError("Redis revisioned cache record is missing its revision delimiter");
+    }
+    const revision = requireCanonicalRevision(value.slice(revisionStart, revisionEnd));
+    const payload = value.slice(revisionEnd + 1);
+    if (state === "a") {
+        if (payload.length !== 0) {
+            throw new TypeError("Redis absent revisioned cache record must not contain a payload");
+        }
+        return Object.freeze({ kind: "absent", revision });
+    }
+    return Object.freeze({ kind: "present", revision, value: payload });
+}
+/** Parse the exact two Redis Lua read result variants. */
+export function parseRedisRevisionReadResult(value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError("Redis revision read result must be an array");
+    }
+    if (value.length === 2 && value[0] === 0) {
+        return snapshotCacheRevisionResult({
+            value: null,
+            revision: requireCanonicalRevision(value[1]),
+        });
+    }
+    if (value.length === 3 && value[0] === 1 && typeof value[2] === "string") {
+        return snapshotCacheRevisionResult({
+            value: value[2],
+            revision: requireCanonicalRevision(value[1]),
+        });
+    }
+    throw new TypeError("Redis revision read result has an invalid shape");
+}
+/** Parse the exact Redis integer result used by compare-exchange. */
+export function parseRedisRevisionExchangeResult(value) {
+    if (value !== 0 && value !== 1) {
+        throw new TypeError("Redis revision exchange result must be integer zero or one");
+    }
+    return requireCacheExchangeResult(value === 1);
+}

package/esm/routing-invalidation-bus.d.ts

@@ -0,0 +1,33 @@
+import type { ProxyRoutingInvalidationEvent, ProxyRoutingInvalidationPublisher } from "veryfront/extensions/distributed/routing-invalidation-support";
+type RedisListener = (message: string, channel: string) => void;
+export interface RoutingInvalidationRedisClient {
+    connect(): Promise<void>;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, listener: RedisListener): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    close(): Promise<void>;
+    destroy(): void;
+    on?(event: "error", listener: (error: unknown) => void): unknown;
+}
+interface RoutingInvalidationLogger {
+    info(message: string, extra?: Record<string, unknown>): void;
+    warn(message: string, extra?: Record<string, unknown>): void;
+    error(message: string, error?: unknown, extra?: Record<string, unknown>): void;
+}
+export interface ProxyRoutingInvalidationBus extends ProxyRoutingInvalidationPublisher {
+    close(): Promise<void>;
+}
+interface StartProxyRoutingInvalidationBusOptions {
+    acknowledgementTimeoutMs?: number;
+    createClient?: (redisUrl: string) => RoutingInvalidationRedisClient | Promise<RoutingInvalidationRedisClient>;
+    expectedReplicas?: number;
+    now?: () => number;
+    logger?: RoutingInvalidationLogger;
+    onInvalidate: (event: ProxyRoutingInvalidationEvent) => unknown | Promise<unknown>;
+    integritySecret?: string;
+    redisUrl?: string;
+    replicaId?: string;
+}
+export declare function startProxyRoutingInvalidationBus(options: StartProxyRoutingInvalidationBusOptions): Promise<ProxyRoutingInvalidationBus | null>;
+export {};
+//# sourceMappingURL=routing-invalidation-bus.d.ts.map

package/esm/routing-invalidation-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-invalidation-bus.d.ts","sourceRoot":"","sources":["../src/routing-invalidation-bus.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,6BAA6B,EAC7B,iCAAiC,EAElC,MAAM,+DAA+D,CAAC;AAgCvE,KAAK,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAGhE,MAAM,WAAW,8BAA8B;IAC7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3D,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;IAChB,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC;CAClE;AAED,UAAU,yBAAyB;IACjC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAChF;AAED,MAAM,WAAW,2BAA4B,SAAQ,iCAAiC;IACpF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,UAAU,uCAAuC;IAC/C,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,yBAAyB,CAAC;IACnC,YAAY,EAAE,CAAC,KAAK,EAAE,6BAA6B,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwiBD,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC,CAmY7C"}