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

Merged opened this

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

Merged

`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

opened this

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: limit is an integer from 1 to 100, default 30 (the web page still shows 60). cursor and next_cursor already existed. I added limit to explorePage in src/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 inside q still gets the existing 400 unknown_filter, because existing tests and the MCP tool depend on that. A bad cursor is still 400 invalid_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=100 read.
  • Snapshot: the ranking was already kept for 60 s, so I added no new cache. docs/REFERENCE.md states 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.ts and test/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

Closes #12317

4 earlier comments · 1 event
commented

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: limit is an integer from 1 to 100, default 30 (the web page still shows 60). cursor and next_cursor already existed. I added limit to explorePage in src/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 inside q still gets the existing 400 unknown_filter, because existing tests and the MCP tool depend on that. A bad cursor is still 400 invalid_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=100 read.
  • Snapshot: the ranking was already kept for 60 s, so I added no new cache. docs/REFERENCE.md states 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.ts and test/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

commented

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.

commented

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/explore declared limit as a bare integer in the served contract. It now uses limitTo(100), so the document states 1 to 100, which is what the handler enforces. The change is in src/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=60 explicitly, so it still covers two pages over 70 apps.

Not touched:

  • Red on main too: first-screen-line, spawn-pipes, spawn-sites, mcp-table and did-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.

Changes requested — before the latest push

Two changes before this lands.

  1. 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 unparameterised kind=app read returns exactly 30 rows and a next_cursor. Box 1 depends on that default.
  1. 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: or sort: 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.

commented

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=app read must return exactly 30 rows and a string next_cursor, so a default of 60, 100 or none would fail it.
  • Docs: in docs/REFERENCE.md the terminal explore paragraph is whole again, and the "An unknown kind: or sort: word…" paragraph follows it. The GET /api/v1/explore parameters 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.

commented

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…", and render-subtitles-shift: "a writer's shift…") pass on this branch, alone and again after the merge. bun x tsc --noEmit is clean. explore.test.ts and explore-api-paging.test.ts also 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.md and the explore tests. Neither failing test goes near that endpoint. The check log itself says render-subtitles-shift is green on main at f18c0e5. 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.ts gave no output, so I can't say it passed. scripts/fast.ts reported 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.

Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs