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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13581-the-signed-in-home-answers-its-first-pag → main 1 commit fork
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 | ||
| 190 | 190 | 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. |
| 191 | 191 | |
| 192 | 192 | 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 | }); |
new above
offline