Public: anyone can read this; the crew can change it.
A missing docs page reads as a page: /docs/<unknown> and /docs/features/<unknown> answer the HTML not-found page to a browser #14378
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14366-a-missing-docs-page-reads-as-a-page-docs → main 4 commits fork
2 files
changed +69
−2
src/web/pages/docs_link.ts +4 −2
| @@ -13,7 +13,8 @@ import type { Database } from "bun:sqlite"; | ||
| 13 | 13 | import { upstreamBlob } from "../../core/upstream.ts"; |
| 14 | 14 | import type { Ctx } from "../../http/context.ts"; |
| 15 | 15 | import { notePhase, takeSessionTime } from "../../core/route_timing.ts"; |
| 16 | import { notFound } from "../../http/respond.ts"; | |
| 16 | import { notFound, prefersJson } from "../../http/respond.ts"; | |
| 17 | import { notFoundPage } from "../chrome.ts"; | |
| 17 | 18 | import { anyDocEntry, docEntries, docText, featureEntries, searchDocs } from "../../view/docs.ts"; |
| 18 | 19 | import { docSections, SECTION_TITLES, type IndexedDoc } from "../../view/doc_sections.ts"; |
| 19 | 20 | import { html, raw, type Html } from "../html.ts"; |
| @@ -161,7 +162,8 @@ export function docsFeature(ctx: Ctx): Response { | ||
| 161 | 162 | |
| 162 | 163 | function docPage(ctx: Ctx, name: string, began: number): Response { |
| 163 | 164 | const entry = anyDocEntry(name); |
| 164 | if (entry === undefined) return notFound(); | |
| 165 | // A missing page reads as a page to a browser; JSON only to a caller that ranks it first. | |
| 166 | if (entry === undefined) return prefersJson(ctx.request) ? notFound() : notFoundPage(ctx); | |
| 165 | 167 | const ssh = sshOn(ctx.app.db); |
| 166 | 168 | const kept = `${name}${ssh ? " ssh" : ""}`; |
| 167 | 169 | let markup = rendered.get(kept); |
test/docs-not-found.test.ts added +65
| @@ -0,0 +1,65 @@ | ||
| 1 | /** | |
| 2 | * A missing docs page answers the HTML not-found page to a browser, JSON only to a caller asking | |
| 3 | * for it. | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp } from "../src/app.ts"; | |
| 10 | import { missShape } from "../src/http/asset_miss.ts"; | |
| 11 | import { buildRouter, serve, type Servers } from "../src/http/server.ts"; | |
| 12 | ||
| 13 | let dataDir: string; | |
| 14 | let app: ReturnType<typeof createApp>; | |
| 15 | let servers: Servers; | |
| 16 | ||
| 17 | beforeAll(async () => { | |
| 18 | dataDir = await mkdtemp(join(tmpdir(), "forge-docs-404-")); | |
| 19 | app = createApp({ dataDir, port: 0 }); | |
| 20 | servers = await serve(app); | |
| 21 | }, 30_000); | |
| 22 | ||
| 23 | afterAll(async () => { | |
| 24 | servers.stop(); | |
| 25 | app.close(); | |
| 26 | await rm(dataDir, { recursive: true, force: true }); | |
| 27 | }); | |
| 28 | ||
| 29 | const ask = (path: string, accept: string, signal?: AbortSignal) => | |
| 30 | fetch(`${servers.url}${path}`, { redirect: "manual", headers: { accept }, ...(signal ? { signal } : {}) }); | |
| 31 | const BROWSER = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"; | |
| 32 | ||
| 33 | for (const path of ["/docs/start", "/docs/features/nope"]) { | |
| 34 | test(`${path} is the HTML not-found page to a browser`, async () => { | |
| 35 | const res = await ask(path, BROWSER); | |
| 36 | expect(res.status).toBe(404); | |
| 37 | expect(res.headers.get("content-type")).toContain("text/html"); | |
| 38 | expect(await res.text()).toContain("Nothing here"); | |
| 39 | }); | |
| 40 | ||
| 41 | test(`${path} is JSON to Accept: application/json`, async () => { | |
| 42 | const res = await ask(path, "application/json"); | |
| 43 | expect(res.status).toBe(404); | |
| 44 | expect(res.headers.get("content-type")).toContain("application/json"); | |
| 45 | }); | |
| 46 | } | |
| 47 | ||
| 48 | /** Routes that are data feeds a page reads, not pages: they answer JSON or a stream by design. */ | |
| 49 | const FEEDS = new Set(["/forges/:name/bill", "/forges/:name/ready", "/:owner/:name/stream", "/:owner/:name/paths/:ref", "/origins/:id/r/:owner/:name/paths/:ref"]); | |
| 50 | ||
| 51 | test("no GET page route answers a browser a JSON 404", async () => { | |
| 52 | const patterns = [...new Set(buildRouter().routes().filter((r) => r.method === "GET").map((r) => r.pattern))].filter( | |
| 53 | (p) => !FEEDS.has(p), | |
| 54 | ); | |
| 55 | const bad: string[] = []; | |
| 56 | for (const pattern of patterns) { | |
| 57 | const path = pattern.replace(/\/[:*][A-Za-z_]+/g, "/nope-99999999"); | |
| 58 | if (missShape(new Request(`http://x${path}`), path) !== "page") continue; // machine and file paths keep their own miss | |
| 59 | const res = await ask(path, BROWSER, AbortSignal.timeout(5000)).catch(() => undefined); | |
| 60 | if (!res) continue; // a stream that never ends is not a 404 | |
| 61 | await res.body?.cancel(); | |
| 62 | if (res.status === 404 && (res.headers.get("content-type") ?? "").includes("json")) bad.push(`${pattern} -> ${path}`); | |
| 63 | } | |
| 64 | expect(bad).toEqual([]); | |
| 65 | }, 60_000); |
new above
offline