GET /api/v1/repos/:owner/:name/branches carries an ETag and answers a repeat with 304 until a ref moves #9160

GET /api/v1/repos/:owner/:name/branches now carries a weak etag, and a matching If-None-Match gets an empty 304. The new tests, test/branches-deep.test.ts and test/openapi.test.ts pass, and bun x tsc --noEmit and bun scripts/gate.ts print nothing. I did not run the full suite.

• Tag: it covers limit, cursor, default branch, protectDefault and every ref's name and oid, not only the page's. A push to the default branch therefore changes the tag even on a limit=1 page. The 200 also sends cache-control: private, no-cache and vary: authorization, cookie. I used weakEtag and holds from src/http/etag.ts.
• 304 timing: the 304 is returned after the ref listing and before compareBranches, so no per-branch git compare runs.
• Refusals: a bad limit or cursor is still a 422 and an unseen repository still a 404, with no tag on either.
• OpenAPI: the route's summary in getApiV1ReposOwnerNameBranches.ts names the ETag, If-None-Match and the 304, and it lists 304 in alsoStatus.
• Tests: test/branches-etag.test.ts covers the 200 and 304, and a change of tag on a branch push, a default push, a new branch and a deleted branch. It also covers limit and cursor tagging their own page, the 422s and the 404. I did not run it against main; it would fail there because main sends no tag.

I left one thing out. The tests do not assert on Server-Timing for the 304, because the git phase there still includes the cheap ref listing and a timing check would be flaky. They assert the 304 has an empty body instead.

The route is in src/http/api.ts.

Closes #9157

GET /api/v1/repos/:owner/:name/branches now carries a weak etag, and a matching If-None-Match gets an empty 304. The new tests, test/branches-deep.test.ts and test/openapi.test.ts pass, and bun x tsc --noEmit and bun scripts/gate.ts print nothing. I did not run the full suite.

• Tag: it covers limit, cursor, default branch, protectDefault and every ref's name and oid, not only the page's. A push to the default branch therefore changes the tag even on a limit=1 page. The 200 also sends cache-control: private, no-cache and vary: authorization, cookie. I used weakEtag and holds from src/http/etag.ts.
• 304 timing: the 304 is returned after the ref listing and before compareBranches, so no per-branch git compare runs.
• Refusals: a bad limit or cursor is still a 422 and an unseen repository still a 404, with no tag on either.
• OpenAPI: the route's summary in getApiV1ReposOwnerNameBranches.ts names the ETag, If-None-Match and the 304, and it lists 304 in alsoStatus.
• Tests: test/branches-etag.test.ts covers the 200 and 304, and a change of tag on a branch push, a default push, a new branch and a deleted branch. It also covers limit and cursor tagging their own page, the 422s and the 404. I did not run it against main; it would fail there because main sends no tag.

I left one thing out. The tests do not assert on Server-Timing for the 304, because the git phase there still includes the cheap ref listing and a timing check would be flaky. They assert the 304 has an empty body instead.

The route is in src/http/api.ts.

The check failed because no commit message had a Try: line. I added an empty commit with one and pushed it. The code is unchanged from the first push, so the tests are unchanged too.

bun scripts/gate.ts now prints nothing locally. I have not seen the forge's check run on the new push.

Try: GET /api/v1/repos/<owner>/<name>/branches on the preview. Then repeat it with If-None-Match set to the etag it returned, and expect an empty 304.

I've pushed both changes from @sentinel's review to #9160. test/branches-etag.test.ts, test/branches-deep.test.ts and test/openapi.test.ts passed, and tsc and the gate were clean, on the code before I retargeted the deep test's timing regex. After that edit I re-ran only test/branches-etag.test.ts and test/branches-deep.test.ts, and both passed. I did not re-run tsc, the gate or test/openapi.test.ts.

• Compare phase: compareBranches now runs in its own compare phase in src/http/api.ts, after the 304 check. I split it out of the git phase, which now covers only the ref listing and the tag.
• Server-Timing assertion: the 200's Server-Timing header names compare and the 304's does not. The test checks for the phase name only, with no durations.
• Test type: repo is now typed Repo and alice is typed User, replacing the conditional type.
• Edit to an existing test: test/branches-deep.test.ts read the git phase to compare a 30-row page against a 200-row one. The compare cost moved out of that phase, so it now reads compare. Its assertion is unchanged.

I agree the Server-Timing check is not flaky when it tests the phase name instead of how long it took.

Try: GET /api/v1/repos/<owner>/<name>/branches on the preview and look for compare in Server-Timing. Repeat it with If-None-Match set to the returned etag and the 304 has no compare.

The check failed on test/api-branches-timing.test.ts, and the fix was to the test, not the code. That test pinned the branches route's Server-Timing phases to session, git, render. The route now reports compare as its own phase, which the review asked for, so the test was out of date. It now expects session, git, compare, render. I re-ran that file and it passes (2 tests); I did not re-run the rest of the suite, and I pushed without waiting for the forge's check.

The 304 path reports session, git and no compare, as the review wanted.

Try: GET /api/v1/repos/<owner>/<name>/branches on the preview. Server-Timing lists session, git, compare, render in that order.