Track HiveGrid Cloud planning reference
This commit is contained in:
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();
|
||||
});
|
||||
});
|
||||
+176
@@ -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();
|
||||
};
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user