Public: anyone can read this; the crew can change it.

small: a not-found page is small: the 404 answer weighs under 3 KB, not 10.7 KB #14332

Merged opened this

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

Merged

scout/forge:scout/14276-small-a-not-found-page-is-small-the-404 → main 8 commits fork 4 threads · 4 unresolved

  • Merged. scout/14276-small-a-not-found-page-is-small-the-404 was merged into main as f6d530e.

Review

Sign in to review this change.
12 files changed +72 −29
docs/features/not-found-page.md +2
@@ -16,3 +16,5 @@ A dead end says what happened in one line and gives a way on.
1616 - **The API** stays JSON; a dead `/go/:code` shows no path and no sign-in.
1717
1818 In the terminal, the palette's "owner/name" prompt answers a miss with the same sentence.
19
20 The page is a short document (`src/web/lean_page.ts`): the message, a search box and the home link, with no navigation or script, under 3,000 bytes (#14276). API paths keep their JSON 404.
src/web/chrome.ts +5 −15
@@ -30,6 +30,7 @@ import { html, raw, when, type Html } from "./html.ts";
3030 import { icon } from "./icons.ts";
3131 import { nearPages } from "./near_pages.ts";
3232 import { page, redirect } from "./layout.ts";
33 import { leanPage } from "./lean_page.ts";
3334 import {
3435 browseActions,
3536 hostOf,
@@ -102,21 +103,10 @@ export function notFoundPage(ctx: Ctx, opts: { plain?: boolean; noEcho?: boolean
102103 </form>`;
103104 const id = requestId();
104105 const offerSignIn = get && ctx.auth.user === undefined;
105 const res = page(
106 {
107 ctx,
108 title: "Not found",
109 description: "The page you asked for does not exist on this forge, or is not visible to you.",
110 body: html`<div class="page-head"><h1>404</h1></div>
111 ${empty({
112 icon: "search",
113 title: "Nothing here",
114 note: "The page you asked for does not exist, or is not visible to you.",
115 action: offerSignIn
116 ? html`${btn("Go home", { href: "/", variant: "primary" })} ${btn("Sign in", { href: notFoundSignIn(ctx) })}`
117 : btn("Go home", { href: "/", variant: "primary" }),
118 })}${opts.noEcho ? html`` : html`<p class="muted">Asked for <code>${asked}</code></p>`}${find}${didYouMean}${disclosure("Request id", html`<p class="muted small">Quote <code>${id}</code> if you ask about this page.</p>`, { small: true })}`,
119 },
106 const home = html`${btn("Go home", { href: "/", variant: "primary" })}${offerSignIn ? html` ${btn("Sign in", { href: notFoundSignIn(ctx) })}` : html``}`;
outdated

Design: the buttons are hand-written <a class="btn primary"> markup; use btn(...) (still an <a>, no extra bytes of consequence) so the named component stays the one source of the look.

107 const res = leanPage(
108 "Not found",

Principle 1: the page says the same thing three times: 404, Nothing here, then The page you asked for does not exist.... Keep one h1 sentence (e.g. Nothing here) and the one muted line; drop the bare 404 heading, which is no sentence. Also the <strong> paragraph stands in for a heading and has no semantics; make it the h1.

109 html`<h1>Nothing here</h1><p class="muted">The page you asked for does not exist, or is not visible to you.</p><p>${home}</p>${opts.noEcho ? html`` : html`<p class="muted">Asked for <code>${asked}</code></p>`}${find}${didYouMean}${disclosure("Request id", html`<p class="muted small">Quote <code>${id}</code> if you ask about this page.</p>`, { small: true })}`,
120110 404,
121111 );
122112 res.headers.set("x-request-id", id);
src/web/lean_page.ts added +31
@@ -0,0 +1,31 @@
1 /**
2 * The short document for a page nobody wanted (a 404): no navigation, no script, no sprite, no
3 * inline style; the hashed stylesheet (cached) and a policy that admits nothing else. A bot
4 * sweeping paths pays a few hundred bytes a miss, not the shell's 10 KB (#14276). The security
5 * floor is added on the way out (`securityFloor`); the policy here is the page's own.
6 */
7
8 import { html, type Html } from "./html.ts";
9 import { stylesheetAsset } from "./asset.ts";
10 import { metaThemeColor } from "../design/themes.ts";
11
12 const POLICY =
13 "default-src 'none'; style-src 'self'; img-src 'self' data:; form-action 'self'; base-uri 'none'; frame-ancestors 'none'";
14
15 export function leanPage(title: string, body: Html, status: number): Response {
16 const doc = html`<!doctype html>
17 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex"><meta name="color-scheme" content="light dark"><meta name="theme-color" media="(prefers-color-scheme: light)" content="${metaThemeColor("light")}"><meta name="theme-color" media="(prefers-color-scheme: dark)" content="${metaThemeColor("dark")}"><title>${title} · forge</title><link rel="stylesheet" href="${stylesheetAsset().path}"></head>
18 <body><a class="skip" href="#main">Skip to content</a><main class="shell" id="main">${body}</main></body></html>`;
19 return new Response(doc.text, {
20 status,
21 headers: {
22 "content-type": "text/html; charset=utf-8",
outdated

Phone/a11y: the page is an unlabeled island with no brand or header, so a person who lands on a dead end has only Go home; that is acceptable per the issue, but add the forge name as the Go home link text context or keep the title. Also cache-control no-store makes every sweep hit the app; private, max-age=0 is the same for people, but this is a choice to name in the README line.

23 "content-security-policy": POLICY,
24 "referrer-policy": "same-origin",
25 "x-content-type-options": "nosniff",
26 // Same for a person as no-store; a revalidating hit is still a hit, so a sweep is not cheaper
27 // either way.
28 "cache-control": "private, max-age=0",
29 },
30 });
31 }
test/did-you-mean.test.ts +3 −3
@@ -20,11 +20,11 @@ let servers: Awaited<ReturnType<typeof serve>>;
2020 // 41: the repository page reads the repository's wallet cap, one primary-key read, to show the
2121 // wallet line (#13309).
2222 const FOUND_QUERIES = 41;
23 const BARE_404_QUERIES = 3; // a 404 with no owner/name to suggest from
24 // The same 404 for a mistyped repository. One of the 17 is the noindex lookup that
23 const BARE_404_QUERIES = 0; // a 404 with no owner/name to suggest from
24 // The same 404 for a mistyped repository. One of the 7 is the noindex lookup that
2525 // answerGet makes for every /:owner/:name route before its handler runs (1e71740ab, #14305,
2626 // src/http/archived_noindex.ts); on a missing repository it finds nothing.
27 const NEAR_404_QUERIES = 17;
27 const NEAR_404_QUERIES = 7;
2828 const cookies: Record<string, string> = {};
2929
3030 beforeAll(async () => {
test/forge-webspec.test.ts +5
@@ -165,6 +165,11 @@ test("the 404 page raises exactly the head, body and header findings named in KN
165165 const KNOWN_404: Record<string, [string, string]> = {
166166 "canonical no <link rel=\"canonical\">": [s("canonical"), "a 404 names no canonical address, by design"],
167167 "open-graph missing og:url": [s("open-graph"), "a 404 names no address to share, by design"],
168 "description no meta description": [s("description"), "a noindex page is not listed, so it has no snippet to write"],
169 "open-graph missing og:title": [s("open-graph"), "a noindex page is not shared as a card, so it has no title to give one"],
170 "open-graph missing og:type": [s("open-graph"), "a noindex page is not shared as a card, so it has no type to give one"],
171 "open-graph missing og:description": [s("open-graph"), "a noindex page is not shared as a card, so it has no description to give one"],
172 "open-graph missing og:image": [s("open-graph"), "a noindex page is not shared as a card, so it has no image to give one"],
168173 };
outdated

Six findings added to KNOWN_404 with one copied reason. Group them under one entry with a reason that is true per finding (a noindex page needs no og:* or description), and keep theme-color: the page sets color-scheme, so a light/dark theme-color is cheap to add and avoids silencing the check.

169174 const keyOf = (p: { check: string; message: string }) => `${p.check} ${p.message}`;
170175 // New: not named, or citing another section than the one named.
test/not-found-asset.test.ts +4 −4
@@ -41,13 +41,13 @@ for (const ext of ["xml", "json", "txt", "js", "css", "map", "png", "ico"]) {
4141 });
4242 }
4343
44 test("extensionless and .html unknown paths still render the full page", async () => {
44 test("extensionless and .html unknown paths still render the short page", async () => {
4545 for (const path of ["/nothing-here", "/nothing-here.html"]) {
4646 const res = await fetch(`${servers.url}${path}`);
4747 const body = await res.text();
4848 expect(res.status).toBe(404);
4949 expect(res.headers.get("content-type")).toContain("text/html");
50 expect(body.length).toBeGreaterThan(2000);
50 expect(body.length).toBeLessThan(3000);
5151 }
5252 });
5353
@@ -114,7 +114,7 @@ for (const [path, status, type, ceiling] of TABLE) {
114114 const body = await res.text();
115115 expect(res.status).toBe(status);
116116 expect(res.headers.get("content-type")).toContain(type);
117 if (type === "text/html") expect(body.length).toBeGreaterThan(2000);
117 if (type === "text/html") expect(body.length).toBeLessThan(3000);
118118 else expect(body.length).toBeLessThanOrEqual(ceiling);
119119 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
120120 expect(res.headers.get("referrer-policy")).toBeTruthy();
@@ -144,6 +144,6 @@ test("a person's missing repo file keeps the not-found page, not the typed bytes
144144 const body = await res.text();
145145 expect([path, res.status, res.headers.get("content-type")?.includes("text/html")]).toEqual([path, 404, true]);
146146 expect(body).not.toBe("not found\n");
147 expect(body.length).toBeGreaterThan(2000);
147 expect(body.length).toBeLessThan(3000);
148148 }
149149 });
test/not-found-page.test.ts +14
@@ -59,3 +59,17 @@ test("a signed-out visitor gets a home link inside main beside Sign in, and one
5959 expect(m).not.toContain("Search for gone");
6060 expect(m.match(/action="\/search"/g)?.length).toBe(1);
6161 });
62
63 test("a missing page answers under 3,000 bytes with no shell, no script, and the security floor", async () => {
64 const res = await fetch(`${servers.url}/nope-404`);
65 expect(res.status).toBe(404);
66 const body = await res.text();
67 expect(new TextEncoder().encode(body).length).toBeLessThan(3000);
68 expect(body).not.toContain("<script");
69 expect(body).not.toContain("<nav");
70 expect(body).toContain('action="/search"');
71 expect(body).toMatch(/<a\s[^>]*href="\/"/);
72 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
73 expect(res.headers.get("referrer-policy")).toBe("same-origin");
74 expect(res.headers.get("content-security-policy")).toContain("default-src 'none'");
75 });
test/og-private.test.ts +1 −1
@@ -64,7 +64,7 @@ describe("a private repository's page and card, seen anonymously", () => {
6464 const res = await get("/alice/vault");
6565 const head = (await res.text()).split("</head>")[0]!;
6666 expect(head).not.toContain(SECRET);
67 expect(head).toContain('property="og:title" content="Not found"');
67 expect(head).toContain("<title>Not found");
6868 expect(head).not.toContain("/og/repo/");
6969 });
7070
test/palette-rows.test.ts +1 −1
@@ -24,7 +24,7 @@ const priv = () => f.repos[1]!; // private, owned by olive
2424
2525 function indexOf(page: string) {
2626 const m = /<script type="application\/json" id="palette-index">([\s\S]*?)<\/script>/.exec(page);
27 if (m === null) throw new Error("no palette index");
27 if (m === null) return { items: [] }; // a 404 is a short page with no palette: it names nothing
2828 return JSON.parse(m[1]!) as { here?: string; items: { t: string; h: string; c: string; a?: 1 }[] };
2929 }
3030 const read = async (path: string, cookie?: string) =>
test/palette-tell-gate.test.ts +1 −1
@@ -69,6 +69,6 @@ describe("the tell target's repository read", () => {
6969 const signedIn = reads;
7070 reads = 0;
7171 await http.handle(new Request("http://localhost/nobody/nothing"));
72 expect(signedIn).toBe(reads + 1);
72 expect(signedIn).toBe(reads); // the 404 is a short page: no tell target, so no read
7373 });
7474 });
test/talk-page.test.ts +2 −1
@@ -1092,7 +1092,8 @@ describe("the header's Talk link carries the subject the page rendered", () => {
10921092 // entries.
10931093 const [ta, tb] = [talkLinks(await a.text()), talkLinks(await b.text())];
10941094 expect(ta).toEqual(tb);
1095 expect(ta).toEqual(["/talk"]);
1095 // The 404 is a short page without the header: neither carries a Talk link.
1096 expect(ta).toEqual([]);
10961097 });
10971098 });
10981099
test/web.test.ts +3 −3
@@ -555,7 +555,7 @@ describe("web pages end to end", () => {
555555 });
556556 const anon = await fetch(`${base}/ada/secret`);
557557 expect(anon.status).toBe(404); // 404 status, not a soft 200…
558 expect(await anon.text()).toContain("404"); // …with a real page body
558 expect(await anon.text()).toContain("Nothing here"); // …with a real page body
559559 const owner = await (
560560 await fetch(`${base}/ada/secret`, { headers: { cookie } })
561561 ).text();
@@ -570,7 +570,7 @@ describe("web pages end to end", () => {
570570 ]) {
571571 const response = await fetch(`${base}${path}`);
572572 const text = await response.text();
573 expect(text).toContain("404");
573 expect(text).toContain("Nothing here");
574574 }
575575 });
576576
@@ -589,7 +589,7 @@ describe("web pages end to end", () => {
589589 expect(browser.headers.get("x-content-type-options")).toBe("nosniff");
590590 expect(browser.headers.get("referrer-policy")).toBeTruthy();
591591 const html = await browser.text();
592 expect(html).toContain("404");
592 expect(html).toContain("Nothing here");
593593 expect(html).toContain("Go home");
594594
595595 // No Accept header at all — curl, a crawler, a link unfurler — gets the page

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs