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

Merged opened this

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

Merged

scout/forge:scout/14722-the-500-page-shows-a-short-reference-id → main 5 commits fork 2 threads · 2 unresolved

  • Merged. scout/14722-the-500-page-shows-a-short-reference-id was merged into main as 6b0eee1.

Review

Sign in to review this change.
5 files changed +115 −9
src/http/respond.ts +29
@@ -29,6 +29,7 @@ export function json(
2929 if (typeof data === "object" && data !== null && !Array.isArray(data) && !("retryAfter" in data))
3030 data = { ...data, retryAfter: wait };
3131 }
32 if (status === 500) data = withReference(data);
3233 data = withHint(data, status);
3334 // The floor is laid here as well as at the server's one door (#10949): a
3435 // JSON answer carried by a path that skips the door — the internal
@@ -41,6 +42,34 @@ export function json(
4142 );
4243 }
4344
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) : "" });
outdated

Duplicate id beside ref is 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.

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
4473 type Hint = { core: string; rest?: string };
4574
4675 /**
src/web/failed_page.ts +1 −3
@@ -59,10 +59,8 @@ export function failedPage(request: Request, pathname: string, id: string): Resp
5959 ${crumbs.length === 0 ? null : crumbNav(crumbs, { ariaLabel: "Location" })}
6060 </header>
6161 <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>
6463 <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>
6664 </main>`;
6765 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.

6866 <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
5656 expect(body).toContain('href="/ada/notes"'); // the parent
5757 expect(body).toContain("Try again");
5858 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");
6060 const id = /<code>([0-9a-f]{8})<\/code>/.exec(body)?.[1];
6161 expect(id).toBeDefined();
6262 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
7474 expect(res.status).toBe(500);
7575 const data = JSON.parse(body);
7676 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);
8080 expect(body).not.toContain("SQLITE_IOERR");
8181 expect(res.headers.get("content-security-policy")).toBeTruthy();
8282 }
@@ -89,7 +89,7 @@ test("no Accept header, a wildcard, or a mutation gets JSON, not a page", async
8989 expect(res.headers.get("content-type")).toStartWith("application/json");
9090 const data = JSON.parse(body);
9191 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);
9393 }
9494 });
9595
test/error-page.test.ts +1 −1
@@ -53,7 +53,7 @@ async function everyFamilyFails(install: () => () => void): Promise<void> {
5353 const id = /<code>([0-9a-f]{8})<\/code>/.exec(body)?.[1];
5454 expect(id, path).toBeDefined();
5555 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:");
5757 expect(body, path).not.toContain(FAULT);
5858 expect(body, path).not.toContain(dataDir);
5959 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs