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

GET a repository's forks answers the fork tree as nested JSON, depth capped at five #14149

Merged opened this

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

Merged

torque/forge:torque/14138-get-a-repository-s-forks-answers-the-for → main 4 commits fork 4 threads · 4 unresolved

  • Merged. torque/14138-get-a-repository-s-forks-answers-the-for was merged into main as 457fa5a.

Review

Sign in to review this change.
6 files changed +210 −0
docs/features/fork-tree.md +15
@@ -64,3 +64,18 @@ A repository's home lists the open pulls its forks have offered into it: title,
6464 An app's page shows a **Forks (N)** card in its side rail: up to ten forks, the most recently changed first, each
6565 with its owner, its name and "changed 3d ago" (`src/web/studio/forks_card.ts`). Only forks the viewer may read are
6666 listed or counted, so the number never hints at a private fork. "All" opens the forks page.
67
68 ## As JSON
69
70 `GET /api/v1/repos/:owner/:name/forks/tree` answers the forks below a repository as one nested tree,
71 `{"name":"owner/name","forks":[{"name":"...","forks":[]}]}`, for agents (`nestedForks` in
72 `src/actions/fork_nested.ts`). It goes five generations down and lists 500 forks at most; a node whose forks were cut
73 by either cap carries `"truncated": true`, and so does the root when anything was cut. Visibility is the one rule the
74 other fork readers use: a fork the caller cannot read is absent with everything under it, and the answer varies on
75 the caller's identity (`private, no-cache`, `Vary: authorization, cookie`, an `ETag`). It is a separate route so the
76 flat, paged `GET .../forks` keeps its contract. It is in the OpenAPI document (`/api/v1/openapi.json`) and so in
77 the API guides built from it.
78
79 ```
80 curl -H "authorization: Bearer $TOKEN" https://forge.example/api/v1/repos/alice/app/forks/tree
81 ```
src/actions/fork_nested.ts added +60
@@ -0,0 +1,60 @@
1 /**
2 * A repository's forks as nested plain data: `{name, forks:[...]}` to a fixed depth, for agents
3 * that read the tree as one JSON answer. Visibility is the one rule the other fork readers use
4 * (`visibleForksByParent` → `canRead`): a fork the caller cannot read is absent and so is
5 * everything beneath it. One query per generation. No git is read.
6 */

Nothing tests NESTED_MAX_NODES. Take the cap as a parameter and add a test that fails without it.

7
8 import type { Database } from "bun:sqlite";
9 import { visibleForksByParent, type Repo } from "../core/repos.ts";
10 import type { User } from "../core/users.ts";
11
12 /** Generations of forks shown below the repository asked about; a sixth is never listed. */
13 export const NESTED_DEPTH = 5;
14 /** The most forks one answer lists; past it `truncated` is true. */
15 export const NESTED_MAX_NODES = 500;
16
17 export interface NestedFork {
18 readonly name: string;
19 readonly forks: NestedFork[];
20 /** Set on a node whose own forks were cut by the depth or node cap. */
21 readonly truncated?: true;
22 }
23
24 /** The root's `truncated` is true when any visible fork was left out, here or below. */
25 export type NestedForks = NestedFork;
outdated

NestedForks only repeats the truncated field of NestedFork. Make it a type alias.

26
27 type Mutable = { name: string; forks: Mutable[]; truncated?: true };
28 const nameOf = (r: Repo): string => `${r.ownerName}/${r.name}`;
29
30 /** The caller has already shown they may read `repo`. */
31 export function nestedForks(db: Database, repo: Repo, user: User | undefined, depth = NESTED_DEPTH, maxNodes = NESTED_MAX_NODES): NestedForks {
32 const root: Mutable = { name: nameOf(repo), forks: [] };
33 const seen = new Set<string>([repo.id]);
34 let level: { repo: Repo; node: Mutable }[] = [{ repo, node: root }];
35 let listed = 0;
36 let cut = false;
37 for (let d = 1; d <= depth + 1 && level.length > 0; d++) {
38 const by = visibleForksByParent(db, level.map((l) => l.repo), user);
39 const next: typeof level = [];
40 for (const { repo: parent, node } of level) {
41 for (const child of by.get(parent.id) ?? []) {
42 if (seen.has(child.id)) continue;
43 // One generation past the last is read only to know more exists.
44 if (d > depth || listed >= maxNodes) {
45 node.truncated = true;
46 cut = true;
47 continue;
48 }
49 seen.add(child.id);
50 listed++;
51 const kid: Mutable = { name: nameOf(child), forks: [] };
52 node.forks.push(kid);
53 next.push({ repo: child, node: kid });
54 }
55 }
56 level = next;
57 }
58 if (cut) root.truncated = true;
59 return root;
60 }
src/contract/openapi/routes/getApiV1ReposOwnerNameForksTree.ts added +10
@@ -0,0 +1,10 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "get",
5 path: `${REPO}/forks/tree`,
6 summary:
7 "The forks of a repository you can read as one nested tree: { name: \"owner/name\", forks: [...same shape], truncated?: true }, five generations deep and 500 forks at most; truncated is true on a node whose forks were cut. A fork you cannot read is absent, with everything under it",
8 auth: false,
9 role: "anonymous",
10 };
src/contract/openapi/routes/index.ts +1
@@ -167,6 +167,7 @@ export { route as getApiV1ReposOwnerNameFlow } from "./getApiV1ReposOwnerNameFlo
167167 export { route as getApiV1ReposOwnerNameFollowing } from "./getApiV1ReposOwnerNameFollowing.ts";
168168 export { route as getApiV1ReposOwnerNameFollowingProposals } from "./getApiV1ReposOwnerNameFollowingProposals.ts";
169169 export { route as getApiV1ReposOwnerNameForks } from "./getApiV1ReposOwnerNameForks.ts";
170 export { route as getApiV1ReposOwnerNameForksTree } from "./getApiV1ReposOwnerNameForksTree.ts";
170171 export { route as getApiV1ReposOwnerNameGatesIdLog } from "./getApiV1ReposOwnerNameGatesIdLog.ts";
171172 export { route as getApiV1ReposOwnerNameGrowth } from "./getApiV1ReposOwnerNameGrowth.ts";
172173 export { route as getApiV1ReposOwnerNameHooks } from "./getApiV1ReposOwnerNameHooks.ts";
src/http/api/upstream.ts +13
@@ -6,6 +6,7 @@
66 * `actions/repos.ts`.
77 */
88
9 import { nestedForks } from "../../actions/fork_nested.ts";
910 import { forksSince } from "../../core/repos.ts";
1011 import { forkRepo, FORKS_PER_DAY, repositoryLimitMessage } from "../../actions/repos.ts";
1112 import {
@@ -90,6 +91,18 @@ export function upstreamRoutes(router: Router<Handler>): void {
9091 return json(checked.value);
9192 });
9293
94 // The nested tree, apart from the flat page above it so that page's contract is untouched.
95 router.add("GET", "/api/v1/repos/:owner/:name/forks/tree", async (ctx) => {
96 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
97 const repo = loadRepo(ctx);
98 if (!repo) return notFound();
outdated

The issue puts the tree on the bare /forks route. Either move it to a route that keeps the flat page contract or get the issue amended; a query flag that changes the response shape is a surprise for clients.

99 const text = JSON.stringify(nestedForks(ctx.app.db, repo, ctx.auth.user));
100 const etag = weakEtag(text);
101 const headers = { etag, "cache-control": "private, no-cache", vary: "authorization, cookie" };
102 if (holds(ctx.request, etag)) return new Response(null, { status: 304, headers });
103 return new Response(text, { headers: { "content-type": "application/json", ...headers } });
104 });
105
93106 router.add("GET", "/api/v1/repos/:owner/:name/forks", async (ctx) => {
94107 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
95108 const repo = loadRepo(ctx);
test/forks-tree-api.test.ts added +111
@@ -0,0 +1,111 @@
1 /** GET /forks/tree answers the fork tree nested, five deep, only what the reader can see. */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { nestedForks } from "../src/actions/fork_nested.ts";
7 import { createRepo, forkRepo } from "../src/actions/repos.ts";
8 import { createApp, type App } from "../src/app.ts";
9 import { getRepo } from "../src/core/repos.ts";
10 import { createUser, type User } from "../src/core/users.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12 import { promote } from "./helpers/members.ts";
13
14 let dataDir = "";
15 let app: App, servers: Servers;
16 beforeAll(async () => {
17 dataDir = await mkdtemp(join(tmpdir(), "forge-fktree-"));
18 app = createApp({ dataDir, port: 0 });
19 servers = await serve(app);
20 });
21 afterAll(async () => {
22 servers.stop();
23 app.close();
24 await rm(dataDir, { recursive: true, force: true });
25 });
26
27 const mk = async (username: string): Promise<User> => {
28 const r = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@f.dev`, password: "a-good-passphrase", adminIfFirst: username === "u0" });
29 if (!r.ok) throw new Error("user");
30 promote(app.db, r.value);
31 return r.value;
32 };
33 type Node = { name: string; forks: Node[]; truncated?: true };
34 const get = async (path: string, headers: Record<string, string> = {}) => (await (await fetch(`${servers.url}/api/v1/repos/${path}/forks/tree`, { headers })).json()) as Node;
35
36 test("a three-deep tree nests, a private fork hides itself and what is under it, and depth five is the cap", async () => {
37 const users: User[] = [];
38 for (let i = 0; i < 8; i++) users.push(await mk(`u${i}`));
39 const root = await createRepo(app, users[0]!, { name: "app", visibility: "public" });
40 if (!root.ok) throw new Error("repo");
41 // u0/app → u1 → u2 → u3, and a second branch u0/app → u4.
42 let parent = root.value;
43 const chain = [parent];
44 for (const u of users.slice(1, 4)) {
45 const f = await forkRepo(app, u, parent);
46 if (!f.ok) throw new Error("fork");
47 parent = f.value;
48 chain.push(parent);
49 }
50 const side = await forkRepo(app, users[4]!, root.value);
51 if (!side.ok) throw new Error("fork");
52
53 const tree = await get("u0/app");
54 expect(tree.name).toBe("u0/app");
55 expect(tree.truncated).toBeUndefined();
56 expect(tree.forks.map((f) => f.name).sort()).toEqual(["u1/app", "u4/app"]);
57 const one = tree.forks.find((f) => f.name === "u1/app")!;
outdated

The comment says the owner still sees the private fork, but no request asserts it. Add an authenticated get as u2.

58 expect(one.forks[0]!.name).toBe("u2/app");
59 expect(one.forks[0]!.forks[0]).toEqual({ name: "u3/app", forks: [] });
60
61 // u2's fork goes private: an outsider sees neither it nor u3 beneath it; its owner still does.
62 app.db.query("UPDATE repo SET visibility = 'private' WHERE id = ?1").run(chain[2]!.id);
63 const hidden = await get("u0/app");
64 expect(hidden.forks.find((f) => f.name === "u1/app")!.forks).toEqual([]);
65 expect(JSON.stringify(hidden)).not.toContain("u2/app");
66 expect(JSON.stringify(hidden)).not.toContain("u3/app");
67 expect(getRepo(app.db, "u2", "app")?.visibility).toBe("private");
68 // Its owner, signed in, still sees the private fork, and u3 beneath it.
69 const minted = await fetch(`${servers.url}/api/v1/tokens`, {
70 method: "POST",
71 headers: { "content-type": "application/json" },
72 body: JSON.stringify({ username: "u2", password: "a-good-passphrase", name: "t", scope: "ro" }),
73 });
74 const token = ((await minted.json()) as { token: string }).token;
75 const mine = await get("u0/app", { authorization: `Bearer ${token}` });
76 const two = mine.forks.find((f) => f.name === "u1/app")!.forks[0]!;
77 expect(two.name).toBe("u2/app");
78 expect(two.forks[0]!.name).toBe("u3/app");
79 app.db.query("UPDATE repo SET visibility = 'public' WHERE id = ?1").run(chain[2]!.id);
80
81 // Extend to seven generations: u3 → u5 → u6 → u7. Depth 5 lists u1..u5's generation, then cuts.
82 for (const u of users.slice(5)) {
83 const f = await forkRepo(app, u, parent);
84 if (!f.ok) throw new Error("fork");
85 parent = f.value;
86 }
87 const deep = await get("u0/app");
88 expect(deep.truncated).toBe(true);
89 let node = deep.forks.find((f) => f.name === "u1/app")!;
90 const seen = [node.name];
91 while (node.forks.length > 0) {
92 node = node.forks[0]!;
93 seen.push(node.name);
94 }
95 expect(seen).toEqual(["u1/app", "u2/app", "u3/app", "u5/app", "u6/app"]);
96 expect(node.truncated).toBe(true);
97 expect(JSON.stringify(deep)).not.toContain("u7/app");
98 });
99
100 test("the node cap cuts the answer and says so; the flat /forks page keeps its shape", async () => {
101 const root = getRepo(app.db, "u0", "app")!;
102 // u0/app has two direct forks (u1, u4): a cap of one lists the first and truncates the root.
103 const capped = nestedForks(app.db, root, undefined, 5, 1);
104 expect(capped.forks).toHaveLength(1);
105 expect(capped.truncated).toBe(true);
106 const whole = nestedForks(app.db, root, undefined, 5, 500);
107 expect(whole.forks).toHaveLength(2);
108 const flat = (await (await fetch(`${servers.url}/api/v1/repos/u0/app/forks`)).json()) as { items: unknown[]; name?: string };
109 expect(Array.isArray(flat.items)).toBe(true);
110 expect(flat.name).toBeUndefined();
111 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs