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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13009-immutable-assets-carry-a-content-hash-an → main 5 commits fork 2 threads · 2 unresolved

  • Merged. scout/13009-immutable-assets-carry-a-content-hash-an was merged into main as 56fa077.

Review

Sign in to review this change.
3 files changed +154 −11
src/http/server.ts +20 −6
@@ -149,6 +149,8 @@ import {
149149 speculationAsset,
150150 spriteAsset,
151151 shellAsset,
152 keepReleaseAssets,
153 keptAssetNamed,
152154 stylesheetAsset,
153155 stylesheetRedirect,
154156 stylesheetResponse,
@@ -824,7 +826,11 @@ export function buildRouter(): Router<Handler> {
824826 // a short-lived redirect for pages rendered before the hash existed.
825827 router.add("GET", "/assets/:name.css", (ctx) => {
826828 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 }
828834 return stylesheetResponse(ctx.request);
829835 });
830836 // What the open web expects of a site, from the forge's own facts.
@@ -857,9 +863,11 @@ export function buildRouter(): Router<Handler> {
857863 // with, so a miss means an old tab, and an old tab should reload.
858864 router.add("GET", "/assets/:name.js", async (ctx) => {
859865 const shell = shellAsset();
866 const dir = ctx.app.config.dataDir;
860867 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);
863871 if (ctx.params.name === TOOLBAR_NAME) return toolbarResponse(ctx.request);
864872 const own = pageScriptNamed(ctx.params.name!, ctx.app.config.dataDir);
865873 if (own !== undefined) return fileResponse(ctx.request, own);
@@ -877,9 +885,14 @@ export function buildRouter(): Router<Handler> {
877885 return assetResponse(ctx.request, asset);
878886 });
879887 // 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 });
883896 // The machine shell's terminal emulator (`web/machine-term-asset.ts`).
884897 router.add("GET", "/assets/:name.wasm", (ctx) =>
885898 ctx.params.name === ghosttyWasmAsset().name ? wasmResponse(ctx.request) : notFound(),
@@ -2616,6 +2629,7 @@ export function forgeHttp(app: App): ForgeHttp {
26162629 }
26172630
26182631 export async function serve(app: App): Promise<Servers> {
2632 keepReleaseAssets(app.config.dataDir);
26192633 const router = buildRouter();
26202634 const apiRouter = buildApiRouter();
26212635 await clearStaleSockets(app);
src/web/asset.ts +38 −5
@@ -269,7 +269,7 @@ export function pageScriptAsset(js: string, dataDir?: string): FileAsset {
269269 asset = fileAsset("page", "js", body, "text/javascript; charset=utf-8");
270270 remember(key, asset);
271271 }
272 if (dataDir !== undefined) keep(dataDir, asset);
272 if (dataDir !== undefined) keep(dataDir, asset.name, asset.code, "js");
273273 return asset;
274274 }
275275
@@ -287,12 +287,12 @@ const pruned = new Set<string>();
287287 export const pageScriptDir = (dataDir: string): string => join(dataDir, "page-scripts");
288288
289289 /** 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}`;
292292 if (kept.has(id)) return;
293293 kept.add(id);
294294 const dir = pageScriptDir(dataDir);
295 const file = join(dir, `${asset.name}.js`);
295 const file = join(dir, `${name}.${ext}`);
296296 try {
297297 mkdirSync(dir, { recursive: true });
298298 if (!pruned.has(dir)) {
@@ -305,7 +305,7 @@ function keep(dataDir: string, asset: FileAsset): void {
305305 return;
306306 }
307307 const tmp = `${file}.${process.pid}.tmp`;
308 writeFileSync(tmp, asset.code);
308 writeFileSync(tmp, code);
309309 renameSync(tmp, file);
310310 } catch (error) {
311311 // Not fatal: this process still serves it from memory.
@@ -348,3 +348,36 @@ export function pageScriptNamed(name: string, dataDir?: string): FileAsset | und
348348 export function fileResponse(request: Request, asset: FileAsset): Response {
349349 return staticResponse(request, asset.code, asset.type, asset.etag);
350350 }
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())}"`);
outdated

No-op .replace on an already-quoted string: delete it and compare asset.etag to "${sha256(body)}" directly.

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/. mkdir it here so the test passes alone and in any order.

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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs