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

Parked opened this
Closed without merging

scout/forge:scout/5243-the-openapi-document-describes-browsing → main 2 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
2 files changed +118 −2
src/contract/openapi.ts +85
@@ -38,6 +38,18 @@ const APP_REFUSALS = {
3838
3939 const REPO = "/api/v1/repos/{owner}/{name}";
4040
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
4153 export const ROUTES: readonly Route[] = [
outdated

Nit: there are two blank lines here; the file uses one between declarations.

4254 { method: "get", path: "/api/v1/apps", summary: "List the apps whose repositories you can read; answers { items, next_cursor }", auth: false },
4355 {
@@ -923,6 +935,79 @@ export const ROUTES: readonly Route[] = [
923935 refused: "403, the code does not work",
924936 },
925937 },
938 {
939 method: "get",
940 path: `${BROWSE}/blob/{ref}/{path}`,
941 summary:
outdated

Minor: the handler registers *path, which matches many segments, but an OpenAPI {path} parameter cannot contain /. Add a sentence to the summary (here and on tree/{ref}/{path}) saying path may span several segments, e.g. src/a/b.ts, so a generated client does not percent-encode the slashes.

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 },
9261011 {
9271012 method: "post",
9281013 path: "/api/v1/user/password",
test/openapi.test.ts +33 −2
@@ -31,9 +31,9 @@ test("every described route is registered in the router", () => {
3131 .map((f) => readFileSync(f, "utf8"))
3232 .join("\n");
3333 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")}`),
3535 );
36 const shape = (p: string) => p.replace(/\{\w+\}|:\w+/g, ":");
36 const shape = (p: string) => p.replace(/\{\w+\}|[:*]\w+/g, ":");
3737 const shapes = new Set([...registered].map((r) => shape(r)));
3838 for (const r of ROUTES) {
3939 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", () =>
201201 expect(doc.paths[`${A}/env`].get.summary).toContain("never read back");
202202 expect(doc.paths[`${A}/{env}/redeploy`].post.responses["202"]).toBeDefined();
203203 });
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 branches is checked against the live route. The issue asks for one refusal per row, so loop this over all nine paths (one example per templated path) and assert 401 unauthorized for each one.

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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs