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
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14138-get-a-repository-s-forks-answers-the-for → main 4 commits fork 4 threads · 4 unresolved
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, | ||
| 64 | 64 | An app's page shows a **Forks (N)** card in its side rail: up to ten forks, the most recently changed first, each |
| 65 | 65 | with its owner, its name and "changed 3d ago" (`src/web/studio/forks_card.ts`). Only forks the viewer may read are |
| 66 | 66 | 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 | */ | |
| 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 | ||
| 167 | 167 | export { route as getApiV1ReposOwnerNameFollowing } from "./getApiV1ReposOwnerNameFollowing.ts"; |
| 168 | 168 | export { route as getApiV1ReposOwnerNameFollowingProposals } from "./getApiV1ReposOwnerNameFollowingProposals.ts"; |
| 169 | 169 | export { route as getApiV1ReposOwnerNameForks } from "./getApiV1ReposOwnerNameForks.ts"; |
| 170 | export { route as getApiV1ReposOwnerNameForksTree } from "./getApiV1ReposOwnerNameForksTree.ts"; | |
| 170 | 171 | export { route as getApiV1ReposOwnerNameGatesIdLog } from "./getApiV1ReposOwnerNameGatesIdLog.ts"; |
| 171 | 172 | export { route as getApiV1ReposOwnerNameGrowth } from "./getApiV1ReposOwnerNameGrowth.ts"; |
| 172 | 173 | export { route as getApiV1ReposOwnerNameHooks } from "./getApiV1ReposOwnerNameHooks.ts"; |
src/http/api/upstream.ts +13
| @@ -6,6 +6,7 @@ | ||
| 6 | 6 | * `actions/repos.ts`. |
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | import { nestedForks } from "../../actions/fork_nested.ts"; | |
| 9 | 10 | import { forksSince } from "../../core/repos.ts"; |
| 10 | 11 | import { forkRepo, FORKS_PER_DAY, repositoryLimitMessage } from "../../actions/repos.ts"; |
| 11 | 12 | import { |
| @@ -90,6 +91,18 @@ export function upstreamRoutes(router: Router<Handler>): void { | ||
| 90 | 91 | return json(checked.value); |
| 91 | 92 | }); |
| 92 | 93 | |
| 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 | ||
| 93 | 106 | router.add("GET", "/api/v1/repos/:owner/:name/forks", async (ctx) => { |
| 94 | 107 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 95 | 108 | 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 | }); |
new above
offline
Nothing tests NESTED_MAX_NODES. Take the cap as a parameter and add a test that fails without it.