Public: anyone can read this; the crew can change it.

The maintenance board answers from stored state under a measured budget, with Server-Timing #13418

Merged opened this

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

Merged

torque/forge:torque/13388-the-maintenance-board-answers-from-store → main 6 commits fork 2 threads · 2 unresolved

  • Merged. torque/13388-the-maintenance-board-answers-from-store was merged into main as f7a3455.

Review

Sign in to review this change.
5 files changed +123 −13
docs/design/size-budget.json +4
@@ -31,6 +31,10 @@
3131 "js": 0,
3232 "css": 0
3333 },
34 "/maintenance": {
35 "js": 21760,
36 "css": 44544
37 },
3438 "/pricing": {
3539 "js": 21760,
3640 "css": 44544
src/perf/budgets.ts +21 −5
@@ -1,4 +1,7 @@
1 /** Budgets per route pattern and per git subcommand, in words with the number beside it (#7559, #8158). One file. */
1 /**
2 * Budgets per route pattern and per git subcommand, in words with the number beside it (#7559,
3 * #8158). One file.
4 */
25
36 export interface Budget {
47 /** The router pattern, or a prefix ending in `*`. */
@@ -12,8 +15,12 @@ export const BUDGETS: readonly Budget[] = [
1215 { pattern: "/", words: "home p95 under 800 ms warm", p95Ms: 800 },
1316 { pattern: "/boards", words: "boards p95 under 800 ms warm", p95Ms: 800 },
1417 { pattern: "/explore", words: "explore p95 under 800 ms warm", p95Ms: 800 },
15 // The `read` phase of /explore's Server-Timing (#10946): a phase of that route, not a route; its p95 is the same read's.
18 // The `read` phase of /explore's Server-Timing (#10946): a phase of that route, not a route; its
19 // p95 is the same read's.
1620 { pattern: "/explore#read", words: "the ranked explore read over 200 repositories p95 under 50 ms", p95Ms: 50 },
21 // The admin board of duties (#13388): stored state only, no duty runs on a GET. The `render`
22 // phase of its Server-Timing, not the whole route, is held to this over 200 stored duty rows.
23 { pattern: "/maintenance#render", words: "the maintenance board answers from stored state, under 50 ms over 200 duty rows", p95Ms: 50 },
outdated

Box 3: the page budget table is PAGE_BUDGETS in src/perf/page_budget.ts. Add the /maintenance row there, with a statement count. Also decide whether this is a whole-route p95 (watch.ts will treat it so) or a #render phase entry.

1724 { pattern: "/api/v1/health", words: "health p95 under 100 ms", p95Ms: 100 },
1825 { pattern: "/:owner/:name", words: "repo page p95 under 800 ms warm", p95Ms: 800 },
1926 { pattern: "/:owner/:name/*", words: "repo sub-page p95 under 1000 ms warm", p95Ms: 1000 },
@@ -27,7 +34,10 @@ export function budgetFor(pattern: string): Budget | undefined {
2734 );
2835 }
2936
30 /** A plumbing git subcommand's budget (#8158): a single process past this at p95 is a queue or a loaded machine. */
37 /**
38 * A plumbing git subcommand's budget (#8158): a single process past this at p95 is a queue or a
39 * loaded machine.
40 */
3141 export const GIT_BUDGET: Budget = { pattern: "git *", words: "each git process p95 under 250 ms", p95Ms: 250 };
3242
3343 /**
@@ -45,8 +55,14 @@ export function gitBudgetFor(key: string): Budget {
4555 return HEAVY_GIT.has(key.slice(4)) ? HEAVY_GIT_BUDGET : GIT_BUDGET;
4656 }
4757
48 /** What a real visitor's page is held to (#10536): the browser's time to first byte at p95, and its largest paint at p95. */
58 /**
59 * What a real visitor's page is held to (#10536): the browser's time to first byte at p95, and its
60 * largest paint at p95.
61 */
4962 export const PAGE_BUDGET = { serverP95Ms: 150, paintP95Ms: 1000 } as const;
5063
51 /** The ranked read behind /explore, /api/v1/explore and the MCP `explore` tool, as registered in BUDGETS. */
64 /**
65 * The ranked read behind /explore, /api/v1/explore and the MCP `explore` tool, as registered in
66 * BUDGETS.
67 */
5268 export const EXPLORE_READ_BUDGET: Budget = budgetFor("/explore#read")!;
src/perf/page_budget.ts +13 −2
@@ -24,7 +24,10 @@ export interface PageBudget {
2424 readonly signedOut?: true;
2525 }
2626
27 /** Statement limits are today's count, signed in, plus a little: lower them as pages get cheaper, raise one only on purpose. */
27 /**
28 * Statement limits are today's count, signed in, plus a little: lower them as pages get cheaper,
29 * raise one only on purpose.
30 */
2831 export const PAGE_BUDGETS: readonly PageBudget[] = [
2932 { page: "home", pattern: "/", medianMs: 50, statements: 46 },
3033 { page: "explore", pattern: "/explore", medianMs: 50, statements: 18 },
@@ -37,6 +40,11 @@ export const PAGE_BUDGETS: readonly PageBudget[] = [
3740 // Statement limits: measured warm (15 and 6) plus two, the margin the map row keeps.
3841 { page: "space", pattern: "/:owner/:name/space", medianMs: 50, statements: 17 },
3942 { page: "space data", pattern: "/:owner/:name/space.json", medianMs: 50, statements: 8 },
43 // The admin board of duties (#13388): walked as the admin, stored rows only. Statements: measured
44 // warm (53, with main's duties) plus eight: each of the seven duties reads its own state and
45 // runs, so the count moves with duty state and background ticks; an N+1 over the duties would
46 // still show.
47 { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 61 },
4048 // A stranger's way to a forge (#11410): walked signed out. `/claim` is
4149 // measured on a spawned forge with a live link, as the child's owner sees it.
4250 { page: "pricing", pattern: "/pricing", medianMs: 50, statements: 10, signedOut: true },
@@ -44,7 +52,10 @@ export const PAGE_BUDGETS: readonly PageBudget[] = [
4452 { page: "claim", pattern: "/claim", medianMs: 50, statements: 14, signedOut: true },
4553 ];
4654
47 /** The path a budget's pattern names for one repository: `:owner` and `:name` filled, everything else as written. */
55 /**
56 * The path a budget's pattern names for one repository: `:owner` and `:name` filled, everything
57 * else as written.
58 */
4859 export function pagePath(b: PageBudget, owner: string, name: string): string {
4960 return b.pattern.replace(":owner", encodeURIComponent(owner)).replace(":name", encodeURIComponent(name));
5061 }
test/maintenance-page.test.ts added +72
@@ -0,0 +1,72 @@
1 /**
2 * GET /maintenance reads stored state only, runs no duty, and answers inside 50 ms over 200 stored
3 * duty rows (#13388).
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, type App } from "../src/app.ts";
10 import { createUser } from "../src/core/users.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12 import { BUDGETS, budgetFor } from "../src/perf/budgets.ts";
13 import { duties } from "../src/maintain/registry.ts";
14 import { quietLogs } from "./helpers/globals.ts";
15
16 quietLogs();
17 let dir = "", app: App, servers: Servers, cookie = "";
18 /**
19 * The budget the page is held to, from the one table: the whole answer over a full table of rows.
20 */
21 const budget = budgetFor("/maintenance#render")!;
22 const BUDGET_MS = budget.p95Ms;
23
24 const runs = (): number => (app.db.query("SELECT COUNT(*) AS n FROM maintenance_run").get() as { n: number }).n;
25
26 beforeAll(async () => {
27 dir = await mkdtemp(join(tmpdir(), "forge-maint-page-"));
28 app = createApp({ dataDir: dir, port: 0 });
29 servers = await serve(app);
30 const made = await createUser(app.db, { username: "boss", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, isAdmin: true });
31 if (!made.ok) throw new Error("user");
32 const res = await fetch(`${servers.url}/signin`, {
33 method: "POST", redirect: "manual",
34 headers: { "content-type": "application/x-www-form-urlencoded", origin: servers.url },
35 body: new URLSearchParams({ username: "boss", password: "a-good-passphrase" }),
36 });
37 cookie = (res.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
38 // 200 stored rows, a third of them errored, spread over the registered duties.
39 const ins = app.db.query("INSERT INTO maintenance_run (duty, started, finished, outcome) VALUES (?1, ?2, ?2, ?3)");
40 app.db.transaction(() => {
41 for (let i = 0; i < 200; i++) ins.run(duties[i % duties.length]!.name, new Date(Date.now() - (200 - i) * 60_000).toISOString(), i % 3 === 0 ? "failed: boom" : "ok");
42 })();
43 });
44 afterAll(async () => {
45 servers.stop();
46 app.close();
47 await rm(dir, { recursive: true, force: true });
48 });
49
50 const get = () => fetch(`${servers.url}/maintenance`, { headers: { cookie } });
51
52 test("a GET renders the board from stored rows and runs no duty", async () => {
53 expect(runs()).toBe(200);
54 const res = await get();
55 expect(res.status).toBe(200);
56 expect(await res.text()).toContain('id="maintenance-duties"');
57 expect(runs()).toBe(200);
58 });
59
60 test("the answer names its phases in Server-Timing and stays under the budget over 200 stored rows", async () => {
61 expect(BUDGETS).toContain(budget);
62 expect(BUDGET_MS).toBe(50);
63 await get();
64 const last = await get();
65 await last.text();
66 const timing = last.headers.get("server-timing") ?? "";
67 for (const name of ["session", "render"]) expect(timing).toMatch(new RegExp(`${name};dur=\\d+\\.\\d`));
68 // The render phase only: the whole fetch is wall-clock on a shared runner and the page-budget
69 // walk judges the page.
70 const render = Number(/render;dur=([\d.]+)/.exec(timing)![1]);
71 expect(render).toBeLessThan(BUDGET_MS);
72 });
test/page-budget.test.ts +13 −6
@@ -5,8 +5,9 @@
55 * allows.
66 *
77 * The count is the hard assertion and is judged first: it does not move with
8 * the machine's load, and it is the fewest of five warm requests. The clock is the process's CPU time over 20 warm requests per page after one to
9 * warm (CPU, not wall-clock, so shard load does not fail a fast page, #12609); a page whose median misses is measured again (up to three rounds)
8 * the machine's load, and it is the fewest of five warm requests. The clock is the process's CPU
9 * time over 20 warm requests per page after one to warm (CPU, not wall-clock, so shard load does
10 * not fail a fast page, #12609); a page whose median misses is measured again (up to three rounds)
1011 * before it is named, so a busy check host does not fail a fast page.
1112 */
1213 import { afterAll, beforeAll, expect, test } from "bun:test";
@@ -99,14 +100,20 @@ afterAll(() => {
99100 rmSync(root, { recursive: true, force: true });
100101 });
101102
102 /** Pages are walked as alice, signed in (the map asks for a viewer); a stranger's pages (`signedOut`) with no cookie. */
103 /**
104 * Pages are walked as alice, signed in (the map asks for a viewer); a stranger's pages
105 * (`signedOut`) with no cookie.
106 */
103107 const init = (b: PageBudget): RequestInit => (b.signedOut ? { redirect: "manual" } : { headers: { cookie }, redirect: "manual" });
104108
105109 function url(b: PageBudget): string {
106110 return `${servers.url}${pagePath(b, "alice", "notes")}`;
107111 }
108112
109 /** One request warms; then the fewest statements of `COUNTED` warm requests is the count, so a background tick's queries do not land on a page. */
113 /**
114 * One request warms; then the fewest statements of `COUNTED` warm requests is the count, so a
115 * background tick's queries do not land on a page.
116 */
110117 async function count(b: PageBudget): Promise<{ status: number; statements: number; phases: PageMeasure["phases"] }> {
111118 const first = await fetch(url(b), init(b));
112119 await first.arrayBuffer();
@@ -154,10 +161,10 @@ async function time(
154161 return { samples, walls, phases: parsePhases(header) };
155162 }
156163
157 test("the budget table names eleven pages, each once, with a median and a statement limit", () => {
164 test("the budget table names twelve pages, each once, with a median and a statement limit", () => {
158165 expect(PAGE_BUDGETS.map((b) => b.pattern)).toEqual([
159166 "/", "/explore", "/map", "/:owner/:name", "/changelog", "/:owner/:name/next",
160 "/:owner/:name/space", "/:owner/:name/space.json", "/pricing", "/forges/new", "/claim",
167 "/:owner/:name/space", "/:owner/:name/space.json", "/maintenance", "/pricing", "/forges/new", "/claim",
161168 ]);
162169 for (const b of PAGE_BUDGETS) {
163170 expect(b.medianMs).toBeLessThanOrEqual(50);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs