Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,123 @@
import { describe, expect, test } from "vitest";
import { MemoryAdapter } from "../adapters/memory.js";
import { createSharedStore } from "../factory.js";
import { createCacheStore } from "./cache.js";
interface User {
id: string;
name: string;
}
function buildCache(opts: { ttlSeconds?: number; now?: () => number } = {}) {
const adapter = new MemoryAdapter({ now: opts.now });
const store = createSharedStore({ namespace: "demo-cache", adapter });
const cache = createCacheStore<User>({ store, prefix: "users", ttlSeconds: opts.ttlSeconds ?? 60 });
return { store, cache };
}
describe("createCacheStore", () => {
test("set then get round-trips structured values", async () => {
const { store, cache } = buildCache();
await cache.set("u1", { id: "u1", name: "Alice" });
expect(await cache.get("u1")).toEqual({ id: "u1", name: "Alice" });
await store.close();
});
test("returns null for missing keys", async () => {
const { store, cache } = buildCache();
expect(await cache.get("missing")).toBeNull();
await store.close();
});
test("respects ttl", async () => {
let now = 0;
const { store, cache } = buildCache({ ttlSeconds: 1, now: () => now });
await cache.set("u1", { id: "u1", name: "A" });
now += 2_000;
expect(await cache.get("u1")).toBeNull();
await store.close();
});
test("delete removes a single entry", async () => {
const { store, cache } = buildCache();
await cache.set("u1", { id: "u1", name: "A" });
await cache.delete("u1");
expect(await cache.get("u1")).toBeNull();
await store.close();
});
test("corrupted entries are dropped on get instead of throwing", async () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "demo-cache", adapter });
const cache = createCacheStore<User>({ store, prefix: "users", ttlSeconds: 60 });
await store.set("cache:users:u1", "{not json"); // raw corrupt write
expect(await cache.get("u1")).toBeNull();
expect(await store.get("cache:users:u1")).toBeNull();
await store.close();
});
test("rejects ttl <= 0", () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "demo-cache", adapter });
expect(() => createCacheStore({ store, prefix: "x", ttlSeconds: 0 })).toThrow(/ttlSeconds/);
});
test("custom serializer round-trips values", async () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "demo-cache", adapter });
const cache = createCacheStore<number>({
store,
prefix: "nums",
ttlSeconds: 60,
serializer: { serialize: (v) => `n:${v}`, deserialize: (raw) => Number(raw.slice(2)) },
});
await cache.set("a", 42);
expect(await cache.get("a")).toBe(42);
await store.close();
});
});
describe("createCacheStore — invalidation pub/sub", () => {
test("invalidate publishes the key on the dedicated channel and clears the local entry", async () => {
const { store, cache } = buildCache();
const received: string[] = [];
const stop = await cache.onInvalidate((key) => {
received.push(key);
});
await cache.set("u1", { id: "u1", name: "A" });
await cache.invalidate("u1");
await new Promise((resolve) => setTimeout(resolve, 5));
expect(received).toEqual(["u1"]);
expect(await cache.get("u1")).toBeNull();
await stop();
await store.close();
});
test("invalidate() without key broadcasts a wildcard", async () => {
const { store, cache } = buildCache();
const received: string[] = [];
await cache.onInvalidate((key) => {
received.push(key);
});
await cache.invalidate();
await new Promise((resolve) => setTimeout(resolve, 5));
expect(received).toEqual(["*"]);
await store.close();
});
test("two caches sharing the adapter receive each other's invalidations", async () => {
const adapter = new MemoryAdapter();
const storeA = createSharedStore({ namespace: "demo-cache", adapter });
const storeB = createSharedStore({ namespace: "demo-cache", adapter });
const a = createCacheStore<User>({ store: storeA, prefix: "users", ttlSeconds: 60 });
const b = createCacheStore<User>({ store: storeB, prefix: "users", ttlSeconds: 60 });
const received: string[] = [];
await b.onInvalidate((key) => {
received.push(key);
});
await a.invalidate("u1");
await new Promise((resolve) => setTimeout(resolve, 5));
expect(received).toEqual(["u1"]);
await storeA.close();
});
});
@@ -0,0 +1,89 @@
import type { SharedStore } from "../factory.js";
export interface CacheSerializer<T> {
serialize(value: T): string;
deserialize(raw: string): T;
}
export interface CacheStoreOptions<T> {
store: SharedStore;
prefix: string;
ttlSeconds: number;
serializer?: CacheSerializer<T>;
/**
* Channel suffix used for cross-instance invalidation broadcasts.
* Defaults to `"invalidate"`.
*/
invalidationChannel?: string;
}
export interface CacheStore<T> {
get(key: string): Promise<T | null>;
set(key: string, value: T): Promise<void>;
delete(key: string): Promise<void>;
/**
* Publish an invalidation event so peers can drop their local memo.
* Pass a specific key to invalidate one entry, or `"*"` for the whole
* prefix. The local entry is also deleted when a key is supplied.
*/
invalidate(key?: string): Promise<void>;
/**
* Subscribe to invalidation events. The handler receives the key (or
* `"*"`). Returns an async disposer.
*/
onInvalidate(handler: (key: string) => void | Promise<void>): Promise<() => Promise<void>>;
}
const defaultJsonSerializer = <T>(): CacheSerializer<T> => ({
serialize: (value) => JSON.stringify(value),
deserialize: (raw) => JSON.parse(raw) as T,
});
/**
* JSON-cached values keyed under `cache:<prefix>:<key>`. The cache is
* paired with a pub/sub channel so peer replicas can be notified when
* an entry must be invalidated (e.g. after a Stripe webhook or admin
* edit). Cache misses cost one Redis round-trip; invalidation is a
* single PUBLISH.
*/
export function createCacheStore<T>(options: CacheStoreOptions<T>): CacheStore<T> {
if (options.ttlSeconds <= 0) {
throw new Error("createCacheStore: ttlSeconds must be > 0");
}
const serializer = options.serializer ?? defaultJsonSerializer<T>();
const store = options.store;
const channel = options.invalidationChannel ?? "invalidate";
const bucketKey = (key: string) => `cache:${options.prefix}:${key}`;
const channelName = `cache:${options.prefix}:${channel}`;
return {
async get(key) {
const raw = await store.get(bucketKey(key));
if (raw === null) return null;
try {
return serializer.deserialize(raw);
} catch {
// Corrupted entries are dropped rather than thrown so a single
// bad value cannot poison the cache forever.
await store.del(bucketKey(key));
return null;
}
},
async set(key, value) {
await store.set(bucketKey(key), serializer.serialize(value), { ttlSeconds: options.ttlSeconds });
},
async delete(key) {
await store.del(bucketKey(key));
},
async invalidate(key) {
const payload = key ?? "*";
if (key && key !== "*") {
await store.del(bucketKey(key));
}
await store.publish(channelName, payload);
},
async onInvalidate(handler) {
return store.subscribe(channelName, (msg) => handler(msg));
},
};
}
@@ -0,0 +1,95 @@
import { describe, expect, test } from "vitest";
import { MemoryAdapter } from "../adapters/memory.js";
import { createSharedStore } from "../factory.js";
import { createIdempotencyStore } from "./idempotency.js";
function build(opts: { ttlSeconds?: number; now?: () => number } = {}) {
const adapter = new MemoryAdapter({ now: opts.now });
const store = createSharedStore({ namespace: "idemp", adapter });
const idempotency = createIdempotencyStore({ store, prefix: "stripe", ttlSeconds: opts.ttlSeconds ?? 60 });
return { store, idempotency };
}
describe("createIdempotencyStore", () => {
test("first claim wins, second loses", async () => {
const { store, idempotency } = build();
expect(await idempotency.claim("k")).toBe(true);
expect(await idempotency.claim("k")).toBe(false);
await store.close();
});
test("claim then get returns pending state", async () => {
const { store, idempotency } = build();
await idempotency.claim("k");
expect(await idempotency.get("k")).toEqual({ state: "pending" });
await store.close();
});
test("complete persists the result", async () => {
const { store, idempotency } = build();
await idempotency.claim("k");
await idempotency.complete("k", { ok: true, value: 42 });
expect(await idempotency.get("k")).toEqual({ state: "complete", result: { ok: true, value: 42 } });
await store.close();
});
test("after ttl elapses a new claim is allowed", async () => {
let now = 0;
const { store, idempotency } = build({ ttlSeconds: 1, now: () => now });
expect(await idempotency.claim("k")).toBe(true);
now += 2_000;
expect(await idempotency.claim("k")).toBe(true);
await store.close();
});
test("complete also resets the ttl", async () => {
let now = 0;
const { store, idempotency } = build({ ttlSeconds: 5, now: () => now });
await idempotency.claim("k");
now += 4_000;
await idempotency.complete("k", "done");
now += 4_000;
expect(await idempotency.get("k")).toEqual({ state: "complete", result: "done" });
await store.close();
});
test("forget drops the key", async () => {
const { store, idempotency } = build();
await idempotency.claim("k");
await idempotency.forget("k");
expect(await idempotency.get("k")).toBeNull();
expect(await idempotency.claim("k")).toBe(true);
await store.close();
});
test("corrupt completed payload is evicted on read", async () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "idemp", adapter });
const idempotency = createIdempotencyStore({ store, prefix: "stripe", ttlSeconds: 60 });
await store.set("idempotency:stripe:k", "not-json");
expect(await idempotency.get("k")).toBeNull();
expect(await store.get("idempotency:stripe:k")).toBeNull();
await store.close();
});
test("rejects invalid ttl", () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "idemp", adapter });
expect(() => createIdempotencyStore({ store, prefix: "x", ttlSeconds: 0 })).toThrow(/ttlSeconds/);
});
test("get on a never-claimed key returns null", async () => {
const { store, idempotency } = build();
expect(await idempotency.get("missing")).toBeNull();
await store.close();
});
test("concurrent claims across many keys are independent", async () => {
const { store, idempotency } = build();
const results = await Promise.all(
Array.from({ length: 25 }, (_, idx) => idempotency.claim(`k-${idx}`)),
);
expect(results.every((r) => r)).toBe(true);
await store.close();
});
});
@@ -0,0 +1,66 @@
import type { SharedStore } from "../factory.js";
export interface IdempotencyStoreOptions {
store: SharedStore;
prefix: string;
ttlSeconds: number;
}
export type IdempotencyEntry =
| { state: "pending"; result?: undefined }
| { state: "complete"; result: unknown };
export interface IdempotencyStore {
/**
* Try to claim the key atomically. Returns `true` if this caller now
* owns the work, `false` if another caller already claimed it.
*/
claim(key: string): Promise<boolean>;
/** Mark the key as complete and persist the result. */
complete(key: string, result: unknown): Promise<void>;
/** Read the current state of a key, or `null` if it has not been claimed. */
get(key: string): Promise<IdempotencyEntry | null>;
/** Drop the key (rare — used by manual retries). */
forget(key: string): Promise<void>;
}
const PENDING_MARKER = "__pending__";
/**
* Idempotency-key store backed by SharedStore. `claim()` does a single
* `SET NX EX` round-trip so concurrent callers across replicas cannot
* both acquire the same key. `complete()` overwrites the placeholder
* with a JSON-encoded result and re-applies the TTL.
*/
export function createIdempotencyStore(options: IdempotencyStoreOptions): IdempotencyStore {
if (options.ttlSeconds <= 0) {
throw new Error("createIdempotencyStore: ttlSeconds must be > 0");
}
const store = options.store;
const keyFor = (key: string) => `idempotency:${options.prefix}:${key}`;
return {
async claim(key) {
return store.set(keyFor(key), PENDING_MARKER, { nx: true, ttlSeconds: options.ttlSeconds });
},
async complete(key, result) {
const payload = JSON.stringify({ result });
await store.set(keyFor(key), payload, { ttlSeconds: options.ttlSeconds });
},
async get(key) {
const raw = await store.get(keyFor(key));
if (raw === null) return null;
if (raw === PENDING_MARKER) return { state: "pending" };
try {
const parsed = JSON.parse(raw) as { result: unknown };
return { state: "complete", result: parsed.result };
} catch {
await store.del(keyFor(key));
return null;
}
},
async forget(key) {
await store.del(keyFor(key));
},
};
}
@@ -0,0 +1,25 @@
export {
createFixedWindowRateLimiter,
type FixedWindowDecision,
type FixedWindowRateLimiter,
type FixedWindowRateLimiterOptions,
} from "./rate-limit-fixed.js";
export {
createSlidingWindowRateLimiter,
type SlidingWindowDecision,
type SlidingWindowRateLimiter,
type SlidingWindowRateLimiterOptions,
} from "./rate-limit-sliding.js";
export {
createCacheStore,
type CacheStore,
type CacheStoreOptions,
type CacheSerializer,
} from "./cache.js";
export { createSessionStore, type SessionStore, type SessionStoreOptions } from "./session.js";
export {
createIdempotencyStore,
type IdempotencyStore,
type IdempotencyStoreOptions,
type IdempotencyEntry,
} from "./idempotency.js";
@@ -0,0 +1,82 @@
import { afterEach, describe, expect, test, vi } from "vitest";
import { MemoryAdapter } from "../adapters/memory.js";
import { createSharedStore } from "../factory.js";
import { createFixedWindowRateLimiter } from "./rate-limit-fixed.js";
afterEach(() => {
vi.useRealTimers();
});
function buildLimiter(opts: { windowSeconds?: number; max?: number; now?: () => number } = {}) {
const adapter = new MemoryAdapter({ now: opts.now });
const store = createSharedStore({ namespace: "ratelimit", adapter });
const limiter = createFixedWindowRateLimiter({
store,
prefix: "ip",
windowSeconds: opts.windowSeconds ?? 60,
max: opts.max ?? 3,
});
return { store, limiter };
}
describe("createFixedWindowRateLimiter", () => {
test("allows up to max calls in a window", async () => {
const { limiter, store } = buildLimiter();
expect((await limiter.consume("k")).allowed).toBe(true);
expect((await limiter.consume("k")).allowed).toBe(true);
const third = await limiter.consume("k");
expect(third.allowed).toBe(true);
expect(third.remaining).toBe(0);
const fourth = await limiter.consume("k");
expect(fourth.allowed).toBe(false);
expect(fourth.remaining).toBe(0);
await store.close();
});
test("isolates buckets by key", async () => {
const { limiter, store } = buildLimiter({ max: 1 });
expect((await limiter.consume("a")).allowed).toBe(true);
expect((await limiter.consume("b")).allowed).toBe(true);
expect((await limiter.consume("a")).allowed).toBe(false);
await store.close();
});
test("resets after the window expires", async () => {
let now = 1_000;
const { limiter, store } = buildLimiter({ windowSeconds: 1, max: 1, now: () => now });
expect((await limiter.consume("k")).allowed).toBe(true);
expect((await limiter.consume("k")).allowed).toBe(false);
now += 2_000;
expect((await limiter.consume("k")).allowed).toBe(true);
await store.close();
});
test("reset() drops the counter", async () => {
const { limiter, store } = buildLimiter({ max: 1 });
expect((await limiter.consume("k")).allowed).toBe(true);
expect((await limiter.consume("k")).allowed).toBe(false);
await limiter.reset("k");
expect((await limiter.consume("k")).allowed).toBe(true);
await store.close();
});
test("rejects invalid configuration", () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "ratelimit", adapter });
expect(() =>
createFixedWindowRateLimiter({ store, prefix: "x", windowSeconds: 0, max: 1 }),
).toThrow(/windowSeconds/);
expect(() =>
createFixedWindowRateLimiter({ store, prefix: "x", windowSeconds: 1, max: 0 }),
).toThrow(/max/);
});
test("reports a sensible resetAt", async () => {
const { limiter, store } = buildLimiter({ windowSeconds: 30, max: 5 });
const decision = await limiter.consume("k");
const delta = decision.resetAt.getTime() - Date.now();
expect(delta).toBeGreaterThan(10_000);
expect(delta).toBeLessThanOrEqual(30_000);
await store.close();
});
});
@@ -0,0 +1,90 @@
import { MemoryAdapter } from "../adapters/memory.js";
import type { SharedStore } from "../factory.js";
export interface FixedWindowRateLimiterOptions {
store: SharedStore;
/** Sub-namespace for this limiter (e.g. `"login-ip"`). */
prefix: string;
/** Window length in seconds. */
windowSeconds: number;
/** Allowed actions per window. */
max: number;
}
export interface FixedWindowDecision {
/** True when the request is below the cap. */
allowed: boolean;
/** How many actions are still permitted in the current window. */
remaining: number;
/** Wall-clock time when the current window resets. */
resetAt: Date;
}
export interface FixedWindowRateLimiter {
consume(key: string): Promise<FixedWindowDecision>;
/** Test/admin helper: drop the counter for a key. */
reset(key: string): Promise<void>;
}
const FIXED_WINDOW_SCRIPT = `
local current = redis.call('INCR', KEYS[1])
if current == 1 then
redis.call('EXPIRE', KEYS[1], tonumber(ARGV[1]))
end
local ttl = redis.call('TTL', KEYS[1])
return { current, ttl }
`;
// Register the memory-adapter equivalent so the same eval() call works
// against both backends. The memory adapter resolves scripts by exact
// string match.
MemoryAdapter.registerScript(FIXED_WINDOW_SCRIPT, async (adapter, keys, args) => {
const [key] = keys;
const window = Number.parseInt(args[0] ?? "0", 10);
const current = await adapter.incr(key);
if (current === 1 && window > 0) {
await adapter.expire(key, window);
}
// We do not implement TTL command on the adapter surface; the helper
// computes resetAt locally for the memory case.
return [current, window];
});
/**
* Create a Redis-style fixed-window rate limiter. The window starts on
* the first `consume()` call and resets after `windowSeconds`. The
* decision is computed atomically in Redis via Lua (and sequentially,
* race-free, in the memory adapter).
*/
export function createFixedWindowRateLimiter(options: FixedWindowRateLimiterOptions): FixedWindowRateLimiter {
if (options.windowSeconds <= 0) {
throw new Error("createFixedWindowRateLimiter: windowSeconds must be > 0");
}
if (options.max <= 0) {
throw new Error("createFixedWindowRateLimiter: max must be > 0");
}
const store = options.store;
const bucketKey = (key: string) => `rl:fixed:${options.prefix}:${key}`;
return {
async consume(key) {
const fullKey = store.key(bucketKey(key));
const result = (await store.adapter.eval(FIXED_WINDOW_SCRIPT, [fullKey], [String(options.windowSeconds)])) as
| [number | string, number | string]
| undefined;
const current = Number(result?.[0] ?? 0);
const ttlReported = Number(result?.[1] ?? options.windowSeconds);
const ttl = ttlReported > 0 ? ttlReported : options.windowSeconds;
const remaining = Math.max(0, options.max - current);
return {
allowed: current <= options.max,
remaining,
resetAt: new Date(Date.now() + ttl * 1000),
};
},
async reset(key) {
await store.del(bucketKey(key));
},
};
}
@@ -0,0 +1,73 @@
import { describe, expect, test } from "vitest";
import { MemoryAdapter } from "../adapters/memory.js";
import { createSharedStore } from "../factory.js";
import { createSlidingWindowRateLimiter } from "./rate-limit-sliding.js";
function buildLimiter(opts: { windowSeconds?: number; max?: number; now?: () => number } = {}) {
const adapter = new MemoryAdapter({ now: opts.now });
const store = createSharedStore({ namespace: "rl-sliding", adapter });
const limiter = createSlidingWindowRateLimiter({
store,
prefix: "ip",
windowSeconds: opts.windowSeconds ?? 1,
max: opts.max ?? 3,
now: opts.now,
});
return { store, limiter };
}
describe("createSlidingWindowRateLimiter", () => {
test("allows up to max calls inside a window", async () => {
let now = 1_000_000;
const { limiter, store } = buildLimiter({ windowSeconds: 10, max: 3, now: () => now });
expect((await limiter.consume("k")).allowed).toBe(true);
expect((await limiter.consume("k")).allowed).toBe(true);
const third = await limiter.consume("k");
expect(third.allowed).toBe(true);
expect(third.remaining).toBe(0);
expect((await limiter.consume("k")).allowed).toBe(false);
await store.close();
});
test("trims old entries as the window slides", async () => {
let now = 0;
const { limiter, store } = buildLimiter({ windowSeconds: 1, max: 2, now: () => now });
await limiter.consume("k");
await limiter.consume("k");
expect((await limiter.consume("k")).allowed).toBe(false);
now += 1_500;
expect((await limiter.consume("k")).allowed).toBe(true);
await store.close();
});
test("isolates per-key buckets", async () => {
const { limiter, store } = buildLimiter({ windowSeconds: 60, max: 1 });
expect((await limiter.consume("a")).allowed).toBe(true);
expect((await limiter.consume("b")).allowed).toBe(true);
expect((await limiter.consume("a")).allowed).toBe(false);
await store.close();
});
test("reset clears the bucket", async () => {
const { limiter, store } = buildLimiter({ windowSeconds: 60, max: 1 });
await limiter.consume("k");
expect((await limiter.consume("k")).allowed).toBe(false);
await limiter.reset("k");
expect((await limiter.consume("k")).allowed).toBe(true);
await store.close();
});
test("rejects invalid configuration", () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "rl-sliding", adapter });
expect(() => createSlidingWindowRateLimiter({ store, prefix: "x", windowSeconds: 0, max: 1 })).toThrow(/windowSeconds/);
expect(() => createSlidingWindowRateLimiter({ store, prefix: "x", windowSeconds: 1, max: 0 })).toThrow(/max/);
});
test("returns oldestAt for the current consume call", async () => {
const { limiter, store } = buildLimiter({ windowSeconds: 60, max: 5 });
const decision = await limiter.consume("k");
expect(decision.oldestAt).not.toBeNull();
await store.close();
});
});
@@ -0,0 +1,107 @@
import { MemoryAdapter } from "../adapters/memory.js";
import type { SharedStore } from "../factory.js";
export interface SlidingWindowRateLimiterOptions {
store: SharedStore;
prefix: string;
windowSeconds: number;
max: number;
/** Override the clock (test only). Defaults to `Date.now`. */
now?: () => number;
}
export interface SlidingWindowDecision {
allowed: boolean;
remaining: number;
/** Timestamp of the oldest event inside the current window, if any. */
oldestAt: Date | null;
}
export interface SlidingWindowRateLimiter {
consume(key: string): Promise<SlidingWindowDecision>;
reset(key: string): Promise<void>;
}
// Lua script: trim old entries, count remaining, append the new one and
// extend the key TTL. Returns the count *after* the new entry was
// inserted.
const SLIDING_WINDOW_SCRIPT = `
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local member = ARGV[3]
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
local count = redis.call('ZCARD', key)
redis.call('ZADD', key, now, member)
redis.call('EXPIRE', key, math.ceil(window / 1000) + 1)
local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
return { count + 1, oldest[2] or '' }
`;
MemoryAdapter.registerScript(SLIDING_WINDOW_SCRIPT, async (adapter, keys, args) => {
const [key] = keys;
const now = Number(args[0]);
const windowMs = Number(args[1]);
const member = args[2];
await adapter.zRemRangeByScore(key, 0, now - windowMs);
const before = await adapter.zCard(key);
await adapter.zAdd(key, now, member);
await adapter.expire(key, Math.ceil(windowMs / 1000) + 1);
return [before + 1, ""];
});
/**
* Sorted-set sliding-window limiter. Each `consume` records the current
* timestamp; entries older than `windowSeconds` are trimmed before the
* count is taken so the window slides continuously instead of resetting
* on a fixed boundary.
*/
export function createSlidingWindowRateLimiter(
options: SlidingWindowRateLimiterOptions,
): SlidingWindowRateLimiter {
if (options.windowSeconds <= 0) {
throw new Error("createSlidingWindowRateLimiter: windowSeconds must be > 0");
}
if (options.max <= 0) {
throw new Error("createSlidingWindowRateLimiter: max must be > 0");
}
const store = options.store;
const windowMs = options.windowSeconds * 1000;
const clock = options.now ?? (() => Date.now());
let seq = 0;
const bucketKey = (key: string) => `rl:sliding:${options.prefix}:${key}`;
return {
async consume(key) {
const now = clock();
seq += 1;
const member = `${now}:${seq}`;
const fullKey = store.key(bucketKey(key));
const result = (await store.adapter.eval(
SLIDING_WINDOW_SCRIPT,
[fullKey],
[String(now), String(windowMs), member],
)) as [number | string, string | number] | undefined;
const count = Number(result?.[0] ?? 0);
const oldestRaw = String(result?.[1] ?? "");
let oldestAt: Date | null = null;
if (oldestRaw) {
const parsed = Number(oldestRaw);
if (Number.isFinite(parsed)) oldestAt = new Date(parsed);
}
if (!oldestAt) {
// Memory adapter doesn't surface the oldest entry; approximate
// with the current timestamp which is the conservative answer.
oldestAt = new Date(now);
}
return {
allowed: count <= options.max,
remaining: Math.max(0, options.max - count),
oldestAt,
};
},
async reset(key) {
await store.del(bucketKey(key));
},
};
}
@@ -0,0 +1,82 @@
import { describe, expect, test } from "vitest";
import { MemoryAdapter } from "../adapters/memory.js";
import { createSharedStore } from "../factory.js";
import { createSessionStore } from "./session.js";
interface SessionData {
userId: string;
role: "admin" | "user";
}
function buildSession(opts: { ttlSeconds?: number; now?: () => number } = {}) {
const adapter = new MemoryAdapter({ now: opts.now });
const store = createSharedStore({ namespace: "session-test", adapter });
const sessions = createSessionStore<SessionData>({ store, prefix: "web", ttlSeconds: opts.ttlSeconds ?? 60 });
return { store, sessions };
}
describe("createSessionStore", () => {
test("set then get round-trips payload", async () => {
const { store, sessions } = buildSession();
await sessions.set("s1", { userId: "u1", role: "admin" });
expect(await sessions.get("s1")).toEqual({ userId: "u1", role: "admin" });
await store.close();
});
test("get returns null for missing sessions", async () => {
const { store, sessions } = buildSession();
expect(await sessions.get("missing")).toBeNull();
await store.close();
});
test("ttl elapses without touch", async () => {
let now = 0;
const { store, sessions } = buildSession({ ttlSeconds: 1, now: () => now });
await sessions.set("s1", { userId: "u1", role: "user" });
now += 2_000;
expect(await sessions.get("s1")).toBeNull();
await store.close();
});
test("touch refreshes the ttl", async () => {
let now = 0;
const { store, sessions } = buildSession({ ttlSeconds: 5, now: () => now });
await sessions.set("s1", { userId: "u1", role: "user" });
now += 4_000;
expect(await sessions.touch("s1")).toBe(true);
now += 4_000;
// Still alive because touch reset the 5s window.
expect(await sessions.get("s1")).not.toBeNull();
await store.close();
});
test("touch on missing session returns false", async () => {
const { store, sessions } = buildSession();
expect(await sessions.touch("nope")).toBe(false);
await store.close();
});
test("destroy removes the session", async () => {
const { store, sessions } = buildSession();
await sessions.set("s1", { userId: "u1", role: "user" });
await sessions.destroy("s1");
expect(await sessions.get("s1")).toBeNull();
await store.close();
});
test("corrupt payload is dropped on read", async () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "session-test", adapter });
const sessions = createSessionStore<SessionData>({ store, prefix: "web", ttlSeconds: 60 });
await store.set("session:web:s1", "not-json");
expect(await sessions.get("s1")).toBeNull();
expect(await store.get("session:web:s1")).toBeNull();
await store.close();
});
test("rejects invalid ttl", () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "session-test", adapter });
expect(() => createSessionStore({ store, prefix: "x", ttlSeconds: 0 })).toThrow(/ttlSeconds/);
});
});
@@ -0,0 +1,50 @@
import type { SharedStore } from "../factory.js";
export interface SessionStoreOptions {
store: SharedStore;
prefix: string;
ttlSeconds: number;
}
export interface SessionStore<TData = unknown> {
get(sessionId: string): Promise<TData | null>;
set(sessionId: string, data: TData): Promise<void>;
destroy(sessionId: string): Promise<void>;
/** Reset the TTL on an existing session without rewriting payload. */
touch(sessionId: string): Promise<boolean>;
}
/**
* Session-data helper. Sessions are JSON-encoded and TTL'd; `touch`
* refreshes the TTL so active users do not get logged out mid-request.
* TTL is mandatory — sessions must never live forever in the cache.
*/
export function createSessionStore<TData = unknown>(options: SessionStoreOptions): SessionStore<TData> {
if (options.ttlSeconds <= 0) {
throw new Error("createSessionStore: ttlSeconds must be > 0");
}
const store = options.store;
const keyFor = (sessionId: string) => `session:${options.prefix}:${sessionId}`;
return {
async get(sessionId) {
const raw = await store.get(keyFor(sessionId));
if (raw === null) return null;
try {
return JSON.parse(raw) as TData;
} catch {
await store.del(keyFor(sessionId));
return null;
}
},
async set(sessionId, data) {
await store.set(keyFor(sessionId), JSON.stringify(data), { ttlSeconds: options.ttlSeconds });
},
async destroy(sessionId) {
await store.del(keyFor(sessionId));
},
async touch(sessionId) {
return store.expire(keyFor(sessionId), options.ttlSeconds);
},
};
}
@@ -0,0 +1,192 @@
import { afterEach, describe, expect, test, vi } from "vitest";
import { MemoryAdapter } from "../adapters/memory.js";
import { createSharedStore } from "../factory.js";
import { createTwoTierCache } from "./two-tier-cache.js";
interface Value {
id: string;
name: string;
}
function buildPair(opts: { pubsubEnabled?: boolean } = {}) {
const adapter = new MemoryAdapter();
const storeA = createSharedStore({ namespace: "ns", adapter });
const storeB = createSharedStore({ namespace: "ns", adapter });
const a = createTwoTierCache<Value>({
store: storeA,
namespace: "subscription",
ttlSeconds: 60,
pubsubEnabled: opts.pubsubEnabled,
});
const b = createTwoTierCache<Value>({
store: storeB,
namespace: "subscription",
ttlSeconds: 60,
pubsubEnabled: opts.pubsubEnabled,
});
return { a, b, storeA, storeB };
}
async function flushPubSubMicrotasks() {
await Promise.resolve();
await Promise.resolve();
}
describe("createTwoTierCache", () => {
afterEach(() => {
vi.useRealTimers();
});
test("set populates both tiers; get returns from L1 without hitting L2 a second time", async () => {
const { a, storeA } = buildPair();
await a.set("t1", { id: "t1", name: "Alpha" });
// L1 hit
expect(a.l1.get("t1")).toEqual({ id: "t1", name: "Alpha" });
// L2 hit
expect(await a.l2.get("t1")).toEqual({ id: "t1", name: "Alpha" });
expect(await a.get("t1")).toEqual({ id: "t1", name: "Alpha" });
await storeA.close();
});
test("get falls back to L2 on L1 miss and populates L1", async () => {
const { a, storeA } = buildPair();
// Write through L2 directly so L1 is cold.
await a.l2.set("t1", { id: "t1", name: "Alpha" });
expect(a.l1.get("t1")).toBeUndefined();
expect(await a.get("t1")).toEqual({ id: "t1", name: "Alpha" });
expect(a.l1.get("t1")).toEqual({ id: "t1", name: "Alpha" });
await storeA.close();
});
test("invalidate(key) clears local L1+L2 and publishes so peer L1 drops the same key", async () => {
const { a, b, storeA } = buildPair();
await a.set("t1", { id: "t1", name: "Alpha" });
await b.set("t1", { id: "t1", name: "Alpha" });
await b.subscribe();
await a.invalidate("t1");
await flushPubSubMicrotasks();
expect(a.l1.get("t1")).toBeUndefined();
expect(b.l1.get("t1")).toBeUndefined();
await storeA.close();
});
test("invalidate() with no key broadcasts wildcard and clears every L1", async () => {
const { a, b, storeA } = buildPair();
await a.set("k1", { id: "k1", name: "x" });
await a.set("k2", { id: "k2", name: "y" });
await b.set("k1", { id: "k1", name: "x" });
await b.subscribe();
await a.invalidate();
await flushPubSubMicrotasks();
expect(Array.from(a.l1.keys())).toEqual([]);
expect(Array.from(b.l1.keys())).toEqual([]);
await storeA.close();
});
test("invalidate({ localOnly: true }) does NOT publish — peer L1 stays warm", async () => {
const { a, b, storeA } = buildPair();
await a.set("t1", { id: "t1", name: "x" });
await b.set("t1", { id: "t1", name: "x" });
await b.subscribe();
await a.invalidate("t1", { localOnly: true });
await flushPubSubMicrotasks();
expect(a.l1.get("t1")).toBeUndefined();
expect(b.l1.get("t1")).toEqual({ id: "t1", name: "x" });
await storeA.close();
});
test("pubsubEnabled=false makes subscribe a no-op and skips PUBLISH", async () => {
const { a, b, storeA } = buildPair({ pubsubEnabled: false });
await a.set("t1", { id: "t1", name: "x" });
await b.set("t1", { id: "t1", name: "x" });
const dispose = await b.subscribe();
await a.invalidate("t1");
await flushPubSubMicrotasks();
// local L1 always cleared on the invalidator
expect(a.l1.get("t1")).toBeUndefined();
// peer L1 stays warm because PUBLISH was skipped
expect(b.l1.get("t1")).toEqual({ id: "t1", name: "x" });
await dispose();
await storeA.close();
});
test("subscribe forwards key to extra handler", async () => {
const { a, b, storeA } = buildPair();
const handler = vi.fn();
await b.subscribe(handler);
await a.invalidate("t1");
await flushPubSubMicrotasks();
expect(handler).toHaveBeenCalledWith("t1");
await storeA.close();
});
test("rejects ttl <= 0 and missing namespace", () => {
const adapter = new MemoryAdapter();
const store = createSharedStore({ namespace: "ns", adapter });
expect(() => createTwoTierCache({ store, namespace: "x", ttlSeconds: 0 })).toThrow(/ttlSeconds/);
expect(() => createTwoTierCache({ store, namespace: "", ttlSeconds: 60 })).toThrow(/namespace/);
});
test("flushLocal clears the entire L1 (recovery path after reconnect)", async () => {
const { a, storeA } = buildPair();
await a.set("t1", { id: "t1", name: "x" });
await a.set("t2", { id: "t2", name: "y" });
a.flushLocal();
expect(Array.from(a.l1.keys())).toEqual([]);
// L2 still has the entries
expect(await a.l2.get("t1")).toEqual({ id: "t1", name: "x" });
await storeA.close();
});
test("subscribe() registers a reconnect handler that flushes L1 (debounced)", async () => {
vi.useFakeTimers({ now: new Date("2026-05-28T00:00:00.000Z") });
// Build a SharedStore whose adapter exposes a controllable
// reconnect trigger so we can simulate a Redis 'ready' event.
const memoryAdapter = new MemoryAdapter();
const reconnectHandlers = new Set<() => void | Promise<void>>();
const proxyAdapter = new Proxy(memoryAdapter, {
get(target, prop, receiver) {
if (prop === "onReconnect") {
return (handler: () => void | Promise<void>) => {
reconnectHandlers.add(handler);
return () => {
reconnectHandlers.delete(handler);
};
};
}
const value = Reflect.get(target, prop, receiver);
return typeof value === "function" ? value.bind(target) : value;
},
});
const store = createSharedStore({ namespace: "ns", adapter: proxyAdapter });
const cache = createTwoTierCache<Value>({
store,
namespace: "subscription",
ttlSeconds: 60,
reconnectFlushDebounceMs: 50,
});
const dispose = await cache.subscribe();
await cache.set("t1", { id: "t1", name: "x" });
expect(cache.l1.get("t1")).toEqual({ id: "t1", name: "x" });
// Fire the reconnect event — handler should flush L1.
for (const h of reconnectHandlers) await h();
expect(cache.l1.get("t1")).toBeUndefined();
// Re-populate; a second reconnect within the debounce window MUST
// NOT flush again (proves debounce works).
await cache.set("t2", { id: "t2", name: "y" });
for (const h of reconnectHandlers) await h();
expect(cache.l1.get("t2")).toEqual({ id: "t2", name: "y" });
// After the debounce window elapses, the next reconnect flushes.
vi.advanceTimersByTime(60);
for (const h of reconnectHandlers) await h();
expect(cache.l1.get("t2")).toBeUndefined();
// Disposer must remove the reconnect handler too.
await dispose();
expect(reconnectHandlers.size).toBe(0);
await store.close();
});
});
@@ -0,0 +1,176 @@
// Real-Redis integration test for the two-tier cache. Skipped by
// default — opt-in either by exporting `PUBSUB_TEST_REDIS_URL` (any
// reachable Redis) or by ensuring Docker is available so the suite
// can spin up its own container via `testcontainers`. Mirrors the
// `packages/db/src/outbox-claim.test.ts` opt-in pattern: the file
// must NEVER fail by default.
//
// The boot happens at module top-level (with a hard timeout) so vitest
// can decide before registration whether to skip the suite. This
// sidesteps the chicken-and-egg where `beforeAll` would never run if
// every test was already statically marked `.skipIf(true)`.
import type { StartedTestContainer } from "testcontainers";
import { afterAll, describe, expect, it } from "vitest";
import { RedisAdapter } from "../adapters/redis.js";
import { createSharedStore } from "../factory.js";
import { createTwoTierCache } from "./two-tier-cache.js";
interface Value {
id: string;
name: string;
}
const explicitUrl = process.env.PUBSUB_TEST_REDIS_URL?.trim();
const dockerOptOut = process.env.PUBSUB_TEST_USE_DOCKER === "false";
interface Backend {
redisUrl: string;
container?: StartedTestContainer;
}
async function bootBackend(): Promise<Backend | undefined> {
if (explicitUrl) {
return { redisUrl: explicitUrl };
}
if (dockerOptOut) return undefined;
try {
const { GenericContainer } = await import("testcontainers");
const started = await new GenericContainer("redis:7-alpine").withExposedPorts(6379).start();
const host = started.getHost();
const port = started.getMappedPort(6379);
return { redisUrl: `redis://${host}:${port}`, container: started };
} catch (err) {
// eslint-disable-next-line no-console
console.warn(
"[two-tier-cache.testcontainers] skipping: could not start Redis container —",
err instanceof Error ? err.message : err,
);
return undefined;
}
}
// Top-level await — vitest 3 + ESM permit this and it lets the describe
// block see a concrete boolean at registration time.
const backend = await bootBackend();
const skip = !backend;
const redisUrl = backend?.redisUrl;
function buildCachePair(opts: { db?: number } = {}) {
if (!redisUrl) throw new Error("redisUrl not initialised");
const adapterA = new RedisAdapter({ redisUrl, db: opts.db ?? 7 });
const adapterB = new RedisAdapter({ redisUrl, db: opts.db ?? 7 });
const storeA = createSharedStore({ namespace: "ns", adapter: adapterA });
const storeB = createSharedStore({ namespace: "ns", adapter: adapterB });
const cacheA = createTwoTierCache<Value>({
store: storeA,
namespace: "two-tier-it",
ttlSeconds: 60,
reconnectFlushDebounceMs: 50,
});
const cacheB = createTwoTierCache<Value>({
store: storeB,
namespace: "two-tier-it",
ttlSeconds: 60,
reconnectFlushDebounceMs: 50,
});
return { cacheA, cacheB, storeA, storeB, adapterA, adapterB };
}
afterAll(async () => {
if (backend?.container) {
try {
await backend.container.stop();
} catch {
/* best effort */
}
}
}, 30_000);
describe.skipIf(skip)("two-tier cache against real Redis (integration)", () => {
it("fans out invalidations across instances via pub/sub", async () => {
const { cacheA, cacheB, storeA, storeB } = buildCachePair();
try {
await cacheB.subscribe();
await cacheA.set("k1", { id: "k1", name: "Alpha" });
// Cross-instance read goes through L2, not L1.
expect(await cacheB.get("k1")).toEqual({ id: "k1", name: "Alpha" });
expect(cacheB.l1.get("k1")).toEqual({ id: "k1", name: "Alpha" });
await cacheA.invalidate("k1");
// Pub/sub fan-out is async; give the subscriber a moment.
await new Promise((resolve) => setTimeout(resolve, 100));
expect(cacheB.l1.get("k1")).toBeUndefined();
expect(await cacheB.get("k1")).toBeNull();
} finally {
await storeA.close();
await storeB.close();
}
}, 30_000);
it("flushes L1 after a redis reconnect", async () => {
const { cacheA, storeA, adapterA } = buildCachePair();
try {
await cacheA.subscribe();
await cacheA.set("k1", { id: "k1", name: "x" });
await cacheA.set("k2", { id: "k2", name: "y" });
expect(cacheA.l1.get("k1")).toEqual({ id: "k1", name: "x" });
// Force a disconnect on the primary client and let ioredis
// reconnect on its own. We poke the internal client because the
// adapter doesn't expose a "kill connection" API — this is the
// narrowest possible test seam.
await reconnectPrimary(adapterA);
// Wait for the debounced reconnect-flush handler to land.
await new Promise((resolve) => setTimeout(resolve, 200));
expect(Array.from(cacheA.l1.keys())).toEqual([]);
// L2 still has the entries — repopulating from L2 must work.
expect(await cacheA.get("k1")).toEqual({ id: "k1", name: "x" });
} finally {
await storeA.close();
}
}, 30_000);
it("after disconnect+reconnect, a peer's L2 mutation is visible because L1 was flushed", async () => {
const { cacheA, cacheB, storeA, storeB, adapterA } = buildCachePair();
try {
await cacheA.subscribe();
await cacheA.set("kx", { id: "kx", name: "v1" });
expect(cacheA.l1.get("kx")).toEqual({ id: "kx", name: "v1" });
// Disconnect A; while A is down, B mutates L2 directly. The
// invalidate-publish from B never reaches A — pub/sub has no
// persistence.
await cacheB.set("kx", { id: "kx", name: "v2" });
await reconnectPrimary(adapterA);
await new Promise((resolve) => setTimeout(resolve, 200));
expect(cacheA.l1.get("kx")).toBeUndefined();
expect(await cacheA.get("kx")).toEqual({ id: "kx", name: "v2" });
} finally {
await storeA.close();
await storeB.close();
}
}, 30_000);
});
/**
* Force ioredis to cycle through `'reconnecting'` → `'ready'` so the
* adapter's onReconnect handlers fire. `disconnect(true)` schedules an
* automatic reconnect; calling `connect()` ourselves races against
* that and frequently throws `Redis is already connecting/connected`.
*/
async function reconnectPrimary(adapter: RedisAdapter): Promise<void> {
type IoRedisLike = {
disconnect(reconnect?: boolean): void;
once(event: string, listener: () => void): unknown;
status?: string;
};
const primary = (adapter as unknown as { primary: IoRedisLike }).primary;
const ready = new Promise<void>((resolve) => {
primary.once("ready", () => resolve());
});
primary.disconnect(true);
await ready;
}
@@ -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();
};
},
};
}