Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
+274
@@ -0,0 +1,274 @@
|
||||
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 `Map` with no
|
||||
* eviction; pass an `LRUCache` if you need bounded memory.
|
||||
*/
|
||||
l1Cache?: TwoTierL1Cache<T>;
|
||||
/** 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;
|
||||
}
|
||||
|
||||
class MapL1Cache<T> implements TwoTierL1Cache<T> {
|
||||
private readonly map = new Map<string, T>();
|
||||
get(key: string): T | undefined {
|
||||
return this.map.get(key);
|
||||
}
|
||||
set(key: string, value: T): void {
|
||||
this.map.set(key, value);
|
||||
}
|
||||
delete(key: string): boolean {
|
||||
return this.map.delete(key);
|
||||
}
|
||||
clear(): void {
|
||||
this.map.clear();
|
||||
}
|
||||
keys(): IterableIterator<string> {
|
||||
return this.map.keys();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 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 l1 = options.l1Cache ?? new MapL1Cache<T>();
|
||||
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();
|
||||
};
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user