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

A fork tree reader returns an app's ancestors, siblings and descendants as plain data, filtered by what the caller may read #10510

Parked opened this
Closed without merging

scout/forge:scout/10508-a-fork-tree-reader-returns-an-app-s-ance → main 5 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +206 −2
scripts/hollow-allow.ts +7 −1
@@ -18,4 +18,10 @@ export type Allowed = {
1818 issue: number;
1919 };
2020
21 export const ALLOWED: readonly Allowed[] = [];
21 export const ALLOWED: readonly Allowed[] = [
22 {
23 orphan: "src/actions/fork_tree.ts#forkTree",
24 reason: "the data half of the fork tree; its HTTP and MCP doors are split off #10388",
25 issue: 10388,
26 },
27 ];
scripts/unreached-allow.json +1 −1
@@ -1,4 +1,5 @@
11 [
2 "src/actions/fork_tree.ts",
23 "src/apps/cloud.ts",
34 "src/boards/machine.ts",
45 "src/crew/governor_log.ts",
@@ -15,7 +16,6 @@
1516 "src/flow/review_rounds.ts",
1617 "src/flow/shared_red.ts",
1718 "src/flow/stale_fold.ts",
18 "src/kernel/why_now.ts",
1919 "src/spawn/pod.ts",
2020 "src/tui/gallery.ts",
2121 "src/tui/ui/qr.ts",
src/actions/fork_tree.ts added +96
@@ -0,0 +1,96 @@
1 /**
2 * An app's place in its fork tree as plain data: its ancestors up to the
3 * root the caller may read, then every readable descendant of that root
4 * breadth-first (so siblings come with it). No git is read.
5 */
6
7 import type { Database } from "bun:sqlite";
8 import { forkParentFor, visibleForks, type Repo } from "../core/repos.ts";
9 import { forkFollowMode } from "../core/fork_follow.ts";
10 import type { User } from "../core/users.ts";
11
12 /** How far below the root the tree is walked when the caller does not say. */
13 export const DEFAULT_TREE_DEPTH = 4;
14 /** The deepest a caller may ask for; more is clamped, not refused. */
15 export const MAX_TREE_DEPTH = 8;
16 /** Most nodes returned; past it `truncated` is true. Bounds the work of one call. */
17 export const MAX_TREE_NODES = 200;
18
19 export type TreeFollow = "take-updates" | "offers" | "autonomous";
20
21 export interface TreeNode {
22 readonly repo: string;
23 readonly parent: string | null;
24 readonly depth: number;
25 readonly follow: TreeFollow;
26 }
27
28 export interface ForkTree {
29 readonly root: string;
30 readonly nodes: TreeNode[];
31 readonly truncated: boolean;
32 }
33
34 const nameOf = (r: Repo): string => `${r.ownerName}/${r.name}`;
35
36 /** A fork that follows nothing (the root) is autonomous; "tell-me" is the fork offering back. */
37 function followOf(db: Database, repo: Repo, hasParent: boolean): TreeFollow {
38 if (!hasParent) return "autonomous";
39 return forkFollowMode(db, repo.id) === "take-updates" ? "take-updates" : "offers";
40 }
41
42 const clamp = (n: number | undefined, fallback: number, max: number): number =>
43 n === undefined || !Number.isFinite(n) ? fallback : Math.min(max, Math.max(0, Math.floor(n)));
44
45 export function forkTree(
46 db: Database,
47 repo: Repo,
48 user: User | undefined,
49 opts: { depth?: number; limit?: number } = {},
50 ): ForkTree {
51 const depthCap = clamp(opts.depth, DEFAULT_TREE_DEPTH, MAX_TREE_DEPTH);
52 const limit = Math.max(1, clamp(opts.limit, MAX_TREE_NODES, MAX_TREE_NODES));
53
54 // Ancestors: each hop only while the caller may read the parent.
55 const seen = new Set<string>([repo.id]);
56 const chain: Repo[] = [repo];
57 for (let at = repo; ; ) {
58 const up = forkParentFor(db, at, user);
59 if (up === undefined || seen.has(up.id)) break;
60 seen.add(up.id);
61 chain.push(up);
62 at = up;
63 }
64 chain.reverse(); // root first
65 const root = chain[0]!;
66
67 // Breadth-first from the root. The path down to `repo` is kept past the
68 // depth cap so the node asked about is always in its own tree.
69 const onPath = new Set(chain.map((r) => r.id));
70 const nodes: TreeNode[] = [];
71 const visited = new Set<string>([root.id]);
72 const add = (r: Repo, parent: Repo | undefined, depth: number): void => {
73 nodes.push({
74 repo: nameOf(r),
75 parent: parent === undefined ? null : nameOf(parent),
76 depth,
77 follow: followOf(db, r, parent !== undefined),
78 });
79 };
80 add(root, undefined, 0);
81 let level: Repo[] = [root];
82 for (let depth = 1; level.length > 0; depth++) {
83 const next: Repo[] = [];
84 for (const parent of level) {
85 for (const kid of visibleForks(db, parent.id, user)) {
86 if (visited.has(kid.id) || (depth > depthCap && !onPath.has(kid.id))) continue;
87 if (nodes.length >= limit) return { root: nameOf(root), nodes, truncated: true };
88 visited.add(kid.id);
89 add(kid, parent, depth);
90 next.push(kid);
91 }
92 }
93 level = next;
94 }
95 return { root: nameOf(root), nodes, truncated: false };
96 }
test/fork-tree-reader.test.ts added +102
@@ -0,0 +1,102 @@
1 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
2 import { mkdtemp, rm } from "node:fs/promises";
3 import { tmpdir } from "node:os";
4 import { join } from "node:path";
5 import { createRepo, forkRepo } from "../src/actions/repos.ts";
6 import { forkTree, MAX_TREE_NODES } from "../src/actions/fork_tree.ts";
7 import { getRepo } from "../src/core/repos.ts";
8 import { setForkFollowMode } from "../src/core/fork_follow.ts";
9 import { createApp, type App } from "../src/app.ts";
10 import { createUser, type User } from "../src/core/users.ts";
11 import { statements } from "./helpers/statements.ts";
12 import { expectWork } from "./helpers/work.ts";
13 import { promote } from "./helpers/members.ts";
14
15 const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
16 if (!r.ok) throw new Error(JSON.stringify(r.error));
17 return r.value;
18 };
19
20 let dataDir: string;
21 let app: App;
22 const users: Record<string, User> = {};
23 const repo = (o: string, n: string) => getRepo(app.db, o, n)!;
24
25 beforeAll(async () => {
26 dataDir = await mkdtemp(join(tmpdir(), "forge-fork-tree-reader-"));
27 app = createApp({ dataDir, port: 0 });
28 for (const name of ["alice", "acme", "bob", "carol", "dan", "stranger"]) {
29 users[name] = must(
30 await createUser(app.db, {
31 origin: "seed",
32 trusted: true,
33 username: name,
34 email: `${name}@f.dev`,
35 password: "a-good-passphrase",
36 adminIfFirst: name === "alice",
37 }),
38 );
39 promote(app.db, users[name]!);
40 }
41 const root = must(await createRepo(app, users["alice"]!, { name: "app", visibility: "public" }));
42 const acme = must(await forkRepo(app, users["acme"]!, root));
43 const bob = must(await forkRepo(app, users["bob"]!, acme));
44 must(await forkRepo(app, users["carol"]!, root)); // a sibling of acme's fork
45 must(await forkRepo(app, users["dan"]!, bob, "secret", { visibility: "private" }));
46 must(await forkRepo(app, users["dan"]!, getRepo(app.db, "dan", "secret")!, "deep", { visibility: "public" }));
47 setForkFollowMode(app.db, bob.id, "take-updates");
48 }, 60_000);
49
50 afterAll(async () => {
51 app.close();
52 await rm(dataDir, { recursive: true, force: true });
53 });
54
55 describe("forkTree", () => {
56 test("read from the middle: ancestors, then every descendant of the root", () => {
57 const t = forkTree(app.db, repo("acme", "app"), users["stranger"]);
58 expect(t.root).toBe("alice/app");
59 expect(t.truncated).toBe(false);
60 expect(t.nodes).toEqual([
61 { repo: "alice/app", parent: null, depth: 0, follow: "autonomous" },
62 { repo: "acme/app", parent: "alice/app", depth: 1, follow: "offers" },
63 { repo: "carol/app", parent: "alice/app", depth: 1, follow: "offers" },
64 { repo: "bob/app", parent: "acme/app", depth: 2, follow: "take-updates" },
65 ]);
66 });
67
68 test("a private fork and everything under it is gone for a stranger, present for its owner", () => {
69 const names = (u: User | undefined) => forkTree(app.db, repo("bob", "app"), u).nodes.map((n) => n.repo);
70 const stranger = names(users["stranger"]);
71 expect(stranger.join()).not.toContain("secret");
72 expect(stranger.join()).not.toContain("deep");
73 const owner = names(users["dan"]);
74 expect(owner).toContain("dan/secret");
75 expect(owner).toContain("dan/deep");
76 expect(owner).not.toEqual(stranger);
77 });
78
79 test("depth is capped and the asked-for node stays in", () => {
80 const t = forkTree(app.db, repo("alice", "app"), users["dan"], { depth: 1 });
81 expect(t.nodes.map((n) => n.repo).sort()).toEqual(["acme/app", "alice/app", "carol/app"]);
82 expect(forkTree(app.db, repo("alice", "app"), users["dan"], { depth: 99 }).nodes.length).toBe(6);
83 });
84
85 test("nodes are capped and truncation is said; 200 forks cost a bounded count of statements", async () => {
86 const root = repo("alice", "app");
87 const ins = app.db.query(
88 "INSERT INTO repo (id, owner_id, name, visibility, fork_parent_id) VALUES (?1, ?2, ?3, 'public', ?4)",
89 );
90 for (let i = 0; i < MAX_TREE_NODES; i++) ins.run(`bulk-${i}`, users["carol"]!.id, `bulk${i}`, root.id);
91 forkTree(app.db, root, users["stranger"]);
92 let t!: ReturnType<typeof forkTree>;
93 const cost = await statements(app.db, async () => {
94 t = forkTree(app.db, root, users["stranger"]);
95 });
96 // One child query per visited node plus a few reads each: bounded, no git, no N+1 per row.
97 expectWork(cost, { max: 2_000 });
98 expect(t.nodes.length).toBe(MAX_TREE_NODES);
99 expect(t.truncated).toBe(true);
100 expect(forkTree(app.db, root, users["stranger"], { limit: 5 }).nodes.length).toBe(5);
101 });
102 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs