Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -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 () => {
@@ -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);
@@ -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 () => {
@@ -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 () => {
@@ -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,