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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/12707-a-page-that-fails-says-where-you-are-off → main 5 commits fork 5 threads · 5 unresolved
4 files
changed +210
−4
src/http/respond.ts +15
| @@ -198,6 +198,21 @@ export function prefersJson(request: Request): boolean { | ||
| 198 | 198 | ); |
| 199 | 199 | } |
| 200 | 200 | |
| 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 | ||
| 201 | 216 | /** A page's 404 for a caller that asked for JSON: a refusal it can read. */ |
| 202 | 217 | export const pageNotFoundAsJson = (origin: string) => |
| 203 | 218 | json( |
src/http/server.ts +18 −4
| @@ -103,6 +103,7 @@ import { isRead, readOnlyRefusal } from "./read_only.ts"; | ||
| 103 | 103 | import { fullRefusal, isFullError, noteFull } from "../kernel/full_disk.ts"; |
| 104 | 104 | import { running } from "../kernel/version.ts"; |
| 105 | 105 | import { runGit } from "../git/env.ts"; |
| 106 | import { failedPage, requestId } from "../web/failed_page.ts"; | |
| 106 | 107 | import { noteRefusedInternal } from "../kernel/internal_refused.ts"; |
| 107 | 108 | import { CONTRIBUTE_PUSH_MAX_BYTES } from "../core/contribute_token.ts"; |
| 108 | 109 | import { forkPushLines } from "../actions/fork_push.ts"; |
| @@ -609,6 +610,7 @@ import { | ||
| 609 | 610 | pageNotFoundAsJson, |
| 610 | 611 | prefersHtml, |
| 611 | 612 | prefersJson, |
| 613 | asksForPage, | |
| 612 | 614 | securityFloor, |
| 613 | 615 | BodyTooLarge, |
| 614 | 616 | bodyTooLarge, |
| @@ -2445,7 +2447,7 @@ export interface Servers { | ||
| 2445 | 2447 | * "refused") and a 403 |
| 2446 | 2448 | * when a database trigger refused, else a 500 that says nothing of the fault. |
| 2447 | 2449 | */ |
| 2448 | function failure(app: App, error: unknown): Response { | |
| 2450 | function failure(app: App, error: unknown, request?: Request): Response { | |
| 2449 | 2451 | if (error instanceof BodyTooLarge) return securityFloor(bodyTooLarge(error)); |
| 2450 | 2452 | if (isFullError(error)) { |
| 2451 | 2453 | noteFull(app.config.dataDir); |
| @@ -2459,8 +2461,20 @@ function failure(app: App, error: unknown): Response { | ||
| 2459 | 2461 | app.log.warn("refused by the database", { reason: refused, shown }); |
| 2460 | 2462 | return securityFloor(json({ error: "refused", message: shown }, 403)); |
| 2461 | 2463 | } |
| 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; | |
| 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); | |
| 2464 | 2478 | } |
| 2465 | 2479 | |
| 2466 | 2480 | /** 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> { | ||
| 2795 | 2809 | if (namesFrame(request)) notePhase(request, "compress", performance.now() - compressing); |
| 2796 | 2810 | return done; |
| 2797 | 2811 | }, |
| 2798 | (error) => failure(owner, error), | |
| 2812 | (error) => failure(owner, error, request), | |
| 2799 | 2813 | ); |
| 2800 | 2814 | try { |
| 2801 | 2815 | 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 | }); |
new above
offline
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.