Public: anyone can read this; the crew can change it.
Immutable assets carry a content hash and `immutable` cache headers, with a test that fails without them #13020
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13009-immutable-assets-carry-a-content-hash-an → main 5 commits fork 2 threads · 2 unresolved
3 files
changed +154
−11
src/http/server.ts +20 −6
| @@ -149,6 +149,8 @@ import { | ||
| 149 | 149 | speculationAsset, |
| 150 | 150 | spriteAsset, |
| 151 | 151 | shellAsset, |
| 152 | keepReleaseAssets, | |
| 153 | keptAssetNamed, | |
| 152 | 154 | stylesheetAsset, |
| 153 | 155 | stylesheetRedirect, |
| 154 | 156 | stylesheetResponse, |
| @@ -824,7 +826,11 @@ export function buildRouter(): Router<Handler> { | ||
| 824 | 826 | // a short-lived redirect for pages rendered before the hash existed. |
| 825 | 827 | router.add("GET", "/assets/:name.css", (ctx) => { |
| 826 | 828 | if (ctx.params.name === "forge") return stylesheetRedirect(); |
| 827 | if (ctx.params.name !== stylesheetAsset().name) return notFound(); | |
| 829 | const dir = ctx.app.config.dataDir; | |
| 830 | if (ctx.params.name !== stylesheetAsset().name) { | |
| 831 | const old = keptAssetNamed(dir, ctx.params.name!, "css"); | |
| 832 | return old === undefined ? notFound() : fileResponse(ctx.request, old); | |
| 833 | } | |
| 828 | 834 | return stylesheetResponse(ctx.request); |
| 829 | 835 | }); |
| 830 | 836 | // What the open web expects of a site, from the forge's own facts. |
| @@ -857,9 +863,11 @@ export function buildRouter(): Router<Handler> { | ||
| 857 | 863 | // with, so a miss means an old tab, and an old tab should reload. |
| 858 | 864 | router.add("GET", "/assets/:name.js", async (ctx) => { |
| 859 | 865 | const shell = shellAsset(); |
| 866 | const dir = ctx.app.config.dataDir; | |
| 860 | 867 | if (ctx.params.name === shell.name) return assetResponse(ctx.request, shell); |
| 861 | if (ctx.params.name === beaconAsset().name) | |
| 862 | return assetResponse(ctx.request, beaconAsset()); | |
| 868 | if (ctx.params.name === beaconAsset().name) return assetResponse(ctx.request, beaconAsset()); | |
| 869 | const prev = keptAssetNamed(dir, ctx.params.name!, "js"); | |
| 870 | if (prev !== undefined) return fileResponse(ctx.request, prev); | |
| 863 | 871 | if (ctx.params.name === TOOLBAR_NAME) return toolbarResponse(ctx.request); |
| 864 | 872 | const own = pageScriptNamed(ctx.params.name!, ctx.app.config.dataDir); |
| 865 | 873 | if (own !== undefined) return fileResponse(ctx.request, own); |
| @@ -877,9 +885,14 @@ export function buildRouter(): Router<Handler> { | ||
| 877 | 885 | return assetResponse(ctx.request, asset); |
| 878 | 886 | }); |
| 879 | 887 | // The icon sprite and the speculation rules: hashed, immutable, one file each. |
| 880 | router.add("GET", "/assets/:name.svg", (ctx) => | |
| 881 | ctx.params.name === spriteAsset().name ? fileResponse(ctx.request, spriteAsset()) : notFound(), | |
| 882 | ); | |
| 888 | router.add("GET", "/assets/:name.svg", (ctx) => { | |
| 889 | const dir = ctx.app.config.dataDir; | |
| 890 | if (ctx.params.name !== spriteAsset().name) { | |
| 891 | const old = keptAssetNamed(dir, ctx.params.name!, "svg"); | |
| 892 | return old === undefined ? notFound() : fileResponse(ctx.request, old); | |
| 893 | } | |
| 894 | return fileResponse(ctx.request, spriteAsset()); | |
| 895 | }); | |
| 883 | 896 | // The machine shell's terminal emulator (`web/machine-term-asset.ts`). |
| 884 | 897 | router.add("GET", "/assets/:name.wasm", (ctx) => |
| 885 | 898 | ctx.params.name === ghosttyWasmAsset().name ? wasmResponse(ctx.request) : notFound(), |
| @@ -2616,6 +2629,7 @@ export function forgeHttp(app: App): ForgeHttp { | ||
| 2616 | 2629 | } |
| 2617 | 2630 | |
| 2618 | 2631 | export async function serve(app: App): Promise<Servers> { |
| 2632 | keepReleaseAssets(app.config.dataDir); | |
| 2619 | 2633 | const router = buildRouter(); |
| 2620 | 2634 | const apiRouter = buildApiRouter(); |
| 2621 | 2635 | await clearStaleSockets(app); |
src/web/asset.ts +38 −5
| @@ -269,7 +269,7 @@ export function pageScriptAsset(js: string, dataDir?: string): FileAsset { | ||
| 269 | 269 | asset = fileAsset("page", "js", body, "text/javascript; charset=utf-8"); |
| 270 | 270 | remember(key, asset); |
| 271 | 271 | } |
| 272 | if (dataDir !== undefined) keep(dataDir, asset); | |
| 272 | if (dataDir !== undefined) keep(dataDir, asset.name, asset.code, "js"); | |
| 273 | 273 | return asset; |
| 274 | 274 | } |
| 275 | 275 | |
| @@ -287,12 +287,12 @@ const pruned = new Set<string>(); | ||
| 287 | 287 | export const pageScriptDir = (dataDir: string): string => join(dataDir, "page-scripts"); |
| 288 | 288 | |
| 289 | 289 | /** Write once per data dir per process; touch it if it is there, so pruning spares what is in use. */ |
| 290 | function keep(dataDir: string, asset: FileAsset): void { | |
| 291 | const id = `${dataDir}\0${asset.name}`; | |
| 290 | function keep(dataDir: string, name: string, code: string, ext: string): void { | |
| 291 | const id = `${dataDir}\0${name}.${ext}`; | |
| 292 | 292 | if (kept.has(id)) return; |
| 293 | 293 | kept.add(id); |
| 294 | 294 | const dir = pageScriptDir(dataDir); |
| 295 | const file = join(dir, `${asset.name}.js`); | |
| 295 | const file = join(dir, `${name}.${ext}`); | |
| 296 | 296 | try { |
| 297 | 297 | mkdirSync(dir, { recursive: true }); |
| 298 | 298 | if (!pruned.has(dir)) { |
| @@ -305,7 +305,7 @@ function keep(dataDir: string, asset: FileAsset): void { | ||
| 305 | 305 | return; |
| 306 | 306 | } |
| 307 | 307 | const tmp = `${file}.${process.pid}.tmp`; |
| 308 | writeFileSync(tmp, asset.code); | |
| 308 | writeFileSync(tmp, code); | |
| 309 | 309 | renameSync(tmp, file); |
| 310 | 310 | } catch (error) { |
| 311 | 311 | // Not fatal: this process still serves it from memory. |
| @@ -348,3 +348,36 @@ export function pageScriptNamed(name: string, dataDir?: string): FileAsset | und | ||
| 348 | 348 | export function fileResponse(request: Request, asset: FileAsset): Response { |
| 349 | 349 | return staticResponse(request, asset.code, asset.type, asset.etag); |
| 350 | 350 | } |
| 351 | ||
| 352 | const KEPT_TYPES: Record<string, string> = { | |
| 353 | css: "text/css; charset=utf-8", | |
| 354 | js: "text/javascript; charset=utf-8", | |
| 355 | svg: "image/svg+xml; charset=utf-8", | |
| 356 | }; | |
| 357 | const KEPT_NAME = /^(forge|shell|beacon|i)-[0-9a-f]{16}$/; | |
| 358 | ||
| 359 | /** Keep this release's own assets on disk, once at boot: the next release answers their hashes. */ | |
| 360 | export function keepReleaseAssets(dataDir: string): void { | |
| 361 | keep(dataDir, stylesheetAsset().name, css, "css"); | |
| 362 | keep(dataDir, shellAsset().name, shellAsset().code, "js"); | |
| 363 | keep(dataDir, beaconAsset().name, beaconAsset().code, "js"); | |
| 364 | keep(dataDir, spriteAsset().name, spriteAsset().code, "svg"); | |
| 365 | } | |
| 366 | ||
| 367 | /** | |
| 368 | * An asset of an earlier release, by its hashed name: read back from disk, and | |
| 369 | * served only if the bytes hash to the name. Never a path the request chose. | |
| 370 | */ | |
| 371 | export function keptAssetNamed(dataDir: string, name: string, ext: string): FileAsset | undefined { | |
| 372 | const type = KEPT_TYPES[ext]; | |
| 373 | if (type === undefined || !KEPT_NAME.test(name)) return undefined; | |
| 374 | let body: string; | |
| 375 | try { | |
| 376 | body = readFileSync(join(pageScriptDir(dataDir), `${name}.${ext}`), "utf8"); | |
| 377 | } catch { | |
| 378 | return undefined; | |
| 379 | } | |
| 380 | const hash = sha256(body); | |
| 381 | if (name.slice(name.indexOf("-") + 1) !== hash.slice(0, 16)) return undefined; | |
| 382 | return { path: `/assets/${name}.${ext}`, name, code: body, etag: `"${hash}"`, type }; | |
| 383 | } |
test/assets.test.ts added +96
| @@ -0,0 +1,96 @@ | ||
| 1 | /** | |
| 2 | * Every /assets/* response is immutable and content-hashed; a page names the hash; | |
| 3 | * an old hash still resolves for one release. | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 11 | import { sha256 } from "../src/kernel/hash.ts"; | |
| 12 | import { beaconAsset, shellAsset, spriteAsset, stylesheetAsset } from "../src/web/asset.ts"; | |
| 13 | ||
| 14 | let dataDir = ""; | |
| 15 | let app: App, servers: Servers; | |
| 16 | ||
| 17 | beforeAll(async () => { | |
| 18 | dataDir = await mkdtemp(join(tmpdir(), "forge-assets-")); | |
| 19 | app = createApp({ dataDir, port: 0 }); | |
| 20 | servers = await serve(app); | |
| 21 | }); | |
| 22 | afterAll(async () => { | |
| 23 | servers.stop(); | |
| 24 | app.close(); | |
| 25 | await rm(dataDir, { recursive: true, force: true }); | |
| 26 | }); | |
| 27 | ||
| 28 | const IMMUTABLE = "public, max-age=31536000, immutable"; | |
| 29 | ||
| 30 | test("each asset's URL carries a hash of its bytes and is served immutable", async () => { | |
| 31 | for (const asset of [stylesheetAsset(), shellAsset(), beaconAsset(), spriteAsset()]) { | |
| 32 | const res = await fetch(`${servers.url}${asset.path}`); | |
| 33 | expect(res.status).toBe(200); | |
| 34 | expect(res.headers.get("cache-control")).toBe(IMMUTABLE); | |
| 35 | expect(res.headers.get("etag")).toBe(asset.etag); | |
| 36 | expect(asset.etag).toBe(`"${sha256(await res.text())}"`); | |
| 37 | expect(asset.path).toMatch(/-[0-9a-f]{16}\.\w+$/); | |
| 38 | } | |
| 39 | }); | |
| 40 | ||
| 41 | test("the first paint references the hashed stylesheet", async () => { | |
| 42 | const html = await (await fetch(`${servers.url}/`)).text(); | |
| 43 | expect(html).toContain(stylesheetAsset().path); | |
| 44 | }); | |
| 45 | ||
| 46 | const keptDir = () => join(dataDir, "page-scripts"); | |
| 47 | ||
| 48 | /** Put a previous release's file on disk under its hashed name, as boot would have kept it. */ | |
| 49 | async function keptFile(prefix: string, ext: string, body: string): Promise<string> { | |
| 50 | const name = `${prefix}-${sha256(body).slice(0, 16)}`; | |
| 51 | await mkdir(keptDir(), { recursive: true }); | |
| 52 | await writeFile(join(keptDir(), `${name}.${ext}`), body); | |
| 53 | return `/assets/${name}.${ext}`; | |
| 54 | } | |
| 55 | ||
| 56 | for (const [prefix, ext, type] of [ | |
| 57 | ["forge", "css", "text/css"], | |
| 58 | ["shell", "js", "text/javascript"], | |
| 59 | ["beacon", "js", "text/javascript"], | |
outdated
Depends on the previous test having created page-scripts/. |
||
| 60 | ["i", "svg", "image/svg+xml"], | |
| 61 | ] as const) { | |
| 62 | test(`a stale ${prefix}-<hash>.${ext} from the previous release still resolves, immutable`, async () => { | |
| 63 | const body = `/* previous release of ${prefix} */`; | |
| 64 | const res = await fetch(`${servers.url}${await keptFile(prefix, ext, body)}`); | |
| 65 | expect(res.status).toBe(200); | |
| 66 | expect(await res.text()).toBe(body); | |
| 67 | expect(res.headers.get("cache-control")).toBe(IMMUTABLE); | |
| 68 | expect(res.headers.get("content-type")).toContain(type); | |
| 69 | }); | |
| 70 | } | |
| 71 | ||
| 72 | test("a kept file whose bytes do not hash to its name is not served", async () => { | |
| 73 | const name = `forge-${"0".repeat(16)}`; | |
| 74 | await mkdir(keptDir(), { recursive: true }); | |
| 75 | await writeFile(join(keptDir(), `${name}.css`), "x{}"); | |
| 76 | expect((await fetch(`${servers.url}/assets/${name}.css`)).status).toBe(404); | |
| 77 | }); | |
| 78 | ||
| 79 | test("a name outside the kept pattern is never read from disk", async () => { | |
| 80 | const path = await keptFile("other", "css", "a{}"); | |
| 81 | expect((await fetch(`${servers.url}${path}`)).status).toBe(404); | |
| 82 | }); | |
| 83 | ||
| 84 | test("the sprite is named i-<hash>, which the kept pattern matches", () => { | |
| 85 | expect(spriteAsset().name).toMatch(/^i-[0-9a-f]{16}$/); | |
| 86 | }); | |
| 87 | ||
| 88 | test("boot keeps this release's assets for the next one", async () => { | |
| 89 | for (const [asset, ext] of [ | |
| 90 | [stylesheetAsset(), "css"], | |
| 91 | [shellAsset(), "js"], | |
| 92 | [beaconAsset(), "js"], | |
| 93 | [spriteAsset(), "svg"], | |
| 94 | ] as const) | |
| 95 | expect(await Bun.file(join(keptDir(), `${asset.name}.${ext}`)).exists()).toBe(true); | |
| 96 | }); |
new above
offline
No-op
.replaceon an already-quoted string: delete it and compareasset.etagto"${sha256(body)}"directly.