@veryfront/ext-redis 0.1.1186 → 0.1.1190

package/README.md

@@ -32,6 +32,18 @@ Core Redis facades fail closed with an actionable install recommendation until
 extension orchestration registers the provider. Workspace and compiled-binary
 availability do not bypass that activation boundary.
 
+## Redis-backed infrastructure primitives
+
+The package also exports bounded Redis implementations for distributed cache,
+render-cache, rate-limit, routing-invalidation, and agent-memory composition.
+These primitives are explicit: constructing one does not activate Redis for
+unrelated framework features, and each owner must close or destroy the
+resource it creates.
+
+Durable workflow storage is intentionally not part of this release. It will be
+published after the provider-neutral workflow recovery contracts land, rather
+than coupling this package to unpublished core APIs.
+
 ## Configuration
 
 The shared client facade reads `REDIS_URL` when an explicit URL is not passed.

package/esm/_dnt.polyfills.d.ts

@@ -0,0 +1,12 @@
+declare global {
+    interface Object {
+        /**
+         * Determines whether an object has a property with the specified name.
+         * @param o An object.
+         * @param v A property name.
+         */
+        hasOwn(o: object, v: PropertyKey): boolean;
+    }
+}
+export {};
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/esm/_dnt.polyfills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAeA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd;;;;WAIG;QACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;KAC5C;CACF;AAED,OAAO,EAAE,CAAC"}

package/esm/_dnt.polyfills.js

@@ -0,0 +1,15 @@
+// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
+if (!Object.hasOwn) {
+    Object.defineProperty(Object, "hasOwn", {
+        value: function (object, property) {
+            if (object == null) {
+                throw new TypeError("Cannot convert undefined or null to object");
+            }
+            return Object.prototype.hasOwnProperty.call(Object(object), property);
+        },
+        configurable: true,
+        enumerable: false,
+        writable: true,
+    });
+}
+export {};

package/esm/_dnt.shims.d.ts

@@ -0,0 +1,11 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+export { crypto, type Crypto, type SubtleCrypto, type AlgorithmIdentifier, type Algorithm, type RsaOaepParams, type BufferSource, type AesCtrParams, type AesCbcParams, type AesGcmParams, type CryptoKey, type KeyAlgorithm, type KeyType, type KeyUsage, type EcdhKeyDeriveParams, type HkdfParams, type HashAlgorithmIdentifier, type Pbkdf2Params, type AesDerivedKeyParams, type HmacImportParams, type JsonWebKey, type RsaOtherPrimesInfo, type KeyFormat, type RsaHashedKeyGenParams, type RsaKeyGenParams, type BigInteger, type EcKeyGenParams, type NamedCurve, type CryptoKeyPair, type AesKeyGenParams, type HmacKeyGenParams, type RsaHashedImportParams, type EcKeyImportParams, type AesKeyAlgorithm, type RsaPssParams, type EcdsaParams } from "@deno/shim-crypto";
+export { setInterval, setTimeout } from "@deno/shim-timers";
+export declare const dntGlobalThis: Omit<typeof globalThis, "Deno" | "crypto" | "setInterval" | "setTimeout"> & {
+    Deno: typeof Deno;
+    crypto: import("@deno/shim-crypto").Crypto;
+    setInterval: any;
+    setTimeout: any;
+};
+//# sourceMappingURL=_dnt.shims.d.ts.map

package/esm/_dnt.shims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.shims.d.ts","sourceRoot":"","sources":["../src/_dnt.shims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,KAAK,uBAAuB,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,KAAK,UAAU,EAAE,KAAK,kBAAkB,EAAE,KAAK,SAAS,EAAE,KAAK,qBAAqB,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErvB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAQ5D,eAAO,MAAM,aAAa;;;;;CAA2C,CAAC"}

package/esm/_dnt.shims.js

@@ -0,0 +1,68 @@
+import { Deno } from "@deno/shim-deno";
+export { Deno } from "@deno/shim-deno";
+import { crypto } from "@deno/shim-crypto";
+export { crypto } from "@deno/shim-crypto";
+import { setInterval, setTimeout } from "@deno/shim-timers";
+export { setInterval, setTimeout } from "@deno/shim-timers";
+const dntGlobals = {
+    Deno,
+    crypto,
+    setInterval,
+    setTimeout,
+};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/esm/agent-memory.d.ts

@@ -0,0 +1,60 @@
+/****
+ * Redis Memory Backend
+ *
+ * Distributed memory implementation using Redis for multi-process deployments.
+ * Enables conversation persistence across server restarts and horizontal scaling.
+ */
+import { type Memory, type MemoryConfigBase, type MemoryStats, type MinimalMessage } from "veryfront/extensions/distributed/agent-memory-support";
+/**
+ * Redis client interface (compatible with ioredis and node-redis)
+ */
+export interface RedisEvalOptions {
+    keys: string[];
+    arguments: string[];
+}
+export interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        EX?: number;
+    }): Promise<unknown>;
+    del(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    eval?(script: string, options: RedisEvalOptions): Promise<unknown>;
+    sendCommand?(args: string[]): Promise<unknown>;
+    call?(command: string, ...args: string[]): Promise<unknown>;
+}
+/**
+ * Redis memory configuration
+ */
+export interface RedisMemoryConfig extends MemoryConfigBase {
+    type: "redis";
+    /** Redis client instance */
+    client: RedisClient;
+    /** Key prefix for namespacing */
+    keyPrefix?: string;
+    /** User ID for per-user memory isolation */
+    userId?: string;
+    /** TTL in seconds (default: 24 hours) */
+    ttl?: number;
+}
+/** Implement redis memory. */
+export declare class RedisMemory<M extends MinimalMessage = MinimalMessage> implements Memory<M> {
+    private client;
+    private agentId;
+    private userId;
+    private keyPrefix;
+    private ttl;
+    private config;
+    constructor(agentId: string, config: RedisMemoryConfig);
+    private getKey;
+    private parseMessages;
+    add(message: M): Promise<void>;
+    getMessages(): Promise<M[]>;
+    clear(): Promise<void>;
+    getStats(): Promise<MemoryStats>;
+    touch(): Promise<void>;
+    private atomicAdd;
+}
+/** Create redis memory. */
+export declare function createRedisMemory<M extends MinimalMessage = MinimalMessage>(agentId: string, config: RedisMemoryConfig): RedisMemory<M>;
+//# sourceMappingURL=agent-memory.d.ts.map

package/esm/agent-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory.d.ts","sourceRoot":"","sources":["../src/agent-memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,cAAc,EACpB,MAAM,uDAAuD,CAAC;AAI/D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,WAAW,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,IAAI,EAAE,OAAO,CAAC;IACd,4BAA4B;IAC5B,MAAM,EAAE,WAAW,CAAC;IACpB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA4ED,8BAA8B;AAC9B,qBAAa,WAAW,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,YAAW,MAAM,CAAC,CAAC,CAAC;IACtF,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,MAAM,CAAoB;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB;IAStD,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,aAAa;IAgBrB,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9B,WAAW,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC;IAQ3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC;IAehC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAYtB,OAAO,CAAC,SAAS;CA2BlB;AAED,2BAA2B;AAC3B,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACzE,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,iBAAiB,GACxB,WAAW,CAAC,CAAC,CAAC,CAEhB"}

package/esm/agent-memory.js

@@ -0,0 +1,173 @@
+/****
+ * Redis Memory Backend
+ *
+ * Distributed memory implementation using Redis for multi-process deployments.
+ * Enables conversation persistence across server restarts and horizontal scaling.
+ */
+import { estimateTokens, } from "veryfront/extensions/distributed/agent-memory-support";
+import { withSpan } from "veryfront/observability/otlp-setup";
+import { agentLogger } from "veryfront/utils/logger";
+const DEFAULT_TTL = 86_400; // 24 hours
+const DEFAULT_KEY_PREFIX = "veryfront:agent:memory:";
+const ATOMIC_ADD_SCRIPT = `
+local key = KEYS[1]
+local message_json = ARGV[1]
+local max_messages = tonumber(ARGV[2]) or 0
+local max_tokens = tonumber(ARGV[3]) or 0
+local ttl = tonumber(ARGV[4]) or 0
+
+local function decode_json(value, label)
+  local ok, decoded = pcall(cjson.decode, value)
+  if not ok then
+    return nil, redis.error_reply("CORRUPT_REDIS_MEMORY_JSON:" .. label)
+  end
+  if type(decoded) ~= "table" then
+    return nil, redis.error_reply("CORRUPT_REDIS_MEMORY_JSON:" .. label)
+  end
+  return decoded, nil
+end
+
+local messages = {}
+local current = redis.call("GET", key)
+if current and current ~= "" then
+  local decoded, decode_error = decode_json(current, "stored")
+  if decode_error then return decode_error end
+  messages = decoded
+end
+
+local message, message_error = decode_json(message_json, "message")
+if message_error then return message_error end
+table.insert(messages, message)
+
+if max_messages > 0 then
+  while #messages > max_messages do
+    table.remove(messages, 1)
+  end
+end
+
+local function message_text_length(item)
+  if type(item) ~= "table" or type(item.parts) ~= "table" then return 0 end
+  local total = 0
+  for _, part in ipairs(item.parts) do
+    if type(part) == "table" and part.type == "text" and type(part.text) == "string" then
+      total = total + string.len(part.text)
+    end
+  end
+  return total
+end
+
+local function estimate_tokens(items)
+  local total = 0
+  for _, item in ipairs(items) do
+    total = total + message_text_length(item)
+  end
+  return math.ceil(total / 4)
+end
+
+if max_tokens > 0 then
+  while #messages > 1 and estimate_tokens(messages) > max_tokens do
+    table.remove(messages, 1)
+  end
+end
+
+local encoded = cjson.encode(messages)
+if ttl > 0 then
+  redis.call("SET", key, encoded, "EX", ttl)
+else
+  redis.call("SET", key, encoded)
+end
+
+return #messages
+`;
+/** Implement redis memory. */
+export class RedisMemory {
+    client;
+    agentId;
+    userId;
+    keyPrefix;
+    ttl;
+    config;
+    constructor(agentId, config) {
+        this.client = config.client;
+        this.agentId = agentId;
+        this.userId = config.userId ?? "anonymous";
+        this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
+        this.ttl = config.ttl ?? DEFAULT_TTL;
+        this.config = config;
+    }
+    getKey() {
+        return `${this.keyPrefix}${this.agentId.length}:${this.agentId}:${this.userId.length}:${this.userId}`;
+    }
+    parseMessages(data) {
+        if (!data)
+            return [];
+        try {
+            return JSON.parse(data);
+        }
+        catch (error) {
+            // Do NOT swallow-and-return []: add() would then overwrite the key with a
+            // single message and permanently destroy the stored history. Surface the
+            // corruption so the caller aborts instead of silently truncating.
+            agentLogger.error("Corrupted JSON in Redis memory; refusing to overwrite", {
+                errorName: error instanceof Error ? error.name : typeof error,
+                keyLength: this.getKey().length,
+            });
+            throw error;
+        }
+    }
+    add(message) {
+        return withSpan("agent.memory.redis.add", async () => {
+            const key = this.getKey();
+            await this.atomicAdd(key, message);
+        }, { "memory.type": "redis", "memory.agent_id": this.agentId, "memory.ttl": this.ttl });
+    }
+    getMessages() {
+        return withSpan("agent.memory.redis.getMessages", async () => this.parseMessages(await this.client.get(this.getKey())), { "memory.type": "redis", "memory.agent_id": this.agentId });
+    }
+    clear() {
+        return withSpan("agent.memory.redis.clear", async () => {
+            await this.client.del(this.getKey());
+        }, { "memory.type": "redis", "memory.agent_id": this.agentId });
+    }
+    getStats() {
+        return withSpan("agent.memory.redis.getStats", async () => {
+            const messages = await this.getMessages();
+            return {
+                totalMessages: messages.length,
+                estimatedTokens: estimateTokens(messages),
+                type: "redis",
+            };
+        }, { "memory.type": "redis", "memory.agent_id": this.agentId });
+    }
+    touch() {
+        return withSpan("agent.memory.redis.touch", async () => {
+            // TTL <= 0 means no expiration, so touch is a no-op
+            if (this.ttl <= 0)
+                return;
+            await this.client.expire(this.getKey(), this.ttl);
+        }, { "memory.type": "redis", "memory.agent_id": this.agentId, "memory.ttl": this.ttl });
+    }
+    atomicAdd(key, message) {
+        const args = [
+            JSON.stringify(message),
+            String(this.config.maxMessages ?? 0),
+            String(this.config.maxTokens ?? 0),
+            String(this.ttl),
+        ];
+        if (typeof this.client.sendCommand === "function") {
+            return this.client.sendCommand(["EVAL", ATOMIC_ADD_SCRIPT, "1", key, ...args]).then(() => { });
+        }
+        if (typeof this.client.call === "function") {
+            return this.client.call("EVAL", ATOMIC_ADD_SCRIPT, "1", key, ...args).then(() => { });
+        }
+        if (typeof this.client.eval === "function") {
+            return this.client.eval(ATOMIC_ADD_SCRIPT, { keys: [key], arguments: args }).then(() => { });
+        }
+        throw new Error("RedisMemory requires Redis sendCommand(), call(), or eval() for atomic add(); " +
+            "non-atomic GET/SET append is not supported");
+    }
+}
+/** Create redis memory. */
+export function createRedisMemory(agentId, config) {
+    return new RedisMemory(agentId, config);
+}

package/esm/cache-administration.d.ts

@@ -0,0 +1,5 @@
+import type { DistributedCacheAdministration } from "veryfront/extensions/distributed/cache-support";
+import type { RedisClientManager, RedisClientOptions } from "./redis-client-manager.js";
+/** Keep Redis cursor and command semantics behind the provider contract. */
+export declare function createRedisCacheAdministration(manager: RedisClientManager, clientOptions: RedisClientOptions): DistributedCacheAdministration;
+//# sourceMappingURL=cache-administration.d.ts.map

package/esm/cache-administration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-administration.d.ts","sourceRoot":"","sources":["../src/cache-administration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAG/B,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAEV,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAiCnC,4EAA4E;AAC5E,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,kBAAkB,EAC3B,aAAa,EAAE,kBAAkB,GAChC,8BAA8B,CAmGhC"}

package/esm/cache-administration.js

@@ -0,0 +1,113 @@
+import { isRedisAtomicCounterKey, REDIS_LOGICAL_DELETE_SCRIPT } from "./cache-backend.js";
+import { parseRevisionedCacheRecord } from "./revisioned-cache-record.js";
+import { REVISIONED_CACHE_KEY_PREFIX, stripOwnedDistributedCacheKeyPrefix, } from "veryfront/extensions/distributed/cache-support";
+const SCAN_COUNT = 100;
+const DELETE_BATCH_SIZE = 1_000;
+const MAX_SCAN_ITERATIONS = 10_000;
+const MAX_SCANNED_KEYS = 100_000;
+function escapeRedisGlobLiteral(value) {
+    return value.replace(/[\\*?\[\]]/g, "\\$&");
+}
+function requireScanResult(value, prefix) {
+    if (!value ||
+        !Number.isSafeInteger(value.cursor) ||
+        value.cursor < 0 ||
+        !Array.isArray(value.keys) ||
+        !value.keys.every((key) => typeof key === "string" && key.startsWith(prefix))) {
+        throw new TypeError("Redis returned an invalid cache-administration SCAN result");
+    }
+    return value;
+}
+/** Keep Redis cursor and command semantics behind the provider contract. */
+export function createRedisCacheAdministration(manager, clientOptions) {
+    const connection = Object.freeze({ ...clientOptions });
+    return Object.freeze({
+        isConfigured() {
+            return manager.isConfigured(connection);
+        },
+        async listKeys({ prefix, limit }) {
+            const client = await manager.getClient(connection);
+            const keys = new Set();
+            const seenPhysicalKeys = new Set();
+            const seenCursors = new Set();
+            let cursor = 0;
+            let iterations = 0;
+            let scanned = 0;
+            do {
+                if (iterations++ >= MAX_SCAN_ITERATIONS) {
+                    throw new RangeError("Redis cache administration exceeded the SCAN iteration limit");
+                }
+                if (seenCursors.has(cursor)) {
+                    throw new Error("Redis cache administration repeated a SCAN cursor");
+                }
+                seenCursors.add(cursor);
+                const page = requireScanResult(await client.scan(cursor, {
+                    MATCH: `${escapeRedisGlobLiteral(prefix)}*`,
+                    COUNT: SCAN_COUNT,
+                }), prefix);
+                cursor = page.cursor;
+                scanned += page.keys.length;
+                if (scanned > MAX_SCANNED_KEYS) {
+                    throw new RangeError("Redis cache administration exceeded the key traversal limit");
+                }
+                const candidates = page.keys.filter((key) => {
+                    if (seenPhysicalKeys.has(key))
+                        return false;
+                    seenPhysicalKeys.add(key);
+                    return true;
+                });
+                if (candidates.length === 0)
+                    continue;
+                const values = await client.mGet([...candidates]);
+                if (!Array.isArray(values) ||
+                    values.length !== candidates.length ||
+                    !values.every((value) => value === null || typeof value === "string")) {
+                    throw new TypeError("Redis returned an invalid cache-administration MGET result");
+                }
+                for (let index = 0; index < candidates.length; index++) {
+                    const key = candidates[index];
+                    const value = values[index];
+                    if (value === null)
+                        continue;
+                    if (stripOwnedDistributedCacheKeyPrefix(key).startsWith(REVISIONED_CACHE_KEY_PREFIX)) {
+                        const record = parseRevisionedCacheRecord(value);
+                        if (record.kind === "absent")
+                            continue;
+                    }
+                    if (keys.size === limit) {
+                        return Object.freeze({ keys: Object.freeze([...keys]), truncated: true });
+                    }
+                    keys.add(key);
+                }
+            } while (cursor !== 0);
+            return Object.freeze({ keys: Object.freeze([...keys]), truncated: false });
+        },
+        async deleteKeys(keys) {
+            if (keys.length === 0)
+                return 0;
+            if (keys.some(isRedisAtomicCounterKey)) {
+                throw new TypeError("Redis atomic counters are protected from cache administration");
+            }
+            const client = await manager.getClient(connection);
+            let deleted = 0;
+            for (let index = 0; index < keys.length; index += DELETE_BATCH_SIZE) {
+                const batch = keys.slice(index, index + DELETE_BATCH_SIZE);
+                const classifications = batch.map((key) => stripOwnedDistributedCacheKeyPrefix(key).startsWith(REVISIONED_CACHE_KEY_PREFIX)
+                    ? "1"
+                    : "0").join("");
+                const count = await client.eval(REDIS_LOGICAL_DELETE_SCRIPT, {
+                    keys: batch,
+                    arguments: [classifications, "vf-logical-delete-v1"],
+                });
+                if (typeof count !== "number" ||
+                    !Number.isSafeInteger(count) ||
+                    count < 0 ||
+                    count > batch.length) {
+                    throw new TypeError("Redis returned an invalid cache-administration DEL count");
+                }
+                deleted += count;
+            }
+            return deleted;
+        },
+    });
+}

package/esm/cache-backend.d.ts

@@ -0,0 +1,46 @@
+import { isRedisConfigured, type RedisClientManager, type RedisClientOptions } from "./redis-client-manager.js";
+import { type CacheBackend, type RevisionedCacheBackend } from "veryfront/extensions/distributed/cache-support";
+export declare const REDIS_LOGICAL_DELETE_SCRIPT: string;
+/** Test whether a physical Redis key is the protected namespace counter. */
+export declare function isRedisAtomicCounterKey(key: unknown): key is string;
+export interface RedisCacheBackendOptions {
+    clientManager?: RedisClientManager;
+    clientOptions?: RedisClientOptions;
+}
+export { isRedisConfigured };
+export declare class RedisCacheBackend implements CacheBackend {
+    readonly type: "distributed";
+    getWithRevision?: RevisionedCacheBackend["getWithRevision"];
+    compareExchange?: RevisionedCacheBackend["compareExchange"];
+    private readonly keyPrefix;
+    private readonly atomicCounterKey;
+    private readonly clientManager;
+    private readonly clientOptions;
+    constructor(keyPrefix?: string, options?: RedisCacheBackendOptions);
+    private prefixKey;
+    private resetAfterFailure;
+    private clearRevisionCapability;
+    private publishRevisionCapability;
+    private probeRevisionCapability;
+    private getClientForRead;
+    private requireClient;
+    initialize(): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    getWithinLimit(key: string, maximumBytes: number): Promise<string | null>;
+    private decodeOrdinaryRead;
+    getRemainingTtlSeconds(key: string): Promise<number | null>;
+    getBatch(keys: string[]): Promise<Map<string, string | null>>;
+    set(key: string, value: string, ttlSeconds?: any): Promise<void>;
+    setBatch(entries: Array<{
+        key: string;
+        value: string;
+        ttl?: number;
+    }>): Promise<void>;
+    del(key: string): Promise<void>;
+    delByPattern(pattern: string): Promise<number>;
+    private assertDeleteCount;
+    private requireRevisionedKey;
+    private readWithRevision;
+    private exchangeRevision;
+}
+//# sourceMappingURL=cache-backend.d.ts.map

package/esm/cache-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-backend.d.ts","sourceRoot":"","sources":["../src/cache-backend.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,iBAAiB,EAEjB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAKL,KAAK,YAAY,EAUjB,KAAK,sBAAsB,EAE5B,MAAM,gDAAgD,CAAC;AAqNxD,eAAO,MAAM,2BAA2B,QAyCvC,CAAC;AAyIF,4EAA4E;AAC5E,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAEnE;AAQD,MAAM,WAAW,wBAAwB;IACvC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAGD,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B,qBAAa,iBAAkB,YAAW,YAAY;IACpD,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAU;IAC/B,eAAe,CAAC,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IAC5D,eAAe,CAAC,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,SAAS,SAAsB,EAAE,OAAO,GAAE,wBAA6B;IAOnF,OAAO,CAAC,SAAS;YAIH,iBAAiB;IAS/B,OAAO,CAAC,uBAAuB;IAK/B,OAAO,CAAC,yBAAyB;YAiBnB,uBAAuB;YAyBvB,gBAAgB;YAYhB,aAAa;IAO3B,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IA0BxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAiBxC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkC/E,OAAO,CAAC,kBAAkB;IASpB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAiB3D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IAsC7D,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,UAAU,MAA4B,GACrC,OAAO,CAAC,IAAI,CAAC;IA0BV,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BrF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/B,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiEpD,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,oBAAoB;YAOd,gBAAgB;YAehB,gBAAgB;CA4B/B"}