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

/explore says what it did with a sort it does not know: ?sort=zzz renders the default with no word #14403

Merged opened this

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

Merged

scout/forge:scout/14392-explore-says-what-it-did-with-a-sort-it → main 4 commits fork 3 threads · 3 unresolved

  • Merged. scout/14392-explore-says-what-it-did-with-a-sort-it was merged into main as 282deda.

Review

Sign in to review this change.
14 files changed +239 −66
docs/REFERENCE.md +4 −3
@@ -375,9 +375,10 @@ the words it takes, on the page, in the terminal and in a `note` field of
375375 `cursor` (opaque: pass back the `next_cursor` of the page before; null on the
376376 last page), and answers `{ query, items, next_cursor }`. Rows order by the
377377 sort value, then kind and name, so tied scores never repeat or skip a row
378 across pages. A `sort`, `kind` or `limit` parameter that is unknown or not an
379 integer in range is a 422 `{ error: "invalid", field, message }` naming the
380 field (a word typed inside `q` is still a 400 `unknown_filter`); a cursor that
378 across pages. Any parameter that is unknown or out of range (`sort`, `kind`,
379 `since`, `updated`, `min_forks`, `limit`, …) is a 422
380 `{ error: "invalid", field, message }` naming the field and the allowed values
381 (a word typed inside `q` is a 422 `unknown_filter` with `field: "q"`); a cursor that
381382 is not one is `invalid_cursor` 400. A cursor is a position in one ranking
382383 snapshot, which the forge keeps for 60 seconds: scores that change between
383384 pages can move a row across the position, so a client that must see a stable
docs/features/explore.md +6 −6
@@ -39,7 +39,7 @@ A like is a `feed_like` row (one per person and post, `src/feed/likes.ts`). An a
3939
4040 In `score`, likes add `0.5 × ln(1 + likes)`, small next to forks (3) and ships (2). The weight is a constant in `explore.ts`, not one of the front page's admin weights.
4141
42 An unknown `sort:` word is a 400 naming the sorts above (see the end of this page).
42 An unknown `sort:` word is refused as every unknown value is: a 303 on the page, a 422 on the API (see the end of this page).
4343
4444 When an unknown `kind:`, `sort:`, `updated:` or `archived:` value is within edit distance 2 of a known one (and nearer than the value is long, so one or two characters of junk suggest nothing), the note ends with `Did you mean <a>sort:forks</a>?`, a link to the same view with that word mended (in the parameter form below, `/explore?sort=forks`). Only the first such word is mended per line; a word repeated is mended everywhere. `GET /api/v1/explore` and the MCP `explore` tool carry the same as `suggest` (`"garden sort:forks"`, the whole corrected line), absent when there is none. The terminal shows it as plain text under "Read as:". It is a pure function of the line: nothing is looked up.
4545
@@ -55,7 +55,7 @@ What a person filters on `/explore` an agent filters with the same words. Each f
5555 | Show archived | `archived=yes` | `?archived=yes` | `{ archived: "yes" }` |
5656 | (owner link on a row) | `owner=name` | `?owner=name` | `{ owner: "name" }` |
5757 | (type it) at least N forks by people | `forks=3` (0–1000) | `?forks=3` | `{ forks: "3" }` |
58 | (type it) the same floor, as shared links say it | `min_forks=3` (`forks=` wins when both are given); not a whole number from 0 to 1000 is `400` naming `min_forks`, on the page and the API | `?min_forks=3` | `{ min_forks: "3" }` |
58 | (type it) the same floor, as shared links say it | `min_forks=3` (`forks=` wins when both are given); not a whole number from 0 to 1000 is refused naming `min_forks`: a 303 on the page, a `422` on the API | `?min_forks=3` | `{ min_forks: "3" }` |
5959 | (type it) at least N merges in 30 days | `ships=1` (0–1000) | `?ships=1` | `{ ships: "1" }` |
6060 | (type it) awake in the last 30 days | `live=yes` (`no` is no filter) | `?live=yes` | `{ live: "yes" }` |
6161 | Mine (signed in, beside the kind tabs) | `mine=yes` (`no` is no filter) | `?mine=yes` | `{ mine: "yes" }` |
@@ -63,13 +63,13 @@ What a person filters on `/explore` an agent filters with the same words. Each f
6363
6464 The one line still works everywhere: `?q=kind:app sort:forks garden` and `{ q: "kind:app sort:forks garden" }` read the same as the separate parameters, and old `/explore?q=…` links keep working. When a parameter and the same key in `q` are both given, the parameter wins (`?q=sort:name&sort=forks` sorts by forks). A parameter's value is one word; one the explorer does not take is an unknown word like any typed in `q`, and is refused the same way (below). The terminal's search line takes only the line. It takes `forks:N`, `ships:N` and `live:yes` there too (`screens/dashboard.ts` reads the line with `readExploreLine`): `forks:1 live:no` leaves the rows the page leaves, and `forks:abc` or `live:maybe` is named under `Read as:` as `forks:abc is not a count`, `live:maybe is not an answer`.
6565
66 A bad `min_forks`, `since`, `updated` or `kind` parameter (`?since=9y`, `?kind=nope`) is `400` naming the parameter, on the page and the API alike (#14046): the API answers `{ "error": "invalid", "field": "since", "message": "since is not a window — use 1d, 7d, 30d" }`, and the page still draws the same sentence over the unfiltered list. The sentence names the parameter and never repeats the value. `since` is judged only when `updated` is not given, `min_forks` only when `forks` is not.
66 A bad `min_forks`, `since`, `updated` or `kind` parameter (`?since=9y`, `?kind=nope`) is refused naming the parameter (#14046, #14392): the API answers `422`: `{ "error": "invalid", "field": "since", "message": "since is not a window — use 1d, 7d, 30d" }`, and the page answers `303` to the same address without it, then draws the same sentence once over the unfiltered list. The sentence names the parameter and never repeats the value. `since` is judged only when `updated` is not given, `min_forks` only when `forks` is not.
6767
6868 The three return the same ordered rows (`test/explore-parity.test.ts`; the URL form in `test/explore-url.test.ts`).
6969
70 A `forks:` or `ships:` value that is not a whole number from 0 to 1000 (`abc`, `-1`, `1.5`, `1001`) and a `live:` that is not yes or no are unknown words like any other: `400` naming the word. Spawned forges carry no numbers, so any of the three leaves them out. The page's filter chips, `Drop` links and `Clear filters` carry the three words.
70 A `forks:` or `ships:` value that is not a whole number from 0 to 1000 (`abc`, `-1`, `1.5`, `1001`) and a `live:` that is not yes or no are unknown words like any other: refused naming the word (below). Spawned forges carry no numbers, so any of the three leaves them out. The page's filter chips, `Drop` links and `Clear filters` carry the three words.
7171
72 An unknown filter word is refused the same way everywhere: `400` from the API (`{ "error": "unknown_filter", "message": "sort:bogus is not a sort — use score, forks, …", "suggest"? }`), an `unknown_filter` error from the MCP tool, and `400` on the page, which still draws the note, the did-you-mean link and the results. This replaces the earlier note-only answer (#7595).
72 One rule for what `/explore` does not take (#14392): an unknown sort, kind, filter word, window, count or `page` is dropped, and said once. The page answers `303` to the address with it dropped (other parameters, tracking included, stay as they came) and the next page opens with one note and, when a word is near, the did-you-mean link; a `page` that is junk, zero or past the last says `page is not a page number` or `there is no page N — showing page M`. `GET /api/v1/explore` answers `422` for every one, naming the field and the allowed words: `{ "error": "invalid", "field": "sort", "message": "sort:bogus is not a sort — use score, forks, …" }` for a separate parameter, and for a word typed in `q` `{ "error": "unknown_filter", "field": "q", "message": …, "suggest"? }`. The MCP tool says the same words as an `unknown_filter` error. Known values are never redirected. Tests: `test/explore-unknown-params.test.ts`.
7373
7474 ## Mine (#13161)
7575
@@ -77,7 +77,7 @@ An unknown filter word is refused the same way everywhere: `400` from the API (`
7777
7878 ## Paging (#11376)
7979
80 A list holds 60 rows a page. When there are more, `/explore` ends with **Previous** and **Next** links around "Page N of M", plain links that keep kind, sort, since, owner, archived and the words and add `page=N` (page 1 has no `page`). `?page=2` is server-rendered and works without JavaScript. The page links say `rel="prev"` and `rel="next"`. An old `?cursor=` link shows the first page with one line saying the link is out of date. A `page` that is junk, zero or negative shows the first page, and one past the end shows the last, never an error. `GET /api/v1/explore` returns `next_cursor` and takes `?cursor=`, and the MCP `explore` tool takes and returns the same cursor.
80 A list holds 60 rows a page. When there are more, `/explore` ends with **Previous** and **Next** links around "Page N of M", plain links that keep kind, sort, since, owner, archived and the words and add `page=N` (page 1 has no `page`). `?page=2` is server-rendered and works without JavaScript. The page links say `rel="prev"` and `rel="next"`. An old `?cursor=` link shows the first page with one line saying the link is out of date. A `page` that is junk, zero or negative is a 303 to the first page, and one past the end to the last, each with its one-line note, never an error. `GET /api/v1/explore` returns `next_cursor` and takes `?cursor=`, and the MCP `explore` tool takes and returns the same cursor.
8181
8282 The terminal's explore lines page the same way: when the answer carries `next_cursor` the list ends with one line, `more results — n`, and `n` fetches the next page and appends it; the last page shows no line. The cursor is kept with the line it came from, so changing the line starts again at the first page. A cursor the forge refuses shows the first page with one plain line (`that page is no longer there — showing the first page`), never an error screen. A fetch that fails (not a refusal) keeps the pages already shown and says `could not fetch more results — n to retry`. The line takes the list's last row, so it shows on any terminal tall enough for a list.
8383
src/http/api.ts +6 −6
@@ -364,6 +364,7 @@ import {
364364 readExploreLine,
365365 exploreLineFrom,
366366 badExploreParam,
367 EXPLORE_PARAMS,
367368 } from "../actions/explore.ts";
368369 import { frontInput, frontJson, setFront } from "../actions/front.ts";
369370 import { COPIES_PER_DAY, makeItYours } from "../actions/make_it_yours.ts";
@@ -3658,9 +3659,8 @@ export function apiRoutes(router: Router<Handler>): void {
36583659 // Explore (#607): the rows /explore shows, for the same one line.
36593660 router.add("GET", "/api/v1/explore", async (ctx) => {
36603661 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
3661 // The separate `sort` and `limit` parameters are refused with 422 naming the
3662 // field; a bad `min_forks`, `since`, `updated` or `kind` with 400 naming it, as
3663 // the page does; a word typed in `q` keeps its 400 `unknown_filter`.
3662 // One rule: whatever the explorer does not take is 422, naming the field and the allowed
3663 // values: `limit`, a separate filter parameter, or a word typed in `q` (`unknown_filter`).
36643664 const limitRaw = ctx.url.searchParams.get("limit");
36653665 if (limitRaw !== null && !(/^\d{1,3}$/.test(limitRaw) && Number(limitRaw) >= 1 && Number(limitRaw) <= 100))
36663666 return json({ error: "invalid", field: "limit", message: "limit is an integer from 1 to 100" }, 422);
@@ -3668,17 +3668,17 @@ export function apiRoutes(router: Router<Handler>): void {
36683668 if (queryTooLong(ctx.url.searchParams.get("q")))
36693669 return json({ error: "invalid", field: "q", message: QUERY_TOO_LONG }, 422);
36703670 const refused = badExploreParam((name) => ctx.url.searchParams.get(name));
3671 if (refused !== null) return json({ error: "invalid", field: refused.field, message: refused.message }, 400);
3671 if (refused !== null) return json({ error: "invalid", field: refused.field, message: refused.message }, 422);
outdated

Only kind is 422; every other bad explore value stays 400. Make the whole refusal 422 (field + allowed values) so the API follows one rule, and test each.

36723672 const line = exploreLineFrom((name) => ctx.url.searchParams.get(name));
36733673 const { query, unknown } = readExploreLine(line);
3674 for (const field of ["sort"] as const) {
3674 for (const field of EXPLORE_PARAMS) {
36753675 const given = ctx.url.searchParams.get(field);
36763676 if (given !== null && given.trim() !== "" && unknown.some((w) => w.toLowerCase().startsWith(`${field}:`)))
36773677 return json({ error: "invalid", field, message: exploreNote(unknown) }, 422);
36783678 }
36793679 const suggest = exploreSuggestion(line);
36803680 if (unknown.length > 0)
3681 return json({ error: "unknown_filter", message: exploreNote(unknown), ...(suggest === undefined ? {} : { suggest: suggest.line }) }, 400);
3681 return json({ error: "unknown_filter", message: exploreNote(unknown), field: "q", ...(suggest === undefined ? {} : { suggest: suggest.line }) }, 422);
36823682 const mine = runRepos(ctx.app, ctx.auth);
36833683 // A run token is shown only the rows of its own repositories; the cut
36843684 // and the cursor are made from those rows alone.
src/web/studio/explore.ts +31 −9
@@ -14,6 +14,7 @@ import {
1414 exploreCount,
1515 exploreFiltered,
1616 exploreLineFrom,
17 EXPLORE_PARAMS,
1718 badExploreParam,
1819 exploreParams,
1920 exploreNote,
@@ -191,22 +192,47 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
191192 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
192193 const line = exploreLineFrom((name) => ctx.url.searchParams.get(name));
193194 const { query, unknown } = readExploreLine(line);
194 // A bad `min_forks`, `since`, `updated` or `kind` is refused with 400 naming the parameter;
195 // a bad word typed in `q` (or another parameter) keeps its noted 200.
195 // A bad `min_forks`, `since`, `updated` or `kind` is named by its parameter; any other word
196 // the line does not take is named as the word. Either way the note is said once, after a 303.
196197 const refused = badExploreParam((name) => ctx.url.searchParams.get(name));

refused and the 400 re-make branch below are now unreachable after the 303 (the builder says so). Remove the dead code here, not in a follow-up. Also an unknown page is not handled by the new rule (box 1).

197198 const note = refused?.message ?? exploreNote(unknown);
198199 const suggestion = exploreSuggestion(line);
200 // One rule for what the explorer does not take: 303 to the address with it dropped, the note
201 // said once as a flash. Other parameters (tracking, `page`) are left as they came.
202 if (unknown.length > 0) {
203 const to = new URL(ctx.url);
204 for (const key of [...EXPLORE_PARAMS, "min_forks", "since", "q"]) to.searchParams.delete(key);
205 for (const [k, v] of new URLSearchParams(exploreParams(query))) to.searchParams.set(k, v);
206 const text = to.searchParams.toString();
207 return redirect(text === "" ? "/explore" : `/explore?${text}`, {
208 url: ctx.url,
209 forgeUrl: ctx.app.config.url,
210 flash: {
211 tone: "attn",
212 message: note,
213 ...(suggestion === undefined ? {} : { link: { href: href(readExploreLine(suggestion.line).query), label: `Did you mean ${suggestion.fix}?` } }),
214 },
215 });
216 }
199217 const ranking = performance.now();
200218 const shown = await explorePageAt(ctx.app, ctx.auth.user, query, explorePageFrom((name) => ctx.url.searchParams.get(name)), undefined, true);
201219 // The address names the page shown: a `page` that is not it (past the last, zero, junk, or a
202 // redundant 1) answers 303 to the same address with the real page, none for page 1.
220 // redundant 1) answers 303 to the same address with the real page, none for page 1. Junk, zero
221 // and past the last say so once, in the same flash as any other word the page did not take.
203222 const asked = ctx.url.searchParams.get("page");
204223 if (asked !== null && !(shown.page > 1 && asked.trim() === String(shown.page))) {
205224 const to = new URL(ctx.url);
206225 if (shown.page > 1) to.searchParams.set("page", String(shown.page));
207226 else to.searchParams.delete("page");
208227 const text = to.searchParams.toString();
209 return redirect(text === "" ? "/explore" : `/explore?${text}`);
228 const digits = /^[0-9]{1,6}$/.test(asked.trim()) ? Number(asked.trim()) : 0;
229 const said =
230 digits === 0 && !/^0*1$/.test(asked.trim())
231 ? "page is not a page number — use a whole number from 1"
232 : digits > shown.pages
233 ? `there is no page ${digits} — showing page ${shown.pages}`
234 : undefined;
235 return redirect(text === "" ? "/explore" : `/explore?${text}`, said === undefined ? undefined : { url: ctx.url, forgeUrl: ctx.app.config.url, flash: { tone: "attn", message: said } });
210236 }
211237 const rows = shown.items;
212238 // Old `?cursor=` links were published; they cannot name a page now, so say so.
@@ -315,10 +341,6 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
315341 extra: "bare",
316342 })}${pager(query, shown.page, shown.pages)}</div>`;
317343 const drawn = page({ ctx, title: "Explore", description: "Public apps, forges and people on this forge, ranked by use, forks, deployments and recency.", body: compact(body), feed: { href: "/explore.atom", title: "Explore" } });
318 // A refused parameter still draws the whole page, the unfiltered list under the note naming
319 // it, so a person who followed a bad link lands somewhere usable; only the status says 400.
320 // The same response is re-made with that status, keeping the drawn headers (security floor,
321 // CSP nonce) as they are.
322344 notePhase(ctx.request, "render", performance.now() - rendering);
323 return refused === null ? drawn : new Response(drawn.body, { status: 400, headers: drawn.headers });
345 return drawn;
324346 }
test/explore-api-paging.test.ts +2 −2
@@ -100,9 +100,9 @@ describe("refusals", () => {
100100 test("limit 101", () => refused("limit=101", "limit"));
101101 test("an empty limit", () => refused("limit=", "limit"));
102102 test("an unknown sort", () => refused("sort=bogus", "sort"));
103 test("an unknown kind is a 400 naming kind, as the page (#14046)", async () => {
103 test("an unknown kind is a 422 naming kind, as the page (#14046)", async () => {
104104 const res = await get("kind=nope");
105 expect(res.status).toBe(400);
105 expect(res.status).toBe(422);
106106 expect(((await res.json()) as { field: string }).field).toBe("kind");
107107 });
108108 test("a cursor that is not one is still 400", async () => {
test/explore-parity.test.ts +8 −7
@@ -17,6 +17,7 @@ import { quietLogs } from "./helpers/globals.ts";
1717 import { proveAll } from "./helpers/verified.ts";
1818 import { promote } from "./helpers/members.ts";
1919 import { exploreParams, groupForks, readExploreLine, type ExploreRow } from "../src/actions/explore.ts";
20 import { seenFetch } from "./helpers/explore_seen.ts";
2021 /** The href the page gives a line: separate parameters, `&` escaped as in markup. */
2122 const linkOf = (line: string): string => `/explore?${exploreParams(readExploreLine(line).query)}`.replace(/&/g, "&amp;");
2223
@@ -234,17 +235,17 @@ describe("one filter, three surfaces", () => {
234235 expect(html).toContain("data-clear-filters");
235236 });
236237
237 test("a junk, negative or huge number is a 400 naming the word on the API, the MCP and the page", async () => {
238 test("a junk, negative or huge number is a 422 naming the word on the API, the MCP and the page", async () => {
238239 for (const bad of ["forks:abc", "ships:-1", "forks:1001", "ships:1.5", "live:maybe"]) {
239240 const api = await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent(bad)}`);
240 expect(api.status).toBe(400);
241 expect(api.status).toBe(422);
241242 const body = (await api.json()) as { error: string; message: string };
242243 expect(body.error).toBe("unknown_filter");
243244 expect(body.message).toContain(bad);
244245 const tool = await mcp(bad);
245246 expect(tool.ok).toBe(false);
246247 expect(tool.text).toContain(bad);
247 const page = await fetch(`${servers.url}/explore?q=${encodeURIComponent(bad)}`);
248 const page = await seenFetch(`${servers.url}/explore?q=${encodeURIComponent(bad)}`);
248249 expect(await page.text()).toContain(bad);
249250 }
250251 expect((await fetch(`${servers.url}/api/v1/explore?q=forks:1000`)).status).toBe(200);
@@ -282,21 +283,21 @@ describe("one filter, three surfaces", () => {
282283 }
283284 });
284285
285 test("an unknown filter is a 400 naming the allowed words on the API and the MCP; the page answers 200 with the note", async () => {
286 test("an unknown filter is a 422 naming the allowed words on the API and the MCP; the page answers 200 with the note", async () => {
286287 const q = encodeURIComponent("sort:bogus");
287288 const api = await fetch(`${servers.url}/api/v1/explore?q=${q}`);
288 expect(api.status).toBe(400);
289 expect(api.status).toBe(422);
289290 const body = (await api.json()) as { error: string; message: string };
290291 expect(body.error).toBe("unknown_filter");
291292 expect(body.message).toContain("use score, forks, ships, likes, use, fresh, new, name");
292293 const tool = await mcp("sort:bogus");
293294 expect(tool.ok).toBe(false);
294295 expect(tool.text).toContain("use score, forks, ships, likes, use, fresh, new, name");
295 const page = await fetch(`${servers.url}/explore?q=${q}`);
296 const page = await seenFetch(`${servers.url}/explore?q=${q}`);
296297 expect(page.status).toBe(200);
297298 expect(await page.text()).toContain("use score, forks, ships, likes, use, fresh, new, name");
298299 for (const bad of ["kind:x", "updated:2y", "archived:maybe"]) {
299 expect((await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent(bad)}`)).status).toBe(400);
300 expect((await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent(bad)}`)).status).toBe(422);
300301 }
301302 });
302303 });
test/explore-since.test.ts +4 −3
@@ -12,6 +12,7 @@ import { serve, type Servers } from "../src/http/server.ts";
1212 import { quietLogs } from "./helpers/globals.ts";
1313 import { proveAll } from "./helpers/verified.ts";
1414 import { promote } from "./helpers/members.ts";
15 import { seenFetch } from "./helpers/explore_seen.ts";
1516
1617 quietLogs();
1718 let dir: string;
@@ -76,9 +77,9 @@ test("since=7d and since=30d keep exactly the apps changed inside the window", a
7677 expect(rows(await get("?kind=app&owner=pine&since=30d&sort=name"))).toEqual(["/pine/fresh", "/pine/stale"]);
7778 });
7879
79 test("an unknown since is a 400 with a note, and the list is whole (#14046)", async () => {
80 const res = await fetch(`${servers.url}/explore?kind=app&owner=pine&since=9y`);
81 expect(res.status).toBe(400);
80 test("an unknown since is a 303 to the address without it, then a 200 with a note, and the list is whole (#14046)", async () => {
81 const res = await seenFetch(`${servers.url}/explore?kind=app&owner=pine&since=9y`);
82 expect(res.status).toBe(200);
8283 const html = await res.text();
8384 expect(rows(html).length).toBe(3);
8485 expect(html).toContain("1d, 7d, 30d");
test/explore-sort.test.ts +2 −1
@@ -12,6 +12,7 @@ import { serve, type Servers } from "../src/http/server.ts";
1212 import { quietLogs } from "./helpers/globals.ts";
1313 import { proveAll } from "./helpers/verified.ts";
1414 import { promote } from "./helpers/members.ts";
15 import { seenFetch } from "./helpers/explore_seen.ts";
1516
1617 quietLogs();
1718 const DAY = 86_400_000;
@@ -56,7 +57,7 @@ afterAll(async () => {
5657 });
5758
5859 const get = async (qs: string) => {
59 const res = await fetch(`${servers.url}/explore${qs}`);
60 const res = await seenFetch(`${servers.url}/explore${qs}`);
6061 return { status: res.status, html: await res.text() };
6162 };
6263 const listed = (html: string): string[] => {
test/explore-unknown-params.test.ts added +124
@@ -0,0 +1,124 @@
1 /**
2 * One rule for what /explore does not take (#14392): the page answers 303 to the address with it
3 * dropped and says so once; the API answers 422 naming the field; the MCP tool says the same words.
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { createApp, type App } from "../src/app.ts";
10 import { serve, type Servers } from "../src/http/server.ts";
11 import { quietLogs } from "./helpers/globals.ts";
12 import { seenFetch } from "./helpers/explore_seen.ts";
13
14 quietLogs();
15 let dir: string;
16 let app: App;
17 let servers: Servers;
18 beforeAll(async () => {
19 dir = await mkdtemp(join(tmpdir(), "forge-explore-params-"));
20 app = createApp({ dataDir: dir, port: 0 });
21 servers = await serve(app);
22 });
23 afterAll(async () => {
24 await servers.stop();
25 app.db.close();
26 await rm(dir, { recursive: true, force: true });
27 });
28
29 const WORDS = "score, forks, ships, likes, use, fresh, new, name";
30
31 test("page: ?sort=zzz is a 303 to the clean address, and the next page says why once", async () => {
32 const res = await fetch(`${servers.url}/explore?sort=zzz&kind=app&utm_source=x`, { redirect: "manual" });
33 expect(res.status).toBe(303);
34 expect(res.headers.get("location")).toBe("/explore?utm_source=x&kind=app");
35 const cookie = res.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
36 const next = await fetch(new URL(res.headers.get("location")!, servers.url), { headers: { cookie } });
37 expect(next.status).toBe(200);
38 const body = await next.text();
39 expect(body).toContain(`sort:zzz is not a sort — use ${WORDS}`);
40 expect(body.split("is not a sort").length).toBe(2);
41 });
42
43 test("page: an unknown kind or a typed word is dropped the same way; known ones are left alone", async () => {
44 const kind = await fetch(`${servers.url}/explore?kind=nope`, { redirect: "manual" });
45 expect(kind.status).toBe(303);
46 expect(kind.headers.get("location")).toBe("/explore");
47 const typed = await fetch(`${servers.url}/explore?q=${encodeURIComponent("garden sort:zzz")}`, { redirect: "manual" });
48 expect(typed.headers.get("location")).toBe("/explore?q=garden");
49 expect((await fetch(`${servers.url}/explore?sort=forks`, { redirect: "manual" })).status).toBe(200);
50 });
51
52 test("api: an unknown sort is 422 naming the field and the allowed values", async () => {
53 const res = await fetch(`${servers.url}/api/v1/explore?sort=zzz`);
54 expect(res.status).toBe(422);
55 const body = (await res.json()) as { field: string; message: string };
56 expect(body.field).toBe("sort");
57 expect(body.message).toContain(WORDS);
58 });
59
60 test("api: an unknown kind is 422 too, as for sort and limit", async () => {
61 const res = await fetch(`${servers.url}/api/v1/explore?kind=nope`);
62 expect(res.status).toBe(422);
63 const body = (await res.json()) as { field: string; message: string };
64 expect(body.field).toBe("kind");
65 expect(body.message).toContain("app, person, forge");
66 });
67
68 test("page: an unknown page is a 303 to the address with the real page, and says so once", async () => {
69 const junk = await fetch(`${servers.url}/explore?page=abc&kind=app`, { redirect: "manual" });
70 expect(junk.status).toBe(303);
71 expect(junk.headers.get("location")).toBe("/explore?kind=app");
72 const body = await (await seenFetch(`${servers.url}/explore?page=abc`)).text();
73 expect(body).toContain("page is not a page number");
74 expect(body.split("is not a page number").length).toBe(2);
75 const past = await (await seenFetch(`${servers.url}/explore?page=99`)).text();
76 expect(past).toContain("there is no page 99 — showing page 1");
77 // A redundant 1 is mended without a note; the first page asked for plainly is left alone.
78 const one = await seenFetch(`${servers.url}/explore?page=1`);
79 expect(one.status).toBe(200);
80 expect(await one.text()).not.toContain("is not a page number");
81 expect((await fetch(`${servers.url}/explore`, { redirect: "manual" })).status).toBe(200);
82 });
83
84 test("page: a known since, min_forks, updated or kind is left alone, no redirect", async () => {
85 for (const qs of ["since=7d", "updated=30d", "min_forks=1", "kind=person", "since=7d&min_forks=2&kind=app"]) {
86 const res = await fetch(`${servers.url}/explore?${qs}`, { redirect: "manual" });
87 expect(res.status).toBe(200);
88 }
89 });
90
91 test("api: every unknown value is 422 naming the field and the allowed values", async () => {
92 const cases: [string, string, string][] = [
93 ["since=9y", "since", "1d, 7d, 30d"],
94 ["updated=9y", "updated", "1d, 7d, 30d"],
95 ["min_forks=abc", "min_forks", "whole number from 0 to 1000"],
96 ["owner=a/b", "owner", "is not a name"],
97 ["archived=maybe", "archived", "yes, no"],
98 ["q=sort:zzz", "q", WORDS],
99 ];
100 for (const [qs, field, words] of cases) {
101 const res = await fetch(`${servers.url}/api/v1/explore?${qs}`);
102 expect(res.status).toBe(422);
103 const body = (await res.json()) as { field: string; message: string };
104 expect(body.field).toBe(field);
105 expect(body.message).toContain(words);
106 }
107 for (const qs of ["since=7d", "min_forks=1", "updated=30d"])
108 expect((await fetch(`${servers.url}/api/v1/explore?${qs}`)).status).toBe(200);
109 });
110
111 test("mcp: the explore tool says the same words", async () => {
112 const res = await fetch(`${servers.url}/mcp`, {
113 method: "POST",
114 headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
115 body: JSON.stringify({
116 jsonrpc: "2.0",
117 id: 1,
118 method: "tools/call",
119 params: { name: "explore", arguments: { sort: "zzz" } },
120 }),
121 });
122 const out = await res.json();
123 expect(JSON.stringify(out)).toContain(`sort:zzz is not a sort — use ${WORDS}`);
124 });
test/explore-unknown-words.test.ts +18 −10
@@ -19,6 +19,14 @@ const linkOf = (line: string): string => `/explore?${exploreParams(readExploreLi
1919
2020 quietLogs();
2121
22 /** A page as a browser gets it: the 303 followed with the flash cookie it set. */
23 async function seen(url: string): Promise<string> {
24 const first = await fetch(url, { redirect: "manual" });
25 if (first.status !== 303) return await first.text();
26 const cookie = first.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
27 return await (await fetch(new URL(first.headers.get("location")!, url), { headers: { cookie } })).text();
28 }
29
2230 describe("readExploreLine", () => {
2331 test("an unknown sort and an unknown kind are returned, and left out of the query", () => {
2432 const read = readExploreLine("sort:bogus kind:nope garden");
@@ -66,7 +74,7 @@ describe("readExploreLine", () => {
6674 try {
6775 const q = encodeURIComponent("owner:trevato updated:2y archived:maybe");
6876 const res = await fetch(`${s.url}/api/v1/explore?q=${q}`);
69 expect(res.status).toBe(400);
77 expect(res.status).toBe(422);
7078 const body = (await res.json()) as { message: string };
7179 expect(body.message).toBe("updated:2y is not a window — use 1d, 7d, 30d; archived:maybe is not an answer — use yes, no");
7280 } finally {
@@ -104,7 +112,7 @@ describe("the page and the API", () => {
104112
105113 test("the page says it once and the filter links drop the word", async () => {
106114 const q = encodeURIComponent("sort:bogus garden");
107 const out = await (await fetch(`${servers.url}/explore?q=${q}`)).text();
115 const out = await seen(`${servers.url}/explore?q=${q}`);
108116 expect(out.split("is not a sort").length).toBe(2);
109117 expect(out).toContain("sort:bogus is not a sort — use score, forks, ships, likes, use, fresh, new, name");
110118 expect(out).not.toContain(encodeURIComponent("sort:bogus"));
@@ -112,7 +120,7 @@ describe("the page and the API", () => {
112120 });
113121
114122 test("the page says an updated:, archived: or owner: word once, escaped", async () => {
115 const page = async (q: string) => await (await fetch(`${servers.url}/explore?q=${encodeURIComponent(q)}`)).text();
123 const page = async (q: string) => await seen(`${servers.url}/explore?q=${encodeURIComponent(q)}`);
116124 expect(await page("updated:2y")).toContain("updated:2y is not a window — use 1d, 7d, 30d");
117125 expect(await page("archived:maybe")).toContain("archived:maybe is not an answer — use yes, no");
118126 const out = await page("owner:<b>");
@@ -121,19 +129,19 @@ describe("the page and the API", () => {
121129 });
122130
123131 test("a known word draws no note", async () => {
124 const out = await (await fetch(`${servers.url}/explore?q=${encodeURIComponent("sort:forks")}`)).text();
132 const out = await seen(`${servers.url}/explore?q=${encodeURIComponent("sort:forks")}`);
125133 expect(out).not.toContain("is not a");
126134 });
127135
128136 test("the note is escaped", async () => {
129 const out = await (await fetch(`${servers.url}/explore?q=${encodeURIComponent("sort:<b>")}`)).text();
137 const out = await seen(`${servers.url}/explore?q=${encodeURIComponent("sort:<b>")}`);
130138 expect(out).toContain("sort:&lt;b&gt; is not a sort");
131139 expect(out).not.toContain("<b>");
132140 });
133141
134 test("the API answers 400 naming the allowed words (#10387)", async () => {
142 test("the API answers 422 naming the allowed words (#10387)", async () => {
135143 const res = await fetch(`${servers.url}/api/v1/explore?q=${encodeURIComponent("kind:nope")}`);
136 expect(res.status).toBe(400);
144 expect(res.status).toBe(422);
137145 const body = (await res.json()) as { error: string; message: string };
138146 expect(body.error).toBe("unknown_filter");
139147 expect(body.message).toContain("kind:nope is not a kind — use app, person, forge");
@@ -199,13 +207,13 @@ describe("did you mean", () => {
199207 const s = await serve(a);
200208 try {
201209 const q = encodeURIComponent("garden sort:froks");
202 const html = await (await fetch(`${s.url}/explore?q=${q}`)).text();
203 expect(html).toContain(`Did you mean <a href="${linkOf("garden sort:forks")}">sort:forks</a>?`);
210 const html = await seen(`${s.url}/explore?q=${q}`);
211 expect(html).toContain(`<a href="${linkOf("garden sort:forks")}">Did you mean sort:forks?</a>`);
204212 const api = (await (await fetch(`${s.url}/api/v1/explore?q=${q}`)).json()) as { suggest?: string };
205213 expect(api.suggest).toBe("garden sort:forks");
206214 const none = (await (await fetch(`${s.url}/api/v1/explore?q=sort:zzzzzzzz`)).json()) as { suggest?: string };
207215 expect(none.suggest).toBeUndefined();
208 const evil = await (await fetch(`${s.url}/explore?q=${encodeURIComponent("sort:<script>")}`)).text();
216 const evil = await seen(`${s.url}/explore?q=${encodeURIComponent("sort:<script>")}`);
209217 expect(evil).not.toContain("<script>");
210218 expect(evil).toContain("sort:&lt;script&gt; is not a sort");
211219 const { tool } = await import("../src/http/mcp/tools/explore.ts");
test/explore-url-filters.test.ts +4 −3
@@ -16,6 +16,7 @@ import { serve, type Servers } from "../src/http/server.ts";
1616 import { quietLogs } from "./helpers/globals.ts";
1717 import { proveAll } from "./helpers/verified.ts";
1818 import { promote } from "./helpers/members.ts";
19 import { seenFetch } from "./helpers/explore_seen.ts";
1920
2021 quietLogs();
2122 let dir: string;
@@ -51,7 +52,7 @@ afterAll(async () => {
5152 });
5253
5354 const get = async (path: string, cookie = "") => {
54 const res = await fetch(`${servers.url}${path}`, { headers: cookie === "" ? {} : { cookie } });
55 const res = await seenFetch(`${servers.url}${path}`, { headers: cookie === "" ? {} : { cookie } });
5556 return { status: res.status, html: await res.text() };
5657 };
5758 const listed = (html: string): string[] => {
@@ -95,9 +96,9 @@ test("a link with three filters renders the same rows as choosing them by hand",
9596 expect((await get("/explore?kind=app")).html).not.toContain(">Mine<");
9697 });
9798
98 test("an unknown filter value is ignored with a one-line note, never a 500 (a bad kind or since is a 400, #14046)", async () => {
99 test("an unknown filter value is ignored with a one-line note, never a 500 (a 303 to the address without it, then a 200, #14046)", async () => {
99100 const plain = listed((await get("/explore", olive)).html);
100 for (const [qs, status] of [["?mine=maybe", 200], ["?kind=zzz", 400], ["?sort=zzz", 200], ["?since=9y", 400]] as const) {
101 for (const [qs, status] of [["?mine=maybe", 200], ["?kind=zzz", 200], ["?sort=zzz", 200], ["?since=9y", 200]] as const) {
101102 const res = await get(`/explore${qs}`, olive);
102103 expect(res.status).toBe(status);
103104 expect(res.html).toContain('role="status"');
test/explore-url.test.ts +16 −15
@@ -13,6 +13,7 @@ import { quietLogs } from "./helpers/globals.ts";
1313 import { proveAll } from "./helpers/verified.ts";
1414 import { expectWork, requestStatements } from "./helpers/work.ts";
1515 import { promote } from "./helpers/members.ts";
16 import { seenFetch } from "./helpers/explore_seen.ts";
1617
1718 quietLogs();
1819 let dir: string;
@@ -43,7 +44,7 @@ afterAll(async () => {
4344 });
4445
4546 const page = async (qs: string) => {
46 const res = await fetch(`${servers.url}/explore${qs}`);
47 const res = await seenFetch(`${servers.url}/explore${qs}`);
4748 return { status: res.status, html: await res.text() };
4849 };
4950 const listed = (html: string): string[] => {
@@ -78,11 +79,11 @@ test("an unknown parameter is ignored; an invalid value is named and the default
7879 expect(listed(bad.html)).toEqual(listed(plain.html));
7980 });
8081
81 // Was a 200 for every bad value (#11819); #14046 makes a bad kind, updated or since a 400 naming
82 // the parameter. The page under it is the same: the note and the unfiltered list, escaped.
83 test("an unknown sort is a 200, an unknown kind or updated a 400, each with a plain note and the unfiltered list, escaped (#11819, #14046)", async () => {
82 // Was a 200 for every bad value (#11819); #14046 names the parameter; #14392 answers a 303 to the
83 // address without it. The page under it is the same: the note and the unfiltered list, escaped.
84 test("an unknown sort, kind or updated is a 303 to the address without it, then a 200 with a plain note and the unfiltered list, escaped (#11819, #14046)", async () => {
8485 const plain = listed((await page("")).html);
85 for (const [qs, status] of [["?kind=bogus", 400], ["?sort=bogus", 200], ["?updated=9y", 400], ["?since=9y", 400], [`?kind=${encodeURIComponent("<script>x</script>")}`, 400]] as const) {
86 for (const [qs, status] of [["?kind=bogus", 200], ["?sort=bogus", 200], ["?updated=9y", 200], ["?since=9y", 200], [`?kind=${encodeURIComponent("<script>x</script>")}`, 200]] as const) {
8687 const res = await page(qs);
8788 expect(res.status).toBe(status);
8889 expect(res.html).toContain('role="status"');
@@ -106,13 +107,13 @@ test("the chips link with separate parameters", async () => {
106107 expect(exploreParams(readExploreLine("kind:app sort:forks owner:olive garden").query)).toBe("kind=app&sort=forks&owner=olive&q=garden");
107108 });
108109
109 test("`since` is the `updated` window: same line, bad value is a noted 400 (#11232, #14046)", async () => {
110 test("`since` is the `updated` window: same line, bad value is a 303 then a noted 200 (#11232, #14046)", async () => {
110111 expect(exploreLineFrom((n) => (n === "since" ? "7d" : null))).toBe("updated:7d");
111112 expect(exploreLineFrom((n) => (n === "since" ? "9y" : null))).toBe("updated:9y");
112 const ok = await fetch(`${servers.url}/explore?kind=app&since=7d`);
113 const ok = await fetch(`${servers.url}/explore?kind=app&since=7d`, { redirect: "manual" });
113114 expect(ok.status).toBe(200);
114 const bad = await fetch(`${servers.url}/explore?since=9y`);
115 expect(bad.status).toBe(400);
115 const bad = await seenFetch(`${servers.url}/explore?since=9y`);
116 expect(bad.status).toBe(200);
116117 expect(await bad.text()).toContain("1d, 7d, 30d");
117118 });
118119
@@ -162,7 +163,7 @@ test("active filters show as a chip row whose removes are links, escaped (#11819
162163 expect(hostile.html).not.toContain("<img src=x");
163164 });
164165
165 test("since, updated and kind: a bad one is a 400 naming the parameter, on the page and the API (#14046)", async () => {
166 test("since, updated and kind: a bad one is a 303 then a noted 200 on the page, a 422 naming the parameter on the API (#14046)", async () => {
166167 const plain = listed((await page("")).html);
167168 for (const [qs, field, words] of [
168169 ["since=9y", "since", "since is not a window"],
@@ -171,12 +172,12 @@ test("since, updated and kind: a bad one is a 400 naming the parameter, on the p
171172 ["kind=app&since=1y", "since", "since is not a window"],
172173 ] as const) {
173174 const res = await page(`?${qs}`);
174 expect(res.status).toBe(400);
175 expect(res.status).toBe(200);

Assertions were loosened to match the new behaviour (e.g. is not a count instead of min_forks is not a count) and titles still say 400. Keep the specific words and update the titles.

175176 expect(res.html).toContain(words);
176177 // The bad parameter never narrows; a good one beside it still does.
177178 expect(listed(res.html)).toEqual(qs.startsWith("kind=app&") ? listed((await page("?kind=app")).html) : plain);
178179 const api = await fetch(`${servers.url}/api/v1/explore?${qs}`);
179 expect(api.status).toBe(400);
180 expect(api.status).toBe(422);
180181 expect((await api.json()) as unknown).toMatchObject({ error: "invalid", field });
181182 }
182183 // A good value, any case, still narrows; `updated` wins over `since`, which is then not judged.
@@ -186,17 +187,17 @@ test("since, updated and kind: a bad one is a 400 naming the parameter, on the p
186187 }
187188 });
188189
189 test("min_forks narrows the page and the API; a bad one is a 400 naming min_forks (#14046)", async () => {
190 test("min_forks narrows the page and the API; a bad one is a 303, a noted 200 and a 422 naming min_forks (#14046)", async () => {
190191 const plain = listed((await page("")).html);
191192 const ok = await page("?min_forks=1&kind=app");
192193 expect(ok.status).toBe(200);
193194 expect(listed(ok.html).length).toBeLessThan(plain.length);
194195 for (const bad of ["abc", "-1", "1001"]) {
195196 const res = await page(`?min_forks=${bad}`);
196 expect(res.status).toBe(400);
197 expect(res.status).toBe(200);
197198 expect(res.html).toContain("min_forks is not a count");
198199 const api = await fetch(`${servers.url}/api/v1/explore?min_forks=${bad}`);
199 expect(api.status).toBe(400);
200 expect(api.status).toBe(422);
200201 expect(((await api.json()) as { field: string }).field).toBe("min_forks");
201202 }
202203 expect((await fetch(`${servers.url}/api/v1/explore?min_forks=0`)).status).toBe(200);
test/explore.test.ts +2 −1
@@ -23,6 +23,7 @@ import { quietLogs } from "./helpers/globals.ts";
2323 import { proveAll } from "./helpers/verified.ts";
2424 import { promote } from "./helpers/members.ts";
2525 import { exploreParams, readExploreLine } from "../src/actions/explore.ts";
26 import { seenFetch } from "./helpers/explore_seen.ts";
2627 /** The href the page gives a line: separate parameters, `&` escaped as in markup. */
2728 const linkOf = (line: string): string => `/explore?${exploreParams(readExploreLine(line).query)}`.replace(/&/g, "&amp;");
2829
@@ -281,7 +282,7 @@ describe("explore", () => {
281282 });
282283
283284 test("a hostile owner stays escaped text on the page", async () => {
284 const page = await (await fetch(`${base}/explore?q=${encodeURIComponent("owner:<script>alert(1)</script>")}`)).text();
285 const page = await (await seenFetch(`${base}/explore?q=${encodeURIComponent("owner:<script>alert(1)</script>")}`)).text();
285286 expect(page).not.toContain("<script>alert(1)");
286287 expect(page).toContain("&lt;script&gt;alert(1)");
287288 });
test/helpers/explore_seen.ts added +12
@@ -0,0 +1,12 @@
1 /**
2 * A page as a browser gets it: one 303 followed, carrying the flash cookie the redirect set
3 * (/explore says what it dropped there, #14392). Anything else is returned as it came.
4 */
5 export async function seenFetch(url: string, init: RequestInit = {}): Promise<Response> {
6 const first = await fetch(url, { ...init, redirect: "manual" });
7 if (first.status !== 303) return first;
8 const flash = first.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
9 const headers = new Headers(init.headers);
10 headers.set("cookie", [headers.get("cookie"), flash].filter((c) => c).join("; "));
11 return await fetch(new URL(first.headers.get("location")!, url), { ...init, headers });
12 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs