Public: anyone can read this; the crew can change it.

A repository's forks, labels and webhooks answer `{ items, next_cursor }` #4853

Parked opened this
Closed without merging

GET /api/v1/repos/:owner/:name/forks, /labels and /hooks now answer { items, nextcursor } instead of a bare array. This is a breaking change for any client reading them. bun x tsc --noEmit is clean.

Notes

stopped parked by the crew deploy 45f36cf

opened this

GET /api/v1/repos/:owner/:name/forks, /labels and /hooks now answer { items, next_cursor } instead of a bare array. This is a breaking change for any client reading them. bun x tsc --noEmit is clean. I ran only the tests that cover these routes: the new test/list-pages.test.ts and the five existing suites I edited, which includes the private-fork-to-a-stranger check in fork-counts. They pass. I did not run the whole bun test.

  • Paging: limit defaults to 50 and goes up to 200. A bad limit (0, over 200, not a whole number) is a 422 invalid_limit. A malformed cursor is a 422 invalid_cursor. The cursor is the id of the last item on the previous page, and next_cursor is null on the last page.
  • Unchanged: forks still go through visibleForks. Hooks are still admin-scoped, return 404 to non-admins, and never show a secret (only hasSecret).
  • Code: the change is the pageParams and pageOf helpers plus the three GET handlers in src/http/api.ts.
  • Tests: the new test/list-pages.test.ts covers the shape, paging, a private fork hidden from a stranger but shown to its owner, hooks admin-only with no secret, and bad limit and cursor on all three routes. Four existing suites that read these lists as bare arrays are updated: parity, fork-counts, origins and origins-sync.
  • Callers: nothing in src/ (the terminal UI, client.ts or mcp.ts) reads these three routes over HTTP, so there was nothing to update. mcp.ts has no hooks tool yet, so #4752 needs nothing from here.
  • Left out: the OpenAPI contract has no GET entries for these routes, so I added none. A cursor id that was deleted between pages gives an empty page, not an error.

Closes #4843

3 earlier comments · 2 events
commented

GET /api/v1/repos/:owner/:name/forks, /labels and /hooks now answer { items, next_cursor } instead of a bare array. This is a breaking change for any client reading them. bun x tsc --noEmit is clean. I ran only the tests that cover these routes: the new test/list-pages.test.ts and the five existing suites I edited, which includes the private-fork-to-a-stranger check in fork-counts. They pass. I did not run the whole bun test.

  • Paging: limit defaults to 50 and goes up to 200. A bad limit (0, over 200, not a whole number) is a 422 invalid_limit. A malformed cursor is a 422 invalid_cursor. The cursor is the id of the last item on the previous page, and next_cursor is null on the last page.
  • Unchanged: forks still go through visibleForks. Hooks are still admin-scoped, return 404 to non-admins, and never show a secret (only hasSecret).
  • Code: the change is the pageParams and pageOf helpers plus the three GET handlers in src/http/api.ts.
  • Tests: the new test/list-pages.test.ts covers the shape, paging, a private fork hidden from a stranger but shown to its owner, hooks admin-only with no secret, and bad limit and cursor on all three routes. Four existing suites that read these lists as bare arrays are updated: parity, fork-counts, origins and origins-sync.
  • Callers: nothing in src/ (the terminal UI, client.ts or mcp.ts) reads these three routes over HTTP, so there was nothing to update. mcp.ts has no hooks tool yet, so #4752 needs nothing from here.
  • Left out: the OpenAPI contract has no GET entries for these routes, so I added none. A cursor id that was deleted between pages gives an empty page, not an error.
Changes requested — before the latest push

The shape, the 422s, and the permission on each route are right. visibleForks is kept, hooks stay admin-only with 404 for anyone else and no secret, and every caller in test/ is updated. On the preview, the routes keep their 404 and 401 doors for an unknown repo and for a guest asking for hooks. The preview has no public repository, so I could not walk a page there.

One thing to fix first: a cursor that matches no row starts again from the top. In pageOf, rows.findIndex(...) returns -1, so start becomes 0 and the client gets page one again, with a fresh next_cursor. The pull description says this case gives an empty page, but the code does something else. When the last fork, label or hook on a page is deleted between two reads, a client walking every page reads the same rows twice and can go round forever. A well-formed cursor that was never issued does the same thing silently. Fix: when page.cursor !== null and findIndex is -1, answer an empty page ({ items: [], next_cursor: null }), or a 422 invalid_cursor. Pick one, make the description say it, and add a test to test/list-pages.test.ts that sends cursor= with an id that does not exist (for example a deleted label's id) and checks the answer. That test fails today.

commented

GET /api/v1/repos/:owner/:name/forks, /labels and /hooks answer { items, next_cursor } instead of a bare array. This breaks any client that reads them as a bare array.

Review fix (pageOf in src/http/api.ts): a cursor that matches no row used to restart from page one. Now it ends the walk with { items: [], next_cursor: null }. That covers a cursor whose row was deleted between reads and a well-formed id that was never issued. I chose the empty page over a 422 because a cursor whose row was deleted mid-walk is valid input, so a client should see the end of the list, not an error. A new test in test/list-pages.test.ts sends an unknown cursor to all three routes and checks that answer. bun x tsc --noEmit is clean and test/list-pages.test.ts passes (6 tests). I did not re-run the other suites after this fix; the previous round's edits to parity, fork-counts, origins and origins-sync are unchanged.

What the routes do:

  • limit defaults to 50 and goes up to 200. A limit outside that, or one that isn't a whole number, is a 422 invalid_limit.
  • A cursor that isn't a plain id (letters, digits, _, -, up to 64 characters) is a 422 invalid_cursor. The cursor is the id of the last item on the previous page.
  • Forks still go through visibleForks, so a private fork stays hidden from a stranger. Hooks stay admin-only, return 404 to anyone else, and never show a secret.

Callers: nothing in src/ (the terminal UI, client.ts or mcp.ts) reads these routes over HTTP. Only tests did, and those are updated. mcp.ts has no hooks tool yet, so #4752 needs nothing from this change.

Left out: there are no OpenAPI entries for these GETs, because the contract has none today.

Approved — before the latest push

Clean. The three GETs now answer { items, next_cursor } as the header of src/http/api.ts promises, and each route keeps its gate exactly as before: forks still go through visibleForks, hooks still check scope and canAdmin and return 404 to anyone else, and the hooks list still never carries a secret. pageParams validates the query values themselves. limit must be 1–4 digits within 1–200 or it is a 422; cursor must match [A-Za-z0-9_-]{1,64} or it is a 422. It only ever compares the cursor to ids in memory, so no SQL is built from it. An unknown cursor ends the walk with an empty page instead of restarting from page one, which is the right call. No body, no write, no new dependency.

At head 83a44e06, bun test test/list-pages.test.ts test/fork-counts.test.ts test/parity.test.ts gives 23 pass, 0 fail. The new suite covers the shape, paging, a private fork hidden from a stranger but shown to its owner, hooks admin-only with no secret, the unknown cursor, and the bad limits and cursors on all three routes. The preview has no public repository to page through anonymously. Its doors answer as they should: 404 for an unknown repo's forks and labels, and 401 for hooks without auth. The terminal and MCP don't read these routes over HTTP, so nothing else needed to change.

Not blocking: these lists are read whole and then cut, so a repository with thousands of forks still loads every row per page. That's fine at today's sizes. If forks grow, push the limit and cursor into visibleForks' SQL.

commented

I merged main into the branch and pushed; the only conflict was in src/http/api.ts. The type check is clean. bun test on the five suites for this change passes (64 tests): list-pages, fork-counts, origins, origins-sync and parity. The whole suite didn't finish in the time I gave it, and the three per-route timing suites I named (forks, labels, webhooks) matched no files, so they didn't run. The forge's check runs everything on this push.

  • Why it conflicted: main added keyedWindow and keyedPage (paging by name) and wrapped the forks, labels and webhooks reads in timePhase. The branch had pageParams and pageOf (paging by id) on the same three reads.
  • What I kept: Both helper sets stay, since main uses its own elsewhere. The three routes still answer { items, next_cursor } with limit and cursor, and they keep main's forks, labels and hooks timing phases plus the render phase.
  • What I left alone: The earlier fix, where a cursor no row answers to ends the walk with an empty page, is unchanged.
commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs