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
GET /contract/openapi.json now has a row for each of the nine origin-browse reads, and the routes themselves are unchanged. test/openapi.test.ts passes (14 tests). tsc couldn't run here because the bun type definitions were missing.
stopped parked by the crew deploy e682561
2 earlier comments · 1 event
GET /contract/openapi.json now has a row for each of the nine origin-browse reads, and the routes themselves are unchanged. test/openapi.test.ts passes (14 tests). tsc couldn't run here because the bun type definitions were missing.
- Rows added:
branches,tags,labels,paths/{ref},tree/{ref},tree/{ref}/{path},blob/{ref}/{path},commitsandcommits/{sha}, all under/api/v1/user/origins/{id}/browse/{owner}/{name}. They sit just before/api/v1/user/password, beside their neighbours by path. - Query parameters: only
commitstakes any,refandcursor.refdefaults to the origin's default branch. - Refusals: every row lists the codes
sourceFailureandrequireAccountproduce (seesrc/http/api.ts):unauthorized(401)forbidden(403)not_found(404)rate_limited(429)origin_unauthorized(502)origin_unreachable(502)
blobextras: its row addstoo_large(413) and describes the{ tooLarge, size }body.- Param name: the handler calls the commit param
:oid. The document names it{sha}, as the issue does. - New test: a new test in
test/openapi.test.tsasserts all nine paths are in the document and thatcommitslistscursor. It also checks thatblobliststoo_largeand that the others listorigin_unreachable. For the refusal match, it callsbrancheswithout a login against a real server and gets a 401 witherror: "unauthorized". - Existing test fixed: "every described route is registered in the router" only read double-quoted route strings and
:paramsegments. It missed the browse routes, which are written as `${BROWSE}/…withpath. I widened its regex to accept backticks, expand${BROWSE}, and treatpath` as a param. The test was wrong, not the code. - Refusal coverage: the test checks only one refusal code against the live route. The other codes depend on a connected origin that fails in a particular way, and I did not stand one up for each.
- Left out: the landing read
GET …/browse/{owner}/{name}, plus theissuesandpullsreads andcontribute. The issue didn't list them.
I checked the preview at this head. /contract/openapi.json has all nine browse rows with the right path and query parameters. Each of the nine routes answers 401 unauthorized without a login, which matches the documented refusals. The refusal codes match sourceFailure and requireAccount in src/http/api.ts, and the routes themselves are unchanged. I found no security problem: the change only adds documentation and tests.
Fix first: issue #5243 asks the test to check "that one refusal code per row matches what the route answers". The new test calls only branches against the live server, so 8 of the 9 rows have no check against their route. If one of them were registered under a different path, or its documented refusal were wrong, no test would fail. Loop the live call over all nine tails you already list:
for (const tail of ["branches", "tags", "labels", "paths/main", "tree/main", "tree/main/a", "blob/main/a/b", "commits", "commits/abc"]) {
const res = await fetch(`${servers.url}/api/v1/user/origins/x/browse/o/n/${tail}`);
expect(res.status, tail).toBe(401);
expect(((await res.json()) as any).error, tail).toBe("unauthorized");
}
Then assert that each row's responses.default.description contains ` unauthorized `. Two smaller points are in the line comments.
I addressed all three of sentinel's points and pushed to the same branch. test/openapi.test.ts passes. I did not re-run tsc or the design lint.
- Live check on every row: the test now calls all nine routes against a real server with no login. Each answers 401
unauthorized, and each row's refusal text must list `unauthorized`. - Multi-segment
path: the summaries fortree/{ref}/{path}andblob/{ref}/{path}now saypathmay span several segments, e.g.src/a/b.ts, and the slashes go as they are. - Blank line: I collapsed the extra blank line in
src/contract/openapi.ts. The same replace removed every other double blank line in the file, but I didn't check the diff for those.
The check covers only the unauthorized refusal. The other refusals (not_found, rate_limited, origin_unauthorized, origin_unreachable, and too_large on blob) still have no live check, since they need a connected origin that fails in a particular way. The routes themselves are unchanged.
Parked by the crew: the check failed ("a restore clones in parallel > clones: 6 never runs more than 6 at once, and reaches 6 with 20 bundles") and the decider saw no point in another try
GET /contract/openapi.jsonnow has a row for each of the nine origin-browse reads, and the routes themselves are unchanged.test/openapi.test.tspasses (14 tests).tsccouldn't run here because thebuntype definitions were missing.branches,tags,labels,paths/{ref},tree/{ref},tree/{ref}/{path},blob/{ref}/{path},commitsandcommits/{sha}, all under/api/v1/user/origins/{id}/browse/{owner}/{name}. They sit just before/api/v1/user/password, beside their neighbours by path.commitstakes any,refandcursor.refdefaults to the origin's default branch.sourceFailureandrequireAccountproduce (seesrc/http/api.ts):unauthorized(401)forbidden(403)not_found(404)rate_limited(429)origin_unauthorized(502)origin_unreachable(502)blobextras: its row addstoo_large(413) and describes the{ tooLarge, size }body.:oid. The document names it{sha}, as the issue does.test/openapi.test.tsasserts all nine paths are in the document and thatcommitslistscursor. It also checks thatblobliststoo_largeand that the others listorigin_unreachable. For the refusal match, it callsbrancheswithout a login against a real server and gets a 401 witherror: "unauthorized".:paramsegments. It missed the browse routes, which are written as `${BROWSE}/…withpath. I widened its regex to accept backticks, expand${BROWSE}, and treatpath` as a param. The test was wrong, not the code.GET …/browse/{owner}/{name}, plus theissuesandpullsreads andcontribute. The issue didn't list them.Closes #5243