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

The signed-in home answers its first page inside a stated budget on a forge with 5,000 events, measured by query plan and Server-Timing #13595

Merged opened this

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

Merged

scout/forge:scout/13581-the-signed-in-home-answers-its-first-pag → main 1 commit fork

  • Merged. scout/13581-the-signed-in-home-answers-its-first-pag was merged into main as c5a7eaa.

Review

Sign in to review this change.
2 files changed +158 −0
docs/FEED.md +13
@@ -190,3 +190,16 @@ To read it back: `GET /api/v1/feed/likes?item=event:…` (or `feed_like` with `a
190190 In the terminal, the Feed screen (`ssh` in, then Ctrl-K and "Feed") marks a liked post `♥ n` and one others like `♡ n`; `l` on the post under the cursor likes it and a second `l` takes it back. It runs the same `readInteraction` check as the page and writes through `setLike` (`toggleLike` only picks the act from the current state), and the write moves the forge's write clock, so web viewers see it on their next live refresh. `h` on a post lists its ledger there (who, act, when, newest first; `m` for older rows), behind the same check.
191191
192192 The how-to, the decisions and what was left out: `docs/features/feed-like-ledger.md`.
193
194 ## Budget (#13581)
195
196 The signed-in home (`/`), the feed page (`/feed`) and `GET /api/v1/feed` answer their
197 first page on a forge with 5,000 events inside a stated budget, proved by
198 `test/home-feed-budget.test.ts`:
199
200 - Every read of the `event` table, ranked (`feed.ts`) or timeline
201 (`timeline.ts`), walks an index: no `SCAN`, no `TEMP B-TREE` in its query plan.
202 - A first page reads at most 900 rows in all, whatever the log's depth (measured
203 at about a third of that).
204 - The `app` phase of `Server-Timing` on a warm read stays under 50 ms. The plan
205 and the row count are the judges; the clock is a generous second check.
test/home-feed-budget.test.ts added +145
@@ -0,0 +1,145 @@
1 /**
2 * The signed-in home answers its first page inside a stated budget on a forge with 5,000 events
3 * (#13581; docs/FEED.md, "Budget"). Plan and rows first; the clock only as a generous second check.
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtempSync, rmSync } from "node:fs";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createApp, type App } from "../src/app.ts";
10 import { createRepo } from "../src/actions/repos.ts";
11 import { createUser, type User } from "../src/core/users.ts";
12 import { createSession } from "../src/core/sessions.ts";
13 import { serve } from "../src/http/server.ts";
14 import { readFeedPage } from "../src/feed/feed.ts";
15 import { readTimeline, TIMELINE_START } from "../src/feed/timeline.ts";
16 import { promote } from "./helpers/members.ts";
17
18 const SEEDED = 5000;
19 /**
20 * Rows one first page may read in all: the timeline's 100-event batches (at most 5) and the
21 * viewer's own acts.
22 */
23 const ROW_BUDGET = 900;
24 /**
25 * The app phase of a warm read, in ms: ten times what it measures, so only a lost index trips it.
26 */
27 const APP_MS = 50;
28
29 let root = "";
30 let app: App;
31 let viewer: User;
32 let repoId = "";
33 let n = 0;
34
35 beforeAll(async () => {
36 root = mkdtempSync(join(tmpdir(), "forge-home-budget-"));
37 app = createApp({ dataDir: root, port: 0 });
38 const first = await createUser(app.db, { origin: "seed", trusted: true, username: "root", allowReserved: true, email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
39 if (!first.ok) throw new Error(first.error);
40 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", allowReserved: true, email: "[email protected]", password: "a-good-passphrase", adminIfFirst: false });
41 if (!made.ok) throw new Error(made.error);
42 viewer = made.value;
43 promote(app.db, viewer);
44 const repo = await createRepo(app, viewer, { name: "open", visibility: "public" });
45 if (!repo.ok) throw new Error(JSON.stringify(repo));
46 repoId = repo.value.id;
47 app.db.transaction(() => {
48 for (let i = 0; i < SEEDED; i++)
49 app.bus.append({ kind: "run.finished", repoId, actorId: viewer.id, payload: { kind: "agent", state: "ok", summary: `work ${i}`, runId: `r${i}` } });
50 })();
51 });
52 afterAll(() => {
53 app.close();
54 rmSync(root, { recursive: true, force: true });
55 });
56
57 type Probe = { sql: string; rows: number };
58
59 /** Every SELECT `work` runs, with the rows it returned. */
60 function probe(work: () => void): Probe[] {
61 const db = app.db;
62 const original = db.query.bind(db);
63 const seen: Probe[] = [];
64 (db as unknown as { query: unknown }).query = (sql: string) => {
65 const stmt = original(sql) as unknown as Record<string, (...a: unknown[]) => unknown>;
66 if (!/^\s*SELECT/i.test(sql)) return stmt;
67 return new Proxy(stmt, {
68 get(target, prop) {
69 const v = target[prop as string]!;
70 if (prop !== "all" && prop !== "get") return typeof v === "function" ? v.bind(target) : v;
71 return (...args: unknown[]) => {
72 const out = v.apply(target, args);
73 seen.push({ sql, rows: Array.isArray(out) ? out.length : out == null ? 0 : 1 });
74 return out;
75 };
76 },
77 });
78 };
79 try {
80 work();
81 } finally {
82 (db as unknown as { query: unknown }).query = original;
83 }
84 return seen;
85 }
86
87 /**
88 * A write first, so the candidate caches (stamped by the write clock) read afresh: the cold read.
89 */
90 const write = () =>
91 app.bus.append({ kind: "run.finished", repoId, actorId: viewer.id, payload: { kind: "agent", state: "ok", summary: `fresh ${n++}`, runId: `f${n}` } });
92
93 const reads: Record<string, () => unknown> = {
94 "the ranked feed": () => readFeedPage(app.db, viewer, { limit: 20, withoutAsks: true, now: Date.now() }),
95 "the timeline": () => readTimeline(app.db, viewer, { before: undefined, limit: 20 }),
96 };
97
98 for (const [name, read] of Object.entries(reads)) {
99 test(`${name}'s reads of the event table walk an index and a bounded number of rows`, () => {
100 write();
101 const seen = probe(() => void read());
102 const ofEvents = seen.filter(({ sql }) => /\b(FROM|JOIN) event\b/.test(sql));
103 expect(ofEvents.length).toBeGreaterThanOrEqual(1);
104 const bad: string[] = [];
105 for (const { sql } of ofEvents) {
106 const top = Math.max(0, ...[...sql.matchAll(/\?(\d+)/g)].map((m) => Number(m[1])));
107 const args = Array.from({ length: top }, () => viewer.id);
108 for (const row of app.db.query(`EXPLAIN QUERY PLAN ${sql}`).all(...args)) {
109 const line = (row as { detail: string }).detail;
110 if (/^SCAN (?!.*USING (COVERING )?INDEX)/.test(line) || line.includes("TEMP B-TREE")) bad.push(`${line}\n in: ${sql.replace(/\s+/g, " ").slice(0, 160)}`);
111 }
112 }
113 expect(bad).toEqual([]);
114 expect(seen.reduce((t, r) => t + r.rows, 0)).toBeLessThanOrEqual(ROW_BUDGET);
115 });
116 }
117
118 test("the timeline's first page is a page, whatever the log's depth", () => {
119 const page = readTimeline(app.db, viewer, { before: undefined, limit: 20 });
120 expect(page.items.length).toBe(20);
121 expect(page.next_cursor).not.toBeNull();
122 expect(TIMELINE_START).toBe("now");
123 });
124
125 test("a signed-in home, feed and feed API answer a warm read with the app phase under the budget", async () => {
126 const servers = await serve(app);
127 try {
128 const cookie = `forge_session=${createSession(app.db, viewer.id).token}`;
129 for (const path of ["/", "/feed", "/api/v1/feed"]) {
130 const get = async () => {
131 const res = await fetch(`${servers.url}${path}`, { headers: { cookie } });
132 expect(res.status).toBe(200);
133 await res.arrayBuffer();
134 const m = /(?:^|, )app;dur=([\d.]+)/.exec(res.headers.get("server-timing") ?? "");
135 expect(m).not.toBeNull();
136 return Number(m![1]);
137 };
138 await get(); // cold
139 const warm = Math.min(await get(), await get(), await get());
140 expect(warm).toBeLessThan(APP_MS);
141 }
142 } finally {
143 servers.stop();
144 }
145 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs