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

The issue list refuses query parameters it does not read, and accepts labels= and milestone= #14816

Merged opened this in answer to

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

Merged

scout/forge:scout/14793-the-issue-list-refuses-query-parameters → main 8 commits fork

  • Merged. scout/14793-the-issue-list-refuses-query-parameters was merged into main as 7373235.

Review

Sign in to review this change.
10 files changed +257 −11
docs/features/api-list-filters.md added +22
@@ -0,0 +1,22 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: labels= and milestone=: filter the issue and pull lists, and a parameter they do not read is a 422
4 ---
5 # labels= and milestone=: filter the issue and pull lists
6
7 The issue list (`GET /api/v1/repos/OWNER/NAME/issues`) and the pull list (`…/pulls`) read a fixed set of query parameters, and refuse any other.
8
9 ```
10 GET /api/v1/repos/OWNER/NAME/issues?labels=P0%20Trust,bug
11 GET /api/v1/repos/OWNER/NAME/issues?milestone=731&state=all
12 GET /api/v1/repos/OWNER/NAME/pulls?labels=bug
13 ```
14
15 - **`labels=a,b`** keeps the items carrying every label named (AND), each by name (case-insensitive) or id. It works on both lists and combines with `label=`, `author=` and `state=`. More than 20 names is a 422 `invalid_labels`.
16 - **`milestone=N`** (issues only) keeps the issues beneath issue N: everything it waits for, directly or through others. This is the tree the milestone page counts. The walk never passes through the plan's furniture (pillar umbrellas, the Later umbrella, the gate), and the sealed scope still applies to what it finds.
17 - **`milestone=` refuses** with a 422 `invalid_milestone` when N is not a whole number, is not an issue of this repository the caller can see (a pull's number included), or is the **Later umbrella or the Later gate**. The plan counts as Later everything that waits behind the gate, which runs the other way through the graph from Later's own links, so a walk of Later's links would come up short of the plan. Read deferred work from `GET /api/v1/repos/OWNER/NAME/map` instead.
18 - **Any other parameter is a 422 `unknown_parameter`.** Its `message` names what the list does not read, and `accepted` lists what it does: `state, label, labels, author, cursor, limit`, plus `fields, milestone` on the issue list. `fields=a,b` (see [fields](api-fields.md)) is read before this check, on both lists.
19
20 **This breaks clients that send extra parameters.** Before, the forge ignored a parameter it did not read. A typo such as `?lables=bug`, or a filter the forge does not have such as `?milestone=` on pulls, returned the whole list as if it were filtered. Now the same request is a 422. A client that adds its own parameters (a cache-buster such as `?_=123`, tracking tags) must drop them for these two lists. `?page=` and `?offset=` keep their own 400 `invalid_query` (see [the API reference](api-reference.md)).
21
22 Code: `listQuery` in `src/http/api.ts` (the accepted names, `labels`), `milestoneScope` in `src/http/api/issues.ts`, and the `labels`/`beneath` filters of `listIssues` in `src/core/issues.ts`. Tests: `test/api-list-query.test.ts`.
src/contract/openapi/routes/getApiV1ReposOwnerNameIssues.ts +1 −1
@@ -1,3 +1,3 @@
11 import { ISSUE_ITEM_KEYS, LIST_QUERY, REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: `${REPO}/issues`, summary: "List a repository's issues", detail: "List a repository's issues; the repository's standing direction issue carries standing: true and is the one open issue counts.openIssues leaves out; fields=brief leaves out bodies and comments, any other fields value is a 422 invalid_fields; the 200 carries a weak etag of the page and cache-control private, no-cache (it varies by reader), and a repeat sending If-None-Match gets 304 with no body", auth: false, role: "anonymous", alsoStatus: [304], itemKeys: ISSUE_ITEM_KEYS, query: { ...LIST_QUERY, fields: "string" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)", invalid_state: "state is not open, closed or all (422)" }, refuses: [404] };
3 export const route: Route = { method: "get", path: `${REPO}/issues`, summary: "List a repository's issues", detail: "List a repository's issues; the repository's standing direction issue carries standing: true and is the one open issue counts.openIssues leaves out; fields=brief leaves out bodies and comments, any other fields value is a 422 invalid_fields; the 200 carries a weak etag of the page and cache-control private, no-cache (it varies by reader), and a repeat sending If-None-Match gets 304 with no body; milestone=N lists the tree beneath issue N, refusing the Later umbrella and gate, whose deferred count is the map's; labels=a,b keeps issues carrying every one", auth: false, role: "anonymous", alsoStatus: [304], itemKeys: ISSUE_ITEM_KEYS, query: { ...LIST_QUERY, fields: "string", milestone: "integer" }, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)", invalid_state: "state is not open, closed or all (422)", unknown_parameter: "a parameter this list does not read (422)", invalid_labels: "over 20 labels (422)", invalid_milestone: "milestone is not an issue of this repository the caller can see, or is the Later umbrella or gate (422)" }, refuses: [404] };
src/contract/openapi/routes/getApiV1ReposOwnerNamePulls.ts +1 −1
@@ -1,3 +1,3 @@
11 import { ISSUE_ITEM_KEYS, LIST_QUERY, REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: `${REPO}/pulls`, summary: "List a repository's pulls", detail: "List a repository's pulls; carries a weak `etag` of the page sent (cache-control private, no-cache; vary authorization, cookie), and a repeat sending If-None-Match gets 304 with no body until a pull in the page is opened, pushed to, checked, merged or closed", auth: false, role: "anonymous", alsoStatus: [304], itemKeys: [...ISSUE_ITEM_KEYS, "baseBranch", "headBranch", "baseOid", "headOid", "mergedAt", "mergedOid", "headRepoId", "crossRepo", "originHeadRepo", "revertsPullId", "variantGroup", "author", "check", "preview", "variantSiblings", "mergeable", "conflicts"], query: LIST_QUERY, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)", invalid_state: "state is not open, closed or all (422)" }, refuses: [404] };
3 export const route: Route = { method: "get", path: `${REPO}/pulls`, summary: "List a repository's pulls", detail: "List a repository's pulls; carries a weak `etag` of the page sent (cache-control private, no-cache; vary authorization, cookie), and a repeat sending If-None-Match gets 304 with no body until a pull in the page is opened, pushed to, checked, merged or closed", auth: false, role: "anonymous", alsoStatus: [304], itemKeys: [...ISSUE_ITEM_KEYS, "baseBranch", "headBranch", "baseOid", "headOid", "mergedAt", "mergedOid", "headRepoId", "crossRepo", "originHeadRepo", "revertsPullId", "variantGroup", "author", "check", "preview", "variantSiblings", "mergeable", "conflicts"], query: LIST_QUERY, refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)", invalid_cursor: "cursor is not the next_cursor of a previous page (422)", invalid_state: "state is not open, closed or all (422)", unknown_parameter: "a parameter this list does not read (422)", invalid_labels: "over 20 labels (422)" }, refuses: [404] };
src/contract/openapi/shared.ts +1 −1
@@ -96,7 +96,7 @@ export const REPO_LIST_SHAPES: Readonly<Record<string, ReplyShape>> = {
9696 };
9797
9898 /** What `listQuery` in `http/api.ts` reads from a list of issues or pulls. */
99 export const LIST_QUERY = { state: "string", limit: limitTo(LIST_LIMIT_MAX), cursor: "integer", label: "string", author: "string" };
99 export const LIST_QUERY = { state: "string", limit: limitTo(LIST_LIMIT_MAX), cursor: "integer", label: "string", labels: "string", author: "string" };
100100
101101 /** What the label routes for issues and pulls refuse by stable `error` code. */
102102 export const LABEL_REFUSALS = {
src/core/issues.ts +25 −2
@@ -471,6 +471,14 @@ export interface ListIssuesOptions {
471471 kind?: IssueKind;
472472 /** Only issues carrying this label (by name, case-insensitive, or id). */
473473 label?: string;
474 /** Only issues carrying every one of these labels (each by name or id). */
475 labels?: readonly string[];
476 /**
477 * Only issues beneath this milestone (`milestones.ts`): everything the
478 * root waits for, directly or through others, never walking into the
479 * plan's furniture (`structuralIds`).
480 */
481 beneath?: { readonly rootId: string; readonly furniture: readonly string[] };
474482 /** Only issues opened by this username. */
475483 author?: string;
476484 /** Only issues assigned to this username. */
@@ -526,14 +534,29 @@ export function listIssues(
526534 params.push(options.assignee);
527535 where += ` AND assignee.username = ?${params.length} COLLATE NOCASE`;
528536 }
529 if (options.label !== undefined) {
530 params.push(options.label);
537 for (const label of [...(options.label !== undefined ? [options.label] : []), ...(options.labels ?? [])]) {
538 params.push(label);
531539 const p = params.length;
532540 where += ` AND EXISTS (
533541 SELECT 1 FROM issue_label JOIN label ON label.id = issue_label.label_id
534542 WHERE issue_label.issue_id = issue.id
535543 AND (label.id = ?${p} OR label.name = ?${p} COLLATE NOCASE))`;
536544 }
545 if (options.beneath !== undefined) {
546 params.push(options.beneath.rootId);
547 const r = params.length;
548 params.push(JSON.stringify(options.beneath.furniture));
549 const f = params.length;
550 // UNION, not UNION ALL: a cycle in the graph ends the walk.
551 where += ` AND issue.id IN (
552 WITH RECURSIVE tree(id) AS (
553 SELECT d.blocked_by_id FROM issue_dependency d WHERE d.issue_id = ?${r}
554 AND d.blocked_by_id NOT IN (SELECT value FROM json_each(?${f}))
555 UNION
556 SELECT d.blocked_by_id FROM issue_dependency d JOIN tree ON d.issue_id = tree.id
557 WHERE d.blocked_by_id NOT IN (SELECT value FROM json_each(?${f})))
558 SELECT id FROM tree)`;
559 }
537560 if (options.query !== undefined && options.query.trim() !== "") {
538561 // LIKE with an escaped pattern: % and _ from a search box are literal
539562 // characters, not wildcards the user did not ask for.
src/http/api.ts +26 −2
@@ -985,9 +985,32 @@ export function readLimit(ctx: Ctx, fallback: number | undefined): number | unde
985985 return parseLimit(raw, 200, 200) ?? limitRefusal(200);
986986 }
987987
988 /** `?state=&label=&author=&limit=&cursor=` for issue and pull lists. */
989 export function listQuery(ctx: Ctx) {
988 /** What every issue and pull list reads; a route names what more it reads. */
989 export const LIST_PARAMS = ["state", "label", "labels", "author", "cursor", "limit"] as const;
990 /** Labels one `?labels=` may name: more than any issue carries. */
991 const LABELS_MAX = 20;
992
993 /**
994 * `?state=&label=&labels=&author=&limit=&cursor=` for issue and pull lists.
995 * A parameter neither these nor `more` is a 422 naming the accepted ones:
996 * a filter dropped in silence answers the unfiltered list as if filtered.
997 */
998 export function listQuery(ctx: Ctx, more: readonly string[] = []) {
990999 const q = ctx.url.searchParams;
1000 const accepted: readonly string[] = [...LIST_PARAMS, ...more];
1001 const unknown = [...new Set(q.keys())].filter((k) => !accepted.includes(k));
1002 if (unknown.length > 0)
1003 return json(
1004 {
1005 error: "unknown_parameter",
1006 message: `this list does not read ${unknown.map((k) => JSON.stringify(k.slice(0, 40))).join(", ")}; it reads ${accepted.join(", ")}`,
1007 accepted,
1008 },
1009 422,
1010 );
1011 const labels = (q.get("labels") ?? "").split(",").map((l) => l.trim()).filter((l) => l !== "");
1012 if (labels.length > LABELS_MAX)
1013 return apiError("invalid_labels", 422, `labels names at most ${LABELS_MAX}, comma-separated`);
9911014 const limit = readLimit(ctx, undefined);
9921015 if (limit instanceof Response) return limit;
9931016 const stateParam = q.get("state");
@@ -1003,6 +1026,7 @@ export function listQuery(ctx: Ctx) {
10031026 limit: pageLimit(limit),
10041027 ...(rawCursor !== null ? { cursor: Number(rawCursor) } : {}),
10051028 ...(label ? { label } : {}),
1029 ...(labels.length > 0 ? { labels } : {}),
10061030 ...(author ? { author } : {}),
10071031 };
10081032 }
src/http/api/issues.ts +36 −2
@@ -38,7 +38,8 @@ import {
3838 listIssues,
3939 type Issue,
4040 } from "../../core/issues.ts";
41 import { canRead } from "../../core/repos.ts";
41 import { canRead, type Repo } from "../../core/repos.ts";
42 import { pillarsOf, structuralIds } from "../../core/pillars.ts";
4243 import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
4344 import { mayView, sealedScope } from "../../core/sealed.ts";
4445 import {
@@ -160,11 +161,14 @@ export function issueRoutes(router: Router<Handler>): void {
160161 const fields = ctx.url.searchParams.get("fields");
161162 if (fields !== null && fields !== "brief")
162163 return apiError("invalid_fields", 422, "fields must be brief, or left out");
163 const query = listQuery(ctx);
164 const query = listQuery(ctx, ["fields", "milestone"]);
164165 if (query instanceof Response) return query;
166 const beneath = milestoneScope(ctx, repo);
167 if (beneath instanceof Response) return beneath;
165168 const listed = timePhase(ctx.request, "list", () =>
166169 listIssues(ctx.app.db, repo.id, {
167170 ...query,
171 ...(beneath !== undefined ? { beneath } : {}),
168172 kind: "issue",
169173 ...sealedScope(ctx.app.db, repo, ctx.auth.user),
170174 }),
@@ -606,3 +610,33 @@ export function issueRoutes(router: Router<Handler>): void {
606610 },
607611 );
608612 }
613
614 /**
615 * `?milestone=<number>`: the issues beneath that umbrella's tree, as its
616 * milestone counts them (`milestones.ts`). Absent is no scope; a number that
617 * names no issue the reader can see is a 422, never the whole list. The Later
618 * umbrella and the gate are a 422 too: the plan counts as Later what waits
619 * behind the gate, which no walk of their own links gives, and a list short
620 * of the plan's count would read as the whole of it.
621 */
622 function milestoneScope(
623 ctx: Ctx,
624 repo: Repo,
625 ): { rootId: string; furniture: string[] } | undefined | Response {
626 const raw = ctx.url.searchParams.get("milestone");
627 if (raw === null) return undefined;
628 const refused = () =>
629 apiError("invalid_milestone", 422, "milestone is the number of an issue of this repository");
630 if (!/^[1-9]\d{0,15}$/.test(raw)) return refused();
631 const root = getIssue(ctx.app.db, repo.id, Number(raw));
632 if (root === undefined || root.kind !== "issue" || !mayView(ctx.app.db, repo, root, ctx.auth.user)) return refused();
633 const set = pillarsOf(ctx.app.db, repo);
634 if (root.id === set.later?.id || root.id === set.gate?.id)
635 return apiError(
636 "invalid_milestone",
637 422,
638 "milestone is not the Later umbrella or the gate: what is deferred is the plan's own count",
639 `read deferred work from /api/v1/repos/${repo.ownerName}/${repo.name}/map`,
640 );
641 return { rootId: root.id, furniture: [...structuralIds(set)] };
642 }
test/api-list-query.test.ts added +137
@@ -0,0 +1,137 @@
1 /**
2 * The issue and pull lists read what they say they read (#14793): an
3 * unknown parameter is a 422 naming the accepted ones, never the whole
4 * list taken for a filtered one; `labels=` is every label at once;
5 * `milestone=` is the tree beneath that issue.
6 */
7 import { afterAll, beforeAll, expect, test } from "bun:test";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { createRepo } from "../src/actions/repos.ts";
13 import { addDependency } from "../src/core/dependencies.ts";
14 import { createIssue, createLabel, setIssueLabels, type Issue } from "../src/core/issues.ts";
15 import { createUser } from "../src/core/users.ts";
16 import { serve, type Servers } from "../src/http/server.ts";
17 import { quietLogs } from "./helpers/globals.ts";
18
19 quietLogs();
20
21 let dataDir: string;
22 let app: App;
23 let servers: Servers;
24 const n: Record<string, number> = {};
25 const cells = process.env["FORGE_CELLS"];
26
27 beforeAll(async () => {
28 process.env["FORGE_CELLS"] = "off";
29 dataDir = await mkdtemp(join(tmpdir(), "forge-api-list-query-"));
30 app = createApp({ dataDir, port: 0 });
31 servers = await serve(app);
32 const made = await createUser(app.db, {
33 origin: "seed",
34 trusted: true,
35 username: "alice",
36 email: "[email protected]",
37 password: "a-good-passphrase",
38 adminIfFirst: true,
39 });
40 if (!made.ok) throw new Error(String(made.error));
41 const alice = made.value;
42 const repo = await createRepo(app, alice, { name: "r", visibility: "public" });
43 if (!repo.ok) throw new Error(String(repo.error));
44 const issues: Record<string, Issue> = {};
45 const titles = ["root", "child", "grandchild", "outside", "Later: someday", "Later gate: after the pillars"];
46 for (const title of [...titles, "pull"]) {
47 const kind = title === "pull" ? "pull" : "issue";
48 const i = createIssue(app.db, { repoId: repo.value.id, authorId: alice.id, title, kind });
49 if (!i.ok) throw new Error(String(i.error));
50 if (kind === "pull")
51 app.db
52 .query("INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid) VALUES (?, 'main', 'h', 'b', 'h')")
53 .run(i.value.id);
54 issues[title] = i.value;
55 n[title] = i.value.number;
56 }
57 const [p0, bug] = ["P0 Trust", "bug"].map((name) => {
58 const made = createLabel(app.db, repo.value.id, name, "aa0000");
59 if (!made.ok) throw new Error(made.error);
60 return made.value.id;
61 }) as [string, string];
62 setIssueLabels(app.db, issues["child"]!.id, [p0, bug]);
63 setIssueLabels(app.db, issues["outside"]!.id, [p0]);
64 setIssueLabels(app.db, issues["pull"]!.id, [bug]);
65 const links = [["root", "child"], ["child", "grandchild"], ["Later: someday", "outside"], ["Later gate: after the pillars", "root"]] as const;
66 for (const [issue, blocker] of links) {
67 const linked = addDependency(app.db, issues[issue]!, issues[blocker]!, alice.id);
68 if (!linked.ok) throw new Error(String(linked.error));
69 }
70 });
71 afterAll(async () => {
72 await servers.stop();
73 app.close();
74 if (cells === undefined) delete process.env["FORGE_CELLS"];
75 else process.env["FORGE_CELLS"] = cells;
76 await rm(dataDir, { recursive: true, force: true });
77 });
78
79 async function list(query: string, route = "issues") {
80 const res = await fetch(`${servers.url}/api/v1/repos/alice/r/${route}?${query}`);
81 const body = (await res.json()) as { items?: { number: number }[]; error?: string; accepted?: string[]; message?: string };
82 return { status: res.status, body, numbers: (body.items ?? []).map((i) => i.number).sort((a, b) => a - b) };
83 }
84
85 test("labels= keeps the issues carrying every label named", async () => {
86 expect((await list(`labels=${encodeURIComponent("P0 Trust")}`)).numbers).toEqual([n["child"]!, n["outside"]!]);
87 expect((await list(`labels=${encodeURIComponent("P0 Trust, bug")}`)).numbers).toEqual([n["child"]!]);
88 expect((await list("labels=ghost")).numbers).toEqual([]);
89 });
90
91 test("milestone= lists the tree beneath that issue, and nothing else", async () => {
92 expect((await list(`milestone=${n["root"]}`)).numbers).toEqual([n["child"]!, n["grandchild"]!]);
93 expect((await list(`milestone=${n["root"]}&labels=bug`)).numbers).toEqual([n["child"]!]);
94 for (const bad of ["0", "x", "9999"]) {
95 const res = await list(`milestone=${bad}`);
96 expect(res.status).toBe(422);
97 expect(res.body.error).toBe("invalid_milestone");
98 }
99 });
100
101 test("labels= past twenty names is a 422, and twenty is answered", async () => {
102 const names = (count: number) => Array.from({ length: count }, (_, i) => `l${i}`).join(",");
103 for (const route of ["issues", "pulls"]) {
104 const over = await list(`labels=${names(21)}`, route);
105 expect(over.status).toBe(422);
106 expect(over.body.error).toBe("invalid_labels");
107 expect((await list(`labels=${names(20)}`, route)).status).toBe(200);
108 }
109 });
110
111 test("labels= on the pull list keeps the pulls carrying every label named", async () => {
112 expect((await list("labels=bug", "pulls")).numbers).toEqual([n["pull"]!]);
113 expect((await list(`labels=${encodeURIComponent("bug,P0 Trust")}`, "pulls")).numbers).toEqual([]);
114 // fields= is the cursor lists' own (cursor_lists.ts), read before this list's check.
115 expect((await list("fields=number,title", "pulls")).status).toBe(200);
116 });
117
118 test("milestone= refuses a pull, the Later umbrella and the gate", async () => {
119 for (const root of ["pull", "Later: someday", "Later gate: after the pillars"]) {
120 const res = await list(`milestone=${n[root]}`);
121 expect(res.status).toBe(422);
122 expect(res.body.error).toBe("invalid_milestone");
123 }
124 expect((await list(`milestone=${n["Later: someday"]}`)).body.message).toContain("Later");
125 });
126
127 test("an unknown parameter is a 422 that names the accepted ones", async () => {
128 const res = await list("nonsense=1");
129 expect(res.status).toBe(422);
130 expect(res.body.error).toBe("unknown_parameter");
131 expect(res.body.message).toContain('"nonsense"');
132 expect(res.body.accepted).toEqual(["state", "label", "labels", "author", "cursor", "limit", "fields", "milestone"]);
133 const pulls = await list("milestone=1", "pulls");
134 expect(pulls.status).toBe(422);
135 expect(pulls.body.accepted).not.toContain("milestone");
136 expect((await list("state=all&limit=5")).status).toBe(200);
137 });
test/api-page-param.test.ts +7 −1
@@ -70,7 +70,13 @@ for (const path of lists) {
7070 expect(body).toMatchObject(SAYS);
7171 expect(body.hint).toContain("?cursor=");
7272 }
73 expect((await get(`${path}?foo=1`)).status).toBe(200);
73 // The page guard leaves other names alone; the issue and pull lists refuse names they do not
74 // read on their own (#14793), every other list ignores them.
75 const stray = await get(`${path}?foo=1`);
76 if (/\/(issues|pulls)$/.test(path)) {
77 expect(stray.status).toBe(422);
78 expect(((await stray.json()) as { error?: string }).error).toBe("unknown_parameter");
79 } else expect(stray.status).toBe(200);
7480 });
7581 }
7682
test/openapi.test.ts +1 −1
@@ -93,7 +93,7 @@ test("listing issues and pulls is described with the query the handlers read", (
9393 const get = doc.paths[`${R}/${kind}`].get;
9494 expect(get.security).toEqual([]);
9595 const q = get.parameters.filter((p: any) => p.in === "query");
96 const base = ["state", "limit", "cursor", "label", "author"];
96 const base = ["state", "limit", "cursor", "label", "labels", "author", ...(kind === "issues" ? ["milestone"] : [])];
9797 expect(q.map((p: any) => p.name)).toEqual(base); // `fields` is the shared $ref parameter (#14673)
9898 expect(q.find((p: any) => p.name === "limit").schema.type).toBe("integer");
9999 expect(q.find((p: any) => p.name === "state").schema.enum).toEqual(["open", "closed", "all"]);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs