import type { SharedStore } from "../factory.js"; import { createCacheStore, type CacheSerializer, type CacheStore } from "./cache.js"; /** * Minimal LRU/Map-like contract for the L1 in-process cache. Both * `Map` and `LRUCache` satisfy this shape so the * caller can pick whatever fits their memory/eviction strategy. */ export interface TwoTierL1Cache { get(key: string): T | undefined; set(key: string, value: T): void; delete(key: string): boolean | void; clear(): void; keys(): IterableIterator | Iterable; } export interface TwoTierCacheOptions { /** Backing SharedStore. Used for the L2 tier and the pub/sub channel. */ store: SharedStore; /** * Channel namespace. Becomes the L2 prefix and the invalidation channel * suffix. Should describe the subsystem (e.g. `"subscription"`, * `"tenant"`, `"entitlements"`). */ namespace: string; /** TTL applied to L2 (and used as L1 max-age when the cache honours TTL). */ ttlSeconds: number; /** * Optional L1 implementation. Defaults to an internal TTL-aware LRU cache. */ l1Cache?: TwoTierL1Cache; /** Maximum entries in the default L1 cache. Defaults to 10,000. */ l1MaxEntries?: number; /** Override the L1 clock for deterministic tests. Defaults to `Date.now`. */ l1Now?: () => number; /** Optional JSON serializer override for the L2 tier. */ serializer?: CacheSerializer; /** * Suffix used for the pub/sub channel inside the namespace. Defaults * to `"invalidate"`, producing channel * `shared-store::ch:cache::invalidate`. */ invalidationChannel?: string; /** * Global kill-switch. When `false` (e.g. `CACHE_INVALIDATION_ENABLED=false`) * the cache still serves locally but `invalidate()` becomes a local-only * delete + no PUBLISH, and `subscribe()` becomes a no-op. Used for emergency * disable without code change. */ pubsubEnabled?: boolean; /** * Optional logger for subscriber errors / disable warnings. */ logger?: { warn(obj: Record | string, msg?: string): void; info?(obj: Record | string, msg?: string): void; error?(obj: Record | string, msg?: string): void; }; /** * Minimum interval between two reconnect-driven `flushLocal()` calls, * in milliseconds. A flood of `'ready'` events in quick succession * (e.g. ioredis cycling through `'reconnecting' → 'ready'` multiple * times) collapses into a single flush. Defaults to 1000ms. */ reconnectFlushDebounceMs?: number; } export interface InvalidateOptions { /** * When `true`, only purge the local L1 and do NOT publish (use when * reacting to a remote invalidation we already received). Defaults to * `false` (publish + purge). */ localOnly?: boolean; } export interface TwoTierCache { /** Read L1 first, fall back to L2, populate L1 on hit. */ get(key: string): Promise; /** Write both tiers. */ set(key: string, value: T): Promise; /** * Drop one key from both tiers and publish so peer L1s purge. * Pass `key = "*"` (or omit) to broadcast a wildcard flush — L1 is * cleared entirely; L2 entries expire on their own TTL. */ invalidate(key?: string, opts?: InvalidateOptions): Promise; /** Drop one key from L1 only (no L2, no PUBLISH). */ deleteLocal(key: string): void; /** Clear the entire L1. Useful on reconnect to recover lost invalidations. */ flushLocal(): void; /** * Start the subscriber. Must be called once per process per cache during * boot. Returns a disposer that stops the subscriber. No-op when * `pubsubEnabled === false`. */ subscribe(extraHandler?: (key: string) => void | Promise): Promise<() => Promise>; /** Returns the underlying L2 `CacheStore` (advanced / test access). */ readonly l2: CacheStore; /** Returns the L1 instance (advanced / test access). */ readonly l1: TwoTierL1Cache; /** Returns the namespace (debug / test). */ readonly namespace: string; } interface L1Entry { value: T; expiresAt: number; } class BoundedTtlL1Cache implements TwoTierL1Cache { private readonly map = new Map>(); private expiryQueue: Array<{ key: string; expiresAt: number }> = []; private expiryQueueHead = 0; constructor( private readonly maxEntries: number, private readonly ttlMs: number, private readonly clock: () => number, ) {} get(key: string): T | undefined { const entry = this.map.get(key); if (!entry) return undefined; if (entry.expiresAt <= this.clock()) { this.map.delete(key); return undefined; } // Reinsert hits so Map insertion order acts as an O(1) LRU queue. this.map.delete(key); this.map.set(key, entry); return entry.value; } set(key: string, value: T): void { const now = this.clock(); this.pruneExpired(now); this.map.delete(key); const expiresAt = now + this.ttlMs; this.map.set(key, { value, expiresAt }); this.expiryQueue.push({ key, expiresAt }); while (this.map.size > this.maxEntries) { const oldest = this.map.keys().next().value as string | undefined; if (oldest === undefined) break; this.map.delete(oldest); } } delete(key: string): boolean { return this.map.delete(key); } clear(): void { this.map.clear(); this.expiryQueue = []; this.expiryQueueHead = 0; } keys(): IterableIterator { this.pruneExpired(this.clock()); return this.map.keys(); } private pruneExpired(now: number): void { // Expiry order is independent from LRU order so cache hits cannot move an // expired entry behind a live one. Stale queue records from overwrites and // LRU evictions are ignored by comparing their timestamp with the map. while (this.expiryQueueHead < this.expiryQueue.length) { const candidate = this.expiryQueue[this.expiryQueueHead]; if (candidate.expiresAt > now) break; this.expiryQueueHead += 1; const current = this.map.get(candidate.key); if (current?.expiresAt === candidate.expiresAt) this.map.delete(candidate.key); } if (this.expiryQueueHead >= 1_024 && this.expiryQueueHead * 2 >= this.expiryQueue.length) { this.expiryQueue = this.expiryQueue.slice(this.expiryQueueHead); this.expiryQueueHead = 0; } } } /** * Build a two-tier cache: in-process L1 + SharedStore L2 + pub/sub * cross-replica invalidation. * * Reads probe L1 first (sub-microsecond), then L2 (one Redis GET), and * populate L1 on hit. Writes go to both tiers. `invalidate(key)` * deletes from both tiers locally and PUBLISHes the key on the * invalidation channel so peer replicas drop the same entry from * their L1 within milliseconds. * * Boot sequence on each process that needs L1: * * ```ts * const cache = createTwoTierCache({ store, namespace: "subscription", ttlSeconds: 300 }); * await cache.subscribe(); // start listening once per process * ``` */ export function createTwoTierCache(options: TwoTierCacheOptions): TwoTierCache { if (!options.namespace) { throw new Error("createTwoTierCache: namespace is required"); } if (options.ttlSeconds <= 0) { throw new Error("createTwoTierCache: ttlSeconds must be > 0"); } const l1MaxEntries = options.l1MaxEntries ?? 10_000; if (!Number.isSafeInteger(l1MaxEntries) || l1MaxEntries <= 0) { throw new Error("createTwoTierCache: l1MaxEntries must be a positive safe integer"); } const l1 = options.l1Cache ?? new BoundedTtlL1Cache(l1MaxEntries, options.ttlSeconds * 1_000, options.l1Now ?? (() => Date.now())); const l2 = createCacheStore({ store: options.store, prefix: options.namespace, ttlSeconds: options.ttlSeconds, serializer: options.serializer, invalidationChannel: options.invalidationChannel, }); const pubsubEnabled = options.pubsubEnabled !== false; const logger = options.logger; const reconnectDebounceMs = options.reconnectFlushDebounceMs ?? 1000; const flushLocal = (): void => { l1.clear(); }; let lastReconnectFlushAt = 0; const debouncedReconnectFlush = (): void => { const now = Date.now(); if (now - lastReconnectFlushAt < reconnectDebounceMs) { return; } lastReconnectFlushAt = now; flushLocal(); logger?.info?.( { component: "two-tier-cache", namespace: options.namespace }, `two-tier cache ${options.namespace}: redis reconnected, L1 flushed`, ); }; const deleteLocal = (key: string): void => { l1.delete(key); }; return { namespace: options.namespace, l1, l2, async get(key) { const hit = l1.get(key); if (hit !== undefined) return hit; const fromL2 = await l2.get(key); if (fromL2 !== null) { l1.set(key, fromL2); } return fromL2; }, async set(key, value) { l1.set(key, value); await l2.set(key, value); }, async invalidate(key, opts) { const localOnly = opts?.localOnly === true; // Local L1 purge first — every replica handles its own L1 on // invalidation receipt so this also covers `localOnly` paths. if (!key || key === "*") { flushLocal(); } else { deleteLocal(key); } if (localOnly || !pubsubEnabled) { // Best-effort L2 delete when targeting a specific key, so the // local replica does not serve a stale L2 on the next miss. if (key && key !== "*") { try { await l2.delete(key); } catch (err) { logger?.error?.({ component: "two-tier-cache", namespace: options.namespace, err }, "l2 delete failed"); } } return; } // Publishes and clears L2 (for specific keys) in one shot. try { await l2.invalidate(key); } catch (err) { logger?.error?.({ component: "two-tier-cache", namespace: options.namespace, err }, "l2 invalidate failed"); } }, deleteLocal, flushLocal, async subscribe(extraHandler) { if (!pubsubEnabled) { logger?.warn?.( { component: "two-tier-cache", namespace: options.namespace }, "two-tier-cache: pubsub disabled, subscriber not started", ); return async () => { /* no-op */ }; } const disposer = await l2.onInvalidate(async (key) => { try { if (!key || key === "*") { flushLocal(); } else { deleteLocal(key); } if (extraHandler) { await extraHandler(key); } } catch (err) { logger?.error?.( { component: "two-tier-cache", namespace: options.namespace, err, key }, "two-tier-cache: subscriber handler threw", ); } }); // Wire a reconnect-flush so invalidations published while the // Redis connection was down (and therefore lost — pub/sub has no // persistence) cannot leave this replica's L1 serving stale // values forever. On the memory adapter this is a noop disposer. const removeReconnect = options.store.adapter.onReconnect(() => { try { debouncedReconnectFlush(); } catch (err) { logger?.error?.( { component: "two-tier-cache", namespace: options.namespace, err }, "two-tier-cache: reconnect-flush handler threw", ); } }); return async () => { removeReconnect(); await disposer(); }; }, }; }