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

A page that fails says where you are, offers the way back and a request id, and never shows a stack #12710

Merged opened this

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

Merged

scout/forge:scout/12707-a-page-that-fails-says-where-you-are-off → main 5 commits fork 5 threads · 5 unresolved

  • Merged. scout/12707-a-page-that-fails-says-where-you-are-off was merged into main as dd220a1.

Review

Sign in to review this change.
4 files changed +210 −4
src/http/respond.ts +15
@@ -198,6 +198,21 @@ export function prefersJson(request: Request): boolean {
198198 );
199199 }
200200
201 /**
202 * Whether this caller is a browser asking for a page: a GET or HEAD whose
203 * Accept names `text/html` itself (a bare wildcard, as curl sends, does not).
204 */
205 export function asksForPage(request: Request): boolean {
206 if (request.method !== "GET" && request.method !== "HEAD") return false;
207 for (const range of (request.headers.get("accept") ?? "").split(",")) {
208 const [type, ...params] = range.split(";");
209 if ((type ?? "").trim().toLowerCase() !== "text/html") continue;
210 const q = params.map((x) => x.split("=").map((y) => y.trim())).find(([k]) => k === "q")?.[1];
211 if (q === undefined || Number(q) > 0) return true;
212 }
213 return false;
214 }
215
201216 /** A page's 404 for a caller that asked for JSON: a refusal it can read. */
202217 export const pageNotFoundAsJson = (origin: string) =>
203218 json(
src/http/server.ts +18 −4
@@ -103,6 +103,7 @@ import { isRead, readOnlyRefusal } from "./read_only.ts";
103103 import { fullRefusal, isFullError, noteFull } from "../kernel/full_disk.ts";
104104 import { running } from "../kernel/version.ts";
105105 import { runGit } from "../git/env.ts";
106 import { failedPage, requestId } from "../web/failed_page.ts";
106107 import { noteRefusedInternal } from "../kernel/internal_refused.ts";
107108 import { CONTRIBUTE_PUSH_MAX_BYTES } from "../core/contribute_token.ts";
108109 import { forkPushLines } from "../actions/fork_push.ts";
@@ -609,6 +610,7 @@ import {
609610 pageNotFoundAsJson,
610611 prefersHtml,
611612 prefersJson,
613 asksForPage,
612614 securityFloor,
613615 BodyTooLarge,
614616 bodyTooLarge,
@@ -2445,7 +2447,7 @@ export interface Servers {
24452447 * "refused") and a 403
24462448 * when a database trigger refused, else a 500 that says nothing of the fault.
24472449 */
2448 function failure(app: App, error: unknown): Response {
2450 function failure(app: App, error: unknown, request?: Request): Response {
24492451 if (error instanceof BodyTooLarge) return securityFloor(bodyTooLarge(error));
24502452 if (isFullError(error)) {
24512453 noteFull(app.config.dataDir);
@@ -2459,8 +2461,20 @@ function failure(app: App, error: unknown): Response {
24592461 app.log.warn("refused by the database", { reason: refused, shown });
24602462 return securityFloor(json({ error: "refused", message: shown }, 403));
24612463 }
2462 app.log.error("unhandled request error", { error: String(error) });
2463 return securityFloor(json({ error: "internal" }, 500));
2464 const id = requestId();
2465 app.log.error("unhandled request error", { id, error: String(error) });
2466 const path = request === undefined ? "/" : new URL(request.url).pathname;
outdated

Machine detection is a path allowlist plus Accept: json. Invert it: HTML only for GET/HEAD that accept text/html; all else JSON with the id.

2467 const machine = path === "/api" || path.startsWith("/api/") || path === "/mcp" || path.startsWith("/mcp/");
2468 if (request !== undefined && !machine && asksForPage(request)) {
2469 try {
2470 return securityFloor(failedPage(request, path, id));
outdated

Silent empty catch: log the render fault with the id before falling back.

2471 } catch (fault) {
2472 app.log.error("the failed page could not render", { id, error: String(fault) });
2473 }
2474 }
2475 const response = json({ error: "internal", id }, 500);
2476 response.headers.set("x-request-id", id);
2477 return securityFloor(response);
24642478 }
24652479
24662480 /** A response with one header set, copying it when its headers are frozen. */
@@ -2795,7 +2809,7 @@ export async function serve(app: App): Promise<Servers> {
27952809 if (namesFrame(request)) notePhase(request, "compress", performance.now() - compressing);
27962810 return done;
27972811 },
2798 (error) => failure(owner, error),
2812 (error) => failure(owner, error, request),
27992813 );
28002814 try {
28012815 const first = await Promise.race([work, gone.promise]);
src/web/failed_page.ts added +78
@@ -0,0 +1,78 @@
1 /**
2 * The page a browser sees when a handler threw: the forge's header and
3 * crumbs, one plain sentence with a short request id the owner can find in
4 * the log, and the way back (home, and the page's parent). Never the error's
5 * message or stack.
6 *
7 * It renders from the request alone — no database, no session, no sprite —
8 * because the database may be what failed — which is why it cannot use
9 * `layout.page` (its topbar reads the session and counts); it reuses the
10 * database-free `crumbs` and `btn` of ui.ts. The crumbs are the path's own
11 * segments, so the route is "known" without a lookup.
12 */
13 import { stylesheetAsset } from "./asset.ts";
14 import { bootCss } from "../design/themes.ts";
15 import { html, type Html } from "./html.ts";
16 import { btn, crumbs as crumbNav } from "./ui.ts";
17
18 const MAX_CRUMBS = 4;
19 const MAX_LABEL = 40;
20
21 /** A short id: eight hex characters, enough to find one line in a log. */
22 export function requestId(): string {
23 return crypto.randomUUID().replaceAll("-", "").slice(0, 8);
24 }
25
26 /** The path's segments as crumbs (label, address), trimmed to a few. */
27 export function failedCrumbs(pathname: string): { label: string; href: string }[] {
28 const segments = pathname.split("/").filter((s) => s !== "");
29 const crumbs: { label: string; href: string }[] = [];
30 let href = "";
31 for (const segment of segments.slice(0, MAX_CRUMBS)) {
32 href += `/${segment}`;
33 let label = segment;
34 try {
35 label = decodeURIComponent(segment);
36 } catch {}
37 crumbs.push({ label: label.length > MAX_LABEL ? `${label.slice(0, MAX_LABEL)}…` : label, href });
38 }
39 return crumbs;
40 }
41
42 /** The parent of a path: one segment up, `/` at the top. */
43 export function parentOf(pathname: string): string {
44 const segments = pathname.split("/").filter((s) => s !== "");
45 return segments.length <= 1 ? "/" : `/${segments.slice(0, -1).join("/")}`;
46 }
47
48 export function failedPage(request: Request, pathname: string, id: string): Response {
49 const crumbs = failedCrumbs(pathname);
outdated

Hand-rolled header/crumbs instead of the shared chrome and named components (docs/DESIGN.md).

50 const parent = parentOf(pathname);
51 const body: Html = html`<a class="skip" href="#main">Skip to content</a>
52 <header class="topbar" role="banner">
53 <a href="/" class="wordmark"><span class="mark"></span>forge</a>
54 ${crumbs.length === 0 ? null : crumbNav(crumbs, { ariaLabel: "Location" })}
55 </header>
56 <main class="shell" id="main">

Non-blocking: the topbar is hand-written here, so it can drift from layout.page. Consider extracting a database-free topbar both use.

57 <div class="page-head"><h1>Something went wrong</h1></div>
58 <p>The forge failed to show this page. Request id <code>${id}</code>.</p>
59 <p class="actions">${btn("Go home", { href: "/", variant: "primary" })}
60 ${parent === "/" ? null : btn("Go up one level", { href: parent })}</p>
outdated

Principle 1 and 8: one confident plain sentence; drop 'Nothing you did caused it, and trying again may work' and the extra explaining line.

61 </main>`;
62 const text = `<!doctype html><html lang="en"><head><meta charset="utf-8" />
63 <meta name="viewport" content="width=device-width, initial-scale=1" />
64 <title>Something went wrong · forge</title><meta name="robots" content="noindex" />
65 <meta name="color-scheme" content="light dark" />
66 <style>${bootCss}</style><link rel="stylesheet" href="${stylesheetAsset().path}" /></head>
67 <body>${body.text}</body></html>`;
68 const hash = `'sha256-${new Bun.CryptoHasher("sha256").update(bootCss).digest("base64")}'`;
69 return new Response(request.method === "HEAD" ? null : text, {
70 status: 500,
71 headers: {
72 "content-type": "text/html; charset=utf-8",
73 "content-security-policy": `default-src 'none'; style-src 'self' ${hash}; img-src 'self' data:; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`,
74 "cache-control": "no-store",
75 "x-request-id": id,
76 },
77 });
78 }
test/error-page-500.test.ts added +99
@@ -0,0 +1,99 @@
1 /**
2 * A page that fails (#12707): a browser gets the forge's chrome, one plain
3 * sentence, the way back and a request id; the same id is in the log line
4 * and the JSON error of a machine route; the fault itself never leaves.
5 */
6 import { afterAll, beforeAll, expect, spyOn, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { createApp, type App } from "../src/app.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12 import { failedCrumbs, parentOf } from "../src/web/failed_page.ts";
13
14 const SECRET = "hunter2-the-database-password";
15 let dataDir = "";
16 let app: App, servers: Servers;
17
18 beforeAll(async () => {
19 dataDir = await mkdtemp(join(tmpdir(), "forge-500-"));
20 app = createApp({ dataDir, port: 0 });
21 servers = await serve(app);
22 }, 30_000);
23
24 afterAll(async () => {
25 servers?.stop();
26 app?.close();
27 await rm(dataDir, { recursive: true, force: true });
28 });
29
30 async function failing(path: string, accept: string | undefined, method = "GET"): Promise<{ res: Response; body: string; logs: string }> {
31 const query = app.db.query.bind(app.db);
32 const spy = spyOn(console, "error").mockImplementation(() => {});
33 app.db.query = (() => {
34 throw new Error(`SQLITE_IOERR at ${dataDir}/forge.db with password=${SECRET}`);
35 }) as typeof app.db.query;
36 try {
37 const res = await fetch(`${servers.url}${path}`, {
38 method,
39 headers: { ...(accept === undefined ? {} : { accept }), "accept-encoding": "identity" },
40 keepalive: false,
41 });
42 const body = await res.text();
43 return { res, body, logs: spy.mock.calls.map((c) => c.join(" ")).join("\n") };
44 } finally {
45 app.db.query = query;
46 spy.mockRestore();
47 }
48 }
49
50 test("a throwing page answers 500 with chrome, the way back and an id found in the log", async () => {
51 const { res, body, logs } = await failing("/ada/notes/issues", "text/html");
52 expect(res.status).toBe(500);
53 expect(res.headers.get("content-type")).toStartWith("text/html");
54 expect(body).toContain('class="topbar"');
55 expect(body).toContain('class="crumbs"');
56 expect(body).toContain('href="/ada/notes"'); // the parent
57 expect(body).toContain('href="/"');
58 const id = /<code>([0-9a-f]{8})<\/code>/.exec(body)?.[1];
59 expect(id).toBeDefined();
60 expect(res.headers.get("x-request-id")).toBe(id!);
61 expect(logs).toContain(id!);
62 for (const leak of ["SQLITE_IOERR", SECRET, dataDir, "forge.db", "unknown"]) expect(body).not.toContain(leak);
63 expect(body).not.toMatch(/\bat .*\.ts:\d+/);
64 expect(body).not.toMatch(/\bError:/);
65 for (const header of ["content-security-policy", "x-content-type-options", "referrer-policy"])
66 expect(res.headers.get(header)).toBeTruthy();
67 });
68
69 test("a machine route keeps its JSON error, the id in the log and in x-request-id", async () => {
70 for (const path of ["/api/v1/user", "/mcp"]) {
71 const { res, body, logs } = await failing(path, "text/html", "GET");
72 expect(res.status).toBe(500);
73 const data = JSON.parse(body);
74 expect(data.error).toBe("internal");
75 expect(data.id).toMatch(/^[0-9a-f]{8}$/);
76 expect(res.headers.get("x-request-id")).toBe(data.id);
77 expect(logs).toContain(data.id);
78 expect(body).not.toContain("SQLITE_IOERR");
79 expect(res.headers.get("content-security-policy")).toBeTruthy();
80 }
81 });
82
83 test("no Accept header, a wildcard, or a mutation gets JSON, not a page", async () => {
84 for (const [accept, method] of [[undefined, "GET"], ["*/*", "GET"], ["text/html", "POST"]] as const) {
85 const { res, body } = await failing("/", accept, method);
86 expect(res.status).toBe(500);
87 expect(res.headers.get("content-type")).toStartWith("application/json");
88 const data = JSON.parse(body);
89 expect(data.error).toBe("internal");
90 expect(res.headers.get("x-request-id")).toBe(data.id);
91 }
92 });
93
94 test("crumbs and parent come from the path alone", () => {
95 expect(failedCrumbs("/").length).toBe(0);
96 expect(failedCrumbs("/a/b/c").map((c) => c.href)).toEqual(["/a", "/a/b", "/a/b/c"]);
97 expect(parentOf("/a/b/c")).toBe("/a/b");
98 expect(parentOf("/a")).toBe("/");
99 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs