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

Merged opened this

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

Merged

mason/forge:mason/14718-maintenance-is-readable-as-json-for-an-a → main 8 commits fork 1 thread · 1 unresolved

  • Merged. mason/14718-maintenance-is-readable-as-json-for-an-a was merged into main as c587fe8.

Review

Sign in to review this change.
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.
1515 costs one statement.
1616 - **In the terminal.** The Maintenance screen (`src/tui/screens/maintenance.ts`, admins) ends with
1717 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[] = [
131131 "sitemap.xml",
132132 "releases",
133133 "releases.json",
134 "maintenance.json",
134135 "changelog.atom",
135136 "explore.atom",
136137 "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";
4545 import { pipelinePage } from "../web/pages/pipeline.ts";
4646 import { adminDataPage, appDataCsv, appDataPage, dataPage } from "../web/pages/data.ts";
4747 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";
4949 import { maintenanceBudget } from "../web/pages/maintenance_budgets.ts";
5050 import { nightlyOutputPage, resiliencePage } from "../web/pages/resilience.ts";
5151 import { agentStartSet, billingLinksSet, limitsPage, limitsSet, quotasSet, signupSet, inviteMint, inviteRevoke } from "../web/pages/admin-limits.ts";
@@ -1167,6 +1167,7 @@ export function buildRouter(): Router<Handler> {
11671167 router.add("GET", "/resilience", resiliencePage);
11681168 router.add("GET", "/data", dataPage);
11691169 router.add("GET", "/maintenance", maintenancePage);
1170 router.add("GET", "/maintenance.json", maintenanceJson);
11701171 router.add("POST", "/maintenance/prepare", maintenancePrepare);
11711172 router.add("POST", "/maintenance/resume", maintenanceResume);
11721173 router.add("POST", "/maintenance/budget", maintenanceBudget);
src/maintenance/findings.ts +35 −4
@@ -32,16 +32,47 @@ export interface Findings {
3232 * (`degraded_history.ts` prunes them), so the grouping reads a bounded table.
3333 */
3434 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 } {
3543 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
3846 FROM degraded_span s
3947 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
4048 ORDER BY s.opened_at DESC, s.id DESC LIMIT ?2`,
4149 )
4250 .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 };
4576 }
4677
4778 /** "seen 3 days", the words the row ends on. */
src/web/pages/maintenance.ts +23 −1
@@ -4,12 +4,13 @@
44 * once the forge is back, when and what was verified.
55 */
66
7 import { json } from "../../http/respond.ts";
78 import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
89 import { dutyStates, switchDuty } from "../../maintain/pause.ts";
910 import { DISMISS_DAYS, REASON_MAX, dismiss, dismissals, dismissalWords } from "../../maintain/dismiss.ts";
1011 import { duties, quietLine, splitDuties } from "../../maintenance/duties.ts";
1112 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";
1314 import { NOTHING_FILED, filedPieces } from "../../maintenance/filed.ts";
1415 import { statusWithStandby } from "../../maintenance/standby.ts";
1516 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;
7677 return out;
7778 }
7879
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
outdated

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).

92 * Accept.
93 */
7994 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> {
80101 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);
81103 const denied = admin(ctx);
82104 if (denied) return denied;
83105 const rendering = performance.now();
test/design-audit.test.ts +1 −1
@@ -17,7 +17,7 @@ const doc = readFileSync("docs/design/audit.md", "utf8");
1717
1818 /** Routes that answer a file, a fragment, a redirect hop or a callback. */
1919 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(\/|$))/;
2121
2222 const getRoutes = [
2323 ...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> = {
4747 "/openapi.json": "a redirect to the contract document",
4848 "/favicon.ico": "the tab icon, an image",
4949 "/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",
5051 "/changelog.atom": "Atom feed of /changelog",
5152 "/explore.atom": "Atom feed of /explore",
5253 "/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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs