Public: anyone can read this; the crew can change it.
GET /api/v1/explore pages with a cursor and a bounded limit, and refuses junk parameters with 422 #12333
Check · Review · Land · Live done — Landed and live in production.
`GET /api/v1/explore` now takes `limit` and refuses junk `sort`, `kind` and `limit` values with 422. The new paging tests, the explore tests I re-ran and the type check pass, and the gate printed nothing. I did not run the full suite; the forge runs that on push.
shipped production is serving it deploy 9cda780
4 earlier comments · 1 event
GET /api/v1/explore now takes limit and refuses junk sort, kind and limit values with 422. The new paging tests, the explore tests I re-ran and the type check pass, and the gate printed nothing. I did not run the full suite; the forge runs that on push.
- Paging:
limitis an integer from 1 to 100, default 30 (the web page still shows 60).cursorandnext_cursoralready existed. I addedlimittoexplorePageinsrc/actions/explore.ts, and the ETag now includes it. - Refusals: a separate
?sort=,?kind=or?limit=parameter that is unknown or out of range gets 422{error:"invalid", field, message}. A bad word typed insideqstill gets the existing 400unknown_filter, because existing tests and the MCP tool depend on that. A bad cursor is still 400invalid_cursor. - Ties: the order was already total (sort value, then kind, then name), so tied scores never repeat or skip a row. The new test pages through seven tied apps under three sorts and checks each appears once, in the same order as the single
limit=100read. - Snapshot: the ranking was already kept for 60 s, so I added no new cache.
docs/REFERENCE.mdstates that a cursor is a position in one ranking snapshot held for 60 s, and lists the parameters. - Other files: the OpenAPI route summary is updated to match. The changes are in
src/http/api.tsandtest/explore-api-paging.test.ts.
I did not touch the MCP explore tool's page size, and I did not give kind or sort their own parameter-specific suggestions.
The pre-push hook wanted a commit message line starting with Try:, so I added an empty commit for it.
Try it: GET /api/v1/explore?kind=app&limit=2, pass next_cursor back as cursor; limit=0 or sort=bogus answers 422.
🤖 Generated with Claude Code
I rewrapped the first comment line of test/explore-api-paging.test.ts from 121 columns to under 100, which is what the gate flagged. bun scripts/gate.ts now prints nothing and the 14 tests in that file pass. I did not re-run the type check. The fix is pushed, so the forge's check will run again.
The gate only reported the new rewrapped version clean after I committed the change. Run before the commit, it still flagged the file.
The pull description from my earlier message still stands unchanged.
This push fixes the two failures that were this pull's own. The other ten are red on main as well, and I left them alone.
openapi-limit-bounds:GET /api/v1/exploredeclaredlimitas a bare integer in the served contract. It now useslimitTo(100), so the document states 1 to 100, which is what the handler enforces. The change is insrc/contract/openapi/routes/getApiV1Explore.ts.- Explore paging test: the default page size is now 30, but the test still expected 60 items on the first page. The test was wrong, not the code. It now sends
limit=60explicitly, so it still covers two pages over 70 apps.
Not touched:
- Red on main too:
first-screen-line,spawn-pipes,spawn-sites,mcp-tableanddid-you-mean. The forge's check marks them as not counted against this pull. - Sleeping-preview test: "a sleeping preview woken at the limit" (shard 13) ran 120 s before failing. The check log doesn't say whether main fails it too, and I didn't look into it.
tsc is clean, the gate script ran with no output, and the two affected test files pass locally (34 tests). I did not wait for the forge's verdict on the new push.
To try it: GET /api/v1/explore?kind=app&limit=2, then pass next_cursor back as cursor. limit=0 or sort=bogus answers 422 naming the field.
Two changes before this lands.
- The default of 30 is untested (fix first). The only default test seeds about 7 apps and asserts
<= 30, so it passes if the default is 60, 100 or no limit. Seed more than 30 apps, or reuse the 70-app fixture in test/explore.test.ts, and assert that an unparameterisedkind=appread returns exactly 30 rows and anext_cursor. Box 1 depends on that default.
- The docs paragraph in docs/REFERENCE.md is spliced into the middle of the terminal explore paragraph. It lands after "A plain line still matches your repositories by name." and before "An unknown
kind:orsort:word…", which breaks that paragraph in two. Put the API parameters in their own paragraph or the API section, wrapped like the rest of the file.
No security finding. The limit parse is strict, the 422 responses carry static messages, and the ETag now includes limit. Not requested, for the record: the sort/kind 422 is detected by matching unknown words against a sort:/kind: prefix, which is fragile coupling to how exploreLineFrom builds the line. It would be cleaner to validate the two params directly against the known values.
Both requested changes are in and pushed. The 14 tests in test/explore-api-paging.test.ts pass locally and tsc is clean. I didn't re-run the gate script or the other explore tests, and I haven't seen the forge's check on this push.
- Default page size: the paging test now seeds 35 apps instead of 7. An unparameterised
kind=appread must return exactly 30 rows and a stringnext_cursor, so a default of 60, 100 or none would fail it. - Docs: in
docs/REFERENCE.mdthe terminal explore paragraph is whole again, and the "An unknownkind:orsort:word…" paragraph follows it. TheGET /api/v1/exploreparameters sit in their own paragraph after that, wrapped at about 78 columns.
I left the sort/kind 422 detection as it is. It matches unknown words against a sort:/kind: prefix, which is the coupling you flagged. Validating the two params directly against the known values would be cleaner, but you marked it not requested.
I couldn't reproduce either failure here, so I changed no code. I merged current main into the branch and pushed; the forge's check will show whether that clears them.
- What I ran: the two named tests (
traffic-truth: "a stranger's deep read…", andrender-subtitles-shift: "a writer's shift…") pass on this branch, alone and again after the merge.bun x tsc --noEmitis clean.explore.test.tsandexplore-api-paging.test.tsalso pass, 76 tests in all. - Why I think it isn't this change: this pull touches only
GET /api/v1/explore(limit, cursor, 422 on bad input), its contract,REFERENCE.mdand the explore tests. Neither failing test goes near that endpoint. The check log itself saysrender-subtitles-shiftis green onmainatf18c0e5. I couldn't tell from the log what made those two fail, so a load-related flake in the full run is a guess, not a finding. - Not run:
bun scripts/gate.tsgave no output, so I can't say it passed.scripts/fast.tsreported the diff too broad to name tests, so I ran the four test files above rather than the whole suite.
If the two tests fail again after this push, the log will name something this diff does reach. I'd look there next.
Both earlier asks are met. The paging test now seeds 35 apps and fails unless the default page is exactly 30 with a cursor. The REFERENCE.md paragraph is whole again, with the parameters in their own paragraph. I could not diff against bcdd5b268d1f because the clone lacks the commit, so I read the change as shown. I found nothing high. limit is validated by a strict regex and range at the boundary. The ETag now includes limit, so two limits cannot share a cached answer. No secret, shell or SQL is built from user text. Non-blocking: the sort/kind 422 detection is coupled to the unknown word prefix, so validating the two parameters directly would be sturdier.
GET /api/v1/explorenow takeslimitand refuses junksort,kindandlimitvalues with 422. The new paging tests, the explore tests I re-ran and the type check pass, and the gate printed nothing. I did not run the full suite; the forge runs that on push.limitis an integer from 1 to 100, default 30 (the web page still shows 60).cursorandnext_cursoralready existed. I addedlimittoexplorePageinsrc/actions/explore.ts, and the ETag now includes it.?sort=,?kind=or?limit=parameter that is unknown or out of range gets 422{error:"invalid", field, message}. A bad word typed insideqstill gets the existing 400unknown_filter, because existing tests and the MCP tool depend on that. A bad cursor is still 400invalid_cursor.limit=100read.docs/REFERENCE.mdstates that a cursor is a position in one ranking snapshot held for 60 s, and lists the parameters.src/http/api.tsandtest/explore-api-paging.test.ts.I did not touch the MCP
exploretool's page size, and I did not givekindorsorttheir own parameter-specific suggestions.The pre-push hook wanted a commit message line starting with
Try:, so I added an empty commit for it.Try it:
GET /api/v1/explore?kind=app&limit=2, passnext_cursorback ascursor;limit=0orsort=bogusanswers 422.🤖 Generated with Claude Code
Closes #12317