mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 15:23:29 +00:00
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:
1 parent
fef24a89bb
commit
a5dd8e1d1a
7 files changed
+755
No files matched your search
+130
@@ -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
@@ -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"),
|
||||
);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user