mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-19 00:12:18 +00:00
v1.4.34 — apple-health import + reliability + web-freeze
The final functional web release before the iOS native client lands.
Headline work: a streaming Apple Health `export.zip` importer for
prospective iOS-migrating accounts, a server-side aggregation cache
that collapses the three hottest dashboard reads onto in-process LRU
slots with single-flight coalescing and per-user invalidation, a
broader compliance classifier with a dedicated `early` bucket so
ahead-of-window doses count as compliant, the Coach launch surface
hoisted onto every authed page with a dashboard-hero CTA, and a
trimmer Settings shelf that folds Sources into Targets. The release
also lights up the `cache.<name>.outcome` annotation on the active
wide event so production logs carry the cache hit-ratio signal
without leaking userIds.
### Added
- **Server-side aggregation cache.** A new `ServerCache<T>` primitive
(`src/lib/cache/server-cache.ts`) extends the v1.4.33 Coach snapshot
LRU shape into a reusable per-route layer with TTL expiry,
capacity-bounded LRU eviction, single-flight read coalescing, and
per-instance hit / miss / eviction / stampede counters. Wires the
three hottest dashboard reads — `/api/analytics` (slim + default),
`/api/gamification/achievements`, `/api/medications/intake?scope=compliance`
— and bolts per-user invalidation onto every measurement / mood /
medication / workout / dashboard-widget write endpoint so the next
read paints fresh data instead of waiting out the TTL. Every cache
hit / miss surfaces on the active wide event as
`cache.<name>.outcome` + `cache.<name>.key_hash` so production logs
carry the hit-ratio signal without leaking userIds.
- **Apple Health `export.zip` import.** New endpoint
`POST /api/import/apple-health-export` (synchronous multipart
upload, asynchronous ingest via a dedicated pg-boss
`apple-health-import` worker, per-`MeasurementType` ingestion
stats). Streams the upload straight to disk so a multi-gigabyte
export never lands in V8 heap, hashes the bytes inline for
content-based idempotency, and unpacks `apple_health_export/export.xml`
with a hand-rolled ZIP central-directory walker that handles Zip64
for archives past the 4 GB barrier. The parser folds every
`<Record>`, `<Workout>`, `<Correlation>`, and `<ClinicalRecord>`
into the existing `Measurement` and `Workout` row shapes — spot
rows keyed by `HKMetadataKeyExternalUUID` (or a deterministic
`sample:<sha256>` fallback), cumulative HK types collapsed into
one `stats:<HKType>:<YYYY-MM-DD>` row per user-local day to match
the iOS daily-aggregation convention. Live per-stage progress
surfaces through `GET /api/import/apple-health-export/{jobId}/status`.
An admin variant at `POST /api/admin/import-apple-health-export`
imports on behalf of a target user (cookie-only `requireAdmin()`
gate; Bearer tokens never elevate).
- **`ImportJob` schema model + migration.** New Prisma model captures
the per-upload state machine (`queued | unpacking | parsing |
upserting | done | failed`), the content-hash for idempotency
short-circuits, and the per-`MeasurementType` ingestion counters
the status route surfaces back to the client.
- **`lastSeenByType` on `/api/analytics`.** Both the slim
(`?slice=summaries`) and default slices return a per-type
`{ lastSeenAt, daysAgo }` map. The dashboard trend tiles wire 12
mounts to a new `tileStaleDays()` helper so an "X days / weeks /
months ago" hint paints under any per-metric tile whose last
sample crosses the 7-day floor. Six locales gained additive
week / month plural keys; Polish uses the genitive-plural form
that covers every non-1 count the bucket math can produce.
- **Dashboard "Ask the coach" hero CTA.** A new pill next to the
existing "Hinzufügen" / "Add" launches the Coach drawer directly
from the dashboard hero. The `<CoachLaunchProvider>` hoisted from
the insights layout to the auth shell so the drawer is reachable
from every authed route; the floating action button stays scoped
to `/insights/**` so it cannot distract on the dashboard.
- **Shared achievements query hook.** `useAchievementsQuery()`
centralises the three previous consumers — recent-achievements
card, the `/achievements` mother page, and the unlock notifier —
onto one TanStack queryKey + cache slot so dashboard cold mount
fires the endpoint once instead of twice.
- **Typed authed Cache-Control presets.** New
`src/lib/http/cache-headers.ts` module exports
`NO_STORE_BUT_BFCACHE = "private, max-age=0, must-revalidate"`,
`SHORT_LIVED_PUBLIC`, and an `applyAuthedHeaders()` helper. The
presets land at the framework level via a `next.config.ts`
`headers()` rule that stamps the bfcache-friendly directive on
every authed HTML response, restoring Chromium bfcache eligibility
for in-app back / forward navigation.
- **`scripts/print-bundle-report.mjs`.** Restores the at-a-glance
"top client chunks by parsed size" signal Turbopack dropped from
`next build`; reads `.next/analyze/client.json` (written by
`@next/bundle-analyzer` when `pnpm analyze` runs with `ANALYZE=1`)
and prints a sorted table plus totals.
### Changed
- **Settings sidebar: "Sources" folded into "Targets & Sources".**
Per-metric threshold ranges and per-metric source priority now
share one `/settings/thresholds` page so the same metric's
threshold and device-source preference sit together instead of
one sidebar entry away. `/settings/sources` keeps a
`permanentRedirect` so external bookmarks and docs links follow
through unchanged. Section count: 11 → 10.
- **Insights tab strip: vital pills collapse under a "Vitals"
parent.** Five vital pills (HRV, Resting HR, Oxygen, Body
Temperature, Active Energy) hide behind one parent pill that
opens a popover sub-list. Parent-pill active state mirrors the
URL so spatial orientation survives the collapse; each sub-page
keeps its own URL and bookmark resolves unchanged. Strip
footprint: 14 → 10 entries when every metric has data.
- **Coolify env-var audit.** `mcp__coolify-apps01__env_vars`
inspection captured the section-1 / section-2 duplicates that
have accumulated under apps-01 since v1.3.1. Audit pinned at
`.planning/round-v1434-iwa-coolify-env-audit.md`; no env-var
deletes performed (operator action).
### Fixed
- **Compliance classifier: early intakes count as compliant.** The
classifier picked up a dedicated `early` bucket (window-start
minus three hours through window-start), the `on_time` post-window
tolerance widened from one hour to three hours, and the `late`
band sits between the new `on_time` ceiling and the configurable
`lateMinutes` knob. Heatmap consumers route the new bucket
through the compliant path; the dedicated `early` counter rides
on `DailyComplianceEntry` for downstream consumers that want to
distinguish ahead-of-window from on-window intakes.
- **Compliance heatmap fallback retired.** The v1.4.33 defensive
`looksClassifierBug` fallthrough is gone now that the underlying
classifier widening removes the every-dose-very-late mode the
fallback covered.
### Performance
- **`/api/gamification/achievements` consumer collapse.** Two of
three previous consumers shared the same TanStack queryKey
literal; the third carried a per-user discriminator so the cache
treated it as a fresh slot. Dashboard cold mount fired the
endpoint twice. Collapsing onto the shared hook trims that to a
single request; with the new server-side cache slot warm, the
duplicate-mount worst case rides single-flight coalescing.
- **GHCR build fires once per release tag.** The
`docker-publish.yml` workflow lost its `push.branches: [main]`
trigger; the `:latest` raw-tag enable rule moved onto the tag
ref so each release produces exactly one multi-arch build that
refreshes both the semver tags and the `:latest` alias.
- **NFT-trace warnings silenced.** `next.config.ts` gained an
`outputFileTracingExcludes` block that narrows the Turbopack
tracer away from the `MAXMIND_LICENSE_KEY` env-access path so
the trace-report no longer warns on every dependent route file.
### Refactor
- **Dashboard analytics consumers.** The two cards that previously
decided their own freshness copy now lean on the typed
`tileStaleDays()` helper and the additive `lastSeenByType` field
on the analytics response. Mood and BD-Zielbereich tiles keep the
default `null` because they have no underlying per-type freshness
signal.
### Accessibility
- **Dashboard hero CTA hits the WCAG 2.5.5 touch-target floor.**
The new "Ask the coach" pill carries `min-h-11` on mobile and
the matching `sm:min-h-9` desktop floor so the touch target
stays above 44 px on the Pixel 5 boundary.
- **Insights tab-strip Vitals parent reads correctly to assistive
tech.** Parent pill carries `aria-current="page"` whenever the
current URL matches one of its child vital sub-pages, plus a
`data-slot="insights-tab-strip-group"` hook for visual-regression
testing.
### Internal
- **Two e2e flake windows tightened.** `onboarding-flicker` swapped
its 12-sample 50 ms poll loop for a single Playwright
auto-retrying `toBeHidden({ timeout: 700 })` assertion so the
1-2 ms race window between the analytics-pending shell and
`useAuth().user` resolving collapses to a single retry slot.
`mobile-viewport` dropped `nav a[href]` from the touch-target
sweep (the bottom-nav owns its own WCAG spec) and gated the
44-px floor on `matchMedia('(min-width: 640px)').matches === false`
so the Pixel 5 viewport never tripped into the `sm:` tier during
WebKit render commits.
- **Server-cache observability.** Every `cached()` invocation passes
an `annotate` callback that lands two keys on the wide event:
`cache.<name>.outcome` ∈ `{ hit | miss | stampede }` and
`cache.<name>.key_hash` (non-reversible djb2 32-bit hash). Ops
can grep `cache.analytics.outcome` over any time window to
compute the hit ratio per deployment.
- **AASA followups verified.** The v1.4.33 `/.well-known/apple-app-site-association`
handler serves a direct 200 on every fronting origin; Apple's
CDN has ingested matching bodies for all three domains.
### Web freeze
v1.4.34 marks the last functional release of the web codebase before
the iOS native client launches. Subsequent v1.4.x tags carry security
fixes, dependency bumps, and hotfix-only corrections. New feature work
is paused until the iOS app clears Apple review, at which point a
v1.5.0 version-bump-only release tags the milestone. The Prisma
schema head comment and `.planning/v15-strategic-plan.md` §5
decision-log row pin the freeze trigger in-tree.
This commit is contained in:
1 parent
7bef199039
commit
affede31a4
104 files changed
+8050
-404
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"),
|
||||
);
|
||||
});
|
||||
});
|
||||
Vendored
+82
@@ -0,0 +1,82 @@
|
||||
/**
|
||||
* v1.4.34 IW-G — per-user cache invalidation helpers.
|
||||
*
|
||||
* Each write endpoint that touches a measurement / mood / medication /
|
||||
* dashboard-widget row calls the matching helper after its successful
|
||||
* database commit. The helpers walk the affected `caches.*` maps and
|
||||
* delete every key whose `userId` prefix matches.
|
||||
*
|
||||
* The "evict the whole user-bucket" stance is intentional: a redundant
|
||||
* eviction costs the next reader one cache miss (cheap, the row's
|
||||
* already paginated and the snapshot LRU sits behind), but an
|
||||
* under-eviction surfaces stale data which is the directive's failure
|
||||
* mode. The full per-write → per-cache fan-out is documented in the
|
||||
* blueprint §6 (`.planning/research/v1434-r-cache-aggregation.md`).
|
||||
*
|
||||
* The helpers are intentionally synchronous — they do `Map.delete()`
|
||||
* over a bounded entry set, which is cheap enough to run inline before
|
||||
* the write endpoint's `apiSuccess()` return. No `await` overhead.
|
||||
*/
|
||||
|
||||
import { caches } from "./server-cache";
|
||||
|
||||
/**
|
||||
* Invalidate every cache that may reflect a user's measurement set.
|
||||
*
|
||||
* Covers: analytics aggregate, achievement progress, workouts cache.
|
||||
* Mood-analytics is invalidated separately via `invalidateUserMood`
|
||||
* because mood writes don't change measurement rows.
|
||||
*/
|
||||
export function invalidateUserMeasurements(userId: string): void {
|
||||
caches.analytics.deleteByPrefix(`${userId}|`);
|
||||
caches.achievements.deleteByPrefix(userId);
|
||||
caches.workouts.deleteByPrefix(`${userId}|`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Invalidate every cache that may reflect a user's mood entries.
|
||||
*
|
||||
* Mood writes also dirty the analytics aggregate (correlations runner
|
||||
* pairs mood × pulse) and achievement progress (consistent-month / mood
|
||||
* badges).
|
||||
*/
|
||||
export function invalidateUserMood(userId: string): void {
|
||||
caches.moodAnalytics.deleteByPrefix(userId);
|
||||
caches.achievements.deleteByPrefix(userId);
|
||||
caches.analytics.deleteByPrefix(`${userId}|`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Invalidate every cache that may reflect a user's medication state.
|
||||
*
|
||||
* Covers the medications cache, the medication-intake compliance cache
|
||||
* (cached daily), and achievement progress.
|
||||
*/
|
||||
export function invalidateUserMedications(userId: string): void {
|
||||
caches.medications.deleteByPrefix(userId);
|
||||
caches.medicationsIntake.deleteByPrefix(`${userId}|`);
|
||||
caches.achievements.deleteByPrefix(userId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Invalidate the dashboard-widget layout cache for a single user.
|
||||
*
|
||||
* Called from the dashboard-widgets PUT / DELETE endpoints when the
|
||||
* user reorders / disables a tile.
|
||||
*/
|
||||
export function invalidateUserDashboardWidgets(userId: string): void {
|
||||
caches.dashboardWidgets.deleteByPrefix(userId);
|
||||
}
|
||||
|
||||
/**
|
||||
* Global eviction of the bug-report-status cache.
|
||||
*
|
||||
* The cache is keyed on the singleton `"singleton"` slot because the
|
||||
* underlying data is a row in `AppSettings`. Any admin write to the
|
||||
* GitHub-token / bug-report-enabled fields invalidates the entire
|
||||
* cache; the per-user `isAdmin` flag is layered on at request time, so
|
||||
* the cache itself only stores role-agnostic shape.
|
||||
*/
|
||||
export function invalidateAppSettings(): void {
|
||||
caches.bugreportStatus.deleteByPrefix("");
|
||||
}
|
||||
Vendored
+299
@@ -0,0 +1,299 @@
|
||||
/**
|
||||
* v1.4.34 IW-G — in-process LRU + single-flight server cache.
|
||||
*
|
||||
* Generalises the v1.4.33 Coach snapshot cache shape
|
||||
* (`src/lib/ai/coach/snapshot.ts:292-336`, commit `af17db5d`) into a
|
||||
* reusable primitive. Same recipe: `Map<string, { expiresAt, value }>`
|
||||
* gives us insertion-order iteration for LRU touch, a hard cap on
|
||||
* entries to bound memory, and a `pending` map so concurrent reads of
|
||||
* the same cold key fan into a single builder call.
|
||||
*
|
||||
* Design notes:
|
||||
*
|
||||
* - LRU touch is `delete + set` so re-insertion moves the key to the
|
||||
* end of the Map's iteration order. Eviction reads the first key
|
||||
* (least-recently-touched) via `map.keys().next().value`.
|
||||
*
|
||||
* - `wrap(key, builder)` is the only public read path. Misses register
|
||||
* the in-flight promise on `pending` before awaiting the builder so
|
||||
* a second caller for the same key inside the build window awaits
|
||||
* the same promise instead of starting a duplicate read. Rejected
|
||||
* promises remove themselves from `pending` so a transient failure
|
||||
* doesn't poison the key.
|
||||
*
|
||||
* - Metrics are per-instance: hits, misses, evictions, stampedes (a
|
||||
* caller that hit the single-flight join), and capacity (current
|
||||
* entry count). Read these via `stats()` for the wide-event
|
||||
* annotations the route handlers attach to each request.
|
||||
*
|
||||
* - The cache is process-local. A multi-instance Coolify deploy keeps
|
||||
* each container's cache isolated; the TTL bounds the staleness
|
||||
* window. The Redis migration path is sketched in the blueprint
|
||||
* (`.planning/research/v1434-r-cache-aggregation.md` §7).
|
||||
*
|
||||
* - `__resetForTests()` matches the snapshot pattern's escape hatch so
|
||||
* vitest's afterEach can clear every instance between tests without
|
||||
* reaching into the private `Map`.
|
||||
*/
|
||||
|
||||
export interface ServerCacheOptions {
|
||||
/** Hard cap on entries. Oldest entry is evicted on overflow. */
|
||||
readonly maxEntries: number;
|
||||
/** Time-to-live in milliseconds. Expired entries miss on read. */
|
||||
readonly ttlMs: number;
|
||||
/**
|
||||
* Optional name for observability — surfaced in `stats().name` so the
|
||||
* wide-event meta keys can carry the cache identity without the
|
||||
* caller having to remember which `caches.*` instance it pulled.
|
||||
*/
|
||||
readonly name?: string;
|
||||
}
|
||||
|
||||
export interface ServerCacheStats {
|
||||
readonly name: string;
|
||||
readonly size: number;
|
||||
readonly hits: number;
|
||||
readonly misses: number;
|
||||
readonly evictions: number;
|
||||
readonly stampedes: number;
|
||||
}
|
||||
|
||||
export class ServerCache<T> {
|
||||
private readonly map = new Map<string, { expiresAt: number; value: T }>();
|
||||
private readonly pending = new Map<string, Promise<T>>();
|
||||
private hits = 0;
|
||||
private misses = 0;
|
||||
private evictions = 0;
|
||||
private stampedes = 0;
|
||||
|
||||
constructor(private readonly opts: ServerCacheOptions) {}
|
||||
|
||||
/**
|
||||
* Read a key. Returns null on miss, expired entry, or absent entry.
|
||||
* Side effect: an expired entry is removed; a live entry is
|
||||
* LRU-touched (re-inserted) so subsequent reads keep it warm.
|
||||
*
|
||||
* Does NOT increment `hits`/`misses` — those live on the
|
||||
* `wrap()` path because the bare `get` is also called from tests
|
||||
* and from the test escape hatch.
|
||||
*/
|
||||
get(key: string): T | null {
|
||||
const entry = this.map.get(key);
|
||||
if (!entry) return null;
|
||||
if (entry.expiresAt <= Date.now()) {
|
||||
this.map.delete(key);
|
||||
return null;
|
||||
}
|
||||
// LRU touch — re-insertion moves the key to the end of the Map's
|
||||
// iteration order (which is the most-recently-used end).
|
||||
this.map.delete(key);
|
||||
this.map.set(key, entry);
|
||||
return entry.value;
|
||||
}
|
||||
|
||||
/** Insert or overwrite. Evicts the oldest entry if the cap is hit. */
|
||||
set(key: string, value: T): void {
|
||||
// The key might already exist (eviction-by-set is a write through
|
||||
// the same slot — no cap eviction needed). Delete-then-set to keep
|
||||
// the LRU ordering predictable.
|
||||
if (this.map.has(key)) {
|
||||
this.map.delete(key);
|
||||
} else if (this.map.size >= this.opts.maxEntries) {
|
||||
const oldest = this.map.keys().next().value;
|
||||
if (oldest !== undefined) {
|
||||
this.map.delete(oldest);
|
||||
this.evictions += 1;
|
||||
}
|
||||
}
|
||||
this.map.set(key, {
|
||||
expiresAt: Date.now() + this.opts.ttlMs,
|
||||
value,
|
||||
});
|
||||
}
|
||||
|
||||
/** Single-key eviction. Returns true when the key was present. */
|
||||
delete(key: string): boolean {
|
||||
return this.map.delete(key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Bulk eviction. Removes every entry whose key starts with `prefix`.
|
||||
* Returns the count of removed entries.
|
||||
*
|
||||
* The invalidation helpers in `./invalidate.ts` use this to flush an
|
||||
* entire user-bucket from a cache without having to enumerate every
|
||||
* possible cache-key variant the user might have warmed.
|
||||
*/
|
||||
deleteByPrefix(prefix: string): number {
|
||||
let removed = 0;
|
||||
for (const key of this.map.keys()) {
|
||||
if (key.startsWith(prefix)) {
|
||||
this.map.delete(key);
|
||||
removed += 1;
|
||||
}
|
||||
}
|
||||
return removed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Read-through + single-flight. On a live hit, returns the cached
|
||||
* value. On a miss, either joins an in-flight builder (single-flight)
|
||||
* or kicks off a new builder, stores the result, and returns it.
|
||||
*
|
||||
* Builder rejections do NOT poison the cache — the `pending` entry
|
||||
* is removed on reject so the next caller retries.
|
||||
*/
|
||||
async wrap(key: string, builder: () => Promise<T>): Promise<{
|
||||
value: T;
|
||||
outcome: "hit" | "miss" | "stampede";
|
||||
}> {
|
||||
const live = this.get(key);
|
||||
if (live !== null) {
|
||||
this.hits += 1;
|
||||
return { value: live, outcome: "hit" };
|
||||
}
|
||||
|
||||
const inFlight = this.pending.get(key);
|
||||
if (inFlight) {
|
||||
this.stampedes += 1;
|
||||
const value = await inFlight;
|
||||
return { value, outcome: "stampede" };
|
||||
}
|
||||
|
||||
this.misses += 1;
|
||||
const promise = builder()
|
||||
.then((value) => {
|
||||
this.set(key, value);
|
||||
return value;
|
||||
})
|
||||
.finally(() => {
|
||||
this.pending.delete(key);
|
||||
});
|
||||
this.pending.set(key, promise);
|
||||
const value = await promise;
|
||||
return { value, outcome: "miss" };
|
||||
}
|
||||
|
||||
/** Snapshot of per-instance counters for the wide-event annotation. */
|
||||
stats(): ServerCacheStats {
|
||||
return {
|
||||
name: this.opts.name ?? "unnamed",
|
||||
size: this.map.size,
|
||||
hits: this.hits,
|
||||
misses: this.misses,
|
||||
evictions: this.evictions,
|
||||
stampedes: this.stampedes,
|
||||
};
|
||||
}
|
||||
|
||||
/** Reset every counter + entry. Test-only escape hatch. */
|
||||
__resetForTests(): void {
|
||||
this.map.clear();
|
||||
this.pending.clear();
|
||||
this.hits = 0;
|
||||
this.misses = 0;
|
||||
this.evictions = 0;
|
||||
this.stampedes = 0;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-route cache instances. Module-scope so every request lands in the
|
||||
* same `Map`. Sizes match the blueprint §5 table.
|
||||
*
|
||||
* The blueprint's full eight-cache roster is provisioned so future
|
||||
* rounds can wire the remaining routes (`/api/medications`,
|
||||
* `/api/dashboard/widgets`, `/api/bugreport/status`, `/api/workouts`,
|
||||
* `/api/mood/analytics`) without churning the helper module.
|
||||
*/
|
||||
export const caches = {
|
||||
analytics: new ServerCache<unknown>({
|
||||
name: "analytics",
|
||||
maxEntries: 1000,
|
||||
ttlMs: 60_000,
|
||||
}),
|
||||
medications: new ServerCache<unknown>({
|
||||
name: "medications",
|
||||
maxEntries: 1000,
|
||||
ttlMs: 60_000,
|
||||
}),
|
||||
achievements: new ServerCache<unknown>({
|
||||
name: "achievements",
|
||||
maxEntries: 1000,
|
||||
ttlMs: 60_000,
|
||||
}),
|
||||
dashboardWidgets: new ServerCache<unknown>({
|
||||
name: "dashboardWidgets",
|
||||
maxEntries: 500,
|
||||
ttlMs: 300_000,
|
||||
}),
|
||||
bugreportStatus: new ServerCache<unknown>({
|
||||
name: "bugreportStatus",
|
||||
maxEntries: 10,
|
||||
ttlMs: 600_000,
|
||||
}),
|
||||
workouts: new ServerCache<unknown>({
|
||||
name: "workouts",
|
||||
maxEntries: 1000,
|
||||
ttlMs: 60_000,
|
||||
}),
|
||||
medicationsIntake: new ServerCache<unknown>({
|
||||
name: "medicationsIntake",
|
||||
maxEntries: 1000,
|
||||
ttlMs: 900_000,
|
||||
}),
|
||||
moodAnalytics: new ServerCache<unknown>({
|
||||
name: "moodAnalytics",
|
||||
maxEntries: 1000,
|
||||
ttlMs: 60_000,
|
||||
}),
|
||||
} as const;
|
||||
|
||||
/**
|
||||
* Non-reversible 32-bit hash of the cache key. Used in wide-event meta
|
||||
* so we can correlate hit / miss patterns without leaking the raw
|
||||
* userId portion of the key into logs.
|
||||
*
|
||||
* djb2 — public domain, two lines, matches the blueprint §8 sketch.
|
||||
*/
|
||||
export function hashCacheKey(key: string): number {
|
||||
let hash = 5381;
|
||||
for (let i = 0; i < key.length; i += 1) {
|
||||
hash = ((hash << 5) + hash + key.charCodeAt(i)) | 0;
|
||||
}
|
||||
return hash >>> 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Read-through wrapper that also annotates the active wide-event with
|
||||
* the cache hit / miss / stampede outcome and a key hash. Matches the
|
||||
* observability contract in the blueprint §8.
|
||||
*
|
||||
* Falls back gracefully when no logging context is active (the
|
||||
* `annotate()` call is a no-op outside of `apiHandler`).
|
||||
*/
|
||||
export async function cached<T>(
|
||||
cache: ServerCache<T>,
|
||||
key: string,
|
||||
builder: () => Promise<T>,
|
||||
annotateFn?: (fields: { meta: Record<string, unknown> }) => void,
|
||||
): Promise<T> {
|
||||
const { value, outcome } = await cache.wrap(key, builder);
|
||||
if (annotateFn) {
|
||||
const name = cache.stats().name;
|
||||
annotateFn({
|
||||
meta: {
|
||||
[`cache.${name}.outcome`]: outcome,
|
||||
[`cache.${name}.key_hash`]: hashCacheKey(key),
|
||||
},
|
||||
});
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
/** Test helper — reset every cache in the registry. */
|
||||
export function __resetAllCachesForTests(): void {
|
||||
for (const cache of Object.values(caches)) {
|
||||
cache.__resetForTests();
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user