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

Every cursor-paged API list sends a Link rel=next header, so an agent follows pages untaught #14660

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

Every cursor-paged API list now sends Link: ; rel="next" while more pages remain, and no Link header on the last page. tsc, scripts/gate.ts --fix, the new test, test/list-cursor-state.test.ts and test/feed-cursor.test.ts all pass. I did not run the full suite; the forge's check does that on push.

Notes

shipped production is serving it deploy 404563e

opened this

Every cursor-paged API list now sends Link: <url>; rel="next" while more pages remain, and no Link header on the last page. tsc, scripts/gate.ts --fix, the new test, test/list-cursor-state.test.ts and test/feed-cursor.test.ts all pass. I did not run the full suite; the forge's check does that on push.

  • How it works: withLinkNext in src/http/cursor_lists.ts is called once from the API response path in src/http/server.ts. It applies to any GET route that the contract marks as cursor-paged. For a 200 JSON reply with a non-empty next_cursor, it adds the header. No individual handler changed. It accepts numeric cursors as well as strings, since the issues and pulls lists use row numbers.
  • The URL: it is built from publicUrl(request, app.config.url), which uses the configured origin and ignores Host and X-Forwarded-* headers. It keeps the caller's other query values (limit, state and so on) and only replaces cursor.
  • Tests: test/link-next.test.ts walks the issues list in three pages, which is five issues at limit=2. It follows each Link and checks that the first two pages have one, the last has none, limit and state survive, and all five items are seen once. A second test sends forged Host and X-Forwarded-* headers and checks they never reach the link.
  • Not done: the header is only added when the reply body has a next_cursor. Lists that page by cursor but return a different body shape get no Link. The OpenAPI document does not mention the header yet.

To try it, request any list with a small limit and read the headers. For example: curl -si -H "authorization: Bearer $TOKEN" "$FORGE_URL/api/v1/repos/OWNER/NAME/issues?limit=2".

The first push was refused by the pre-push hook, which wants a Try: line in a commit message. I added one by amending the commit.

Closes #14642

commented

Every cursor-paged API list now sends Link: <url>; rel="next" while more pages remain, and no Link header on the last page. tsc, scripts/gate.ts --fix, the new test, test/list-cursor-state.test.ts and test/feed-cursor.test.ts all pass. I did not run the full suite; the forge's check does that on push.

  • How it works: withLinkNext in src/http/cursor_lists.ts is called once from the API response path in src/http/server.ts. It applies to any GET route that the contract marks as cursor-paged. For a 200 JSON reply with a non-empty next_cursor, it adds the header. No individual handler changed. It accepts numeric cursors as well as strings, since the issues and pulls lists use row numbers.
  • The URL: it is built from publicUrl(request, app.config.url), which uses the configured origin and ignores Host and X-Forwarded-* headers. It keeps the caller's other query values (limit, state and so on) and only replaces cursor.
  • Tests: test/link-next.test.ts walks the issues list in three pages, which is five issues at limit=2. It follows each Link and checks that the first two pages have one, the last has none, limit and state survive, and all five items are seen once. A second test sends forged Host and X-Forwarded-* headers and checks they never reach the link.
  • Not done: the header is only added when the reply body has a next_cursor. Lists that page by cursor but return a different body shape get no Link. The OpenAPI document does not mention the header yet.

To try it, request any list with a small limit and read the headers. For example: curl -si -H "authorization: Bearer $TOKEN" "$FORGE_URL/api/v1/repos/OWNER/NAME/issues?limit=2".

The first push was refused by the pre-push hook, which wants a Try: line in a commit message. I added one by amending the commit.

Approved

Clean, small, one call site. Link built from configured origin (publicUrl), only cursor replaced, no header on last page or non-200/non-JSON. Tests walk three pages and check forged Host/X-Forwarded are ignored. Non-blocking: the OpenAPI doc does not yet mention the header.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs