feat(cache): server-side LRU primitive + per-user invalidation helpers

Extends the v1.4.33 Coach snapshot LRU shape into a reusable
ServerCache<T> with TTL expiry, capacity-bounded LRU eviction,
single-flight read coalescing, prefix delete, and per-instance
hit/miss/eviction/stampede counters. Adds five invalidation helpers
keyed by the per-user prefix scheme so write endpoints can flush every
cache that may reflect their changed rows in a single call.

The cached() wrapper attaches cache.<name>.outcome + cache.<name>.key_hash
to the active wide event so production logs carry the hit ratio without
leaking the userId portion of the cache key.

Hand-rolled to keep the dependency surface at zero — same recipe as the
snapshot cache the dashboard already relies on. Process-local; multi-
instance staleness is bounded by TTL, the Redis migration path stays a
future option.
This commit is contained in:
Marc-André Bombeck committed 2026-05-16 20:55:05 +02:00
1 parent fef24a89bb
commit a5dd8e1d1a
7 files changed
+755

No files matched your search

+130
View File
@@ -0,0 +1,130 @@
/**
* Unit tests for the per-user invalidation helpers — every helper
* evicts the matching `caches.*` bucket and leaves unrelated entries
* intact.
*/
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import {
__resetAllCachesForTests,
cached,
caches,
} from "../server-cache";
import {
invalidateAppSettings,
invalidateUserDashboardWidgets,
invalidateUserMeasurements,
invalidateUserMedications,
invalidateUserMood,
} from "../invalidate";
const USER_A = "user-a";
const USER_B = "user-b";
beforeEach(() => {
__resetAllCachesForTests();
});
afterEach(() => {
__resetAllCachesForTests();
});
async function primeAllCaches(): Promise<void> {
// Analytics keys carry a slice suffix; the prefix-match must include
// the pipe so user-1 doesn't match user-10 in production traffic.
await cached(caches.analytics, `${USER_A}|default`, async () => ({ a: 1 }));
await cached(caches.analytics, `${USER_A}|summaries`, async () => ({ a: 2 }));
await cached(caches.analytics, `${USER_B}|default`, async () => ({ b: 1 }));
await cached(caches.medications, USER_A, async () => ({ m: 1 }));
await cached(caches.medications, USER_B, async () => ({ m: 2 }));
await cached(caches.medicationsIntake, `${USER_A}|compliance|30`, async () => ({
c: 1,
}));
await cached(caches.medicationsIntake, `${USER_B}|compliance|30`, async () => ({
c: 2,
}));
await cached(caches.achievements, USER_A, async () => ({ ach: 1 }));
await cached(caches.achievements, USER_B, async () => ({ ach: 2 }));
await cached(caches.workouts, `${USER_A}|3|0||`, async () => ({ w: 1 }));
await cached(caches.workouts, `${USER_B}|3|0||`, async () => ({ w: 2 }));
await cached(caches.moodAnalytics, USER_A, async () => ({ mood: 1 }));
await cached(caches.moodAnalytics, USER_B, async () => ({ mood: 2 }));
await cached(caches.dashboardWidgets, USER_A, async () => ({ d: 1 }));
await cached(caches.dashboardWidgets, USER_B, async () => ({ d: 2 }));
await cached(caches.bugreportStatus, "singleton", async () => ({ s: 1 }));
}
describe("invalidateUserMeasurements", () => {
it("evicts analytics + achievements + workouts for the target user only", async () => {
await primeAllCaches();
invalidateUserMeasurements(USER_A);
expect(caches.analytics.get(`${USER_A}|default`)).toBeNull();
expect(caches.analytics.get(`${USER_A}|summaries`)).toBeNull();
expect(caches.achievements.get(USER_A)).toBeNull();
expect(caches.workouts.get(`${USER_A}|3|0||`)).toBeNull();
// User B's caches untouched.
expect(caches.analytics.get(`${USER_B}|default`)).not.toBeNull();
expect(caches.achievements.get(USER_B)).not.toBeNull();
expect(caches.workouts.get(`${USER_B}|3|0||`)).not.toBeNull();
// Mood-analytics not touched by a measurement write.
expect(caches.moodAnalytics.get(USER_A)).not.toBeNull();
});
});
describe("invalidateUserMood", () => {
it("evicts mood-analytics + achievements + analytics", async () => {
await primeAllCaches();
invalidateUserMood(USER_A);
expect(caches.moodAnalytics.get(USER_A)).toBeNull();
expect(caches.achievements.get(USER_A)).toBeNull();
expect(caches.analytics.get(`${USER_A}|default`)).toBeNull();
expect(caches.moodAnalytics.get(USER_B)).not.toBeNull();
expect(caches.analytics.get(`${USER_B}|default`)).not.toBeNull();
});
});
describe("invalidateUserMedications", () => {
it("evicts medications + medications-intake + achievements", async () => {
await primeAllCaches();
invalidateUserMedications(USER_A);
expect(caches.medications.get(USER_A)).toBeNull();
expect(caches.medicationsIntake.get(`${USER_A}|compliance|30`)).toBeNull();
expect(caches.achievements.get(USER_A)).toBeNull();
expect(caches.medications.get(USER_B)).not.toBeNull();
expect(caches.medicationsIntake.get(`${USER_B}|compliance|30`)).not.toBeNull();
});
});
describe("invalidateUserDashboardWidgets", () => {
it("evicts only the dashboardWidgets bucket for the target user", async () => {
await primeAllCaches();
invalidateUserDashboardWidgets(USER_A);
expect(caches.dashboardWidgets.get(USER_A)).toBeNull();
expect(caches.dashboardWidgets.get(USER_B)).not.toBeNull();
// Sibling caches untouched.
expect(caches.analytics.get(`${USER_A}|default`)).not.toBeNull();
});
});
describe("invalidateAppSettings", () => {
it("evicts the entire bug-report status cache (singleton row)", async () => {
await primeAllCaches();
invalidateAppSettings();
expect(caches.bugreportStatus.get("singleton")).toBeNull();
// Per-user caches untouched.
expect(caches.analytics.get(`${USER_A}|default`)).not.toBeNull();
});
});
+232
View File
@@ -0,0 +1,232 @@
/**
* Unit tests for the `ServerCache<T>` primitive — LRU ordering, TTL
* expiry, capacity-cap eviction, prefix delete, single-flight
* coalescing, builder-rejection cleanup, and the `cached()` wrapper's
* observability annotation.
*/
import { afterEach, describe, expect, it, vi } from "vitest";
import {
__resetAllCachesForTests,
cached,
caches,
hashCacheKey,
ServerCache,
} from "../server-cache";
afterEach(() => {
__resetAllCachesForTests();
vi.useRealTimers();
});
describe("ServerCache.get / set", () => {
it("returns the stored value within TTL", () => {
const cache = new ServerCache<string>({ maxEntries: 4, ttlMs: 60_000 });
cache.set("k", "v");
expect(cache.get("k")).toBe("v");
});
it("returns null when the key is absent", () => {
const cache = new ServerCache<string>({ maxEntries: 4, ttlMs: 60_000 });
expect(cache.get("missing")).toBeNull();
});
it("expires entries past the TTL", () => {
vi.useFakeTimers();
const cache = new ServerCache<string>({ maxEntries: 4, ttlMs: 1000 });
cache.set("k", "v");
vi.advanceTimersByTime(999);
expect(cache.get("k")).toBe("v");
vi.advanceTimersByTime(2);
expect(cache.get("k")).toBeNull();
});
});
describe("ServerCache LRU eviction", () => {
it("evicts the oldest entry on capacity overflow", () => {
const cache = new ServerCache<number>({ maxEntries: 3, ttlMs: 60_000 });
cache.set("a", 1);
cache.set("b", 2);
cache.set("c", 3);
cache.set("d", 4); // evicts "a"
expect(cache.get("a")).toBeNull();
expect(cache.get("b")).toBe(2);
expect(cache.get("c")).toBe(3);
expect(cache.get("d")).toBe(4);
expect(cache.stats().evictions).toBe(1);
});
it("touches on read so least-recently-used is evicted", () => {
const cache = new ServerCache<number>({ maxEntries: 3, ttlMs: 60_000 });
cache.set("a", 1);
cache.set("b", 2);
cache.set("c", 3);
// Touch "a" — now "b" is the oldest.
expect(cache.get("a")).toBe(1);
cache.set("d", 4); // evicts "b"
expect(cache.get("a")).toBe(1);
expect(cache.get("b")).toBeNull();
expect(cache.get("c")).toBe(3);
expect(cache.get("d")).toBe(4);
});
it("re-setting an existing key does not count toward eviction", () => {
const cache = new ServerCache<number>({ maxEntries: 2, ttlMs: 60_000 });
cache.set("a", 1);
cache.set("b", 2);
cache.set("a", 99); // overwrite, no eviction
expect(cache.stats().evictions).toBe(0);
expect(cache.get("a")).toBe(99);
expect(cache.get("b")).toBe(2);
});
});
describe("ServerCache.deleteByPrefix", () => {
it("removes every key with a matching prefix", () => {
const cache = new ServerCache<number>({ maxEntries: 16, ttlMs: 60_000 });
cache.set("user-1|analytics", 1);
cache.set("user-1|workouts", 2);
cache.set("user-2|analytics", 3);
const removed = cache.deleteByPrefix("user-1|");
expect(removed).toBe(2);
expect(cache.get("user-1|analytics")).toBeNull();
expect(cache.get("user-1|workouts")).toBeNull();
expect(cache.get("user-2|analytics")).toBe(3);
});
it("returns 0 when no keys match", () => {
const cache = new ServerCache<number>({ maxEntries: 16, ttlMs: 60_000 });
cache.set("user-1|analytics", 1);
expect(cache.deleteByPrefix("user-99|")).toBe(0);
});
});
describe("ServerCache.wrap single-flight", () => {
it("calls the builder once for two concurrent reads of the same key", async () => {
const cache = new ServerCache<string>({ maxEntries: 4, ttlMs: 60_000 });
let callCount = 0;
let resolveBuilder: ((value: string) => void) | null = null;
const builder = vi.fn(
() =>
new Promise<string>((resolve) => {
callCount += 1;
resolveBuilder = resolve;
}),
);
const first = cache.wrap("k", builder);
const second = cache.wrap("k", builder);
// Both reads have landed before the builder resolves.
expect(callCount).toBe(1);
resolveBuilder!("built");
const [firstResult, secondResult] = await Promise.all([first, second]);
expect(firstResult.value).toBe("built");
expect(firstResult.outcome).toBe("miss");
expect(secondResult.value).toBe("built");
expect(secondResult.outcome).toBe("stampede");
expect(builder).toHaveBeenCalledTimes(1);
expect(cache.stats().stampedes).toBe(1);
});
it("returns the cached value as a hit on the third read", async () => {
const cache = new ServerCache<string>({ maxEntries: 4, ttlMs: 60_000 });
const builder = vi.fn(async () => "built");
await cache.wrap("k", builder);
const third = await cache.wrap("k", builder);
expect(third.value).toBe("built");
expect(third.outcome).toBe("hit");
expect(builder).toHaveBeenCalledTimes(1);
expect(cache.stats().hits).toBe(1);
});
it("clears the pending slot on builder rejection so the next call retries", async () => {
const cache = new ServerCache<string>({ maxEntries: 4, ttlMs: 60_000 });
let attempt = 0;
const builder = vi.fn(async () => {
attempt += 1;
if (attempt === 1) throw new Error("transient");
return "ok";
});
await expect(cache.wrap("k", builder)).rejects.toThrow("transient");
const next = await cache.wrap("k", builder);
expect(next.value).toBe("ok");
expect(next.outcome).toBe("miss");
expect(builder).toHaveBeenCalledTimes(2);
});
});
describe("cached() observability wrapper", () => {
it("annotates hit / miss outcome and a hashed key", async () => {
const cache = new ServerCache<string>({
name: "test",
maxEntries: 4,
ttlMs: 60_000,
});
const annotate = vi.fn();
const builder = vi.fn(async () => "v");
await cached(cache, "user-1|default", builder, annotate);
expect(annotate).toHaveBeenCalledWith({
meta: {
"cache.test.outcome": "miss",
"cache.test.key_hash": hashCacheKey("user-1|default"),
},
});
annotate.mockClear();
await cached(cache, "user-1|default", builder, annotate);
expect(annotate).toHaveBeenCalledWith({
meta: expect.objectContaining({
"cache.test.outcome": "hit",
}),
});
});
it("no-ops the annotation when no annotator is passed", async () => {
const cache = new ServerCache<string>({ maxEntries: 4, ttlMs: 60_000 });
const value = await cached(cache, "k", async () => "v");
expect(value).toBe("v");
});
});
describe("global cache registry", () => {
it("exposes the eight blueprint caches as module-scope singletons", () => {
expect(caches.analytics).toBeDefined();
expect(caches.medications).toBeDefined();
expect(caches.achievements).toBeDefined();
expect(caches.dashboardWidgets).toBeDefined();
expect(caches.bugreportStatus).toBeDefined();
expect(caches.workouts).toBeDefined();
expect(caches.medicationsIntake).toBeDefined();
expect(caches.moodAnalytics).toBeDefined();
});
it("__resetAllCachesForTests clears every registry instance", async () => {
await cached(caches.analytics, "user-1|default", async () => ({ ok: 1 }));
expect(caches.analytics.stats().size).toBe(1);
__resetAllCachesForTests();
expect(caches.analytics.stats().size).toBe(0);
expect(caches.analytics.stats().hits).toBe(0);
expect(caches.analytics.stats().misses).toBe(0);
});
});
describe("hashCacheKey", () => {
it("is deterministic and unsigned 32-bit", () => {
const h1 = hashCacheKey("user-1|default");
const h2 = hashCacheKey("user-1|default");
expect(h1).toBe(h2);
expect(h1).toBeGreaterThanOrEqual(0);
expect(h1).toBeLessThanOrEqual(0xffffffff);
});
it("distinguishes near-identical keys", () => {
expect(hashCacheKey("user-1|default")).not.toBe(
hashCacheKey("user-2|default"),
);
});
});