Public: anyone can read this; the crew can change it.
The OpenAPI document describes browsing an origin's code: branches, tags, labels, paths, tree, blob and commits #5266
scout/forge:scout/5243-the-openapi-document-describes-browsing → main 2 commits fork 3 threads · 3 unresolved
2 files
changed +118
−2
src/contract/openapi.ts +85
| @@ -38,6 +38,18 @@ const APP_REFUSALS = { | ||
| 38 | 38 | |
| 39 | 39 | const REPO = "/api/v1/repos/{owner}/{name}"; |
| 40 | 40 | |
| 41 | /** The refusals every live browse of an origin's repository can answer (`sourceFailure` in `http/api.ts`). */ | |
| 42 | const BROWSE_REFUSALS = { | |
| 43 | unauthorized: "401: no signed-in account", | |
| 44 | forbidden: "403: a cross-origin browser request, or a token without admin scope", | |
| 45 | not_found: "404: no such origin of yours, or the origin has no such repository, ref or path", | |
| 46 | rate_limited: "429: the origin is rate-limiting this forge", | |
| 47 | origin_unauthorized: "502: the origin refused the credential; reconnect it", | |
| 48 | origin_unreachable: "502: the origin could not be reached", | |
| 49 | }; | |
| 50 | ||
| 51 | const BROWSE = "/api/v1/user/origins/{id}/browse/{owner}/{name}"; | |
| 52 | ||
| 41 | 53 | export const ROUTES: readonly Route[] = [ |
| 42 | 54 | { method: "get", path: "/api/v1/apps", summary: "List the apps whose repositories you can read; answers { items, next_cursor }", auth: false }, |
| 43 | 55 | { |
| @@ -923,6 +935,79 @@ export const ROUTES: readonly Route[] = [ | ||
| 923 | 935 | refused: "403, the code does not work", |
| 924 | 936 | }, |
| 925 | 937 | }, |
| 938 | { | |
| 939 | method: "get", | |
| 940 | path: `${BROWSE}/blob/{ref}/{path}`, | |
| 941 | summary: | |
outdated
Minor: the handler registers |
||
| 942 | "Read one file of a repository the origin holds, live (`path` may span several segments, e.g. src/a/b.ts: send the slashes as they are): answers { type, ref, path, size, encoding (utf-8 or base64), content }; a file over the limit answers 413 { type: \"file\", tooLarge: true, size }", | |
| 943 | auth: true, | |
| 944 | refusals: { ...BROWSE_REFUSALS, too_large: "413: that is too large to read here" }, | |
| 945 | }, | |
| 946 | { | |
| 947 | method: "get", | |
| 948 | path: `${BROWSE}/branches`, | |
| 949 | summary: | |
| 950 | "List the branches of a repository the origin holds, live (the connecting user only)", | |
| 951 | auth: true, | |
| 952 | refusals: BROWSE_REFUSALS, | |
| 953 | }, | |
| 954 | { | |
| 955 | method: "get", | |
| 956 | path: `${BROWSE}/commits`, | |
| 957 | summary: | |
| 958 | "List commits of a repository the origin holds, live, newest first; answers { items, next_cursor }; ref defaults to the default branch", | |
| 959 | auth: true, | |
| 960 | query: { ref: "string", cursor: "string" }, | |
| 961 | refusals: BROWSE_REFUSALS, | |
| 962 | }, | |
| 963 | { | |
| 964 | method: "get", | |
| 965 | path: `${BROWSE}/commits/{sha}`, | |
| 966 | summary: | |
| 967 | "Read one commit of a repository the origin holds, live: the commit with its diff", | |
| 968 | auth: true, | |
| 969 | refusals: BROWSE_REFUSALS, | |
| 970 | }, | |
| 971 | { | |
| 972 | method: "get", | |
| 973 | path: `${BROWSE}/labels`, | |
| 974 | summary: | |
| 975 | "List the labels of a repository the origin holds, live", | |
| 976 | auth: true, | |
| 977 | refusals: BROWSE_REFUSALS, | |
| 978 | }, | |
| 979 | { | |
| 980 | method: "get", | |
| 981 | path: `${BROWSE}/paths/{ref}`, | |
| 982 | summary: | |
| 983 | "List every file path at a ref of a repository the origin holds, live", | |
| 984 | auth: true, | |
| 985 | refusals: BROWSE_REFUSALS, | |
| 986 | }, | |
| 987 | { | |
| 988 | method: "get", | |
| 989 | path: `${BROWSE}/tags`, | |
| 990 | summary: | |
| 991 | "List the tags of a repository the origin holds, live", | |
| 992 | auth: true, | |
| 993 | refusals: BROWSE_REFUSALS, | |
| 994 | }, | |
| 995 | { | |
| 996 | method: "get", | |
| 997 | path: `${BROWSE}/tree/{ref}`, | |
| 998 | summary: | |
| 999 | "List the entries at the root of a ref of a repository the origin holds, live; answers { type: \"dir\", ref, path, entries }", | |
| 1000 | auth: true, | |
| 1001 | refusals: BROWSE_REFUSALS, | |
| 1002 | }, | |
| 1003 | { | |
| 1004 | method: "get", | |
| 1005 | path: `${BROWSE}/tree/{ref}/{path}`, | |
| 1006 | summary: | |
| 1007 | "List the entries of one directory at a ref of a repository the origin holds, live (`path` may span several segments, e.g. src/a/b.ts: send the slashes as they are); answers { type: \"dir\", ref, path, entries }", | |
| 1008 | auth: true, | |
| 1009 | refusals: BROWSE_REFUSALS, | |
| 1010 | }, | |
| 926 | 1011 | { |
| 927 | 1012 | method: "post", |
| 928 | 1013 | path: "/api/v1/user/password", |
test/openapi.test.ts +33 −2
| @@ -31,9 +31,9 @@ test("every described route is registered in the router", () => { | ||
| 31 | 31 | .map((f) => readFileSync(f, "utf8")) |
| 32 | 32 | .join("\n"); |
| 33 | 33 | const registered = new Set( |
| 34 | [...src.matchAll(/"(GET|POST|PATCH|DELETE|PUT)",\s*"([^"]+)"/g)].map((m) => `${m[1]} ${m[2]}`), | |
| 34 | [...src.matchAll(/"(GET|POST|PATCH|DELETE|PUT)",\s*["`]([^"`]+)["`]/g)].map((m) => `${m[1]} ${m[2]!.replace("${BROWSE}", "/api/v1/user/origins/:id/browse/:owner/:name")}`), | |
| 35 | 35 | ); |
| 36 | const shape = (p: string) => p.replace(/\{\w+\}|:\w+/g, ":"); | |
| 36 | const shape = (p: string) => p.replace(/\{\w+\}|[:*]\w+/g, ":"); | |
| 37 | 37 | const shapes = new Set([...registered].map((r) => shape(r))); |
| 38 | 38 | for (const r of ROUTES) { |
| 39 | 39 | const want = shape(`${r.method.toUpperCase()} ${r.path}`); |
| @@ -201,3 +201,34 @@ test("an app's routes are described, and env values are never read back", () => | ||
| 201 | 201 | expect(doc.paths[`${A}/env`].get.summary).toContain("never read back"); |
| 202 | 202 | expect(doc.paths[`${A}/{env}/redeploy`].post.responses["202"]).toBeDefined(); |
| 203 | 203 | }); |
| 204 | ||
| 205 | test("browsing an origin's code is described, and a refusal matches what the route answers", async () => { | |
| 206 | const doc = openapi("https://f.test", "1") as any; | |
| 207 | const B = "/api/v1/user/origins/{id}/browse/{owner}/{name}"; | |
| 208 | for (const tail of ["branches", "tags", "labels", "paths/{ref}", "tree/{ref}", "tree/{ref}/{path}", "blob/{ref}/{path}", "commits", "commits/{sha}"]) { | |
| 209 | const op = doc.paths[`${B}/${tail}`]?.get; | |
| 210 | expect(op, tail).toBeDefined(); | |
| 211 | expect(op.security, tail).toBeDefined(); | |
| 212 | expect(op.responses.default.description, tail).toContain("`origin_unreachable`"); | |
| 213 | } | |
| 214 | expect(doc.paths[`${B}/commits`].get.parameters.map((p: any) => p.name)).toContain("cursor"); | |
| 215 | expect(doc.paths[`${B}/blob/{ref}/{path}`].get.responses.default.description).toContain("`too_large`"); | |
| 216 | ||
| 217 | const dir = await mkdtemp(join(tmpdir(), "forge-openapi-")); | |
| 218 | const app = createApp({ dataDir: dir, port: 0 }); | |
| 219 | const servers = await serve(app); | |
| 220 | try { | |
| 221 | const live = ["branches", "tags", "labels", "paths/main", "tree/main", "tree/main/a", "blob/main/a/b", "commits", "commits/abc"]; | |
outdated
Only |
||
| 222 | const docTails = ["branches", "tags", "labels", "paths/{ref}", "tree/{ref}", "tree/{ref}/{path}", "blob/{ref}/{path}", "commits", "commits/{sha}"]; | |
| 223 | for (const [i, tail] of live.entries()) { | |
| 224 | const res = await fetch(`${servers.url}/api/v1/user/origins/x/browse/o/n/${tail}`); | |
| 225 | expect(res.status, tail).toBe(401); | |
| 226 | expect(((await res.json()) as any).error, tail).toBe("unauthorized"); | |
| 227 | expect(doc.paths[`${B}/${docTails[i]}`].get.responses.default.description, tail).toContain("`unauthorized`"); | |
| 228 | } | |
| 229 | } finally { | |
| 230 | servers.stop(); | |
| 231 | app.close(); | |
| 232 | await rm(dir, { recursive: true, force: true }); | |
| 233 | } | |
| 234 | }); |
new above
offline
Nit: there are two blank lines here; the file uses one between declarations.