Public: anyone can read this; the crew can change it.
The 500 page shows a short reference id the owner can quote and never a stack, path or SQL #14735
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14722-the-500-page-shows-a-short-reference-id → main 5 commits fork 2 threads · 2 unresolved
5 files
changed +115
−9
src/http/respond.ts +29
| @@ -29,6 +29,7 @@ export function json( | ||
| 29 | 29 | if (typeof data === "object" && data !== null && !Array.isArray(data) && !("retryAfter" in data)) |
| 30 | 30 | data = { ...data, retryAfter: wait }; |
| 31 | 31 | } |
| 32 | if (status === 500) data = withReference(data); | |
| 32 | 33 | data = withHint(data, status); |
| 33 | 34 | // The floor is laid here as well as at the server's one door (#10949): a |
| 34 | 35 | // JSON answer carried by a path that skips the door — the internal |
| @@ -41,6 +42,34 @@ export function json( | ||
| 41 | 42 | ); |
| 42 | 43 | } |
| 43 | 44 | |
| 45 | /** | |
| 46 | * The one calm 500 body (#14722): `{ error, message, hint, ref }` plus the | |
| 47 | * caller's own plain fields. Every 500 is rewritten here, so free text that | |
| 48 | * carried a stack, path or SQL cannot leave: only the caller's `id` survives, as `ref` | |
| 49 | * (the id its log line carries). A 500 with no id gets a fresh one, logged | |
| 50 | * here with the original body's `error` code so the line can still be found. | |
| 51 | */ | |
| 52 | function withReference(data: unknown): unknown { | |
| 53 | const body = typeof data === "object" && data !== null && !Array.isArray(data) ? (data as Record<string, unknown>) : {}; | |
| 54 | let ref = typeof body.id === "string" && /^[0-9a-f]{8}$/.test(body.id) ? body.id : ""; | |
| 55 | if (ref === "") { | |
| 56 | ref = crypto.randomUUID().replaceAll("-", "").slice(0, 8); | |
| 57 | console.error("unhandled 500 body rewritten", { ref, error: typeof body.error === "string" ? body.error.slice(0, 40) : "" }); | |
| 58 | } | |
| 59 | // The caller's code and its own plain fields stay (clients and tests key on | |
| 60 | // them); the free text that could carry a path, SQL or stack does not. | |
| 61 | const kept: Record<string, unknown> = {}; | |
| 62 | for (const [k, v] of Object.entries(body)) if (!["message", "hint", "id", "ref", "stack", "trace", "detail", "error"].includes(k)) kept[k] = v; | |
| 63 | const code = typeof body.error === "string" && /^[a-z][a-z0-9_]{0,39}$/.test(body.error) ? body.error : "internal"; | |
| 64 | return { | |
| 65 | ...kept, | |
| 66 | error: code, | |
| 67 | message: `Something broke on our side. Reference: ${ref}`, | |
| 68 | hint: "Try again in a moment; if it keeps happening, quote the reference to the owner.", | |
| 69 | ref, | |
| 70 | }; | |
| 71 | } | |
| 72 | ||
| 44 | 73 | type Hint = { core: string; rest?: string }; |
| 45 | 74 | |
| 46 | 75 | /** |
src/web/failed_page.ts +1 −3
| @@ -59,10 +59,8 @@ export function failedPage(request: Request, pathname: string, id: string): Resp | ||
| 59 | 59 | ${crumbs.length === 0 ? null : crumbNav(crumbs, { ariaLabel: "Location" })} |
| 60 | 60 | </header> |
| 61 | 61 | <main class="shell" id="main"> |
| 62 | <div class="page-head"><h1>Something went wrong</h1></div> | |
| 63 | <p>The forge failed to show this page. Try again in a moment.</p> | |
| 62 | <div class="page-head"><h1>Something broke on our side. Reference: <code>${id}</code></h1></div> | |
| 64 | 63 | <p class="actions">${btn("Try again", { href: retryTarget(request, pathname), variant: "primary" })}</p> |
| 65 | <p class="muted small">Quote <code>${id}</code> if you ask about this failure.</p> | |
| 66 | 64 | </main>`; |
| 67 | 65 | const text = `<!doctype html><html lang="en"><head><meta charset="utf-8" /> |
outdated
Principle 1: the reference is named in the sentence above and again here, and the h1 already says something went wrong. Drop this line; say it once. |
||
| 68 | 66 | <meta name="viewport" content="width=device-width, initial-scale=1" /> |
test/error-page-500.test.ts +5 −5
| @@ -56,7 +56,7 @@ test("a throwing page answers 500 with chrome, the way back and an id found in t | ||
| 56 | 56 | expect(body).toContain('href="/ada/notes"'); // the parent |
| 57 | 57 | expect(body).toContain("Try again"); |
| 58 | 58 | expect(body).not.toContain("Go up one level"); |
| 59 | expect(body).not.toContain("<details"); // the id stays in plain sight | |
| 59 | expect(body).not.toContain("<details"); | |
| 60 | 60 | const id = /<code>([0-9a-f]{8})<\/code>/.exec(body)?.[1]; |
| 61 | 61 | expect(id).toBeDefined(); |
| 62 | 62 | expect(res.headers.get("x-request-id")).toBe(id!); |
| @@ -74,9 +74,9 @@ test("a machine route keeps its JSON error, the id in the log and in x-request-i | ||
| 74 | 74 | expect(res.status).toBe(500); |
| 75 | 75 | const data = JSON.parse(body); |
| 76 | 76 | expect(data.error).toBe("internal"); |
| 77 | expect(data.id).toMatch(/^[0-9a-f]{8}$/); | |
| 78 | expect(res.headers.get("x-request-id")).toBe(data.id); | |
| 79 | expect(logs).toContain(data.id); | |
| 77 | expect(data.ref).toMatch(/^[0-9a-f]{8}$/); | |
| 78 | expect(res.headers.get("x-request-id")).toBe(data.ref); | |
| 79 | expect(logs).toContain(data.ref); | |
| 80 | 80 | expect(body).not.toContain("SQLITE_IOERR"); |
| 81 | 81 | expect(res.headers.get("content-security-policy")).toBeTruthy(); |
| 82 | 82 | } |
| @@ -89,7 +89,7 @@ test("no Accept header, a wildcard, or a mutation gets JSON, not a page", async | ||
| 89 | 89 | expect(res.headers.get("content-type")).toStartWith("application/json"); |
| 90 | 90 | const data = JSON.parse(body); |
| 91 | 91 | expect(data.error).toBe("internal"); |
| 92 | expect(res.headers.get("x-request-id")).toBe(data.id); | |
| 92 | expect(res.headers.get("x-request-id")).toBe(data.ref); | |
| 93 | 93 | } |
| 94 | 94 | }); |
| 95 | 95 |
test/error-page.test.ts +1 −1
| @@ -53,7 +53,7 @@ async function everyFamilyFails(install: () => () => void): Promise<void> { | ||
| 53 | 53 | const id = /<code>([0-9a-f]{8})<\/code>/.exec(body)?.[1]; |
| 54 | 54 | expect(id, path).toBeDefined(); |
| 55 | 55 | expect(logs, path).toContain(id!); |
| 56 | expect(body, path).toContain("The forge failed to show this page"); | |
| 56 | expect(body, path).toContain("Something broke on our side. Reference:"); | |
| 57 | 57 | expect(body, path).not.toContain(FAULT); |
| 58 | 58 | expect(body, path).not.toContain(dataDir); |
| 59 | 59 | expect(body, path).not.toMatch(/\.tsx?\b/); |
test/error-reference.test.ts added +79
| @@ -0,0 +1,79 @@ | ||
| 1 | /** | |
| 2 | * #14722: a throw carrying a path and SQL answers one calm line and a reference found in the log. | |
| 3 | */ | |
| 4 | import { afterAll, beforeAll, expect, spyOn, test } from "bun:test"; | |
| 5 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 6 | import { tmpdir } from "node:os"; | |
| 7 | import { join } from "node:path"; | |
| 8 | import { createApp, type App } from "../src/app.ts"; | |
| 9 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 10 | ||
| 11 | let dataDir = ""; | |
| 12 | let app: App, servers: Servers; | |
| 13 | beforeAll(async () => { | |
| 14 | dataDir = await mkdtemp(join(tmpdir(), "forge-ref-")); | |
| 15 | app = createApp({ dataDir, port: 0 }); | |
| 16 | servers = await serve(app); | |
| 17 | }, 30_000); | |
| 18 | afterAll(async () => { | |
| 19 | servers?.stop(); | |
| 20 | app?.close(); | |
| 21 | await rm(dataDir, { recursive: true, force: true }); | |
| 22 | }); | |
| 23 | ||
| 24 | async function failing(path: string, accept: string) { | |
| 25 | const query = app.db.query.bind(app.db); | |
| 26 | const spy = spyOn(console, "error").mockImplementation(() => {}); | |
| 27 | const err = new Error(`SELECT secret FROM users WHERE x='1' failed at /srv/forge/src/db.ts:42 in ${dataDir}`); | |
| 28 | app.db.query = (() => { | |
| 29 | throw err; | |
| 30 | }) as typeof app.db.query; | |
| 31 | try { | |
| 32 | const res = await fetch(`${servers.url}${path}`, { headers: { accept, "accept-encoding": "identity" }, keepalive: false }); | |
| 33 | return { res, body: await res.text(), logs: spy.mock.calls.map((c) => c.join(" ")).join("\n") }; | |
| 34 | } finally { | |
| 35 | app.db.query = query; | |
| 36 | spy.mockRestore(); | |
| 37 | } | |
| 38 | } | |
| 39 | const leaks = (b: string) => { | |
| 40 | for (const l of ["SELECT", "FROM users", "/srv/forge", "db.ts", dataDir, "Error:"]) expect(b).not.toContain(l); | |
| 41 | }; | |
| 42 | ||
| 43 | test("the page says one line with the reference, the log has the same id", async () => { | |
| 44 | const { res, body, logs } = await failing("/ada/notes/issues", "text/html"); | |
| 45 | expect(res.status).toBe(500); | |
| 46 | const ref = /Something broke on our side\. Reference: <code>([0-9a-f]{8})<\/code>/.exec(body)?.[1]; | |
| 47 | expect(ref).toBeDefined(); | |
| 48 | expect(logs).toContain(ref!); | |
| 49 | leaks(body); | |
| 50 | }); | |
| 51 | ||
| 52 | test("JSON callers get error, message, hint and ref", async () => { | |
| 53 | const { res, body, logs } = await failing("/api/v1/user", "application/json"); | |
| 54 | expect(res.status).toBe(500); | |
| 55 | const data = JSON.parse(body); | |
| 56 | expect(data.error).toBe("internal"); | |
| 57 | expect(data.ref).toMatch(/^[0-9a-f]{8}$/); | |
| 58 | expect(data.message).toBe(`Something broke on our side. Reference: ${data.ref}`); | |
| 59 | expect(typeof data.hint).toBe("string"); | |
| 60 | expect(logs).toContain(data.ref); | |
| 61 | leaks(body); | |
| 62 | }); | |
| 63 | ||
| 64 | test("any 500 body is normalised: a non-internal one cannot leak, and the real throw's id is in the log", async () => { | |
| 65 | const { json } = await import("../src/http/respond.ts"); | |
| 66 | const spy = spyOn(console, "error").mockImplementation(() => {}); | |
| 67 | try { | |
| 68 | const res = json({ error: "db_failed", message: "SELECT * FROM users at /srv/forge/src/db.ts:9", stack: "Error: x\n at /srv/a.ts:1" }, 500); | |
| 69 | const text = await res.text(); | |
| 70 | const data = JSON.parse(text); | |
| 71 | expect(Object.keys(data).sort()).toEqual(["error", "hint", "message", "ref"]); | |
| 72 | expect(data.error).toBe("db_failed"); | |
| 73 | leaks(text); | |
| 74 | expect(text).not.toContain("stack"); | |
| 75 | expect(spy.mock.calls.map((c) => JSON.stringify(c)).join("\n")).toContain(data.ref); | |
| 76 | } finally { | |
| 77 | spy.mockRestore(); | |
| 78 | } | |
| 79 | }); |
new above
offline
Duplicate
idbesiderefis a second name for one thing. Drop it, or name the callers that need it and when it goes. Also this only normalises bodies with error===internal; any other 500 body is passed through untouched, so the no-leak guarantee is not enforced here.