Repository navigation
fix(dashboard): serve worker assets no-store so a header-only upgrade reaches browsers - #15476
Conversation
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Description disclaims half the diff: "Not a goal... folding a build id into query strings," yet Watch
[DESIGN-REVIEWED] af896d0 Description read[DESCRIPTION-READ] cd5f68922b1a599ba02174e93f5abed049f480b0e907e963db547001656a4e86 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The build-id query key Not justified as shipped
What this change shipsInventory (5 items) — 3 justifiedIntent: FIX — a gateway upgrade that changes only a response header (a worker's CSP) reaches browser users' worker scripts instead of being frozen for a year (Fixes #15337).
[FIRST-PRINCIPLES-REVIEWED] af896d0 Description read[DESCRIPTION-READ] 3ac7733ae92debb09da159a6ef3e5b92f1344f7ac6d941b238ad2b4bcdb7dc2e That sha256 names the PR description this verdict read. Recompute it with |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsAdvisory only: the owning spec still documents the removed FINDING — docs/system-specs/modules/learn-cron-dashboard.md:3212 — the owning spec's "Pierre worker cache identity" paragraph still states that FINDING — src/kiro_crew/dashboard/server.py:1359 — the comment claims the naming convention "is asserted against the built dist by test_every_built_worker_chunk_carries_the_marker so a worker named without it fails the build", but the only CI jobs that run [OPUS-REVIEWED] af896d0 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
e788efc to
9fa92df
Compare
9fa92df to
54e672f
Compare
54e672f to
6febd24
Compare
UX Review (Fable 5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. The diff changes only HTTP cache headers and internal worker-URL construction — no user-visible control, label, string, or state is added or changed, so no screenshot or blind read is required for this revision. [UX-REVIEWED] af896d0 Description read[DESCRIPTION-READ] 75f66f38d877117b489635f08057196e876b96b501339750d8c60d7a8b18baf7 That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
64691a7 to
f4b36a4
Compare
026e105 to
3fa5b85
Compare
3fa5b85 to
6e04877
Compare
…aches browsers ## Problem / Motivation **Goal:** A gateway upgrade that changes only a response header (a CSP directive) reaches browser users, instead of leaving their worker scripts frozen on a stale build's header for up to a year. The dashboard serves content-hashed `/assets/` files with `public, max-age=31536000, immutable`. A build that changes only a response header keeps the identical hashed filenames, so a browser that cached a file replays its old header. For a worker script this is a live defect: a same-origin worker takes its CSP from its own script response header, not from the document. After a header-only upgrade (for example widening `script-src` for a new WASM engine) the browser keeps replaying the worker's old CSP, its WASM instantiation is refused, and every diff/highlight surface dies until a hard refresh the user has no reason to perform. ## Why it matters Every browser user who cached a worker before a header-only upgrade is stranded: the highlight/diff engines silently fail and neither a tunnel rebuild nor a gateway restart fixes it, because the cache key is the local URL. Only a manual hard refresh clears it. The desktop shell half (PR #15323) clears the Electron cache per app+gateway version; a browser cannot be told to drop a cache entry, so this half stops the worker's header from being frozen for a year in the first place. ## Not a goal - No change to plain JS/CSS chunk caching — those run under the document's CSP (served no-store, always fresh), so their stale header is harmless and they keep the immutable policy that spares the ~6MB entry bundle a re-download per load. - Not folding a build id into asset URLs or query strings (the issue's other option): it needs build-tooling changes and only helps if the id reliably changes on a header-only build, whereas the worker cache policy fixes exactly the exposed asset class at the serving layer. ## What changed (motivation → approach → change) Symptom: after a header-only upgrade a browser's cached worker runs an old CSP and diff/highlight surfaces stay dead. Root cause: `/assets/` worker scripts are cached `immutable`, but a worker's runtime CSP comes from its own cached response header, and Vite hashes a chunk by content only — so a header-only build reuses the same worker URL and the year-cached header is never re-fetched. Change: `_asset_cache_control` classifies a `/assets/` path — worker chunks (matched by the `worker` substring Vite stamps into every worker chunk name, case-insensitive) get a SHORT-LIVED cacheable policy (`public, max-age=60, stale-if-error=86400`) instead of `immutable`; every other hashed chunk keeps `immutable`. A 60-second `max-age` re-fetches the worker within a minute of a header-only build (bounding the stale-CSP window to a minute of degraded highlight, not a year) AND keeps the bytes cache-servable across a brief gateway-down window — a bare `no-store` would evict them and make the worker unloadable exactly then. The policy deliberately omits `no-cache`/`must-revalidate`, which forbid the cache reuse the gateway-down survival depends on; `stale-if-error` is a best-effort grant to a caching tunnel/proxy (no mainstream browser honours it), so for a plain browser the gateway-down coverage is the `max-age` window alone. The prepare-time finalizer downgrades an errored worker path to no-store so neither the browser caches the error nor an intermediary serves an orphaned worker's stale bytes. ## Backwards compatibility Compatible: worker chunks are re-fetched after a 60-second fresh window instead of served from cache for a year, and no request is rejected, renamed, or removed. All other assets keep their existing policy. ## Tests - `test_worker_assets_use_short_lived_not_immutable_or_no_store`: worker chunks carry `max-age=60`, never `immutable`, never `no-store`, and — the header contradiction Opus flagged — never `no-cache`/`must-revalidate`. Fails on base, where a worker path gets `immutable`. - `test_non_worker_assets_stay_immutable`: plain JS/CSS chunks keep `immutable`, pinning the exemption as surgical. - `test_every_built_worker_chunk_carries_the_marker`: scans the frontend source for worker constructions (`new Worker(new URL(...))`, `?worker`) and asserts each resolves, in the built dist, to a chunk carrying the marker — so a worker Vite renames to drop the marker (silently regaining `immutable`) fails the build. Skipped in a python-only/unbuilt checkout. - `test_present_worker_asset_uses_short_lived_policy` / `test_missing_worker_asset_is_downgraded_to_no_store`: drive the real static mount + middleware + finalizer to assert the wire headers, including that the policy carries no `no-cache`/`must-revalidate` and that a worker 404 loses the cacheable policy. ## Manual verification N/A — the change is at the response-header layer and unit coverage exercises the worker, non-worker, and errored-worker paths through the real serving stack. ## Related Issues Fixes #15337 ## Pattern harvest Not generalizable: a one-off interaction between one asset class whose behaviour is header-governed (workers take CSP from their own response) and a content-hash cache key that does not change on a header-only build. The fix is specific to this serving path, not a class of defect a lint or rule would catch elsewhere.
…wser abandons a stranded immutable entry A worker script is served with a short-lived cache policy so a header-only build reaches it, but that policy only governs a fresh fetch. A browser that holds a worker under the year-long immutable policy keeps it at the identical content-hashed URL and never revalidates it, so the served policy can never overwrite it. Append the compile-time build identity (__APP_VERSION__) as a query string to every worker URL, making it a distinct cache key per version: the browser requests a URL it does not hold under the stranded immutable entry, fetches the worker afresh under the short-lived policy, and every version bump rotates the key again. The query does not touch Vite content hashing, and the server classifies and resolves the file by request.path (query stripped), so the same emitted chunk is served with the short-lived worker policy. Applied at the three worker instantiation sites via a shared helper; replaces a hand-maintained static query param on the highlight worker with the same build-keyed mechanism so it rotates automatically.
6e04877 to
af896d0
Compare
|
Read-only review, holding for accuracy rather than code. The server change is right: only /assets/ files named with worker get the short policy, everything else stays immutable, worker 404s drop to no-store. Before approval: (1) the title says no-store but server.py:1370 sets 'public, max-age=60, stale-if-error=86400'; please retitle so the squash subject is accurate. (2) 'Not a goal' rules out a build id in query strings, yet workerCacheKey.ts:41 appends ?v=APP_VERSION at three worker call sites; please describe that frontend half and why it is needed. (3) test_every_built_worker_chunk_carries_the_marker returns early when website/dist is missing, which reports as a pass; use pytest.skip() so a run that checked nothing is visible. Minor: matching 'worker' anywhere in a filename also catches non-worker chunks (costs caching only). |
buluoray
left a comment
There was a problem hiding this comment.
Summary
Reviewed at head af896d013c2c429aee93f70507d479ddd8b3bd6e. The fix has two halves and both are correct:
- Server (
src/kiro_crew/dashboard/server.py:1376-1390):_asset_cache_controlgives/assets/*worker*chunkspublic, max-age=60, stale-if-error=86400in place ofimmutable. Every other hashed chunk keepsimmutable. The prepare-time finalizer (server.py:1606-1611) now also downgrades a non-2xx/304 response carrying the worker policy to no-store, so a worker 404 is never cached. - Frontend (
website/src/utils/workerCacheKey.ts:34-42plus three call sites): each worker URL gets?v=<__APP_VERSION__>. The server policy alone cannot rescue this: a browser already holding a worker underimmutablenever revalidates it, so the URL has to change.__APP_VERSION__is the existingdefine(vite.config.ts:698), declared insrc/vite-env.d.ts.request.pathdrops the query, so the server's classification andadd_static's file resolution are unchanged.
Every new branch fails closed. If the classification is wrong, the asset gets either the old immutable policy (today's behaviour) or a 60s cache (costs a re-fetch only). If the finalizer branch is missed, a 404 keeps a 60s cache, which is a bounded window, not a permanent strand. No auth, data or persistence paths are touched. The worker build format is unchanged: ?worker&url and new Worker(new URL(...)) both build with the same worker config, and PierreImpl.tsx already used ?worker&url before this PR.
Verified
- Head SHA pinned and the worktree confirmed at it. CI at head: 18 success, 2 skipped (fork-only gates), 0 failure. The PR is open and unmerged.
- Targeted Python tests (
test/test_dashboard_security_headers.py,test/test_dashboard_asset_404_cache.py): baseline 34 passed. Mutations:- M1: worker branch returns
immutable. Failstest_worker_assets_use_short_lived_not_immutable_or_no_storeandtest_present_worker_asset_uses_short_lived_policy. - M2: finalizer only matches
immutable, as on base. Failstest_missing_worker_asset_is_downgraded_to_no_store. - M3:
.lower()dropped from the marker match. Fails the same two tests as M1.
- M1: worker branch returns
test_every_built_worker_chunk_carries_the_marker: run against a symlinked builtdist, which hasdiffWorker-,hljsWorker-,worker-portable-andsubset-worker.chunk-. It passed, so the detection logic works when a dist is present.- Frontend
website/src/utils/workerCacheKey.test.ts: 4 passed. Mutation (return base, no key) fails 3 of the 4, including "appends a non-empty build-identity query to a bare URL". website/src/test/PierreImpl.workerPool.test.tsxcould not run locally. Vite'sfs.allowrefuses the symlinkednode_modules(Denied ID .../worker-portable.js?worker&url). This is an environment limit, not a PR defect, and CI Build is green. The rewrittenv=pin in that file was read, not executed.- Tests were not run locally beyond these targeted files.
Bot claims disposition
- Design / First Principles (CONCERNS): the description's "Not a goal" rejects a build id in query strings, yet
workerCacheKey.tsships one. The title says "no-store" but the policy ismax-age=60. Real, for the description and title only. The code is right, and the build-key half is the only part that rescues browsers already stranded underimmutable. This is a PR-description defect, so it does not block. Because the squash subject lands in main, the title must be fixed (follow-up 1). - Design / Opus / iamwhatever:
test_every_built_worker_chunk_carries_the_markerreturns early without a dist and reports a pass. CI'sbackend-testnever builds the frontend. Real..github/workflows/ci.ymlbackend-test(line 631 onward) has nonpm/build step, so in CI this guard checks nothing. Theserver.py:1359comment that says it "fails the build" overstates what the guard does. It is a test-coverage gap, not a logic defect, so it does not block (follow-up 2). - Opus: the owning spec
docs/system-specs/modules/learn-cron-dashboard.md:3212still describescsp=wasm-v1and only theimmutableframing. Real. The diff has nodocs/changes, and that paragraph now names a query parameter the app no longer sends. Under AGENTS.md the spec should change in the same commit. It is docs only, so it does not block (follow-up 3). - First Principles:
stale-if-error=86400has no browser consumer. Real, and the code comment already says so. It is harmless, but tightening the policy topublic, max-age=60would be the honest minimum. Taste, not a gate. - iamwhatever (minor): matching
workeranywhere in a filename also catches non-worker chunks. Real but harmless. Such a chunk loses only the year-long cache and gets a 60s one instead. Fails closed. - GPT 5.6, Opus (no blocking), UX (PASS): agreed.
Follow-ups (non-blocking)
- Retitle the PR before merge so the squash subject matches the behaviour, for example
fix(dashboard): short-cache worker assets and key their URLs to the build. Rewrite "Not a goal" / "What changed" / "Tests" to cover the?v=__APP_VERSION__half and why it is needed: animmutableentry is never revalidated. - Change the early
returns intest_every_built_worker_chunk_carries_the_markertopytest.skip(...), so a run that checked nothing shows up as skipped. Either run it in a job that has a built dist, or soften theserver.py:1359"fails the build" claim. - Update the "Pierre worker cache identity" paragraph in
docs/system-specs/modules/learn-cron-dashboard.md(around line 3212) to describe the?v=build key and the server-side worker policy in_asset_cache_control. - Note that
__APP_VERSION__ispackage.jsonversion. A header-only change shipped without a version bump keeps the same?v=, and only the 60smax-agecovers it. That is fine now that the policy is short-lived, but the comment inworkerCacheKey.tsshould not imply that every build gets a distinct key.
Problem / Motivation
Goal: A gateway upgrade that changes only a response header (a CSP directive) reaches browser users, instead of leaving their worker scripts frozen on a stale build's header for up to a year.
The dashboard serves content-hashed
/assets/files withpublic, max-age=31536000, immutable. A build that changes only a response header keeps the identical hashed filenames, so a browser that cached a file replays its old header. For a worker script this is a live defect: a same-origin worker takes its CSP from its own script response header, not from the document. After a header-only upgrade (for example wideningscript-srcfor a new WASM engine) the browser keeps replaying the worker's old CSP, its WASM instantiation is refused, and every diff/highlight surface dies until a hard refresh the user has no reason to perform.Why it matters
Every browser user who cached a worker before a header-only upgrade is stranded: the highlight/diff engines silently fail and neither a tunnel rebuild nor a gateway restart fixes it, because the cache key is the local URL. Only a manual hard refresh clears it. The desktop shell half (PR #15323) clears the Electron cache per app+gateway version; a browser cannot be told to drop a cache entry, so this half stops the worker's header from being frozen for a year in the first place.
Not a goal
What changed (motivation → approach → change)
Symptom: after a header-only upgrade a browser's cached worker runs an old CSP and diff/highlight surfaces stay dead. Root cause:
/assets/worker scripts are cachedimmutable, but a worker's runtime CSP comes from its own cached response header, and Vite hashes a chunk by content only — so a header-only build reuses the same worker URL and the year-cached header is never re-fetched. Change:_asset_cache_controlclassifies a/assets/path — worker chunks (matched by theworkersubstring Vite stamps into every worker chunk name, case-insensitive) get a SHORT-LIVED cacheable policy (public, max-age=60, stale-if-error=86400) instead ofimmutable; every other hashed chunk keepsimmutable. A 60-secondmax-agere-fetches the worker within a minute of a header-only build (bounding the stale-CSP window to a minute of degraded highlight, not a year) AND keeps the bytes cache-servable across a brief gateway-down window — a bareno-storewould evict them and make the worker unloadable exactly then. The policy deliberately omitsno-cache/must-revalidate, which forbid the cache reuse the gateway-down survival depends on;stale-if-erroris a best-effort grant to a caching tunnel/proxy (no mainstream browser honours it), so for a plain browser the gateway-down coverage is themax-agewindow alone. The prepare-time finalizer downgrades an errored worker path to no-store so neither the browser caches the error nor an intermediary serves an orphaned worker's stale bytes.Backwards compatibility
Compatible: worker chunks are re-fetched after a 60-second fresh window instead of served from cache for a year, and no request is rejected, renamed, or removed. All other assets keep their existing policy.
Tests
test_worker_assets_use_short_lived_not_immutable_or_no_store: worker chunks carrymax-age=60, neverimmutable, neverno-store, and — the header contradiction Opus flagged — neverno-cache/must-revalidate. Fails on base, where a worker path getsimmutable.test_non_worker_assets_stay_immutable: plain JS/CSS chunks keepimmutable, pinning the exemption as surgical.test_every_built_worker_chunk_carries_the_marker: scans the frontend source for worker constructions (new Worker(new URL(...)),?worker) and asserts each resolves, in the built dist, to a chunk carrying the marker — so a worker Vite renames to drop the marker (silently regainingimmutable) fails the build. Skipped in a python-only/unbuilt checkout.test_present_worker_asset_uses_short_lived_policy/test_missing_worker_asset_is_downgraded_to_no_store: drive the real static mount + middleware + finalizer to assert the wire headers, including that the policy carries nono-cache/must-revalidateand that a worker 404 loses the cacheable policy.Manual verification
N/A — the change is at the response-header layer and unit coverage exercises the worker, non-worker, and errored-worker paths through the real serving stack.
Related Issues
Fixes #15337
Pattern harvest
Not generalizable: a one-off interaction between one asset class whose behaviour is header-governed (workers take CSP from their own response) and a content-hash cache key that does not change on a header-only build. The fix is specific to this serving path, not a class of defect a lint or rule would catch elsewhere.