Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/shared-store/src/helpers/two-tier-cache.ts
T

341 lines
11 KiB
TypeScript

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<string, T>` and `LRUCache<string, T>` satisfy this shape so the
* caller can pick whatever fits their memory/eviction strategy.
*/
export interface TwoTierL1Cache<T> {
get(key: string): T | undefined;
set(key: string, value: T): void;
delete(key: string): boolean | void;
clear(): void;
keys(): IterableIterator<string> | Iterable<string>;
}
export interface TwoTierCacheOptions<T> {
/** 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<T>;
/** 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<T>;
/**
* Suffix used for the pub/sub channel inside the namespace. Defaults
* to `"invalidate"`, producing channel
* `shared-store:<store-namespace>:ch:cache:<namespace>: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, unknown> | string, msg?: string): void;
info?(obj: Record<string, unknown> | string, msg?: string): void;
error?(obj: Record<string, unknown> | 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<T> {
/** Read L1 first, fall back to L2, populate L1 on hit. */
get(key: string): Promise<T | null>;
/** Write both tiers. */
set(key: string, value: T): Promise<void>;
/**
* 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<void>;
/** 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<void>): Promise<() => Promise<void>>;
/** Returns the underlying L2 `CacheStore` (advanced / test access). */
readonly l2: CacheStore<T>;
/** Returns the L1 instance (advanced / test access). */
readonly l1: TwoTierL1Cache<T>;
/** Returns the namespace (debug / test). */
readonly namespace: string;
}
interface L1Entry<T> {
value: T;
expiresAt: number;
}
class BoundedTtlL1Cache<T> implements TwoTierL1Cache<T> {
private readonly map = new Map<string, L1Entry<T>>();
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<string> {
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<MyValue>({ store, namespace: "subscription", ttlSeconds: 300 });
* await cache.subscribe(); // start listening once per process
* ```
*/
export function createTwoTierCache<T>(options: TwoTierCacheOptions<T>): TwoTierCache<T> {
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<T>(l1MaxEntries, options.ttlSeconds * 1_000, options.l1Now ?? (() => Date.now()));
const l2 = createCacheStore<T>({
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();
};
},
};
}