Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
+49
@@ -191,6 +191,40 @@ describe("MemoryAdapter — sorted sets", () => {
|
||||
expect(await adapter.zCard("k")).toBe(0);
|
||||
await adapter.close();
|
||||
});
|
||||
|
||||
test("expire applies to sorted sets and removes them from reads and scans", async () => {
|
||||
let now = 0;
|
||||
const adapter = new MemoryAdapter({ now: () => now });
|
||||
await adapter.zAdd("rl:sliding:tenant-a", 1, "request-1");
|
||||
expect(await adapter.expire("rl:sliding:tenant-a", 1)).toBe(true);
|
||||
|
||||
now = 1_500;
|
||||
|
||||
expect(await adapter.zCard("rl:sliding:tenant-a")).toBe(0);
|
||||
const keys: string[] = [];
|
||||
for await (const key of adapter.scan("rl:sliding:*")) keys.push(key);
|
||||
expect(keys).toEqual([]);
|
||||
await adapter.close();
|
||||
});
|
||||
|
||||
test("opportunistically sweeps expired sorted-set buckets under high-cardinality writes", async () => {
|
||||
let now = 0;
|
||||
const adapter = new MemoryAdapter({ now: () => now });
|
||||
for (let index = 0; index < 200; index += 1) {
|
||||
const key = `rl:sliding:tenant-${index}`;
|
||||
await adapter.zAdd(key, index, `request-${index}`);
|
||||
await adapter.expire(key, 1);
|
||||
}
|
||||
|
||||
now = 2_000;
|
||||
await adapter.zAdd("rl:sliding:fresh", now, "request-fresh");
|
||||
await adapter.expire("rl:sliding:fresh", 1);
|
||||
|
||||
const keys: string[] = [];
|
||||
for await (const key of adapter.scan("rl:sliding:*")) keys.push(key);
|
||||
expect(keys).toEqual(["rl:sliding:fresh"]);
|
||||
await adapter.close();
|
||||
});
|
||||
});
|
||||
|
||||
describe("MemoryAdapter — eval / scripts", () => {
|
||||
@@ -212,6 +246,21 @@ describe("MemoryAdapter — eval / scripts", () => {
|
||||
expect(MemoryAdapter.hasRegisteredScript("test-script")).toBe(true);
|
||||
await adapter.close();
|
||||
});
|
||||
|
||||
test("serializes concurrent registered scripts like Redis EVAL", async () => {
|
||||
MemoryAdapter.registerScript("atomic-counter-script", async (instance, keys) => {
|
||||
const current = Number.parseInt((await instance.get(keys[0])) ?? "0", 10);
|
||||
await new Promise<void>((resolve) => queueMicrotask(resolve));
|
||||
await instance.set(keys[0], String(current + 1));
|
||||
return current + 1;
|
||||
});
|
||||
const adapter = new MemoryAdapter();
|
||||
|
||||
await Promise.all(Array.from({ length: 25 }, () => adapter.eval("atomic-counter-script", ["counter"], [])));
|
||||
|
||||
expect(await adapter.get("counter")).toBe("25");
|
||||
await adapter.close();
|
||||
});
|
||||
});
|
||||
|
||||
describe("MemoryAdapter — lifecycle", () => {
|
||||
|
||||
+86
-22
@@ -11,6 +11,11 @@ interface SortedSetMember {
|
||||
member: string;
|
||||
}
|
||||
|
||||
interface SortedSetEntry {
|
||||
members: SortedSetMember[];
|
||||
expiresAt: number | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Registry for `eval` scripts. The memory adapter cannot run real Lua,
|
||||
* so it matches the script body against a TypeScript equivalent that
|
||||
@@ -33,13 +38,17 @@ const scriptRegistry = new Map<string, MemoryScriptHandler>();
|
||||
*/
|
||||
export class MemoryAdapter implements SharedStoreAdapter {
|
||||
private readonly kv = new Map<string, KvEntry>();
|
||||
private readonly sortedSets = new Map<string, SortedSetMember[]>();
|
||||
private readonly sortedSets = new Map<string, SortedSetEntry>();
|
||||
private readonly emitter = new EventEmitter();
|
||||
private readonly clock: () => number;
|
||||
private nextExpirySweepAt: number;
|
||||
private writesSinceExpirySweep = 0;
|
||||
private evalTail: Promise<void> = Promise.resolve();
|
||||
private closed = false;
|
||||
|
||||
constructor(options: { now?: () => number } = {}) {
|
||||
this.clock = options.now ?? (() => Date.now());
|
||||
this.nextExpirySweepAt = this.clock() + 1_000;
|
||||
this.emitter.setMaxListeners(0);
|
||||
}
|
||||
|
||||
@@ -70,6 +79,7 @@ export class MemoryAdapter implements SharedStoreAdapter {
|
||||
|
||||
async set(key: string, value: string, opts: SharedStoreSetOptions = {}): Promise<boolean> {
|
||||
this.assertOpen();
|
||||
this.maybeSweepExpired();
|
||||
if (opts.nx) {
|
||||
const existing = this.kv.get(key);
|
||||
if (existing && !this.isExpired(existing)) {
|
||||
@@ -91,6 +101,7 @@ export class MemoryAdapter implements SharedStoreAdapter {
|
||||
|
||||
async incr(key: string, by = 1): Promise<number> {
|
||||
this.assertOpen();
|
||||
this.maybeSweepExpired();
|
||||
const entry = this.kv.get(key);
|
||||
let current = 0;
|
||||
let expiresAt: number | null = null;
|
||||
@@ -110,11 +121,17 @@ export class MemoryAdapter implements SharedStoreAdapter {
|
||||
async expire(key: string, ttlSeconds: number): Promise<boolean> {
|
||||
this.assertOpen();
|
||||
const entry = this.kv.get(key);
|
||||
if (!entry || this.isExpired(entry)) {
|
||||
if (entry) this.kv.delete(key);
|
||||
return false;
|
||||
if (entry) {
|
||||
if (this.isExpired(entry)) {
|
||||
this.kv.delete(key);
|
||||
return false;
|
||||
}
|
||||
entry.expiresAt = ttlSeconds > 0 ? this.clock() + ttlSeconds * 1000 : null;
|
||||
return true;
|
||||
}
|
||||
entry.expiresAt = ttlSeconds > 0 ? this.clock() + ttlSeconds * 1000 : null;
|
||||
const sortedSet = this.getActiveSortedSet(key);
|
||||
if (!sortedSet) return false;
|
||||
sortedSet.expiresAt = ttlSeconds > 0 ? this.clock() + ttlSeconds * 1000 : null;
|
||||
return true;
|
||||
}
|
||||
|
||||
@@ -125,22 +142,27 @@ export class MemoryAdapter implements SharedStoreAdapter {
|
||||
|
||||
scan(pattern: string, opts: SharedStoreScanOptions = {}): AsyncIterable<string> {
|
||||
this.assertOpen();
|
||||
this.sweepExpired();
|
||||
const regex = patternToRegExp(pattern);
|
||||
const snapshot: string[] = [];
|
||||
const snapshot = new Set<string>();
|
||||
for (const [key, entry] of this.kv.entries()) {
|
||||
if (!this.isExpired(entry) && regex.test(key)) {
|
||||
snapshot.push(key);
|
||||
snapshot.add(key);
|
||||
}
|
||||
}
|
||||
for (const key of this.sortedSets.keys()) {
|
||||
if (regex.test(key)) snapshot.add(key);
|
||||
}
|
||||
const keys = [...snapshot];
|
||||
const batchSize = Math.max(1, opts.count ?? 100);
|
||||
let index = 0;
|
||||
return {
|
||||
[Symbol.asyncIterator]: () => ({
|
||||
async next() {
|
||||
if (index >= snapshot.length) {
|
||||
if (index >= keys.length) {
|
||||
return { value: undefined as unknown as string, done: true };
|
||||
}
|
||||
const value = snapshot[index];
|
||||
const value = keys[index];
|
||||
index += 1;
|
||||
// batchSize is honored implicitly by sequential iteration; the
|
||||
// counter exists so callers can reason about it in logs.
|
||||
@@ -176,35 +198,37 @@ export class MemoryAdapter implements SharedStoreAdapter {
|
||||
|
||||
async zAdd(key: string, score: number, member: string): Promise<number> {
|
||||
this.assertOpen();
|
||||
const set = this.sortedSets.get(key) ?? [];
|
||||
const existingIndex = set.findIndex((entry) => entry.member === member);
|
||||
this.maybeSweepExpired();
|
||||
const entry = this.getActiveSortedSet(key) ?? { members: [], expiresAt: null };
|
||||
const existingIndex = entry.members.findIndex((candidate) => candidate.member === member);
|
||||
if (existingIndex >= 0) {
|
||||
set[existingIndex].score = score;
|
||||
this.sortedSets.set(key, set);
|
||||
entry.members[existingIndex].score = score;
|
||||
this.sortedSets.set(key, entry);
|
||||
return 0;
|
||||
}
|
||||
set.push({ score, member });
|
||||
this.sortedSets.set(key, set);
|
||||
entry.members.push({ score, member });
|
||||
this.sortedSets.set(key, entry);
|
||||
return 1;
|
||||
}
|
||||
|
||||
async zRemRangeByScore(key: string, min: number, max: number): Promise<number> {
|
||||
this.assertOpen();
|
||||
const set = this.sortedSets.get(key);
|
||||
if (!set) return 0;
|
||||
const before = set.length;
|
||||
const remaining = set.filter((entry) => entry.score < min || entry.score > max);
|
||||
const entry = this.getActiveSortedSet(key);
|
||||
if (!entry) return 0;
|
||||
const before = entry.members.length;
|
||||
const remaining = entry.members.filter((member) => member.score < min || member.score > max);
|
||||
if (remaining.length === 0) {
|
||||
this.sortedSets.delete(key);
|
||||
} else {
|
||||
this.sortedSets.set(key, remaining);
|
||||
entry.members = remaining;
|
||||
this.sortedSets.set(key, entry);
|
||||
}
|
||||
return before - remaining.length;
|
||||
}
|
||||
|
||||
async zCard(key: string): Promise<number> {
|
||||
this.assertOpen();
|
||||
return this.sortedSets.get(key)?.length ?? 0;
|
||||
return this.getActiveSortedSet(key)?.members.length ?? 0;
|
||||
}
|
||||
|
||||
async eval(script: string, keys: string[], args: string[]): Promise<unknown> {
|
||||
@@ -213,7 +237,19 @@ export class MemoryAdapter implements SharedStoreAdapter {
|
||||
if (!handler) {
|
||||
throw new Error("shared-store memory adapter: unknown eval script (use MemoryAdapter.registerScript)");
|
||||
}
|
||||
return handler(this, keys, args);
|
||||
|
||||
const previous = this.evalTail;
|
||||
let release!: () => void;
|
||||
this.evalTail = new Promise<void>((resolve) => {
|
||||
release = resolve;
|
||||
});
|
||||
await previous;
|
||||
try {
|
||||
this.assertOpen();
|
||||
return await handler(this, keys, args);
|
||||
} finally {
|
||||
release();
|
||||
}
|
||||
}
|
||||
|
||||
onReconnect(_handler: () => void | Promise<void>): () => void {
|
||||
@@ -242,6 +278,34 @@ export class MemoryAdapter implements SharedStoreAdapter {
|
||||
private isExpired(entry: KvEntry): boolean {
|
||||
return entry.expiresAt !== null && entry.expiresAt <= this.clock();
|
||||
}
|
||||
|
||||
private getActiveSortedSet(key: string): SortedSetEntry | undefined {
|
||||
const entry = this.sortedSets.get(key);
|
||||
if (!entry) return undefined;
|
||||
if (entry.expiresAt !== null && entry.expiresAt <= this.clock()) {
|
||||
this.sortedSets.delete(key);
|
||||
return undefined;
|
||||
}
|
||||
return entry;
|
||||
}
|
||||
|
||||
private maybeSweepExpired(): void {
|
||||
this.writesSinceExpirySweep += 1;
|
||||
if (this.clock() < this.nextExpirySweepAt && this.writesSinceExpirySweep < 128) return;
|
||||
this.sweepExpired();
|
||||
}
|
||||
|
||||
private sweepExpired(): void {
|
||||
const now = this.clock();
|
||||
for (const [key, entry] of this.kv) {
|
||||
if (entry.expiresAt !== null && entry.expiresAt <= now) this.kv.delete(key);
|
||||
}
|
||||
for (const [key, entry] of this.sortedSets) {
|
||||
if (entry.expiresAt !== null && entry.expiresAt <= now) this.sortedSets.delete(key);
|
||||
}
|
||||
this.writesSinceExpirySweep = 0;
|
||||
this.nextExpirySweepAt = now + 1_000;
|
||||
}
|
||||
}
|
||||
|
||||
function patternToRegExp(pattern: string): RegExp {
|
||||
|
||||
+14
@@ -60,4 +60,18 @@ describe("createSharedStore — auto adapter selection builds a RedisAdapter", (
|
||||
expect(store.adapter).toBeInstanceOf(RedisAdapter);
|
||||
await store.close();
|
||||
});
|
||||
|
||||
test("fails closed in production when REDIS_URL is missing", () => {
|
||||
vi.stubEnv("NODE_ENV", "production");
|
||||
vi.stubEnv("REDIS_URL", "");
|
||||
expect(() => createSharedStore({ namespace: "demo" })).toThrow(/REDIS_URL is required in production/);
|
||||
});
|
||||
|
||||
test("still permits an explicitly injected adapter in production tests", async () => {
|
||||
vi.stubEnv("NODE_ENV", "production");
|
||||
vi.stubEnv("REDIS_URL", "");
|
||||
const store = createSharedStore({ namespace: "demo", adapter: new MemoryAdapter() });
|
||||
expect(store.adapter).toBeInstanceOf(MemoryAdapter);
|
||||
await store.close();
|
||||
});
|
||||
});
|
||||
@@ -1,6 +1,6 @@
|
||||
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
|
||||
import { MemoryAdapter } from "./adapters/memory.js";
|
||||
import { __resetMemoryWarningForTests, createSharedStore } from "./factory.js";
|
||||
import { __resetMemoryWarningForTests, createSharedStore, resolveSharedStoreChannel } from "./factory.js";
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllEnvs();
|
||||
@@ -52,6 +52,14 @@ describe("createSharedStore — namespace and key validation", () => {
|
||||
test("rejects channels containing pattern characters", async () => {
|
||||
const store = createSharedStore({ namespace: "demo", adapter: new MemoryAdapter() });
|
||||
await expect(store.publish("ch*", "x")).rejects.toThrow(/forbidden characters/);
|
||||
expect(() => resolveSharedStoreChannel(store, "")).toThrow(/must not be empty/);
|
||||
expect(() => resolveSharedStoreChannel(store, "ch?")).toThrow(/forbidden characters/);
|
||||
await store.close();
|
||||
});
|
||||
|
||||
test("resolves validated physical channels for atomic adapter scripts", async () => {
|
||||
const store = createSharedStore({ namespace: "demo", adapter: new MemoryAdapter() });
|
||||
expect(resolveSharedStoreChannel(store, "events:tenant_1")).toBe("shared-store:demo:ch:events:tenant_1");
|
||||
await store.close();
|
||||
});
|
||||
|
||||
|
||||
@@ -22,8 +22,8 @@ export interface CreateSharedStoreOptions {
|
||||
ttlDefault?: number;
|
||||
/**
|
||||
* Redis connection URL. When omitted, the factory checks
|
||||
* `process.env.REDIS_URL`. If still undefined, the in-memory adapter
|
||||
* is used and a warning is emitted.
|
||||
* `process.env.REDIS_URL`. If still undefined, non-production runtimes use
|
||||
* the in-memory adapter and emit a warning. Production fails closed.
|
||||
*/
|
||||
redisUrl?: string;
|
||||
/** Override the Redis logical DB index (default 1). */
|
||||
@@ -97,15 +97,7 @@ export function createSharedStore(options: CreateSharedStoreOptions): SharedStor
|
||||
return `${prefix}${suffix}`;
|
||||
};
|
||||
|
||||
const ensureChannel = (channel: string): string => {
|
||||
if (channel.length === 0) {
|
||||
throw new Error("shared-store channel must not be empty");
|
||||
}
|
||||
if (INVALID_KEY_CHARS.test(channel)) {
|
||||
throw new Error(`shared-store channel contains forbidden characters: ${channel}`);
|
||||
}
|
||||
return `${channelPrefix}${channel}`;
|
||||
};
|
||||
const ensureChannel = (channel: string): string => resolveNamespacedChannel(channelPrefix, channel);
|
||||
|
||||
const applyDefaultTtl = (opts: SharedStoreSetOptions | undefined): SharedStoreSetOptions | undefined => {
|
||||
if (options.ttlDefault === undefined) return opts;
|
||||
@@ -137,6 +129,22 @@ export function createSharedStore(options: CreateSharedStoreOptions): SharedStor
|
||||
};
|
||||
}
|
||||
|
||||
/** Resolve a logical channel for an atomic adapter script without exposing an unvalidated namespace escape. */
|
||||
export function resolveSharedStoreChannel(store: Pick<SharedStore, "namespace">, channel: string): string {
|
||||
validateNamespace(store.namespace);
|
||||
return resolveNamespacedChannel(`${NAMESPACE_PREFIX}:${store.namespace}:ch:`, channel);
|
||||
}
|
||||
|
||||
function resolveNamespacedChannel(prefix: string, channel: string): string {
|
||||
if (channel.length === 0) {
|
||||
throw new Error("shared-store channel must not be empty");
|
||||
}
|
||||
if (INVALID_KEY_CHARS.test(channel)) {
|
||||
throw new Error(`shared-store channel contains forbidden characters: ${channel}`);
|
||||
}
|
||||
return `${prefix}${channel}`;
|
||||
}
|
||||
|
||||
function validateNamespace(namespace: string): void {
|
||||
if (!namespace || namespace.length === 0) {
|
||||
throw new Error("createSharedStore: namespace is required");
|
||||
@@ -155,6 +163,11 @@ function buildAdapter(options: CreateSharedStoreOptions): SharedStoreAdapter {
|
||||
db: options.redisDbIndex ?? 1,
|
||||
});
|
||||
}
|
||||
if (process.env.NODE_ENV === "production") {
|
||||
throw new Error(
|
||||
`createSharedStore: REDIS_URL is required in production for namespace "${options.namespace}"`,
|
||||
);
|
||||
}
|
||||
if (!memoryWarningEmitted) {
|
||||
memoryWarningEmitted = true;
|
||||
options.logger?.warn?.(
|
||||
|
||||
+12
-6
@@ -41,6 +41,16 @@ describe("createFixedWindowRateLimiter", () => {
|
||||
await store.close();
|
||||
});
|
||||
|
||||
test("reserves a weighted batch in one atomic decision", async () => {
|
||||
const { limiter, store } = buildLimiter({ max: 10 });
|
||||
const first = await limiter.consume("batch", 7);
|
||||
expect(first).toMatchObject({ allowed: true, remaining: 3 });
|
||||
const overflow = await limiter.consume("batch", 4);
|
||||
expect(overflow).toMatchObject({ allowed: false, remaining: 0 });
|
||||
await expect(limiter.consume("batch", 0)).rejects.toThrow(/weight/);
|
||||
await store.close();
|
||||
});
|
||||
|
||||
test("resets after the window expires", async () => {
|
||||
let now = 1_000;
|
||||
const { limiter, store } = buildLimiter({ windowSeconds: 1, max: 1, now: () => now });
|
||||
@@ -63,12 +73,8 @@ describe("createFixedWindowRateLimiter", () => {
|
||||
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/);
|
||||
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 () => {
|
||||
|
||||
+13
-7
@@ -21,14 +21,16 @@ export interface FixedWindowDecision {
|
||||
}
|
||||
|
||||
export interface FixedWindowRateLimiter {
|
||||
consume(key: string): Promise<FixedWindowDecision>;
|
||||
/** Atomically reserve one or more actions in the current window. */
|
||||
consume(key: string, weight?: number): 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
|
||||
local weight = tonumber(ARGV[2])
|
||||
local current = redis.call('INCRBY', KEYS[1], weight)
|
||||
if current == weight then
|
||||
redis.call('EXPIRE', KEYS[1], tonumber(ARGV[1]))
|
||||
end
|
||||
local ttl = redis.call('TTL', KEYS[1])
|
||||
@@ -41,8 +43,9 @@ return { current, ttl }
|
||||
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) {
|
||||
const weight = Number.parseInt(args[1] ?? "1", 10);
|
||||
const current = await adapter.incr(key, weight);
|
||||
if (current === weight && window > 0) {
|
||||
await adapter.expire(key, window);
|
||||
}
|
||||
// We do not implement TTL command on the adapter surface; the helper
|
||||
@@ -68,9 +71,12 @@ export function createFixedWindowRateLimiter(options: FixedWindowRateLimiterOpti
|
||||
const bucketKey = (key: string) => `rl:fixed:${options.prefix}:${key}`;
|
||||
|
||||
return {
|
||||
async consume(key) {
|
||||
async consume(key, weight = 1) {
|
||||
if (!Number.isSafeInteger(weight) || weight <= 0) {
|
||||
throw new Error("fixed-window rate-limit weight must be a positive safe integer");
|
||||
}
|
||||
const fullKey = store.key(bucketKey(key));
|
||||
const result = (await store.adapter.eval(FIXED_WINDOW_SCRIPT, [fullKey], [String(options.windowSeconds)])) as
|
||||
const result = (await store.adapter.eval(FIXED_WINDOW_SCRIPT, [fullKey], [String(options.windowSeconds), String(weight)])) as
|
||||
| [number | string, number | string]
|
||||
| undefined;
|
||||
const current = Number(result?.[0] ?? 0);
|
||||
|
||||
+43
@@ -125,6 +125,49 @@ describe("createTwoTierCache", () => {
|
||||
const store = createSharedStore({ namespace: "ns", adapter });
|
||||
expect(() => createTwoTierCache({ store, namespace: "x", ttlSeconds: 0 })).toThrow(/ttlSeconds/);
|
||||
expect(() => createTwoTierCache({ store, namespace: "", ttlSeconds: 60 })).toThrow(/namespace/);
|
||||
expect(() => createTwoTierCache({ store, namespace: "x", ttlSeconds: 60, l1MaxEntries: 0 })).toThrow(
|
||||
/l1MaxEntries/,
|
||||
);
|
||||
});
|
||||
|
||||
test("default L1 entries expire at the configured TTL", async () => {
|
||||
let now = 0;
|
||||
const adapter = new MemoryAdapter({ now: () => now });
|
||||
const store = createSharedStore({ namespace: "ns", adapter });
|
||||
const cache = createTwoTierCache<Value>({
|
||||
store,
|
||||
namespace: "subscription",
|
||||
ttlSeconds: 1,
|
||||
l1Now: () => now,
|
||||
});
|
||||
await cache.set("t1", { id: "t1", name: "Alpha" });
|
||||
expect(cache.l1.get("t1")).toEqual({ id: "t1", name: "Alpha" });
|
||||
|
||||
now = 1_001;
|
||||
|
||||
expect(cache.l1.get("t1")).toBeUndefined();
|
||||
expect(await cache.get("t1")).toBeNull();
|
||||
await store.close();
|
||||
});
|
||||
|
||||
test("default L1 evicts the least-recently-used entry at its maximum", async () => {
|
||||
const adapter = new MemoryAdapter();
|
||||
const store = createSharedStore({ namespace: "ns", adapter });
|
||||
const cache = createTwoTierCache<Value>({
|
||||
store,
|
||||
namespace: "subscription",
|
||||
ttlSeconds: 60,
|
||||
l1MaxEntries: 2,
|
||||
});
|
||||
await cache.set("t1", { id: "t1", name: "Alpha" });
|
||||
await cache.set("t2", { id: "t2", name: "Beta" });
|
||||
cache.l1.get("t1");
|
||||
await cache.set("t3", { id: "t3", name: "Gamma" });
|
||||
|
||||
expect(cache.l1.get("t1")).toEqual({ id: "t1", name: "Alpha" });
|
||||
expect(cache.l1.get("t2")).toBeUndefined();
|
||||
expect(cache.l1.get("t3")).toEqual({ id: "t3", name: "Gamma" });
|
||||
await store.close();
|
||||
});
|
||||
|
||||
test("flushLocal clears the entire L1 (recovery path after reconnect)", async () => {
|
||||
|
||||
+22
-7
@@ -23,6 +23,7 @@ interface Value {
|
||||
|
||||
const explicitUrl = process.env.PUBSUB_TEST_REDIS_URL?.trim();
|
||||
const dockerOptOut = process.env.PUBSUB_TEST_USE_DOCKER === "false";
|
||||
const containerStopDeadlineMs = 5_000;
|
||||
|
||||
interface Backend {
|
||||
redisUrl: string;
|
||||
@@ -36,7 +37,10 @@ async function bootBackend(): Promise<Backend | undefined> {
|
||||
if (dockerOptOut) return undefined;
|
||||
try {
|
||||
const { GenericContainer } = await import("testcontainers");
|
||||
const started = await new GenericContainer("redis:7-alpine").withExposedPorts(6379).start();
|
||||
const started = await new GenericContainer("redis:7-alpine")
|
||||
.withExposedPorts(6379)
|
||||
.withAutoCleanup(true)
|
||||
.start();
|
||||
const host = started.getHost();
|
||||
const port = started.getMappedPort(6379);
|
||||
return { redisUrl: `redis://${host}:${port}`, container: started };
|
||||
@@ -79,13 +83,24 @@ function buildCachePair(opts: { db?: number } = {}) {
|
||||
|
||||
afterAll(async () => {
|
||||
if (backend?.container) {
|
||||
try {
|
||||
await backend.container.stop();
|
||||
} catch {
|
||||
/* best effort */
|
||||
}
|
||||
// Testcontainers' Ryuk sidecar is the authoritative cleanup path. Keep the
|
||||
// direct stop best-effort and bounded because a degraded Docker daemon can
|
||||
// leave its HTTP request pending indefinitely. Avoiding the synchronous
|
||||
// remove call also lets Ryuk finish cleanup after the Vitest worker exits.
|
||||
const stop = backend.container
|
||||
.stop({ timeout: 0, remove: false })
|
||||
.then(() => undefined)
|
||||
.catch(() => undefined);
|
||||
let deadline: NodeJS.Timeout | undefined;
|
||||
await Promise.race([
|
||||
stop,
|
||||
new Promise<void>((resolve) => {
|
||||
deadline = setTimeout(resolve, containerStopDeadlineMs);
|
||||
}),
|
||||
]);
|
||||
if (deadline) clearTimeout(deadline);
|
||||
}
|
||||
}, 30_000);
|
||||
}, 10_000);
|
||||
|
||||
describe.skipIf(skip)("two-tier cache against real Redis (integration)", () => {
|
||||
it("fans out invalidations across instances via pub/sub", async () => {
|
||||
|
||||
+73
-7
@@ -26,10 +26,13 @@ export interface TwoTierCacheOptions<T> {
|
||||
/** 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.
|
||||
* Optional L1 implementation. Defaults to an internal TTL-aware LRU cache.
|
||||
*/
|
||||
l1Cache?: TwoTierL1Cache<T>;
|
||||
/** Maximum entries in the default L1 cache. Defaults to 10,000. */
|
||||
l1MaxEntries?: number;
|
||||
/** Override the L1 clock for deterministic tests. Defaults to `Date.now`. */
|
||||
l1Now?: () => number;
|
||||
/** Optional JSON serializer override for the L2 tier. */
|
||||
serializer?: CacheSerializer<T>;
|
||||
/**
|
||||
@@ -100,23 +103,80 @@ export interface TwoTierCache<T> {
|
||||
readonly namespace: string;
|
||||
}
|
||||
|
||||
class MapL1Cache<T> implements TwoTierL1Cache<T> {
|
||||
private readonly map = new Map<string, T>();
|
||||
interface L1Entry<T> {
|
||||
value: T;
|
||||
expiresAt: number;
|
||||
}
|
||||
|
||||
class BoundedTtlL1Cache<T> implements TwoTierL1Cache<T> {
|
||||
private readonly map = new Map<string, L1Entry<T>>();
|
||||
private expiryQueue: Array<{ key: string; expiresAt: number }> = [];
|
||||
private expiryQueueHead = 0;
|
||||
|
||||
constructor(
|
||||
private readonly maxEntries: number,
|
||||
private readonly ttlMs: number,
|
||||
private readonly clock: () => number,
|
||||
) {}
|
||||
|
||||
get(key: string): T | undefined {
|
||||
return this.map.get(key);
|
||||
const entry = this.map.get(key);
|
||||
if (!entry) return undefined;
|
||||
if (entry.expiresAt <= this.clock()) {
|
||||
this.map.delete(key);
|
||||
return undefined;
|
||||
}
|
||||
// Reinsert hits so Map insertion order acts as an O(1) LRU queue.
|
||||
this.map.delete(key);
|
||||
this.map.set(key, entry);
|
||||
return entry.value;
|
||||
}
|
||||
|
||||
set(key: string, value: T): void {
|
||||
this.map.set(key, value);
|
||||
const now = this.clock();
|
||||
this.pruneExpired(now);
|
||||
this.map.delete(key);
|
||||
const expiresAt = now + this.ttlMs;
|
||||
this.map.set(key, { value, expiresAt });
|
||||
this.expiryQueue.push({ key, expiresAt });
|
||||
while (this.map.size > this.maxEntries) {
|
||||
const oldest = this.map.keys().next().value as string | undefined;
|
||||
if (oldest === undefined) break;
|
||||
this.map.delete(oldest);
|
||||
}
|
||||
}
|
||||
|
||||
delete(key: string): boolean {
|
||||
return this.map.delete(key);
|
||||
}
|
||||
|
||||
clear(): void {
|
||||
this.map.clear();
|
||||
this.expiryQueue = [];
|
||||
this.expiryQueueHead = 0;
|
||||
}
|
||||
|
||||
keys(): IterableIterator<string> {
|
||||
this.pruneExpired(this.clock());
|
||||
return this.map.keys();
|
||||
}
|
||||
|
||||
private pruneExpired(now: number): void {
|
||||
// Expiry order is independent from LRU order so cache hits cannot move an
|
||||
// expired entry behind a live one. Stale queue records from overwrites and
|
||||
// LRU evictions are ignored by comparing their timestamp with the map.
|
||||
while (this.expiryQueueHead < this.expiryQueue.length) {
|
||||
const candidate = this.expiryQueue[this.expiryQueueHead];
|
||||
if (candidate.expiresAt > now) break;
|
||||
this.expiryQueueHead += 1;
|
||||
const current = this.map.get(candidate.key);
|
||||
if (current?.expiresAt === candidate.expiresAt) this.map.delete(candidate.key);
|
||||
}
|
||||
if (this.expiryQueueHead >= 1_024 && this.expiryQueueHead * 2 >= this.expiryQueue.length) {
|
||||
this.expiryQueue = this.expiryQueue.slice(this.expiryQueueHead);
|
||||
this.expiryQueueHead = 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -143,7 +203,13 @@ export function createTwoTierCache<T>(options: TwoTierCacheOptions<T>): TwoTierC
|
||||
if (options.ttlSeconds <= 0) {
|
||||
throw new Error("createTwoTierCache: ttlSeconds must be > 0");
|
||||
}
|
||||
const l1 = options.l1Cache ?? new MapL1Cache<T>();
|
||||
const l1MaxEntries = options.l1MaxEntries ?? 10_000;
|
||||
if (!Number.isSafeInteger(l1MaxEntries) || l1MaxEntries <= 0) {
|
||||
throw new Error("createTwoTierCache: l1MaxEntries must be a positive safe integer");
|
||||
}
|
||||
const l1 =
|
||||
options.l1Cache ??
|
||||
new BoundedTtlL1Cache<T>(l1MaxEntries, options.ttlSeconds * 1_000, options.l1Now ?? (() => Date.now()));
|
||||
const l2 = createCacheStore<T>({
|
||||
store: options.store,
|
||||
prefix: options.namespace,
|
||||
|
||||
@@ -5,6 +5,7 @@ export { MemoryAdapter } from "./adapters/memory.js";
|
||||
export { RedisAdapter, type RedisAdapterOptions } from "./adapters/redis.js";
|
||||
export {
|
||||
createSharedStore,
|
||||
resolveSharedStoreChannel,
|
||||
type CreateSharedStoreOptions,
|
||||
type SharedStore,
|
||||
type SharedStoreLogger,
|
||||
|
||||
Reference in new issue
Block a user