brain-of-reese/.agent/user_stories/cache-busting.md

Story: Cache Busting (Un-stick the Pages)

Phase: 33_cache_busting/ · E2E: tests/e2e/test_cache_busting.py

Narrative

As anyone using Brain of Reese, I want a new deploy to be visible without a hard refresh. Today the five HTML pages reference their CSS/JS with no version at all, so the browser keeps serving stale assets long after the app has moved on — the "the pages are too sticky" report. I want a deploy (a commit) to change what the browser fetches, automatically, with no new services and no CDN.

• Given the app has been redeployed (a new commit)
• When I open — or revisit — any page
• Then the page itself is always revalidated (never served from cache unchecked), its assets are fetched from versioned URLs (?v=<token> — the git short SHA of the deploy, so each commit changes them), and the API — the SSE chat stream in particular — is left byte-for-byte alone.

Acceptance criteria

1. HTML always revalidates. All five pages (/, /index.html, /sources.html, /document.html, /login.html, /tuning.html) ship Cache-Control: no-cache (the page is the cheap redirector to the long-cached assets).
2. Assets are versioned. Every local href/src asset reference on those pages carries ?v=<token> — rewritten in flight by one middleware (a small regex over href/src assets/… refs, leading slash optional, idempotent: an existing query string or fragment is never double-tagged, and non-asset references pass through). The token is non-empty and stable across requests within a process (one token per process, computed once).
3. Immutable assets. /assets/* responses ship Cache-Control: public, max-age=31536000, immutable — safe precisely because the URL carries the token (a deploy changes the token, hence the URL). The unversioned path keeps resolving (the static mount ignores the query string), so old tabs and direct links still work.
4. The token is the deploy. app/core/caching.py::asset_version(): a git checkout (the project root next to frontend/ has a .git — the homelab reality) → git rev-parse --short HEAD with a 5 s timeout (a deploy must not hang a boot); no .git, git missing, non-zero exit, timeout, or empty output → the first 12 hex chars of SHA-256 over the sorted relpath:mtime_ns:size of every regular file under frontend/; a missing/empty static dir → "dev". Cached with functools.cache (== lru_cache(maxsize=None)) — zero per-request git/file cost. A new commit or a frontend content change flips the token on the next process start.
5. The API is untouched. The middleware touches exactly two response shapes (the page paths: body rewrite + no-cache; /assets/*: header only). Everything else — all of /api/*, including the SSE chat stream — passes through with no header changes and no body read (SSE keeps the no-cache its endpoint sets itself). The no-CDN integration test stays green (the rewritten references are same-origin).
6. Quality gates. Unit (tests/unit/test_caching.py): the token's git path, fallback path (stable across an unchanged tree, flips on a touch/modify + cache_clear()), failure path (git raising → content hash, no exception), empty-dir "dev"; the pure rewrite_asset_refs (versioned href/src, no-leading-slash refs, module scripts, idempotency, #fragment/existing-query left alone, non-asset refs untouched). Integration (tests/integration/test_api.py): every page no-cache + versioned references, asset headers, no cache-control injected on /api/health, SSE chat tests unchanged and green. Coverage: app/core/caching.py 100 %, app/ > 90 % (TOTAL ≥ pre-change).
7. E2E (this story's gate). tests/e2e/test_cache_busting.py, run in isolation: a real (fresh-profile) Chromium asserts the wire truth — the document responses are no-cache, the CSS/JS request URLs the browser actually makes carry one shared token (matching this checkout's asset_version()), the asset responses are immutable for a year, and /api/* — including a live SSE chat turn that streams deltas and completes with done — is unaffected (mock LLM, no live aipi; podman compose up -d db for the chat check).

Playwright Mapping Rule

tests/e2e/test_cache_busting.py — run in isolation (Chromium + podman compose up -d db; mock LLM via the shared conftest.py session app; no per-module overrides needed):

1. test_html_pages_are_no_cache_and_versioned → AC 1 + 2 + 3 (the / document response is no-cache; the styles.css request URL carries ?v=<token> and its response is immutable + max-age=31536000; the app.js request URL carries the same token; the served HTML carries no unversioned "/assets/styles.css" reference).
2. test_other_pages_share_the_token → AC 1 + 2 (the /sources.html and /login.html document responses are no-cache; both pages' stylesheet requests carry the same token).
3. test_api_responses_unaffected → AC 5 (/api/health has no cache-control injected — the endpoint's baseline headers only; the SSE chat POST still streams deltas and completes with done).