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

The flow panel on /boards reads its figures from a short-lived cache, so a /boards load never blocks /healthz #6914

Parked opened this
Closed without merging

scout/forge:scout/6897-the-flow-panel-on-boards-reads-its-figur → main 7 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
11 files changed +399 −141
docs/CACHING.md +16
@@ -286,6 +286,22 @@ fixture; all three caches hit):
286286 `feed`; a hit is under 0.1 ms. Every phase over 20 ms is named in the
287287 test's output; none is over 20 ms in the sandbox.
288288
289 ### 7. The flow panel's figures: owner and agent (#6897)
290
291 - **What:** every read the flow panel on `/boards` and the terminal's Flow
292 screen make (`src/flow/panel_cache.ts`): pipeline, throughput, conflicted,
293 requested, idle, parked, queues, hot files. `bun:sqlite` is synchronous, so
294 these stopped `/healthz` while they ran.
295 - **Key:** `owner` or `public`: an agent's public-only figures are never the
296 owner's. Read after the viewer's rights are known.
297 - **Invalidated by:** every write, through the write clock, except request
298 metering (`pageStamp`: the usage counter's flushes are left out of the
299 stamp), which no panel figure shows.
300 - **Max age:** 30 seconds, so a stage's age on `/boards` can be up to 30 s old with no write; only for a `now` within 30 s after the read.
301 `flow` in `Server-Timing` carries `desc="hit"`.
302 - Not in it: the ready-and-held list (`flow/held.ts`, its own 30 s memo) and
303 the duplicate-test figures (in memory).
304
289305 ### Not cached on home
290306
291307 The anonymous door (1.5 ms, 10 statements), the app shelf, and the
src/core/usage_count.ts +5 −3
@@ -15,6 +15,7 @@
1515
1616 import type { Database } from "bun:sqlite";
1717 import { withoutWaiting } from "../kernel/db.ts";
18 import { quietly } from "./write_clock.ts";
1819
1920 export const ROLES = ["anon", "user", "admin", "agent"] as const;
2021 export const SURFACES = ["api", "mcp", "web"] as const;
@@ -124,15 +125,16 @@ export function createUsageCounter(
124125 ON CONFLICT (hour, pattern, method, status, role, surface)
125126 DO UPDATE SET n = n + excluded.n`,
126127 );
127 // Behind another process's lock this throws at once and the counts go back (#6957).
128 withoutWaiting(db, db.transaction(() => {
128 const write = db.transaction(() => {
129129 for (const [key, n] of batch) {
130130 const [hour, pattern, method, status, role, surface] = key.split(
131131 SEP,
132132 ) as [string, string, string, string, string, string];
133133 upsert.run(hour, pattern, method, status, role, surface, n);
134134 }
135 }));
135 });
136 // Behind another process's lock this throws at once and the counts go back (#6957).
137 quietly(db, () => withoutWaiting(db, write));
136138 } catch (err) {
137139 // Put the counts back so a failed write loses nothing.
138140 for (const [key, n] of batch)
src/core/write_clock.ts +32
@@ -37,3 +37,35 @@ export function writeStamp(db: Database): string | undefined {
3737 .get();
3838 return row === null ? undefined : `${row.v}.${row.n}`;
3939 }
40
41 const quiet = new WeakMap<Database, number>();
42
43 /**
44 * Runs `fn`, whose writes no cached page shows; `pageStamp` leaves them out.
45 * Only the usage counter's flush (`usage_count` rows) is wrapped. A cache may use
46 * `pageStamp` only if none of what it reads comes from a wrapped write; the flow
47 * panel's does not. A write made outside the wrapper is counted, by design.
48 */
49 export function quietly<T>(db: Database, fn: () => T): T {
50 const before = db.query<{ n: number }, []>("SELECT total_changes() AS n").get()?.n ?? 0;
51 try {
52 return fn();
53 } finally {
54 const after = db.query<{ n: number }, []>("SELECT total_changes() AS n").get()?.n ?? before;
55 quiet.set(db, (quiet.get(db) ?? 0) + (after - before));
56 }
57 }
58
59 /**
60 * The write clock with `quietly` writes left out, for a cache whose page shows
61 * none of them (request metering writes about once a second on a busy forge).
62 */
63 export function pageStamp(db: Database): string | undefined {
64 if (db.inTransaction) return undefined;
65 const row = db
66 .query<{ n: number; v: number }, []>(
67 "SELECT total_changes() AS n, (SELECT data_version FROM pragma_data_version) AS v",
68 )
69 .get();
70 return row === null ? undefined : `${row.v}.${row.n - (quiet.get(db) ?? 0)}`;
71 }
src/flow/idle_pulls.ts +1 −35
@@ -2,7 +2,7 @@
22 * Idle pulls (#6470): open, unmerged pulls opened by a crew agent whose head
33 * has not moved for 72 h. A pull "moves" at its newest `pull.pushed` event, or
44 * at its opening when it has none. Oldest first, at most 20. `/boards` shows it
5 * through `idlePullsCached`; the read stays bounded by the open agent pulls.
5 * through the flow panel's cache (`flow/panel_cache.ts`); the read stays bounded by the open agent pulls.
66 */
77
88 import type { Database } from "bun:sqlite";
@@ -71,37 +71,3 @@ export function readIdlePulls(db: Database, now = new Date(), publicOnly = false
7171 hours: Math.max(0, (now.getTime() - Date.parse(at)) / HOUR_MS),
7272 }));
7373 }
74
75 /** How long `/boards` reuses one read of the idle pulls while nothing it reads has changed. */
76 export const IDLE_TTL_MS = 60_000;
77 const kept = new WeakMap<Database, Map<number, { at: number; mark: string; value: IdlePull[] }>>();
78
79 /**
80 * What the read depends on, cheaply: the newest event and issue rows and the count of
81 * unmerged pulls. A push, a new or closed pull, or a landing changes it, and the next
82 * page reads again; otherwise a page reuses the read for up to a minute.
83 */
84 function mark(db: Database): string {
85 const row = db
86 .query<{ e: number | null; i: number | null; p: number }, []>(
87 "SELECT (SELECT MAX(rowid) FROM event) AS e, (SELECT MAX(rowid) FROM issue) AS i, (SELECT COUNT(*) FROM pull WHERE merged_at IS NULL) AS p",
88 )
89 .get();
90 return `${row?.e ?? 0}|${row?.i ?? 0}|${row?.p ?? 0}`;
91 }
92
93 /**
94 * `readIdlePulls` for a page: a page that renders on every request reads again only when
95 * what the read depends on moved, and at most once a minute while it doesn't.
96 */
97 export function idlePullsCached(db: Database, now = new Date(), publicOnly = false): IdlePull[] {
98 const mine = kept.get(db) ?? new Map<number, { at: number; mark: string; value: IdlePull[] }>();
99 kept.set(db, mine);
100 const key = publicOnly ? 1 : 0;
101 const seen = mark(db);
102 const hit = mine.get(key);
103 if (hit && hit.mark === seen && now.getTime() >= hit.at && now.getTime() - hit.at < IDLE_TTL_MS) return hit.value;
104 const value = readIdlePulls(db, now, publicOnly);
105 mine.set(key, { at: now.getTime(), mark: seen, value });
106 return value;
107 }
src/flow/panel_cache.ts added +137
@@ -0,0 +1,137 @@
1 /**
2 * What the flow panel reads, remembered (docs/CACHING.md): the figures
3 * `/boards` and the terminal's Flow screen both draw. `bun:sqlite` is
4 * synchronous, so each read the page makes stops every other request,
5 * `/healthz` included; the figures are read once and served again while the
6 * forge's write clock stands still, for 30 seconds at most, and no longer.
7 *
8 * Read it only after the viewer's rights are known: the owner's figures add
9 * up private repositories. An agent's public-only figures are a separate
10 * entry, so neither is ever served as the other.
11 */
12 import type { Database } from "bun:sqlite";
13 import { Stamped } from "../kernel/stamped.ts";
14 import { pageStamp } from "../core/write_clock.ts";
15 import { getRepoById } from "../core/repos.ts";
16 import { pullCounts, warmFiles } from "../crew/hot_files.ts";
17 import { warmingLine } from "../crew/hot_history.ts";
18 import { conflictedPulls, rebaseLane, type ConflictedPull, type RebaseLane } from "./conflicted.ts";
19 import { readIdlePulls, type IdlePull } from "./idle_pulls.ts";
20 import { readParked } from "./parked.ts";
21 import { readPile } from "./pile.ts";
22 import { readPipeline } from "./pipeline.ts";
23 import { readQueues, type QueueRow } from "./queue.ts";
24 import { requestedWaits } from "./requested.ts";
25 import { reviewersBusy } from "./reviewing.ts";
26 import { readThroughput } from "./throughput.ts";
27 import { readLeadTime } from "./lead_time.ts";
28 import { readBuildYield } from "./build_yield.ts";
29 import { readReviewLatency } from "./review_latency.ts";
30 import { readOpeners } from "./openers.ts";
31
32 export const FLOW_MAX_AGE_MS = 30_000;
33
34 /** A file several open pulls touch, in a repository the reader may see. */
35 export interface HotRow {
36 readonly repo: string;
37 readonly path: string;
38 readonly pulls: number;
39 }
40
41 type Pipeline = ReturnType<typeof readPipeline>;
42
43 /** Everything the panel's reads return, as plain data. */
44 export interface FlowFigures {
45 /** When they were read, ms: a reader whose `now` is 30 s or more from it reads afresh. */
46 readonly at: number;
47 readonly stages: Pipeline;
48 readonly flow: ReturnType<typeof readThroughput>;
49 readonly conflicted: readonly ConflictedPull[];
50 readonly lane: RebaseLane;
51 readonly requested: ReturnType<typeof requestedWaits>;
52 readonly busy: ReturnType<typeof reviewersBusy>;
53 readonly lead: ReturnType<typeof readLeadTime>;
54 readonly yielded: ReturnType<typeof readBuildYield>;
55 readonly latency: ReturnType<typeof readReviewLatency>;
56 readonly openers: ReturnType<typeof readOpeners>;
57 readonly pile: ReturnType<typeof readPile>;
58 readonly idle: readonly IdlePull[];
59 readonly parked: ReturnType<typeof readParked>;
60 /** Every repository's queue row the reader may see. */
61 readonly queues: readonly QueueRow[];
62 readonly hot: readonly HotRow[];
63 readonly warming: readonly string[];
64 }
65
66 const caches = new WeakMap<Database, Stamped<FlowFigures>>();
67
68 /** The flow cache of `db`: for tests, which count its hits. */
69 export function flowCache(db: Database): Stamped<FlowFigures> {
70 let cache = caches.get(db);
71 if (cache === undefined) {
72 cache = new Stamped<FlowFigures>({ maxEntries: 8, maxAgeMs: FLOW_MAX_AGE_MS });
73 caches.set(db, cache);
74 }
75 return cache;
76 }
77
78 function visible(db: Database, full: string): boolean {
79 const [owner, name] = full.split("/");
80 return (
81 db
82 .query<{ v: string }, [string, string]>(
83 "SELECT r.visibility AS v FROM repo r JOIN user u ON u.id = r.owner_id WHERE u.username = ?1 AND r.name = ?2",
84 )
85 .get(owner ?? "", name ?? "")?.v === "public"
86 );
87 }
88
89 function hotRows(db: Database, publicOnly: boolean): HotRow[] {
90 const rows: HotRow[] = [];
91 const repos = new Map<string, { name: string; ok: boolean } | undefined>();
92 for (const w of warmFiles()) {
93 if (!repos.has(w.repoId)) {
94 const r = getRepoById(db, w.repoId);
95 repos.set(w.repoId, r && { name: `${r.ownerName}/${r.name}`, ok: !publicOnly || r.visibility === "public" });
96 }
97 const repo = repos.get(w.repoId);
98 if (repo?.ok) rows.push({ repo: repo.name, path: w.path, pulls: w.pulls });
99 }
100 return rows.sort((a, b) => b.pulls - a.pulls || a.path.localeCompare(b.path) || a.repo.localeCompare(b.repo));
101 }
102
103 function read(db: Database, now: Date, publicOnly: boolean): FlowFigures {
104 const stages = readPipeline(db, now);
105 const conflicted = conflictedPulls(db, publicOnly);
106 return {
107 at: now.getTime(),
108 stages,
109 flow: readThroughput(db, stages.map((s) => s.key), now),
110 conflicted,
111 lane: rebaseLane(db, conflicted),
112 requested: requestedWaits(db, publicOnly),
113 busy: reviewersBusy(db, publicOnly),
114 lead: readLeadTime(db, now, publicOnly),
115 yielded: readBuildYield(db, now, publicOnly),
116 latency: readReviewLatency(db, now, publicOnly),
117 openers: readOpeners(db, now, publicOnly),
118 pile: readPile(db, publicOnly),
119 idle: readIdlePulls(db, now, publicOnly),
120 parked: readParked(db, now, publicOnly),
121 queues: readQueues(db, now, { batches: true }).filter((q) => !publicOnly || visible(db, q.repo)),
122 hot: hotRows(db, publicOnly),
123 warming: warmingLine(db, now.getTime(), pullCounts, publicOnly).split("\n").filter((l) => l !== ""),
124 };
125 }
126
127 /**
128 * The panel's figures for a reader; `publicOnly` is an agent's. Valid while the
129 * write clock (request metering left out) holds and while `now` is within 30 seconds after they were read.
130 */
131 export function flowFigures(db: Database, now: Date, publicOnly: boolean): FlowFigures {
132 const stamp = pageStamp(db);
133 if (stamp === undefined) return read(db, now, publicOnly);
134 const cached = flowCache(db).get(publicOnly ? "public" : "owner", stamp, () => read(db, now, publicOnly));
135 const age = now.getTime() - cached.at;
136 return age >= 0 && age < FLOW_MAX_AGE_MS ? cached : read(db, now, publicOnly);

Metering writes move the stamp about once a second, so on a busy forge this recomputes about once a second. Consider a stamp that ignores metering tables.

137 }
src/tui/screens/flow.ts +33 −36
@@ -15,25 +15,24 @@
1515
1616 import type { Database } from "bun:sqlite";
1717 import { HOLDS } from "../../crew/held.ts";
18 import { pullCounts } from "../../crew/hot_files.ts";
19 import { warmingLine } from "../../crew/hot_history.ts";
18 import { flowFigures } from "../../flow/panel_cache.ts";
2019 import type { HeldRow } from "../../flow/held.ts";
21 import { conflictedPulls, conflictedSays, rebaseLane, rebaseLaneSays } from "../../flow/conflicted.ts";
22 import { IDLE_LIMIT, readIdlePulls } from "../../flow/idle_pulls.ts";
23 import { pileSays, readPile } from "../../flow/pile.ts";
24 import { readPipeline, STAGE_LABEL, verdict } from "../../flow/pipeline.ts";
25 import { parkedSays, readParked } from "../../flow/parked.ts";
20 import { conflictedSays, rebaseLaneSays } from "../../flow/conflicted.ts";
21 import { IDLE_LIMIT, type IdlePull } from "../../flow/idle_pulls.ts";
22 import { pileSays } from "../../flow/pile.ts";
23 import { STAGE_LABEL, verdict } from "../../flow/pipeline.ts";
24 import { parkedSays } from "../../flow/parked.ts";
2625 import { firedAlarms } from "../../flow/alarms.ts";
2726 import { readVitals, vitalsFor, vitalsLine } from "../../flow/vitals.ts";
28 import { readLeadTime, type LeadTime } from "../../flow/lead_time.ts";
29 import { buildYieldSays, readBuildYield } from "../../flow/build_yield.ts";
30 import { readReviewLatency, reviewLatencySays } from "../../flow/review_latency.ts";
31 import { readOpeners, type Opener } from "../../flow/openers.ts";
27 import { type LeadTime } from "../../flow/lead_time.ts";
28 import { buildYieldSays } from "../../flow/build_yield.ts";
29 import { reviewLatencySays } from "../../flow/review_latency.ts";
3230 import { clogLines, readClog } from "../../flow/clog_read.ts";
33 import { readQueues, redBatchWords } from "../../flow/queue.ts";
34 import { reviewersBusy, reviewingSays } from "../../flow/reviewing.ts";
35 import { requestedSays, requestedWaits } from "../../flow/requested.ts";
36 import { readThroughput, stageOut, throughputSays } from "../../flow/throughput.ts";
31 import { type Opener } from "../../flow/openers.ts";
32 import { redBatchWords, type QueueRow } from "../../flow/queue.ts";
33 import { reviewingSays } from "../../flow/reviewing.ts";
34 import { requestedSays } from "../../flow/requested.ts";
35 import { stageOut, throughputSays } from "../../flow/throughput.ts";
3736 import type { Ctx, Screen } from "../app/app.ts";
3837 import { binding } from "../app/keys.ts";
3938 import { pad, truncate, wrap } from "../term/width.ts";
@@ -49,28 +48,27 @@ export function flowLines(
4948 now = new Date(),
5049 dups = live().read().duplicates,
5150 /** What an agent reader may see: its queue lines, conflicted pulls and changes-requested waits come already cut to public. */
52 agent?: { queues: ReturnType<typeof readQueues> } | undefined,
51 agent?: { queues: readonly QueueRow[] } | undefined,
5352 /** Why ready issues wait, per autonomous repository (`readHeld`, already cut to what the reader may see). */
5453 held?: readonly HeldRow[],
5554 /** The forge's daily ceiling, which the idle-crew alarm needs to know it is not paused on purpose. */
5655 ceilingUsd: number | null = null,
5756 ): string[] {
58 const stages = readPipeline(db, now);
59 const flow = readThroughput(db, stages.map((s) => s.key), now);
57 const publicOnly = agent !== undefined;
58 const f = flowFigures(db, now, publicOnly);
59 const { stages, flow } = f;
6060 const inner = WIDTH - 6;
61 const queues = agent?.queues ?? readQueues(db, now, { batches: true });
61 const queues = agent?.queues ?? f.queues;
6262 // The row is full at 58 columns: the red-batch rate (#4235) is a line under it.
6363 const red = queues.filter((q) => (q.batches?.batches ?? 0) > 0);
64 const conflictedList = conflictedPulls(db, agent !== undefined);
65 const conflicted = conflictedSays(conflictedList, now.getTime());
66 const lane = rebaseLaneSays(rebaseLane(db, conflictedList));
67 const requested = requestedWaits(db, agent !== undefined);
64 const conflicted = conflictedSays(f.conflicted, now.getTime());
65 const lane = rebaseLaneSays(f.lane);
6866 const waits = [
69 requestedSays(requested.builder, "builder", now.getTime()),
70 requestedSays(requested.reviewer, "reviewer", now.getTime()),
67 requestedSays(f.requested.builder, "builder", now.getTime()),
68 requestedSays(f.requested.reviewer, "reviewer", now.getTime()),
7169 ].flatMap((says) => (says === null ? [] : ["", ...wrap(says, inner)]));
72 const warming = warmingLine(db, now.getTime(), pullCounts, agent !== undefined);
73 const reviewing = reviewingSays(reviewersBusy(db, agent !== undefined));
70 const warming = f.warming.join("\n");
71 const reviewing = reviewingSays(f.busy);
7472 return [
7573 ...wrap(verdict(stages, now.getTime()), inner),
7674 "",
@@ -78,15 +76,15 @@ export function flowLines(
7876 ...(agent === undefined ? clogLines(readClog(db, now), now.getTime()).flatMap((l) => wrap(l, inner)) : []),
7977 ...firedAlarms(db, now, { publicOnly: agent !== undefined, ceilingUsd }).flatMap((a) => wrap(a.says, inner)),
8078 "",
81 ...wrap(parkedSays(readParked(db, now, agent !== undefined)), inner),
79 ...wrap(parkedSays(f.parked), inner),
8280 "",
8381 ...wrap(throughputSays(flow), inner),
8482 "",
85 ...wrap(pileSays(readPile(db, agent !== undefined)), inner),
86 ...wrap(leadTimeSays(readLeadTime(db, now, agent !== undefined)), inner),
87 ...wrap(buildYieldSays(readBuildYield(db, now, agent !== undefined)), inner),
88 ...wrap(reviewLatencySays(readReviewLatency(db, now, agent !== undefined)), inner),
89 ...openerLines(readOpeners(db, now, agent !== undefined), inner),
83 ...wrap(pileSays(f.pile), inner),
84 ...wrap(leadTimeSays(f.lead), inner),
85 ...wrap(buildYieldSays(f.yielded), inner),
86 ...wrap(reviewLatencySays(f.latency), inner),
87 ...openerLines(f.openers, inner),
9088 "",
9189 `${pad("Out", 12)} ${pad("last hour", 9, "right")} ${pad("24 h", 5, "right")}`,
9290 ...flow.stages.map(stageOut).map(
@@ -106,7 +104,7 @@ export function flowLines(
106104 : wrap(`Red batches, last hour: ${red.map((q) => `${q.repo} ${redBatchWords(q)}`).join(", ")}.`, inner)),
107105 ...(lane === null ? [] : ["", ...wrap(`Rebases: ${lane}.`, inner)]),
108106 ...(conflicted === null ? [] : ["", ...wrap(conflicted, inner)]),
109 ...idleLines(db, now, agent !== undefined, inner),
107 ...idleLines(f.idle, inner),
110108 ...waits,
111109 ...(reviewing === null ? [] : ["", ...wrap(reviewing, inner)]),
112110 ...(warming === "" ? [] : ["", ...warming.split("\n").flatMap((l) => wrap(l, inner))]),
@@ -120,8 +118,7 @@ export function flowLines(
120118 const IDLE_SHOWN = 5;
121119
122120 /** A blank line, `idle: N`, then a line per idle crew pull (`flow/idle_pulls.ts`, #6479), oldest first; nothing when none. */
123 export function idleLines(db: Database, now: Date, publicOnly: boolean, inner: number): string[] {
124 const idle = readIdlePulls(db, now, publicOnly);
121 export function idleLines(idle: readonly IdlePull[], inner: number): string[] {
125122 if (idle.length === 0) return [];
126123 return [
127124 "",
src/web/pages/boards-view.ts +2 −1
@@ -19,6 +19,7 @@ import { notFoundPage, signInFirst } from "../chrome.ts";
1919 import { html, when, type Html } from "../html.ts";
2020 import { fragment, page } from "../layout.ts";
2121 import { btn, card, chartBox, empty, field, selectField } from "../ui.ts";
22 import { flowCache } from "../../flow/panel_cache.ts";
2223 import { flowPanel } from "./flow-panel.ts";
2324 import { forgeCeiling } from "../../flow/ceiling.ts";
2425 import { alarmLines, cachedAlarms } from "../studio/alarm_lines.ts";
@@ -104,7 +105,7 @@ export async function boardsList(ctx: Ctx): Promise<Response> {
104105 </ul>`,
105106 { pad: false },
106107 );
107 const flow = timePhase(ctx.request, "flow", () => flowPanel(ctx.app, { kind: "owner" }, ctx.url, "/boards"));
108 const flow = timePhase(ctx.request, "flow", () => flowPanel(ctx.app, { kind: "owner" }, ctx.url, "/boards"), () => flowCache(ctx.app.db));
108109 const rendering = performance.now();
109110 const response = page({
110111 ctx,
src/web/pages/flow-panel.ts +27 −50
@@ -8,14 +8,13 @@
88 */
99
1010 import type { Reader } from "../../actions/telemetry.ts";
11 import { queuesFor, systemFor } from "../../system/telemetry.ts";
12 import { conflictedPulls, conflictedSays, rebaseLane, rebaseLaneSays } from "../../flow/conflicted.ts";
13 import { pileSays, readPile } from "../../flow/pile.ts";
14 import { reviewersBusy, reviewingSays } from "../../flow/reviewing.ts";
15 import { requestedSays, requestedWaits } from "../../flow/requested.ts";
11 import { systemFor } from "../../system/telemetry.ts";
12 import { conflictedSays, rebaseLaneSays } from "../../flow/conflicted.ts";
13 import { pileSays } from "../../flow/pile.ts";
14 import { reviewingSays } from "../../flow/reviewing.ts";
15 import { requestedSays } from "../../flow/requested.ts";
1616 import {
1717 bottleneck,
18 readPipeline,
1918 span,
2019 STAGE_HOLDS,
2120 STAGE_LABEL,
@@ -28,22 +27,19 @@ import {
2827 HOURS,
2928 itemsIn,
3029 OUTFLOW,
31 readThroughput,
3230 stageOf,
3331 type StageThroughput,
3432 } from "../../flow/throughput.ts";
3533 import { type QueueRow, redBatchWords } from "../../flow/queue.ts";
36 import { HOT_PULLS, pullCounts, warmFiles } from "../../crew/hot_files.ts";
37 import { warmingLine } from "../../crew/hot_history.ts";
38 import { getRepoById } from "../../core/repos.ts";
39 import { IDLE_LIMIT, idlePullsCached, type IdlePull } from "../../flow/idle_pulls.ts";
40 import { readParked } from "../../flow/parked.ts";
41 import { hoursWords, readLeadTime } from "../../flow/lead_time.ts";
42 import { buildYieldSays, readBuildYield } from "../../flow/build_yield.ts";
43 import { readReviewLatency, reviewLatencySays } from "../../flow/review_latency.ts";
44 import { openerCounts, readOpeners } from "../../flow/openers.ts";
34 import { HOT_PULLS } from "../../crew/hot_files.ts";
35 import { IDLE_LIMIT, type IdlePull } from "../../flow/idle_pulls.ts";
36 import { hoursWords } from "../../flow/lead_time.ts";
37 import { buildYieldSays } from "../../flow/build_yield.ts";
38 import { reviewLatencySays } from "../../flow/review_latency.ts";
39 import { openerCounts } from "../../flow/openers.ts";
4540 import { readHeld } from "../../flow/held.ts";
4641 import type { App } from "../../app.ts";
42 import { flowFigures, type FlowFigures } from "../../flow/panel_cache.ts";
4743 import { html, type Html } from "../html.ts";
4844 import { heldCard } from "./boards-held.ts";
4945 import { badge, card, meter } from "../ui.ts";
@@ -94,27 +90,19 @@ function outCell(base: string, t: StageThroughput): Html {
9490 /** The panel for `reader`; `base` is the page it sits on, where its counts link. */
9591 export function flowPanel(app: App, reader: Reader, url: URL, base: string): Html {
9692 const now = Date.now();
97 const stages = readPipeline(app.db, new Date(now));
93 const publicOnly = reader.kind === "agent";
94 const f = flowFigures(app.db, new Date(now), publicOnly);
95 const { stages, flow, idle, parked, lead, yielded, latency, openers } = f;
9896 const worst = bottleneck(stages);
99 const flow = readThroughput(app.db, stages.map((s) => s.key), new Date(now));
10097 const out = new Map(flow.stages.map((t) => [t.key, t]));
10198 const landed = out.get("approved");
10299 const dups = systemFor(app, reader).duplicates;
103 const conflictedList = conflictedPulls(app.db, reader.kind === "agent");
104 const conflicted = conflictedSays(conflictedList, now);
105 const lane = rebaseLaneSays(rebaseLane(app.db, conflictedList));
106 const requested = requestedWaits(app.db, reader.kind === "agent");
107 const onBuilder = requestedSays(requested.builder, "builder", now);
108 const onReviewer = requestedSays(requested.reviewer, "reviewer", now);
109 const reviewing = reviewingSays(reviewersBusy(app.db, reader.kind === "agent"));
110 const agent = reader.kind === "agent";
111 const lead = readLeadTime(app.db, new Date(now), agent);
112 const yielded = readBuildYield(app.db, new Date(now), agent);
113 const latency = readReviewLatency(app.db, new Date(now), agent);
114 const openers = readOpeners(app.db, new Date(now), agent);
115 const pile = pileSays(readPile(app.db, reader.kind === "agent"));
116 const idle = idlePullsCached(app.db, new Date(now), reader.kind === "agent");
117 const parked = readParked(app.db, new Date(now), reader.kind === "agent");
100 const conflicted = conflictedSays(f.conflicted, now);
101 const lane = rebaseLaneSays(f.lane);
102 const onBuilder = requestedSays(f.requested.builder, "builder", now);
103 const onReviewer = requestedSays(f.requested.reviewer, "reviewer", now);
104 const reviewing = reviewingSays(f.busy);
105 const pile = pileSays(f.pile);
118106 const newest = parked.newest[0];
119107 const listed = asked(url);
120108 const shown = listed === null ? undefined : out.get(listed.key);
@@ -217,9 +205,9 @@ export function flowPanel(app: App, reader: Reader, url: URL, base: string): Htm
217205 </div>`,
218206 { head: html`<h2>Pipeline</h2><a class="muted small" href="/settings/capacity">Capacity</a>`, id: "pipeline", pad: false },
219207 )}
220 ${hotFilesCard(app, reader)}
208 ${hotFilesCard(f)}
221209 ${heldCard(readHeld(app, reader.kind === "owner", now))}
222 ${queueCard(queuesFor(app, reader, new Date(now), { batches: true }))}
210 ${queueCard(f.queues)}
223211 ${url.searchParams.get("idle") === "all" && idle.length > 0 ? idleList(idle) : null}
224212 ${listed === null || shown === undefined ? null : outList(shown, listed.hour, now)}`;
225213 }
@@ -310,21 +298,10 @@ function outList(t: StageThroughput, hour: number | null, now: number): Html {
310298 /** The most files the panel lists. */
311299 const HOT_LISTED = 10;
312300
313 /** Files several open pulls touch, most-touched first, from what `hot_files.ts` holds in memory. */
314 function hotFilesCard(app: App, reader: Reader): Html {
315 const rows: { repo: string; path: string; pulls: number }[] = [];
316 const repos = new Map<string, { name: string; ok: boolean } | undefined>();
317 for (const w of warmFiles()) {
318 if (!repos.has(w.repoId)) {
319 const r = getRepoById(app.db, w.repoId);
320 repos.set(w.repoId, r && { name: `${r.ownerName}/${r.name}`, ok: reader.kind === "owner" || r.visibility === "public" });
321 }
322 const repo = repos.get(w.repoId);
323 if (repo?.ok) rows.push({ repo: repo.name, path: w.path, pulls: w.pulls });
324 }
325 rows.sort((a, b) => b.pulls - a.pulls || a.path.localeCompare(b.path) || a.repo.localeCompare(b.repo));
326 const top = rows.slice(0, HOT_LISTED);
327 const warming = warmingLine(app.db, Date.now(), pullCounts, reader.kind !== "owner").split("\n").filter((l) => l !== "");
301 /** Files several open pulls touch, most-touched first, from the cached figures. */
302 function hotFilesCard(f: FlowFigures): Html {
303 const top = f.hot.slice(0, HOT_LISTED);
304 const warming = f.warming;
328305 const max = Math.max(1, ...top.map((r) => r.pulls));
329306 return card(
330307 html`<h2>Hot files</h2>
test/caching-doc.test.ts +1 −1
@@ -107,7 +107,7 @@ describe("docs/CACHING.md", () => {
107107
108108 test("each cache says what, key, invalidated by and max age", () => {
109109 const caches = doc.split(/^### \d\. /m).slice(1);
110 expect(caches.length).toBe(6);
110 expect(caches.length).toBe(7);
111111 for (const cache of caches)
112112 for (const part of ["**What:**", "**Key:**", "**Invalidated by:**", "**Max age:**"])
113113 expect(cache).toContain(part);
test/flow-idle-pulls-scale.test.ts −15
@@ -11,8 +11,6 @@ import { join } from "node:path";
1111 import { createApp, type App } from "../src/app.ts";
1212 import { createUser } from "../src/core/users.ts";
1313 import {
14 IDLE_TTL_MS,
15 idlePullsCached,
1614 readIdlePulls,
1715 } from "../src/flow/idle_pulls.ts";
1816
@@ -121,16 +119,3 @@ test("readIdlePulls reads the open agent pulls, not every pull ever made: ten ti
121119 expect(r.hours).toBeGreaterThanOrEqual(72);
122120 }
123121 });
124
125 test("idlePullsCached reads once a minute, then again", () => {
126 const first = idlePullsCached(app.db, NOW, false);
127 const again = idlePullsCached(app.db, new Date(NOW.getTime() + 1_000), false);
128 expect(again).toBe(first);
129 const later = idlePullsCached(
130 app.db,
131 new Date(NOW.getTime() + IDLE_TTL_MS + 1),
132 false,
133 );
134 expect(later).not.toBe(first);
135 expect(later.map((r) => r.pull)).toEqual(first.map((r) => r.pull));
136 });
test/flow-panel-cache.test.ts added +145
@@ -0,0 +1,145 @@
1 /**
2 * The flow panel's figures are cached (#6897): a second /boards load runs none
3 * of the panel's reads and says so in Server-Timing, an agent's public-only
4 * figures stay apart from the owner's, a write recomputes, and a /boards load
5 * never holds /healthz up.
6 */
7 import { afterAll, beforeAll, expect, test } from "bun:test";
8 import { mkdtempSync, rmSync } from "node:fs";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp } from "../src/app.ts";
12 import { createUser } from "../src/core/users.ts";
13 import { flowCache, flowFigures } from "../src/flow/panel_cache.ts";
14 import { createUsageCounter } from "../src/core/usage_count.ts";
15 import { quietly } from "../src/core/write_clock.ts";
16 import { serve } from "../src/http/server.ts";
17 import { baselineMs, expectBudget } from "./helpers/budget.ts";
18 import { proveAll } from "./helpers/verified.ts";
19
20 const PULLS = Number(process.env.FLOW_SEED ?? 300);
21 let root: string;
22 let app: ReturnType<typeof createApp>;
23 let servers: Awaited<ReturnType<typeof serve>>;
24 let cookie: string;
25
26 beforeAll(async () => {
27 root = mkdtempSync(join(tmpdir(), "forge-flow-cache-"));
28 app = createApp({ dataDir: root, port: 0 });
29 const mk = async (username: string, extra: object = {}) => {
30 const r = await createUser(app.db, {
31 origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: "a-good-passphrase", ...extra,
32 });
33 if (!r.ok) throw new Error(r.error);
34 return r.value;
35 };
36 const alice = await mk("alice", { adminIfFirst: true });
37 const bot = await mk("crewmate");
38 app.db.run("UPDATE user SET is_agent = 1 WHERE id = ?", [bot.id]);
39 app.db.run("INSERT INTO repo (id, owner_id, name, visibility) VALUES ('rp', ?, 'pub', 'public')", [alice.id]);
40 app.db.run("INSERT INTO repo (id, owner_id, name, visibility) VALUES ('rs', ?, 'secret', 'private')", [alice.id]);
41 // Many old open crew pulls, each with pushes: the idle read scans events for every one.
42 const old = new Date(Date.now() - 200 * 3_600_000).toISOString();
43 const oid = "0".repeat(40);
44 const issue = app.db.prepare(
45 `INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state, created_at, updated_at)
46 VALUES (?1, ?2, ?3, 'pull', 't', '', ?4, 'open', ?5, ?5)`,
47 );
48 const pull = app.db.prepare(
49 "INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid) VALUES (?1, 'main', ?2, ?3, ?3)",
50 );
51 const ev = app.db.prepare(
52 "INSERT INTO event (id, kind, repo_id, actor_id, payload, created_at) VALUES (?1, 'pull.pushed', ?2, ?3, ?4, ?5)",
53 );
54 app.db.transaction(() => {
55 for (let n = 1; n <= PULLS; n++) {
56 const repo = n % 2 === 0 ? "rp" : "rs";
57 issue.run(`i${n}`, repo, n, bot.id, old);
58 pull.run(`i${n}`, `b${n}`, oid);
59 for (let k = 0; k < 20; k++) ev.run(`e${n}-${k}`, repo, bot.id, JSON.stringify({ number: n + 100000 }), old);
60 }
61 })();
62 proveAll(app);
63 servers = await serve(app);
64 const signin = await fetch(`${servers.url}/signin`, {
65 method: "POST",
66 headers: { origin: servers.url },
67 body: new URLSearchParams({ username: "alice", password: "a-good-passphrase" }),
68 redirect: "manual",
69 });
70 cookie = (signin.headers.get("set-cookie") ?? "").split(";")[0]!;
71 });
72 afterAll(() => {
73 servers.stop();
74 app.close();
75 rmSync(root, { recursive: true, force: true });
76 });
77
78 const boards = () => fetch(`${servers.url}/boards`, { headers: { cookie } });
79 const phase = (res: Response) => (res.headers.get("server-timing") ?? "").split(", ").find((p) => p.startsWith("flow;")) ?? "";
80
81 test("a second /boards load runs none of the panel's reads, and Server-Timing says it was a hit", async () => {
82 flowCache(app.db).clear();
83 const first = await boards();
84 expect(first.status).toBe(200);
85 const cold = await first.text();
86 expect(cold).toContain('id="idle-pulls"');
87 expect(phase(first)).not.toContain("hit");
88 const before = flowCache(app.db).misses;
89 const second = await boards();
90 const warm = await second.text();
91 expect(flowCache(app.db).misses).toBe(before);
92 expect(phase(second)).toContain("hit");
93 expect(warm).toContain('id="idle-pulls"');
94 });
95
96 test("an agent's public-only figures are kept apart from the owner's", () => {
97 const owner = flowFigures(app.db, new Date(), false);
98 const agent = flowFigures(app.db, new Date(), true);
99 expect(owner.queues).not.toBe(agent.queues);
100 expect(owner.idle.some((p) => p.repo === "secret")).toBe(true);
101 expect(agent.idle.length).toBeGreaterThan(0);
102 expect(agent.idle.every((p) => p.repo === "pub")).toBe(true);
103 expect(flowFigures(app.db, new Date(), true)).toBe(agent);
104 expect(flowFigures(app.db, new Date(), false)).toBe(owner);
105 });
106
107 test("a write moves the clock and the next read computes again", () => {
108 const was = flowFigures(app.db, new Date(), false);
109 expect(flowFigures(app.db, new Date(), false)).toBe(was);
110 app.db.run("UPDATE repo SET description = 'x' WHERE id = 'rp'");
111 expect(flowFigures(app.db, new Date(), false)).not.toBe(was);
112 });
outdated

The sleep(1300), the 25 ms polling and the 250 ms bound make this timing-sensitive. Assert on read counts, or drive the write clock directly, so the gate stays fast and does not flake.

113
114 test("request metering does not move the panel's clock; any other write does", () => {
115 const was = flowFigures(app.db, new Date(), false);
116 const counter = createUsageCounter(app.db);
117 counter.count({ pattern: "/boards", method: "GET", status: 200, role: "user", surface: "web" });
118 counter.flush();
119 counter.stop();
120 expect(flowFigures(app.db, new Date(), false)).toBe(was);
121 quietly(app.db, () => 0);
122 app.db.run("UPDATE repo SET description = 'z' WHERE id = 'rp'");
123 expect(flowFigures(app.db, new Date(), false)).not.toBe(was);
124 app.db.run("UPDATE repo SET description = 'y' WHERE id = 'rp'");
125 expect(flowFigures(app.db, new Date(), false)).not.toBe(was);
126 });
127
128 test("with the cache warm, /boards loads read nothing and /healthz is not held up", async () => {
129 await (await boards()).text();
130 flowCache(app.db).clear();
131 await (await boards()).text();
132 const misses = flowCache(app.db).misses;
133 const against = await baselineMs(servers.url);
134 const gaps: number[] = [];
135 let last = performance.now();
136 for (let i = 0; i < 4; i++) {
137 await (await boards()).text();
138 await (await fetch(`${servers.url}/healthz`)).text();
139 const at = performance.now();
140 gaps.push(at - last);
141 last = at;
142 }
143 expect(flowCache(app.db).misses).toBe(misses);
144 expectBudget(Math.max(...gaps), { ms: 250, against });
145 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs