Asset caching: hashed immutable, unhashed revalidated, public/ assets through Vite¶
Problem¶
- maplibre-gl 6 ships its worker as a separate ES module that imports a
sibling
maplibre-gl-shared.mjs. The nginx base image'smime.typeshas nomjsentry, so both were served asapplication/octet-streamand Chrome refused the module (#2835, map missing on Travel). - 1.4.13 added an
.mjslocation with a one-yearimmutableheader, so the broken octet-stream response was cached for a year. A header fix alone cannot reach those browsers. - The same shape hit CSV templates (#2812):
public/templates/*.csvhad noCache-Controlat all, so browsers cached them heuristically and some users kept the old external AI template after it was replaced. public/images, fonts and favicons were stampedimmutableunder stable names. Replacing one under the same name left returning users on the old file for a year.
Decisions¶
- MIME types are registered once at http level with a
types { }block afterinclude mime.types:application/javascript mjs; text/csv csv;. Stock nginx 1.30 has neither. - Only Vite-hashed names get
immutable. The hash is exactly 8 base64url chars (-/_included), matched by a quoted regex"-[A-Za-z0-9_-]{8}\.(ext…)$". Exact count: an open-ended{8,}also matchedmaplibre-gl-shared.mjsthrough-gl-shared. Unquoted braces are parsed by nginx as a block and the server refuses to start. - Everything else revalidates with
no-cache, must-revalidate. The split stays even though the build now emits no unhashed asset: it is the guard for the next unhashed copy someone adds. - The worker is bundled by Vite via
?worker&urlinTripsMap.vue. The shared chunk is inlined into one hashed file, the afterBuild copy inquasar.config.jsis gone, and the worker URL changes, which is what evicts the polluted cache entries. public/assets move tosrc/assetsso every reference is content-hashed:index.htmlfavicon and font preload links, SCSSurl()for fonts and the login background, an explicitimportfor the logo, andimport.meta.globwith?url&no-inlinefor the templates.urlis needed because.csvis not a Vite asset type;no-inlinebecause Vite inlines anything under 4 KB as a data URI.a.downloadkeeps the plain template file name for the user.public/keeps onlyinjectEnv.js(runtime config, served from/tmpby an exact-match location) and a plainfavicon.icofor clients that probe/favicon.icowithout readingindex.html.index.htmllinks it asfavicon.ico?v=<%= appVersion %>(QuasarhtmlVariables, fed by the same git SHA asAPP_VERSION), andlocation = /favicon.icocaches it for a day: releases bust it through the query, bare probes wait a day.- The glob lives in a browser-only leaf,
constant/templateAssets.ts, not intemplateMapping.ts: the latter is imported by a Node-side Playwright test that cannot evaluateimport.meta.glob(same constraint asmergeLivePipelineJob). The leaf keys URLs by file name and throws at boot if anySHIPPED_TEMPLATESentry is not bundled, so a wrong glob path fails the first page load rather than a user's click. - No
expiresdirectives.expiresandadd_header Cache-Controlon the same location emit twoCache-Controlheaders; onlyadd_headerremains. - The template directory is checked from both sides.
backend/tests/unit/test_shipped_csv_templates.pyruns every CSV on disk through the ingestion parser (it lives in the backend because the parser does).frontend/tests/unit/template-mapping.spec.tsasserts the mapping and the directory agree exactly via the exportedSHIPPED_TEMPLATES. A moved directory, an orphan file or a dangling entry (the oldequipments_template.csvdefault, removed here) fails both suites.
Delivered¶
-
2837: MIME registration and the hashed/unhashed split for JS/CSS/MJS.¶
-
2838: worker bundling, split extended to every asset type plus
csv,¶public/assets hashed through Vite, unreferencedpublic/leftovers removed, backend template test and frontend template test repointed atsrc/assets/templates.
Verification¶
Build served from nginxinc/nginx-unprivileged:stable-alpine-slim against
dist/spa: the only unhashed files are index.html, injectEnv.js and
favicon.ico; 22 of 22 templates emitted as hashed files and referenced
from the chunk; hashed js/csv/png/svg/woff2 answer immutable with the
right Content-Type; index.html and /travel answer no-cache.
Not done¶
- A
location ^~ /assets/prefix rule would replace the regexes but would re-stampimmutableon any unhashed file copied intoassets/, which is exactly the failure this plan fixes. Rejected. - Extensions outside the two lists (
.wasm,.webmanifest) fall through tolocation /with noCache-Control. Add them to both lists when one ships.