@chidchanun/bcp 0.2.14 → 0.2.16

package/packages/cache/src/platform-v2.ts

@@ -0,0 +1,1705 @@
+import {
+    randomUUID,
+} from "node:crypto";
+
+export interface CacheAdapterEntry<T = unknown> {
+    key: string;
+    value: T;
+    expiresAt: number | null;
+    tags: string[];
+    paths: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+
+export interface CacheAdapterSetOptions {
+    expiresAt?: number | null;
+    tags?: readonly string[];
+    paths?: readonly string[];
+}
+
+export interface CacheAdapter {
+    get<T = unknown>(
+        key: string
+    ): Promise<CacheAdapterEntry<T> | null>;
+    set<T = unknown>(
+        key: string,
+        value: T,
+        options?: CacheAdapterSetOptions
+    ): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<number>;
+    revalidateTag(tag: string): Promise<number>;
+    revalidatePath(pathname: string): Promise<number>;
+    entries?(): Promise<number>;
+    close?(): Promise<void>;
+}
+
+export interface CacheLockAdapter {
+    acquire(
+        key: string,
+        ownerId: string,
+        ttlMs: number
+    ): Promise<boolean>;
+    extend?(
+        key: string,
+        ownerId: string,
+        ttlMs: number
+    ): Promise<boolean>;
+    release(
+        key: string,
+        ownerId: string
+    ): Promise<boolean>;
+    close?(): Promise<void>;
+}
+
+export interface MemoryCacheAdapter
+extends CacheAdapter {
+    readonly size: number;
+}
+
+export interface MemoryCacheLockAdapter
+extends CacheLockAdapter {
+    readonly size: number;
+}
+
+export interface CacheStoreSetOptions {
+    ttlMs?: number | false;
+    tags?: readonly string[];
+    paths?: readonly string[];
+}
+
+export interface CacheGetOrSetOptions
+extends CacheStoreSetOptions {
+    lockTtlMs?: number;
+    waitTimeoutMs?: number;
+    pollIntervalMs?: number;
+    onLockTimeout?: "load" | "error";
+}
+
+export interface CacheStoreStats {
+    hits: number;
+    misses: number;
+    sets: number;
+    deletes: number;
+    invalidations: number;
+    loads: number;
+    loadErrors: number;
+    lockAcquired: number;
+    lockContentions: number;
+    lockTimeouts: number;
+    inFlight: number;
+    adapterEntries?: number;
+}
+
+export type CacheStoreEvent =
+    | "hit"
+    | "miss"
+    | "set"
+    | "delete"
+    | "invalidate"
+    | "load"
+    | "load-error"
+    | "lock-acquired"
+    | "lock-contention"
+    | "lock-timeout";
+
+export interface CacheMetricsSink {
+    record(
+        event: CacheStoreEvent,
+        value?: number
+    ): void;
+    setInFlight?(value: number): void;
+}
+
+export interface CacheMetricsRegistryLike {
+    counter(
+        name: string,
+        options?: {
+            help?: string;
+            labelNames?: readonly string[];
+        }
+    ): {
+        inc(
+            value?: number,
+            labels?: Readonly<Record<
+                string,
+                string | number | boolean
+            >>
+        ): void;
+    };
+    gauge(
+        name: string,
+        options?: {
+            help?: string;
+            labelNames?: readonly string[];
+        }
+    ): {
+        set(
+            value: number,
+            labels?: Readonly<Record<
+                string,
+                string | number | boolean
+            >>
+        ): void;
+    };
+}
+
+export interface CacheStoreOptions {
+    adapter?: CacheAdapter;
+    lock?: CacheLockAdapter;
+    now?: () => number;
+    idFactory?: () => string;
+    metrics?: CacheMetricsSink;
+}
+
+export interface CacheStore {
+    readonly adapter: CacheAdapter;
+    readonly lock: CacheLockAdapter | undefined;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(
+        key: string,
+        value: T,
+        options?: CacheStoreSetOptions
+    ): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<number>;
+    revalidateTag(tag: string): Promise<number>;
+    revalidatePath(pathname: string): Promise<number>;
+    getOrSet<T>(
+        key: string,
+        loader: () => T | Promise<T>,
+        options?: CacheGetOrSetOptions
+    ): Promise<T>;
+    stats(): Promise<CacheStoreStats>;
+    close(): Promise<void>;
+}
+
+export interface RedisCacheCommandClient {
+    sendCommand(
+        command: string[]
+    ): Promise<unknown>;
+}
+
+export interface RedisCacheAdapterOptions {
+    client: RedisCacheCommandClient;
+    namespace?: string;
+    now?: () => number;
+    serialize?: (value: unknown) => string;
+    deserialize?: (value: string) => unknown;
+    close?: () => Promise<void>;
+}
+
+export interface RedisCacheAdapter
+extends CacheAdapter {
+    readonly namespace: string;
+}
+
+export interface RedisCacheLockAdapterOptions {
+    client: RedisCacheCommandClient;
+    namespace?: string;
+    close?: () => Promise<void>;
+}
+
+export interface RedisCacheLockAdapter
+extends CacheLockAdapter {
+    readonly namespace: string;
+}
+
+interface MemoryCacheRecord
+extends CacheAdapterEntry {
+}
+
+interface MemoryLockRecord {
+    ownerId: string;
+    expiresAt: number;
+}
+
+interface RedisStoredRecord {
+    key: string;
+    value: string;
+    expiresAt: number | null;
+    tags: string[];
+    paths: string[];
+    tagIndexKeys: string[];
+    pathIndexPairs: Array<{
+        path: string;
+        key: string;
+    }>;
+    createdAt: number;
+    updatedAt: number;
+}
+
+const DEFAULT_LOCK_TTL_MS = 30_000;
+const DEFAULT_WAIT_TIMEOUT_MS = 5_000;
+const DEFAULT_POLL_INTERVAL_MS = 25;
+
+export function createMemoryCacheAdapter(
+    options: {
+        now?: () => number;
+    } = {}
+): MemoryCacheAdapter {
+    const now =
+        options.now ?? Date.now;
+    const records =
+        new Map<string, MemoryCacheRecord>();
+
+    const adapter:
+        MemoryCacheAdapter = {
+        get size() {
+            prune();
+            return records.size;
+        },
+
+        async get<T>(
+            rawKey: string
+        ): Promise<CacheAdapterEntry<T> | null> {
+            const key = normalizeKey(rawKey);
+            const entry = records.get(key);
+            if (!entry) {
+                return null;
+            }
+            if (isExpired(entry, now())) {
+                records.delete(key);
+                return null;
+            }
+            return cloneEntry(entry) as CacheAdapterEntry<T>;
+        },
+
+        async set<T>(
+            rawKey: string,
+            value: T,
+            setOptions: CacheAdapterSetOptions = {}
+        ): Promise<void> {
+            const key = normalizeKey(rawKey);
+            const timestamp = now();
+            assertFiniteTimestamp(timestamp, "cache timestamp");
+            const current = records.get(key);
+            const expiresAt = normalizeExpiresAt(
+                setOptions.expiresAt
+            );
+            records.set(key, {
+                key,
+                value,
+                expiresAt,
+                tags: normalizeTags(setOptions.tags),
+                paths: normalizePaths(setOptions.paths),
+                createdAt: current?.createdAt ?? timestamp,
+                updatedAt: timestamp,
+            });
+        },
+
+        async delete(rawKey) {
+            return records.delete(
+                normalizeKey(rawKey)
+            );
+        },
+
+        async clear() {
+            const count = records.size;
+            records.clear();
+            return count;
+        },
+
+        async revalidateTag(rawTag) {
+            const tag = normalizeTag(rawTag);
+            let removed = 0;
+            for (const [key, record] of records) {
+                if (record.tags.includes(tag)) {
+                    records.delete(key);
+                    removed++;
+                }
+            }
+            return removed;
+        },
+
+        async revalidatePath(rawPath) {
+            const pathname = normalizePath(rawPath);
+            let removed = 0;
+            for (const [key, record] of records) {
+                if (
+                    record.paths.some(path =>
+                        pathMatches(path, pathname)
+                    )
+                ) {
+                    records.delete(key);
+                    removed++;
+                }
+            }
+            return removed;
+        },
+
+        async entries() {
+            prune();
+            return records.size;
+        },
+    };
+
+    return adapter;
+
+    function prune(): void {
+        const timestamp = now();
+        for (const [key, record] of records) {
+            if (isExpired(record, timestamp)) {
+                records.delete(key);
+            }
+        }
+    }
+}
+
+export function createMemoryCacheLockAdapter(
+    options: {
+        now?: () => number;
+    } = {}
+): MemoryCacheLockAdapter {
+    const now =
+        options.now ?? Date.now;
+    const locks =
+        new Map<string, MemoryLockRecord>();
+
+    const adapter:
+        MemoryCacheLockAdapter = {
+        get size() {
+            prune();
+            return locks.size;
+        },
+
+        async acquire(rawKey, rawOwnerId, ttlMs) {
+            const key = normalizeKey(rawKey);
+            const ownerId = normalizeOwnerId(rawOwnerId);
+            const ttl = positiveInteger(ttlMs, "lock ttlMs");
+            const timestamp = now();
+            const current = locks.get(key);
+            if (
+                current &&
+                current.expiresAt > timestamp
+            ) {
+                return false;
+            }
+            locks.set(key, {
+                ownerId,
+                expiresAt: timestamp + ttl,
+            });
+            return true;
+        },
+
+        async extend(rawKey, rawOwnerId, ttlMs) {
+            const key = normalizeKey(rawKey);
+            const ownerId = normalizeOwnerId(rawOwnerId);
+            const ttl = positiveInteger(ttlMs, "lock ttlMs");
+            const timestamp = now();
+            const current = locks.get(key);
+            if (
+                !current ||
+                current.ownerId !== ownerId ||
+                current.expiresAt <= timestamp
+            ) {
+                return false;
+            }
+            current.expiresAt = timestamp + ttl;
+            return true;
+        },
+
+        async release(rawKey, rawOwnerId) {
+            const key = normalizeKey(rawKey);
+            const ownerId = normalizeOwnerId(rawOwnerId);
+            const current = locks.get(key);
+            if (!current || current.ownerId !== ownerId) {
+                return false;
+            }
+            locks.delete(key);
+            return true;
+        },
+    };
+
+    return adapter;
+
+    function prune(): void {
+        const timestamp = now();
+        for (const [key, record] of locks) {
+            if (record.expiresAt <= timestamp) {
+                locks.delete(key);
+            }
+        }
+    }
+}
+
+export function createCacheStore(
+    options: CacheStoreOptions = {}
+): CacheStore {
+    const adapter =
+        options.adapter ??
+        createMemoryCacheAdapter({
+            now: options.now,
+        });
+    const lock = options.lock;
+    const now = options.now ?? Date.now;
+    const idFactory =
+        options.idFactory ?? randomUUID;
+    const metrics = options.metrics;
+    const inFlight =
+        new Map<string, Promise<unknown>>();
+    const counters = {
+        hits: 0,
+        misses: 0,
+        sets: 0,
+        deletes: 0,
+        invalidations: 0,
+        loads: 0,
+        loadErrors: 0,
+        lockAcquired: 0,
+        lockContentions: 0,
+        lockTimeouts: 0,
+    };
+    let closed = false;
+
+    const store:
+        CacheStore = {
+        adapter,
+        lock,
+
+        async get<T>(
+            rawKey: string
+        ): Promise<T | undefined> {
+            assertOpen();
+            const key = normalizeKey(rawKey);
+            const entry = await adapter.get<T>(key);
+            if (!entry) {
+                count("misses", "miss");
+                return undefined;
+            }
+            if (
+                entry.expiresAt !== null &&
+                entry.expiresAt <= now()
+            ) {
+                await adapter.delete(key);
+                count("misses", "miss");
+                return undefined;
+            }
+            count("hits", "hit");
+            return entry.value;
+        },
+
+        async set<T>(
+            rawKey: string,
+            value: T,
+            setOptions: CacheStoreSetOptions = {}
+        ): Promise<void> {
+            assertOpen();
+            const key = normalizeKey(rawKey);
+            if (setOptions.ttlMs === 0) {
+                await store.delete(key);
+                return;
+            }
+            const expiresAt =
+                setOptions.ttlMs === undefined ||
+                setOptions.ttlMs === false
+                    ? null
+                    : now() + positiveInteger(
+                        setOptions.ttlMs,
+                        "cache ttlMs"
+                    );
+            await adapter.set(
+                key,
+                value,
+                {
+                    expiresAt,
+                    tags: normalizeTags(setOptions.tags),
+                    paths: normalizePaths(setOptions.paths),
+                }
+            );
+            count("sets", "set");
+        },
+
+        async delete(rawKey) {
+            assertOpen();
+            const removed =
+                await adapter.delete(
+                    normalizeKey(rawKey)
+                );
+            if (removed) {
+                count("deletes", "delete");
+            }
+            return removed;
+        },
+
+        async clear() {
+            assertOpen();
+            const removed = await adapter.clear();
+            if (removed > 0) {
+                counters.invalidations += removed;
+                metrics?.record("invalidate", removed);
+            }
+            return removed;
+        },
+
+        async revalidateTag(rawTag) {
+            assertOpen();
+            const removed =
+                await adapter.revalidateTag(
+                    normalizeTag(rawTag)
+                );
+            if (removed > 0) {
+                counters.invalidations += removed;
+                metrics?.record("invalidate", removed);
+            }
+            return removed;
+        },
+
+        async revalidatePath(rawPath) {
+            assertOpen();
+            const removed =
+                await adapter.revalidatePath(
+                    normalizePath(rawPath)
+                );
+            if (removed > 0) {
+                counters.invalidations += removed;
+                metrics?.record("invalidate", removed);
+            }
+            return removed;
+        },
+
+        async getOrSet<T>(
+            rawKey: string,
+            loader: () => T | Promise<T>,
+            loadOptions: CacheGetOrSetOptions = {}
+        ): Promise<T> {
+            assertOpen();
+            if (typeof loader !== "function") {
+                throw new TypeError(
+                    "BCP Cache: loader must be a function."
+                );
+            }
+            const key = normalizeKey(rawKey);
+            const cached = await store.get<T>(key);
+            if (cached !== undefined) {
+                return cached;
+            }
+
+            const pending = inFlight.get(key);
+            if (pending) {
+                return await pending as T;
+            }
+
+            const promise =
+                loadWithStampedeProtection<T>(
+                    key,
+                    loader,
+                    loadOptions
+                );
+            inFlight.set(key, promise);
+            metrics?.setInFlight?.(inFlight.size);
+            try {
+                return await promise;
+            } finally {
+                inFlight.delete(key);
+                metrics?.setInFlight?.(inFlight.size);
+            }
+        },
+
+        async stats() {
+            assertOpen();
+            return {
+                ...counters,
+                inFlight: inFlight.size,
+                adapterEntries:
+                    adapter.entries
+                        ? await adapter.entries()
+                        : undefined,
+            };
+        },
+
+        async close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            inFlight.clear();
+            metrics?.setInFlight?.(0);
+            const lockClose =
+                lock &&
+                !Object.is(lock, adapter)
+                    ? lock.close?.()
+                    : undefined;
+            await Promise.all([
+                adapter.close?.(),
+                lockClose,
+            ]);
+        },
+    };
+
+    return store;
+
+    async function loadWithStampedeProtection<T>(
+        key: string,
+        loader: () => T | Promise<T>,
+        loadOptions: CacheGetOrSetOptions
+    ): Promise<T> {
+        if (!lock) {
+            return executeLoader(
+                key,
+                loader,
+                loadOptions
+            );
+        }
+
+        const lockTtlMs =
+            positiveInteger(
+                loadOptions.lockTtlMs ??
+                DEFAULT_LOCK_TTL_MS,
+                "lock ttlMs"
+            );
+        const waitTimeoutMs =
+            nonNegativeInteger(
+                loadOptions.waitTimeoutMs ??
+                DEFAULT_WAIT_TIMEOUT_MS,
+                "lock waitTimeoutMs"
+            );
+        const pollIntervalMs =
+            positiveInteger(
+                loadOptions.pollIntervalMs ??
+                DEFAULT_POLL_INTERVAL_MS,
+                "lock pollIntervalMs"
+            );
+        const ownerId =
+            normalizeOwnerId(idFactory());
+        const lockKey =
+            `cache-load:${key}`;
+
+        if (
+            await lock.acquire(
+                lockKey,
+                ownerId,
+                lockTtlMs
+            )
+        ) {
+            count(
+                "lockAcquired",
+                "lock-acquired"
+            );
+            return executeUnderLock(
+                key,
+                ownerId,
+                lockKey,
+                lockTtlMs,
+                loader,
+                loadOptions
+            );
+        }
+
+        count(
+            "lockContentions",
+            "lock-contention"
+        );
+        const waitStartedAt = Date.now();
+        while (
+            Date.now() - waitStartedAt <
+            waitTimeoutMs
+        ) {
+            await sleep(pollIntervalMs);
+            const cached = await store.get<T>(key);
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+
+        count("lockTimeouts", "lock-timeout");
+        if (loadOptions.onLockTimeout === "error") {
+            throw new Error(
+                `BCP Cache: timed out waiting for distributed cache lock for "${key}".`
+            );
+        }
+
+        if (
+            await lock.acquire(
+                lockKey,
+                ownerId,
+                lockTtlMs
+            )
+        ) {
+            count(
+                "lockAcquired",
+                "lock-acquired"
+            );
+            return executeUnderLock(
+                key,
+                ownerId,
+                lockKey,
+                lockTtlMs,
+                loader,
+                loadOptions
+            );
+        }
+
+        return executeLoader(
+            key,
+            loader,
+            loadOptions
+        );
+    }
+
+    async function executeUnderLock<T>(
+        key: string,
+        ownerId: string,
+        lockKey: string,
+        lockTtlMs: number,
+        loader: () => T | Promise<T>,
+        loadOptions: CacheGetOrSetOptions
+    ): Promise<T> {
+        let timer:
+            ReturnType<typeof setTimeout> |
+            undefined;
+        let active = true;
+
+        if (lock?.extend) {
+            const intervalMs =
+                Math.max(
+                    1,
+                    Math.floor(lockTtlMs / 3)
+                );
+            const heartbeat = async () => {
+                if (!active) {
+                    return;
+                }
+                try {
+                    await lock.extend?.(
+                        lockKey,
+                        ownerId,
+                        lockTtlMs
+                    );
+                } catch {
+                    // A failed renewal is allowed to expire naturally.
+                } finally {
+                    if (active) {
+                        timer = setTimeout(
+                            heartbeat,
+                            intervalMs
+                        );
+                    }
+                }
+            };
+            timer = setTimeout(
+                heartbeat,
+                intervalMs
+            );
+        }
+
+        try {
+            const cached = await store.get<T>(key);
+            if (cached !== undefined) {
+                return cached;
+            }
+            return await executeLoader(
+                key,
+                loader,
+                loadOptions
+            );
+        } finally {
+            active = false;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            await lock?.release(
+                lockKey,
+                ownerId
+            );
+        }
+    }
+
+    async function executeLoader<T>(
+        key: string,
+        loader: () => T | Promise<T>,
+        loadOptions: CacheGetOrSetOptions
+    ): Promise<T> {
+        count("loads", "load");
+        try {
+            const value = await loader();
+            await store.set(
+                key,
+                value,
+                loadOptions
+            );
+            return value;
+        } catch (error) {
+            count(
+                "loadErrors",
+                "load-error"
+            );
+            throw error;
+        }
+    }
+
+    function count(
+        key: keyof typeof counters,
+        event: CacheStoreEvent,
+        value = 1
+    ): void {
+        counters[key] += value;
+        metrics?.record(event, value);
+    }
+
+    function assertOpen(): void {
+        if (closed) {
+            throw new Error(
+                "BCP Cache: cache store is closed."
+            );
+        }
+    }
+}
+
+export function createCacheMetrics(
+    registry: CacheMetricsRegistryLike,
+    options: {
+        prefix?: string;
+    } = {}
+): CacheMetricsSink {
+    const prefix =
+        normalizeMetricPrefix(
+            options.prefix ?? "bcp_cache"
+        );
+    const operations =
+        registry.counter(
+            `${prefix}_operations_total`,
+            {
+                help:
+                    "BCP Cache operations by event.",
+                labelNames: [
+                    "event",
+                ],
+            }
+        );
+    const inFlight =
+        registry.gauge(
+            `${prefix}_in_flight`,
+            {
+                help:
+                    "BCP Cache local in-flight loaders.",
+            }
+        );
+
+    return {
+        record(event, value = 1) {
+            operations.inc(
+                value,
+                {
+                    event,
+                }
+            );
+        },
+        setInFlight(value) {
+            inFlight.set(value);
+        },
+    };
+}
+
+export function createRedisCacheAdapter(
+    options: RedisCacheAdapterOptions
+): RedisCacheAdapter {
+    assertRedisClient(options.client);
+    const namespace =
+        normalizeNamespace(
+            options.namespace ??
+            "bcp:{cache}"
+        );
+    const now = options.now ?? Date.now;
+    const serialize =
+        options.serialize ?? JSON.stringify;
+    const deserialize =
+        options.deserialize ?? JSON.parse;
+    const client = options.client;
+
+    const adapter:
+        RedisCacheAdapter = {
+        namespace,
+
+        async get<T>(
+            rawKey: string
+        ): Promise<CacheAdapterEntry<T> | null> {
+            const key = normalizeKey(rawKey);
+            const entryKey = redisEntryKey(
+                namespace,
+                key
+            );
+            const raw =
+                redisString(
+                    await client.sendCommand([
+                        "GET",
+                        entryKey,
+                    ])
+                );
+            if (raw === null) {
+                await client.sendCommand([
+                    "SREM",
+                    redisAllKeysKey(namespace),
+                    entryKey,
+                ]);
+                return null;
+            }
+            const stored =
+                parseStoredRecord(raw);
+            if (
+                stored.expiresAt !== null &&
+                stored.expiresAt <= now()
+            ) {
+                await deleteStoredRecord(
+                    stored,
+                    entryKey
+                );
+                return null;
+            }
+            return {
+                key: stored.key,
+                value:
+                    deserialize(stored.value) as T,
+                expiresAt: stored.expiresAt,
+                tags: [...stored.tags],
+                paths: [...stored.paths],
+                createdAt: stored.createdAt,
+                updatedAt: stored.updatedAt,
+            };
+        },
+
+        async set<T>(
+            rawKey: string,
+            value: T,
+            setOptions: CacheAdapterSetOptions = {}
+        ): Promise<void> {
+            const key = normalizeKey(rawKey);
+            const entryKey = redisEntryKey(
+                namespace,
+                key
+            );
+            const timestamp = now();
+            const tags = normalizeTags(setOptions.tags);
+            const paths = normalizePaths(setOptions.paths);
+            const current = await adapter.get(key);
+            const stored:
+                RedisStoredRecord = {
+                key,
+                value: serializeValue(
+                    value,
+                    serialize
+                ),
+                expiresAt:
+                    normalizeExpiresAt(
+                        setOptions.expiresAt
+                    ),
+                tags,
+                paths,
+                tagIndexKeys:
+                    tags.map(tag =>
+                        redisTagKey(
+                            namespace,
+                            tag
+                        )
+                    ),
+                pathIndexPairs:
+                    paths.map(pathname => ({
+                        path: pathname,
+                        key: redisPathKey(
+                            namespace,
+                            pathname
+                        ),
+                    })),
+                createdAt:
+                    current?.createdAt ??
+                    timestamp,
+                updatedAt: timestamp,
+            };
+            const ttlMs =
+                stored.expiresAt === null
+                    ? 0
+                    : Math.max(
+                        1,
+                        stored.expiresAt - timestamp
+                    );
+            await evalRedis(
+                client,
+                REDIS_SET_SCRIPT,
+                [
+                    entryKey,
+                    redisAllKeysKey(namespace),
+                    redisPathsIndexKey(namespace),
+                ],
+                [
+                    JSON.stringify(stored),
+                    String(ttlMs),
+                ]
+            );
+        },
+
+        async delete(rawKey) {
+            const key = normalizeKey(rawKey);
+            const entryKey = redisEntryKey(
+                namespace,
+                key
+            );
+            const result = await evalRedis(
+                client,
+                REDIS_DELETE_SCRIPT,
+                [
+                    entryKey,
+                    redisAllKeysKey(namespace),
+                    redisPathsIndexKey(namespace),
+                ],
+                []
+            );
+            return Number(result) > 0;
+        },
+
+        async clear() {
+            const entryKeys =
+                redisStringArray(
+                    await client.sendCommand([
+                        "SMEMBERS",
+                        redisAllKeysKey(namespace),
+                    ])
+                );
+            let removed = 0;
+            for (const entryKey of entryKeys) {
+                const result = await evalRedis(
+                    client,
+                    REDIS_DELETE_SCRIPT,
+                    [
+                        entryKey,
+                        redisAllKeysKey(namespace),
+                        redisPathsIndexKey(namespace),
+                    ],
+                    []
+                );
+                removed += Number(result) > 0
+                    ? 1
+                    : 0;
+            }
+            await client.sendCommand([
+                "DEL",
+                redisAllKeysKey(namespace),
+                redisPathsIndexKey(namespace),
+            ]);
+            return removed;
+        },
+
+        async revalidateTag(rawTag) {
+            const tag = normalizeTag(rawTag);
+            const tagKey = redisTagKey(
+                namespace,
+                tag
+            );
+            const result = await evalRedis(
+                client,
+                REDIS_INVALIDATE_SET_SCRIPT,
+                [
+                    tagKey,
+                    redisAllKeysKey(namespace),
+                    redisPathsIndexKey(namespace),
+                ],
+                []
+            );
+            return Number(result) || 0;
+        },
+
+        async revalidatePath(rawPath) {
+            const pathname = normalizePath(rawPath);
+            const registeredPaths =
+                redisStringArray(
+                    await client.sendCommand([
+                        "SMEMBERS",
+                        redisPathsIndexKey(namespace),
+                    ])
+                );
+            const matches = registeredPaths
+                .filter(path =>
+                    pathMatches(path, pathname)
+                )
+                .map(path => ({
+                    path,
+                    key: redisPathKey(
+                        namespace,
+                        path
+                    ),
+                }));
+            if (matches.length === 0) {
+                return 0;
+            }
+            const result = await evalRedis(
+                client,
+                REDIS_INVALIDATE_PATHS_SCRIPT,
+                [
+                    redisAllKeysKey(namespace),
+                    redisPathsIndexKey(namespace),
+                ],
+                [
+                    JSON.stringify(matches),
+                ]
+            );
+            return Number(result) || 0;
+        },
+
+        async entries() {
+            return Number(
+                await client.sendCommand([
+                    "SCARD",
+                    redisAllKeysKey(namespace),
+                ])
+            ) || 0;
+        },
+
+        async close() {
+            await options.close?.();
+        },
+    };
+
+    return adapter;
+
+    async function deleteStoredRecord(
+        _stored: RedisStoredRecord,
+        entryKey: string
+    ): Promise<void> {
+        await evalRedis(
+            client,
+            REDIS_DELETE_SCRIPT,
+            [
+                entryKey,
+                redisAllKeysKey(namespace),
+                redisPathsIndexKey(namespace),
+            ],
+            []
+        );
+    }
+}
+
+export function createRedisCacheLockAdapter(
+    options: RedisCacheLockAdapterOptions
+): RedisCacheLockAdapter {
+    assertRedisClient(options.client);
+    const namespace =
+        normalizeNamespace(
+            options.namespace ??
+            "bcp:{cache}"
+        );
+    const client = options.client;
+
+    return {
+        namespace,
+
+        async acquire(rawKey, rawOwnerId, ttlMs) {
+            const key = redisLockKey(
+                namespace,
+                normalizeKey(rawKey)
+            );
+            const ownerId = normalizeOwnerId(rawOwnerId);
+            const ttl = positiveInteger(
+                ttlMs,
+                "lock ttlMs"
+            );
+            const result =
+                redisString(
+                    await client.sendCommand([
+                        "SET",
+                        key,
+                        ownerId,
+                        "NX",
+                        "PX",
+                        String(ttl),
+                    ])
+                );
+            return result === "OK";
+        },
+
+        async extend(rawKey, rawOwnerId, ttlMs) {
+            const result = await evalRedis(
+                client,
+                REDIS_LOCK_EXTEND_SCRIPT,
+                [
+                    redisLockKey(
+                        namespace,
+                        normalizeKey(rawKey)
+                    ),
+                ],
+                [
+                    normalizeOwnerId(rawOwnerId),
+                    String(
+                        positiveInteger(
+                            ttlMs,
+                            "lock ttlMs"
+                        )
+                    ),
+                ]
+            );
+            return Number(result) > 0;
+        },
+
+        async release(rawKey, rawOwnerId) {
+            const result = await evalRedis(
+                client,
+                REDIS_LOCK_RELEASE_SCRIPT,
+                [
+                    redisLockKey(
+                        namespace,
+                        normalizeKey(rawKey)
+                    ),
+                ],
+                [
+                    normalizeOwnerId(rawOwnerId),
+                ]
+            );
+            return Number(result) > 0;
+        },
+
+        async close() {
+            await options.close?.();
+        },
+    };
+}
+
+function cloneEntry<T>(
+    entry: CacheAdapterEntry<T>
+): CacheAdapterEntry<T> {
+    return {
+        ...entry,
+        tags: [...entry.tags],
+        paths: [...entry.paths],
+    };
+}
+
+function isExpired(
+    entry: CacheAdapterEntry,
+    now: number
+): boolean {
+    return (
+        entry.expiresAt !== null &&
+        entry.expiresAt <= now
+    );
+}
+
+function normalizeExpiresAt(
+    value: number | null | undefined
+): number | null {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    assertFiniteTimestamp(value, "cache expiresAt");
+    return value;
+}
+
+function normalizeKey(value: string): string {
+    const normalized = String(value ?? "").trim();
+    if (!normalized) {
+        throw new TypeError(
+            "BCP Cache: key must be a non-empty string."
+        );
+    }
+    return normalized;
+}
+
+function normalizeOwnerId(value: string): string {
+    const normalized = String(value ?? "").trim();
+    if (!normalized) {
+        throw new TypeError(
+            "BCP Cache: lock ownerId must be a non-empty string."
+        );
+    }
+    return normalized;
+}
+
+function normalizeTag(value: string): string {
+    const normalized = String(value ?? "").trim();
+    if (!normalized) {
+        throw new TypeError(
+            "BCP Cache: cache tags cannot be empty."
+        );
+    }
+    return normalized;
+}
+
+function normalizeTags(
+    values: readonly string[] | undefined
+): string[] {
+    return Array.from(
+        new Set(
+            (values ?? []).map(normalizeTag)
+        )
+    ).sort();
+}
+
+function normalizePath(value: string): string {
+    let pathname = String(value ?? "").trim();
+    if (!pathname) {
+        return "/";
+    }
+    try {
+        if (
+            pathname.startsWith("http://") ||
+            pathname.startsWith("https://")
+        ) {
+            pathname = new URL(pathname).pathname;
+        }
+    } catch {
+        // Fall through to pathname normalization.
+    }
+    pathname = pathname
+        .split("?")[0]
+        .split("#")[0];
+    if (!pathname.startsWith("/")) {
+        pathname = `/${pathname}`;
+    }
+    if (
+        pathname.length > 1 &&
+        pathname.endsWith("/")
+    ) {
+        pathname = pathname.slice(0, -1);
+    }
+    return pathname;
+}
+
+function normalizePaths(
+    values: readonly string[] | undefined
+): string[] {
+    return Array.from(
+        new Set(
+            (values ?? []).map(normalizePath)
+        )
+    ).sort();
+}
+
+function pathMatches(
+    cachedPath: string,
+    invalidatedPath: string
+): boolean {
+    if (invalidatedPath === "/") {
+        return true;
+    }
+    return (
+        cachedPath === invalidatedPath ||
+        cachedPath.startsWith(
+            `${invalidatedPath}/`
+        )
+    );
+}
+
+function positiveInteger(
+    value: number,
+    field: string
+): number {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new TypeError(
+            `BCP Cache: ${field} must be a positive integer.`
+        );
+    }
+    return value;
+}
+
+function nonNegativeInteger(
+    value: number,
+    field: string
+): number {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new TypeError(
+            `BCP Cache: ${field} must be a non-negative integer.`
+        );
+    }
+    return value;
+}
+
+function assertFiniteTimestamp(
+    value: number,
+    field: string
+): void {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(
+            `BCP Cache: ${field} must be a finite number.`
+        );
+    }
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+
+function normalizeMetricPrefix(
+    value: string
+): string {
+    const normalized = value.trim();
+    if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(normalized)) {
+        throw new TypeError(
+            "BCP Cache: metrics prefix contains unsupported characters."
+        );
+    }
+    return normalized;
+}
+
+function normalizeNamespace(value: string): string {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new TypeError(
+            "BCP Cache: Redis namespace must be a non-empty string."
+        );
+    }
+    return normalized.replace(/:+$/g, "");
+}
+
+function encodeRedisPart(value: string): string {
+    return encodeURIComponent(value);
+}
+
+function redisEntryKey(
+    namespace: string,
+    key: string
+): string {
+    return `${namespace}:entry:${encodeRedisPart(key)}`;
+}
+
+function redisTagKey(
+    namespace: string,
+    tag: string
+): string {
+    return `${namespace}:tag:${encodeRedisPart(tag)}`;
+}
+
+function redisPathKey(
+    namespace: string,
+    pathname: string
+): string {
+    return `${namespace}:path:${encodeRedisPart(pathname)}`;
+}
+
+function redisAllKeysKey(namespace: string): string {
+    return `${namespace}:entries`;
+}
+
+function redisPathsIndexKey(namespace: string): string {
+    return `${namespace}:paths`;
+}
+
+function redisLockKey(
+    namespace: string,
+    key: string
+): string {
+    return `${namespace}:lock:${encodeRedisPart(key)}`;
+}
+
+function serializeValue(
+    value: unknown,
+    serialize: (value: unknown) => string
+): string {
+    const result = serialize(value);
+    if (typeof result !== "string") {
+        throw new TypeError(
+            "BCP Cache: Redis serializer must return a string."
+        );
+    }
+    return result;
+}
+
+function parseStoredRecord(
+    value: string
+): RedisStoredRecord {
+    const parsed = JSON.parse(value) as
+        Partial<RedisStoredRecord>;
+    if (
+        !parsed ||
+        typeof parsed.key !== "string" ||
+        typeof parsed.value !== "string" ||
+        !Array.isArray(parsed.tags) ||
+        !Array.isArray(parsed.paths) ||
+        !Array.isArray(parsed.tagIndexKeys) ||
+        !Array.isArray(parsed.pathIndexPairs) ||
+        typeof parsed.createdAt !== "number" ||
+        typeof parsed.updatedAt !== "number"
+    ) {
+        throw new Error(
+            "BCP Cache: invalid Redis cache record."
+        );
+    }
+    return parsed as RedisStoredRecord;
+}
+
+function assertRedisClient(
+    client: RedisCacheCommandClient
+): void {
+    if (
+        !client ||
+        typeof client.sendCommand !== "function"
+    ) {
+        throw new TypeError(
+            "BCP Cache: Redis adapter requires a sendCommand client."
+        );
+    }
+}
+
+function redisString(value: unknown): string | null {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return new TextDecoder().decode(value);
+    }
+    return String(value);
+}
+
+function redisStringArray(value: unknown): string[] {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map(redisString)
+        .filter((item): item is string =>
+            item !== null
+        );
+}
+
+async function evalRedis(
+    client: RedisCacheCommandClient,
+    script: string,
+    keys: string[],
+    args: string[]
+): Promise<unknown> {
+    return client.sendCommand([
+        "EVAL",
+        script,
+        String(keys.length),
+        ...keys,
+        ...args,
+    ]);
+}
+
+const REDIS_SET_SCRIPT = `
+local old = redis.call('GET', KEYS[1])
+if old then
+    local previous = cjson.decode(old)
+    for _, tagKey in ipairs(previous.tagIndexKeys or {}) do
+        redis.call('SREM', tagKey, KEYS[1])
+        if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+    end
+    for _, pair in ipairs(previous.pathIndexPairs or {}) do
+        redis.call('SREM', pair.key, KEYS[1])
+        if redis.call('SCARD', pair.key) == 0 then
+            redis.call('DEL', pair.key)
+            redis.call('SREM', KEYS[3], pair.path)
+        end
+    end
+end
+local record = cjson.decode(ARGV[1])
+if tonumber(ARGV[2]) > 0 then
+    redis.call('SET', KEYS[1], ARGV[1], 'PX', ARGV[2])
+else
+    redis.call('SET', KEYS[1], ARGV[1])
+end
+redis.call('SADD', KEYS[2], KEYS[1])
+for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+    redis.call('SADD', tagKey, KEYS[1])
+end
+for _, pair in ipairs(record.pathIndexPairs or {}) do
+    redis.call('SADD', pair.key, KEYS[1])
+    redis.call('SADD', KEYS[3], pair.path)
+end
+return 1
+`;
+
+const REDIS_DELETE_SCRIPT = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then
+    redis.call('SREM', KEYS[2], KEYS[1])
+    return 0
+end
+local record = cjson.decode(raw)
+for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+    redis.call('SREM', tagKey, KEYS[1])
+    if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+end
+for _, pair in ipairs(record.pathIndexPairs or {}) do
+    redis.call('SREM', pair.key, KEYS[1])
+    if redis.call('SCARD', pair.key) == 0 then
+        redis.call('DEL', pair.key)
+        redis.call('SREM', KEYS[3], pair.path)
+    end
+end
+redis.call('DEL', KEYS[1])
+redis.call('SREM', KEYS[2], KEYS[1])
+return 1
+`;
+
+const REDIS_INVALIDATE_SET_SCRIPT = `
+local members = redis.call('SMEMBERS', KEYS[1])
+local removed = 0
+for _, entryKey in ipairs(members) do
+    local raw = redis.call('GET', entryKey)
+    if raw then
+        local record = cjson.decode(raw)
+        for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+            redis.call('SREM', tagKey, entryKey)
+            if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+        end
+        for _, pair in ipairs(record.pathIndexPairs or {}) do
+            redis.call('SREM', pair.key, entryKey)
+            if redis.call('SCARD', pair.key) == 0 then
+                redis.call('DEL', pair.key)
+                redis.call('SREM', KEYS[3], pair.path)
+            end
+        end
+        redis.call('DEL', entryKey)
+        redis.call('SREM', KEYS[2], entryKey)
+        removed = removed + 1
+    else
+        redis.call('SREM', KEYS[2], entryKey)
+    end
+end
+redis.call('DEL', KEYS[1])
+return removed
+`;
+
+const REDIS_INVALIDATE_PATHS_SCRIPT = `
+local pairs = cjson.decode(ARGV[1])
+local seen = {}
+local removed = 0
+for _, pair in ipairs(pairs) do
+    local members = redis.call('SMEMBERS', pair.key)
+    for _, entryKey in ipairs(members) do
+        if not seen[entryKey] then
+            seen[entryKey] = true
+            local raw = redis.call('GET', entryKey)
+            if raw then
+                local record = cjson.decode(raw)
+                for _, tagKey in ipairs(record.tagIndexKeys or {}) do
+                    redis.call('SREM', tagKey, entryKey)
+                    if redis.call('SCARD', tagKey) == 0 then redis.call('DEL', tagKey) end
+                end
+                for _, pathPair in ipairs(record.pathIndexPairs or {}) do
+                    redis.call('SREM', pathPair.key, entryKey)
+                    if redis.call('SCARD', pathPair.key) == 0 then
+                        redis.call('DEL', pathPair.key)
+                        redis.call('SREM', KEYS[2], pathPair.path)
+                    end
+                end
+                redis.call('DEL', entryKey)
+                redis.call('SREM', KEYS[1], entryKey)
+                removed = removed + 1
+            else
+                redis.call('SREM', KEYS[1], entryKey)
+            end
+        end
+    end
+    redis.call('DEL', pair.key)
+    redis.call('SREM', KEYS[2], pair.path)
+end
+return removed
+`;
+
+const REDIS_LOCK_RELEASE_SCRIPT = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('DEL', KEYS[1])
+end
+return 0
+`;
+
+const REDIS_LOCK_EXTEND_SCRIPT = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('PEXPIRE', KEYS[1], ARGV[2])
+end
+return 0
+`;