Public: anyone can read this; the crew can change it.
/maintenance is readable as JSON for an agent: each finding's duty, severity, one-line cause and its one action #14737
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14718-maintenance-is-readable-as-json-for-an-a → main 8 commits fork 1 thread · 1 unresolved
9 files
changed +142
−7
docs/features/maintenance-findings.md +5
| @@ -15,3 +15,8 @@ held (#14577), so a cause that lasted a month is one line, not thirty. | ||
| 15 | 15 | costs one statement. |
| 16 | 16 | - **In the terminal.** The Maintenance screen (`src/tui/screens/maintenance.ts`, admins) ends with |
| 17 | 17 | the same rows, from `findingLines`. |
| 18 | - **As JSON, for an agent.** `GET /maintenance.json`, or `/maintenance` with | |
| 19 | `Accept: application/json`, answers the same rows as `{duty, severity, cause, action}` objects. | |
| 20 | Admin only, the same rule as the page, so a signed-out caller gets the sign-in redirect (303), | |
| 21 | not a 401. At most 20 rows and no "more" count. `Cache-Control: no-store`; `/maintenance` | |
| 22 | answers `Vary: accept` so a shared cache never hands JSON to a browser or the reverse. |
src/core/reserved.ts +1
| @@ -131,6 +131,7 @@ export const SYSTEM_NAMES: readonly string[] = [ | ||
| 131 | 131 | "sitemap.xml", |
| 132 | 132 | "releases", |
| 133 | 133 | "releases.json", |
| 134 | "maintenance.json", | |
| 134 | 135 | "changelog.atom", |
| 135 | 136 | "explore.atom", |
| 136 | 137 | "sw.js", |
src/http/marks/maintenance-json.json added +4
| @@ -0,0 +1,4 @@ | ||
| 1 | { | |
| 2 | "head": "/maintenance.json", | |
| 3 | "mark": "admin" | |
| 4 | } |
src/http/server.ts +2 −1
| @@ -45,7 +45,7 @@ import { contributePage } from "../web/pages/contribute.ts"; | ||
| 45 | 45 | import { pipelinePage } from "../web/pages/pipeline.ts"; |
| 46 | 46 | import { adminDataPage, appDataCsv, appDataPage, dataPage } from "../web/pages/data.ts"; |
| 47 | 47 | import { fleetAct, fleetReceipt, fleetUndo } from "../web/pages/fleet-ops.ts"; |
| 48 | import { maintenanceDuty, maintenanceDismiss, maintenanceQuiet, maintenanceUnquiet, maintenancePage, maintenancePrepare, maintenanceResume, staleAction, mergedAction, previewAction } from "../web/pages/maintenance.ts"; | |
| 48 | import { maintenanceDuty, maintenanceDismiss, maintenanceQuiet, maintenanceUnquiet, maintenanceJson, maintenancePage, maintenancePrepare, maintenanceResume, staleAction, mergedAction, previewAction } from "../web/pages/maintenance.ts"; | |
| 49 | 49 | import { maintenanceBudget } from "../web/pages/maintenance_budgets.ts"; |
| 50 | 50 | import { nightlyOutputPage, resiliencePage } from "../web/pages/resilience.ts"; |
| 51 | 51 | import { agentStartSet, billingLinksSet, limitsPage, limitsSet, quotasSet, signupSet, inviteMint, inviteRevoke } from "../web/pages/admin-limits.ts"; |
| @@ -1167,6 +1167,7 @@ export function buildRouter(): Router<Handler> { | ||
| 1167 | 1167 | router.add("GET", "/resilience", resiliencePage); |
| 1168 | 1168 | router.add("GET", "/data", dataPage); |
| 1169 | 1169 | router.add("GET", "/maintenance", maintenancePage); |
| 1170 | router.add("GET", "/maintenance.json", maintenanceJson); | |
| 1170 | 1171 | router.add("POST", "/maintenance/prepare", maintenancePrepare); |
| 1171 | 1172 | router.add("POST", "/maintenance/resume", maintenanceResume); |
| 1172 | 1173 | router.add("POST", "/maintenance/budget", maintenanceBudget); |
src/maintenance/findings.ts +35 −4
| @@ -32,16 +32,47 @@ export interface Findings { | ||
| 32 | 32 | * (`degraded_history.ts` prunes them), so the grouping reads a bounded table. |
| 33 | 33 | */ |
| 34 | 34 | export function findingRows(db: Database, cap = FINDING_ROWS): Findings { |
| 35 | const { got, more } = latestSpans(db, cap); | |
| 36 | return { rows: got.map((r) => ({ cause: r.cause, latest: r.sentence, days: r.days, open: r.closed_at === null })), more }; | |
| 37 | } | |
| 38 | ||
| 39 | interface SpanRow { cause: string; sentence: string; href: string; closed_at: number | null; days: number; total: number } | |
| 40 | ||
| 41 | /** The one query behind every reading of the findings: the board, the terminal and the JSON. */ | |
| 42 | function latestSpans(db: Database, cap: number): { got: SpanRow[]; more: number } { | |
| 35 | 43 | const got = db |
| 36 | .query<{ cause: string; sentence: string; closed_at: number | null; days: number; total: number }, [number, number]>( | |
| 37 | `SELECT s.cause, s.sentence, s.closed_at, g.days, COUNT(*) OVER () AS total | |
| 44 | .query<SpanRow, [number, number]>( | |
| 45 | `SELECT s.cause, s.sentence, s.href, s.closed_at, g.days, COUNT(*) OVER () AS total | |
| 38 | 46 | FROM degraded_span s |
| 39 | 47 | JOIN (SELECT cause, MAX(id) AS last, COUNT(DISTINCT opened_at / ?1) AS days FROM degraded_span GROUP BY cause) g ON s.id = g.last |
| 40 | 48 | ORDER BY s.opened_at DESC, s.id DESC LIMIT ?2`, |
| 41 | 49 | ) |
| 42 | 50 | .all(DAY_MS, cap); |
| 43 | const rows = got.map((r) => ({ cause: r.cause, latest: r.sentence, days: r.days, open: r.closed_at === null })); | |
| 44 | return { rows, more: Math.max(0, (got[0]?.total ?? 0) - rows.length) }; | |
| 51 | return { got, more: Math.max(0, (got[0]?.total ?? 0) - got.length) }; | |
| 52 | } | |
| 53 | ||
| 54 | /** One finding for an agent: what degraded, how bad, in one line, and the one place to act. */ | |
| 55 | export interface FindingJson { | |
| 56 | /** The watcher that raised it: the degraded cause's name. */ | |
| 57 | readonly duty: string; | |
| 58 | /** "degraded" while the cause holds; "cleared" once it is gone. */ | |
| 59 | readonly severity: "degraded" | "cleared"; | |
| 60 | /** The latest reading, one line. */ | |
| 61 | readonly cause: string; | |
| 62 | /** The path that shows it and where to act on it. */ | |
| 63 | readonly action: string; | |
| 64 | } | |
| 65 | ||
| 66 | /** The same rows as `findingRows`, as the plain data `/maintenance.json` answers. */ | |
| 67 | export function findingsJson(db: Database): { findings: FindingJson[] } { | |
| 68 | return { | |
| 69 | findings: latestSpans(db, FINDING_ROWS).got.map((r) => ({ | |
| 70 | duty: r.cause, | |
| 71 | severity: r.closed_at === null ? "degraded" : "cleared", | |
| 72 | cause: r.sentence, | |
| 73 | action: r.href, | |
| 74 | })), | |
| 75 | }; | |
| 45 | 76 | } |
| 46 | 77 | |
| 47 | 78 | /** "seen 3 days", the words the row ends on. */ |
src/web/pages/maintenance.ts +23 −1
| @@ -4,12 +4,13 @@ | ||
| 4 | 4 | * once the forge is back, when and what was verified. |
| 5 | 5 | */ |
| 6 | 6 | |
| 7 | import { json } from "../../http/respond.ts"; | |
| 7 | 8 | import { notePhase, takeSessionTime } from "../../core/route_timing.ts"; |
| 8 | 9 | import { dutyStates, switchDuty } from "../../maintain/pause.ts"; |
| 9 | 10 | import { DISMISS_DAYS, REASON_MAX, dismiss, dismissals, dismissalWords } from "../../maintain/dismiss.ts"; |
| 10 | 11 | import { duties, quietLine, splitDuties } from "../../maintenance/duties.ts"; |
| 11 | 12 | import { LEVELS, LEVEL_WORDS, dutiesLevel, levelOf, returnLevel, stateLevel, type Level } from "../../maintenance/level.ts"; |
| 12 | import { findingRows, seenWords } from "../../maintenance/findings.ts"; | |
| 13 | import { findingRows, findingsJson, seenWords } from "../../maintenance/findings.ts"; | |
| 13 | 14 | import { NOTHING_FILED, filedPieces } from "../../maintenance/filed.ts"; |
| 14 | 15 | import { statusWithStandby } from "../../maintenance/standby.ts"; |
| 15 | 16 | import { ABOUT_TO_STOP_ROWS, prepare, resumeNow, status } from "../../maintenance/service.ts"; |
| @@ -76,8 +77,29 @@ export function needsYou(o: { phase: string; healthy?: boolean; overdue: number; | ||
| 76 | 77 | return out; |
| 77 | 78 | } |
| 78 | 79 | |
| 80 | /** | |
| 81 | * GET /maintenance.json: the findings the board lists, for an agent; the same admin rule as the | |
| 82 | * page. | |
| 83 | */ | |
| 84 | export function maintenanceJson(ctx: Ctx): Response { | |
| 85 | const denied = admin(ctx); | |
| 86 | if (denied) return denied; | |
| 87 | return json(findingsJson(ctx.app.db), 200, { "cache-control": "no-store", vary: "accept" }); | |
| 88 | } | |
| 89 | ||
| 90 | /** | |
| 91 | * GET /maintenance: the page, or the findings as JSON when asked; either way the answer varies by | |
| 92 | * Accept. | |
| 93 | */ | |
| 79 | 94 | export async function maintenancePage(ctx: Ctx): Promise<Response> { |
| 95 | const response = await maintenanceAnswer(ctx); | |
| 96 | response.headers.append("vary", "accept"); | |
| 97 | return response; | |
| 98 | } | |
| 99 | ||
| 100 | async function maintenanceAnswer(ctx: Ctx): Promise<Response> { | |
| 80 | 101 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 102 | if ((ctx.request.headers.get("accept") ?? "").split(",").some((t) => t.split(";")[0]!.trim() === "application/json")) return maintenanceJson(ctx); | |
| 81 | 103 | const denied = admin(ctx); |
| 82 | 104 | if (denied) return denied; |
| 83 | 105 | const rendering = performance.now(); |
test/design-audit.test.ts +1 −1
| @@ -17,7 +17,7 @@ const doc = readFileSync("docs/design/audit.md", "utf8"); | ||
| 17 | 17 | |
| 18 | 18 | /** Routes that answer a file, a fragment, a redirect hop or a callback. */ |
| 19 | 19 | const NOT_PAGES = |
| 20 | /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|changelog\.atom$|explore\.atom$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/; | |
| 20 | /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|maintenance\.json$|changelog\.atom$|explore\.atom$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/; | |
| 21 | 21 | |
| 22 | 22 | const getRoutes = [ |
| 23 | 23 | ...server.matchAll(/router\.add\(\s*"GET",\s*"([^"]+)"/g), |
test/forge-looks.test.ts +1
| @@ -47,6 +47,7 @@ const NOT_A_PAGE: Record<string, string> = { | ||
| 47 | 47 | "/openapi.json": "a redirect to the contract document", |
| 48 | 48 | "/favicon.ico": "the tab icon, an image", |
| 49 | 49 | "/releases.json": "JSON feed of /releases", |
| 50 | "/maintenance.json": "JSON rendering of the findings on /maintenance, which is pictured; covered by test/maintenance-json.test.ts", | |
| 50 | 51 | "/changelog.atom": "Atom feed of /changelog", |
| 51 | 52 | "/explore.atom": "Atom feed of /explore", |
| 52 | 53 | "/sitemap.xml": "XML for crawlers", |
test/maintenance-json.test.ts added +70
| @@ -0,0 +1,70 @@ | ||
| 1 | /** /maintenance.json lists the findings the board lists, to the admin only (#14718). */ | |
| 2 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 3 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { createApp, type App } from "../src/app.ts"; | |
| 7 | import { createUser } from "../src/core/users.ts"; | |
| 8 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 9 | import { findingRows } from "../src/maintenance/findings.ts"; | |
| 10 | import { quietLogs } from "./helpers/globals.ts"; | |
| 11 | ||
| 12 | quietLogs(); | |
| 13 | let dir = "", app: App, servers: Servers, cookie = ""; | |
| 14 | ||
| 15 | beforeAll(async () => { | |
| 16 | dir = await mkdtemp(join(tmpdir(), "forge-maint-json-")); | |
| 17 | app = createApp({ dataDir: dir, port: 0 }); | |
| 18 | servers = await serve(app); | |
| 19 | const made = await createUser(app.db, { username: "boss", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, isAdmin: true }); | |
| 20 | if (!made.ok) throw new Error("user"); | |
| 21 | const res = await fetch(`${servers.url}/signin`, { | |
| 22 | method: "POST", redirect: "manual", | |
| 23 | headers: { "content-type": "application/x-www-form-urlencoded", origin: servers.url }, | |
| 24 | body: new URLSearchParams({ username: "boss", password: "a-good-passphrase" }), | |
| 25 | }); | |
| 26 | cookie = (res.headers.get("set-cookie") ?? "").split(";")[0] ?? ""; | |
| 27 | const ins = app.db.query("INSERT INTO degraded_span (cause, sentence, href, opened_at, closed_at) VALUES (?1, ?2, ?3, ?4, ?5)"); | |
| 28 | ins.run("disk-free", "5 GiB left", "/system", 1_000, null); | |
| 29 | ins.run("memory-growth", "40 MiB", "/resilience", 2_000, 3_000); | |
| 30 | }); | |
| 31 | afterAll(async () => { | |
| 32 | servers.stop(); | |
| 33 | app.close(); | |
| 34 | await rm(dir, { recursive: true, force: true }); | |
| 35 | }); | |
| 36 | ||
| 37 | test("the JSON carries the findings the page lists, from the same module", async () => { | |
| 38 | const want = [ | |
| 39 | { duty: "memory-growth", severity: "cleared", cause: "40 MiB", action: "/resilience" }, | |
| 40 | { duty: "disk-free", severity: "degraded", cause: "5 GiB left", action: "/system" }, | |
| 41 | ]; | |
| 42 | for (const res of [ | |
| 43 | await fetch(`${servers.url}/maintenance.json`, { headers: { cookie } }), | |
| 44 | await fetch(`${servers.url}/maintenance`, { headers: { cookie, accept: "application/json" } }), | |
| 45 | ]) { | |
| 46 | expect(res.status).toBe(200); | |
| 47 | expect(res.headers.get("content-type")).toContain("application/json"); | |
| 48 | expect(res.headers.get("x-content-type-options")).toBe("nosniff"); | |
| 49 | expect(res.headers.get("referrer-policy")).toBeTruthy(); | |
| 50 | expect(res.headers.get("content-security-policy")).toBeTruthy(); | |
| 51 | expect(await res.json()).toEqual({ findings: want }); | |
| 52 | } | |
| 53 | const page = await (await fetch(`${servers.url}/maintenance`, { headers: { cookie } })).text(); | |
| 54 | for (const r of findingRows(app.db).rows) expect(page).toContain(`data-finding="${r.cause}"`); | |
| 55 | expect(findingRows(app.db).rows.map((r) => r.cause)).toEqual(want.map((w) => w.duty)); | |
| 56 | }); | |
| 57 | ||
| 58 | test("the page without a JSON accept is still HTML, and a visitor gets no findings", async () => { | |
| 59 | expect((await fetch(`${servers.url}/maintenance`, { headers: { cookie } })).headers.get("content-type")).toContain("text/html"); | |
| 60 | const anon = await fetch(`${servers.url}/maintenance.json`, { redirect: "manual" }); | |
| 61 | expect(anon.status).not.toBe(200); | |
| 62 | expect(await anon.text()).not.toContain("disk-free"); | |
| 63 | }); | |
| 64 | ||
| 65 | test("/maintenance varies by Accept, as HTML and as JSON", async () => { | |
| 66 | const html = await fetch(`${servers.url}/maintenance`, { headers: { cookie } }); | |
| 67 | const asJson = await fetch(`${servers.url}/maintenance`, { headers: { cookie, accept: "application/json" } }); | |
| 68 | expect(html.headers.get("vary")?.toLowerCase()).toContain("accept"); | |
| 69 | expect(asJson.headers.get("vary")?.toLowerCase()).toContain("accept"); | |
| 70 | }); |
new above
offline
Content negotiation without
Vary: accept: the same URL now answers JSON or HTML. Add Vary: accept on both responses (the JSON branch here and the HTML page).