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
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/13388-the-maintenance-board-answers-from-store → main 6 commits fork 2 threads · 2 unresolved
5 files
changed +123
−13
docs/design/size-budget.json +4
| @@ -31,6 +31,10 @@ | ||
| 31 | 31 | "js": 0, |
| 32 | 32 | "css": 0 |
| 33 | 33 | }, |
| 34 | "/maintenance": { | |
| 35 | "js": 21760, | |
| 36 | "css": 44544 | |
| 37 | }, | |
| 34 | 38 | "/pricing": { |
| 35 | 39 | "js": 21760, |
| 36 | 40 | "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 | */ | |
| 2 | 5 | |
| 3 | 6 | export interface Budget { |
| 4 | 7 | /** The router pattern, or a prefix ending in `*`. */ |
| @@ -12,8 +15,12 @@ export const BUDGETS: readonly Budget[] = [ | ||
| 12 | 15 | { pattern: "/", words: "home p95 under 800 ms warm", p95Ms: 800 }, |
| 13 | 16 | { pattern: "/boards", words: "boards p95 under 800 ms warm", p95Ms: 800 }, |
| 14 | 17 | { 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. | |
| 16 | 20 | { 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 }, | |
| 17 | 24 | { pattern: "/api/v1/health", words: "health p95 under 100 ms", p95Ms: 100 }, |
| 18 | 25 | { pattern: "/:owner/:name", words: "repo page p95 under 800 ms warm", p95Ms: 800 }, |
| 19 | 26 | { 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 { | ||
| 27 | 34 | ); |
| 28 | 35 | } |
| 29 | 36 | |
| 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 | */ | |
| 31 | 41 | export const GIT_BUDGET: Budget = { pattern: "git *", words: "each git process p95 under 250 ms", p95Ms: 250 }; |
| 32 | 42 | |
| 33 | 43 | /** |
| @@ -45,8 +55,14 @@ export function gitBudgetFor(key: string): Budget { | ||
| 45 | 55 | return HEAVY_GIT.has(key.slice(4)) ? HEAVY_GIT_BUDGET : GIT_BUDGET; |
| 46 | 56 | } |
| 47 | 57 | |
| 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 | */ | |
| 49 | 62 | export const PAGE_BUDGET = { serverP95Ms: 150, paintP95Ms: 1000 } as const; |
| 50 | 63 | |
| 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 | */ | |
| 52 | 68 | export const EXPLORE_READ_BUDGET: Budget = budgetFor("/explore#read")!; |
src/perf/page_budget.ts +13 −2
| @@ -24,7 +24,10 @@ export interface PageBudget { | ||
| 24 | 24 | readonly signedOut?: true; |
| 25 | 25 | } |
| 26 | 26 | |
| 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 | */ | |
| 28 | 31 | export const PAGE_BUDGETS: readonly PageBudget[] = [ |
| 29 | 32 | { page: "home", pattern: "/", medianMs: 50, statements: 46 }, |
| 30 | 33 | { page: "explore", pattern: "/explore", medianMs: 50, statements: 18 }, |
| @@ -37,6 +40,11 @@ export const PAGE_BUDGETS: readonly PageBudget[] = [ | ||
| 37 | 40 | // Statement limits: measured warm (15 and 6) plus two, the margin the map row keeps. |
| 38 | 41 | { page: "space", pattern: "/:owner/:name/space", medianMs: 50, statements: 17 }, |
| 39 | 42 | { 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 }, | |
| 40 | 48 | // A stranger's way to a forge (#11410): walked signed out. `/claim` is |
| 41 | 49 | // measured on a spawned forge with a live link, as the child's owner sees it. |
| 42 | 50 | { page: "pricing", pattern: "/pricing", medianMs: 50, statements: 10, signedOut: true }, |
| @@ -44,7 +52,10 @@ export const PAGE_BUDGETS: readonly PageBudget[] = [ | ||
| 44 | 52 | { page: "claim", pattern: "/claim", medianMs: 50, statements: 14, signedOut: true }, |
| 45 | 53 | ]; |
| 46 | 54 | |
| 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 | */ | |
| 48 | 59 | export function pagePath(b: PageBudget, owner: string, name: string): string { |
| 49 | 60 | return b.pattern.replace(":owner", encodeURIComponent(owner)).replace(":name", encodeURIComponent(name)); |
| 50 | 61 | } |
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 @@ | ||
| 5 | 5 | * allows. |
| 6 | 6 | * |
| 7 | 7 | * 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) | |
| 10 | 11 | * before it is named, so a busy check host does not fail a fast page. |
| 11 | 12 | */ |
| 12 | 13 | import { afterAll, beforeAll, expect, test } from "bun:test"; |
| @@ -99,14 +100,20 @@ afterAll(() => { | ||
| 99 | 100 | rmSync(root, { recursive: true, force: true }); |
| 100 | 101 | }); |
| 101 | 102 | |
| 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 | */ | |
| 103 | 107 | const init = (b: PageBudget): RequestInit => (b.signedOut ? { redirect: "manual" } : { headers: { cookie }, redirect: "manual" }); |
| 104 | 108 | |
| 105 | 109 | function url(b: PageBudget): string { |
| 106 | 110 | return `${servers.url}${pagePath(b, "alice", "notes")}`; |
| 107 | 111 | } |
| 108 | 112 | |
| 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 | */ | |
| 110 | 117 | async function count(b: PageBudget): Promise<{ status: number; statements: number; phases: PageMeasure["phases"] }> { |
| 111 | 118 | const first = await fetch(url(b), init(b)); |
| 112 | 119 | await first.arrayBuffer(); |
| @@ -154,10 +161,10 @@ async function time( | ||
| 154 | 161 | return { samples, walls, phases: parsePhases(header) }; |
| 155 | 162 | } |
| 156 | 163 | |
| 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", () => { | |
| 158 | 165 | expect(PAGE_BUDGETS.map((b) => b.pattern)).toEqual([ |
| 159 | 166 | "/", "/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", | |
| 161 | 168 | ]); |
| 162 | 169 | for (const b of PAGE_BUDGETS) { |
| 163 | 170 | expect(b.medianMs).toBeLessThanOrEqual(50); |
new above
offline
Box 3: the page budget table is PAGE_BUDGETS in src/perf/page_budget.ts. Add the
/maintenancerow there, with a statement count. Also decide whether this is a whole-route p95 (watch.ts will treat it so) or a#renderphase entry.