Public: anyone can read this; the crew can change it.
Every API list takes `fields=a,b` so an agent asks for only the columns it needs #14687
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14673-every-api-list-takes-fields-a-b-so-an-ag → main 4 commits fork 2 threads · 2 unresolved
10 files
changed +247
−11
docs/features/api-fields.md added +20
| @@ -0,0 +1,20 @@ | ||
| 1 | --- | |
| 2 | topic: Agents: MCP, git, or the terminal | |
| 3 | row: fields=a,b: ask a list for only the columns you need | |
| 4 | --- | |
| 5 | # fields=a,b: ask a list for only the columns you need | |
| 6 | ||
| 7 | Every cursor-paged API list takes `?fields=a,b`. Each item then carries only those keys, and `next_cursor` stays, so an agent reading a long list spends tokens on the columns it uses. | |
| 8 | ||
| 9 | ||
| 10 | GET /api/v1/repos/OWNER/NAME/issues?fields=number,title&limit=50 | |
| 11 | ||
| 12 | ||
| 13 | - **Paging keeps the cut.** The `Link: <...>; rel="next"` header copies your query, `fields` included, so following it returns the next page cut the same way. `next_cursor` is only the cursor: when you build the next request yourself, send `fields` again. | |
| 14 | - **Names are checked against the list's declared item keys**, not against the page. A key an item may omit is accepted, and an empty page answers the same as a full one. An unknown name is a 422 `invalid_fields` that names the accepted keys. | |
| 15 | - **A list that declares no item keys** takes any well-formed name and keeps those an item has. Add `itemKeys` to its route row in `src/contract/openapi/routes/` to make it strict. | |
| 16 | - **Malformed** (empty name, characters other than letters, digits and `_`, more than 50 names) is a 422 `invalid_fields`. | |
| 17 | - The issues list also takes `fields=brief`, which leaves out bodies and comments. | |
| 18 | - An etag the full page carried is not sent on a cut page. | |
| 19 | ||
| 20 | The parameter is declared once in the contract (`components.parameters.fields` in `/contract/openapi.json`); code is `src/http/cursor_lists.ts`. |
src/contract/openapi.ts +15 −3
| @@ -41,6 +41,17 @@ export const ROUTES: readonly Route[] = Object.values(each); | ||
| 41 | 41 | */ |
| 42 | 42 | export const pagesByCursor = (r: Pick<Route, "method" | "query">): boolean => r.method === "get" && r.query !== undefined && "cursor" in r.query; |
| 43 | 43 | |
| 44 | /** The one `fields` parameter every cursor list shares (`http/cursor_lists.ts`, #14673). */ | |
| 45 | export const FIELDS_REF = "#/components/parameters/fields"; | |
| 46 | const FIELDS_PARAM = { | |
| 47 | name: "fields", | |
| 48 | in: "query", | |
| 49 | required: false, | |
| 50 | description: | |
| 51 | "Comma-separated item keys to keep, e.g. `number,title`; `next_cursor` stays. A name that is not a key of the list's items is a 422 `invalid_fields` naming the accepted ones, whatever the page holds; a list that does not declare its keys takes any name and keeps those an item has. The issues list also takes `brief`.", | |
| 52 | schema: { type: "string" }, | |
| 53 | }; | |
| 54 | ||
| 44 | 55 | const PAGE_REFUSAL = "page or offset was sent: this list pages by cursor, pass next_cursor as ?cursor= (400)"; |
| 45 | 56 | |
| 46 | 57 | /** |
| @@ -147,7 +158,7 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 147 | 158 | const rows = routesFor(role); |
| 148 | 159 | for (const r of rows) { |
| 149 | 160 | const refusals = { |
| 150 | ...(pagesByCursor(r) ? { invalid_query: PAGE_REFUSAL } : {}), | |
| 161 | ...(pagesByCursor(r) ? { invalid_query: PAGE_REFUSAL, invalid_fields: "422" } : {}), | |
| 151 | 162 | ...(readsJsonBody(r) ? { invalid_json: "400" } : {}), |
| 152 | 163 | ...(r.method !== "get" ? { cross_origin: "403" } : {}), |
| 153 | 164 | ...r.refusals, |
| @@ -158,7 +169,7 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 158 | 169 | required: true, |
| 159 | 170 | schema: { type: m[1] === "number" || m[1] === "blocker" ? "integer" : "string" }, |
| 160 | 171 | })); |
| 161 | const query = Object.entries(r.query ?? {}).map(([name, t]) => ({ | |
| 172 | const query = Object.entries(r.query ?? {}).filter(([name]) => !(pagesByCursor(r) && name === "fields")).map(([name, t]) => ({ | |
| 162 | 173 | name, |
| 163 | 174 | in: "query", |
| 164 | 175 | required: false, |
| @@ -176,7 +187,7 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 176 | 187 | tags: [tagOf(r.path)], |
| 177 | 188 | summary: r.summary, |
| 178 | 189 | "x-role": r.role, |
| 179 | parameters: [...params, ...query], | |
| 190 | parameters: [...params, ...query, ...(pagesByCursor(r) ? [{ $ref: FIELDS_REF }] : [])], | |
| 180 | 191 | ...(r.body === undefined |
| 181 | 192 | ? {} |
| 182 | 193 | : { |
| @@ -244,6 +255,7 @@ export function openapi(origin: string, version: string, role: Role): Record<str | ||
| 244 | 255 | security: [{ token: [] }], |
| 245 | 256 | paths, |
| 246 | 257 | components: { |
| 258 | parameters: { fields: FIELDS_PARAM }, | |
| 247 | 259 | schemas: { Error: ERROR_SCHEMA }, |
| 248 | 260 | responses: sharedResponses(), |
| 249 | 261 | securitySchemes: { |
src/contract/openapi/routes/getApiV1ReposOwnerNameIssues.ts +2 −2
| @@ -1,3 +1,3 @@ | ||
| 1 | import { LIST_QUERY, REPO, type Route } from "../shared.ts"; | |
| 1 | import { ISSUE_ITEM_KEYS, LIST_QUERY, REPO, type Route } from "../shared.ts"; | |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: `${REPO}/issues`, summary: "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], 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; 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] }; |
src/contract/openapi/routes/getApiV1ReposOwnerNameLabels.ts +1
| @@ -8,6 +8,7 @@ export const route: Route = { | ||
| 8 | 8 | "List a repository's labels by name, each { id, name, color } and, for a repository writer, open (its open issues and pulls, as on the labels page; a reader is told none, since sealed ones are counted); a private repository needs a token; answers { items: [...], next_cursor }; limit 1 to 200, cursor from next_cursor", |
| 9 | 9 | auth: false, |
| 10 | 10 | role: "anonymous", |
| 11 | itemKeys: ["id", "name", "color", "open"], | |
| 11 | 12 | query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, |
| 12 | 13 | refusals: { |
| 13 | 14 | invalid_limit: "limit is not a whole number from 1 to 200 (422)", |
src/contract/openapi/routes/getApiV1ReposOwnerNamePulls.ts +2 −2
| @@ -1,3 +1,3 @@ | ||
| 1 | import { LIST_QUERY, REPO, type Route } from "../shared.ts"; | |
| 1 | import { ISSUE_ITEM_KEYS, LIST_QUERY, REPO, type Route } from "../shared.ts"; | |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: `${REPO}/pulls`, summary: "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], 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; 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] }; |
src/http/cursor_lists.ts +60
| @@ -22,6 +22,66 @@ export function pageParamRefused(pattern: string, q: URLSearchParams): Response | ||
| 22 | 22 | return CURSOR_LISTS.has(pattern) && pagedByNumber(q) ? apiError("invalid_query", 400, PAGE_PARAM_SAYS) : undefined; |
| 23 | 23 | } |
| 24 | 24 | |
| 25 | /** Lists whose own handler already reads `fields=brief`. */ | |
| 26 | const OWN_BRIEF: ReadonlySet<string> = new Set(["/api/v1/repos/:owner/:name/issues"]); | |
| 27 | ||
| 28 | /** The keys each list declares for its items: `itemKeys`, or every field of its `replyShapes`. */ | |
| 29 | const DECLARED: ReadonlyMap<string, readonly string[]> = new Map( | |
| 30 | ROUTES.filter(pagesByCursor).flatMap((r) => { | |
| 31 | const keys = r.itemKeys ?? (r.replyShapes === undefined ? undefined : Object.values(r.replyShapes).flatMap((s) => Object.keys(s.fields))); | |
| 32 | return keys === undefined ? [] : [[patternOf(r.path), [...new Set(keys)].sort()] as const]; | |
| 33 | }), | |
| 34 | ); | |
| 35 | ||
| 36 | /** The columns asked for, and the keys the list declares (none declared: any well-formed name). */ | |
| 37 | export interface Cut { | |
| 38 | readonly names: string[]; | |
| 39 | readonly accepted?: readonly string[] | undefined; | |
| 40 | } | |
| 41 | ||
| 42 | /** | |
| 43 | * `?fields=a,b` on a cursor list (#14673): the names asked for, or a 422 when a name is malformed | |
| 44 | * or, on a list that declares its item keys, not one of them: decided here, before the page is | |
| 45 | * read, so an empty page or a page that omits an optional key answers the same. Left out of the URL | |
| 46 | * the handler reads (it would refuse it), unless it is `brief` on a list whose handler owns that | |
| 47 | * word; the caller's own URL, which `Link` rel=next copies, still carries it. Undefined when the | |
| 48 | * list is not asked to be cut. | |
| 49 | */ | |
| 50 | export function takeFields(pattern: string, url: URL): Cut | Response | undefined { | |
| 51 | if (!CURSOR_LISTS.has(pattern)) return undefined; | |
| 52 | const raw = url.searchParams.get("fields"); | |
| 53 | if (raw === null) return undefined; | |
| 54 | if (raw === "brief" && OWN_BRIEF.has(pattern)) return undefined; | |
| 55 | url.searchParams.delete("fields"); | |
| 56 | const names = raw.split(",").map((n) => n.trim()); | |
| 57 | if (names.length > 50 || names.some((n) => !/^[A-Za-z0-9_]{1,64}$/.test(n))) | |
| 58 | return apiError("invalid_fields", 422, "fields is a comma-separated list of item keys, e.g. fields=number,title", "name keys like number,title; at most 50"); | |
| 59 | const accepted = DECLARED.get(pattern); | |
outdated
Accepted names derived from the items on this page: false 422 for a valid optional key missing from the page, and no validation on an empty page. Use a declared key set per list. |
||
| 60 | const unknown = accepted === undefined ? [] : names.filter((f) => !accepted.includes(f)); | |
| 61 | if (accepted !== undefined && unknown.length > 0) | |
| 62 | return apiError("invalid_fields", 422, `unknown field ${unknown.join(", ")}; accepted: ${accepted.join(", ")}`, `ask for some of: ${accepted.join(", ")}`); | |
| 63 | return { names: [...new Set(names)], accepted }; | |
| 64 | } | |
| 65 | ||
| 66 | /** The page cut to `fields`: each item keeps those of them it has, `next_cursor` stays. */ | |
| 67 | export async function withFields(cut: Cut, response: Response): Promise<Response> { | |
| 68 | if (response.status !== 200 || !(response.headers.get("content-type") ?? "").includes("json")) return response; | |
| 69 | let body: { items?: unknown; next_cursor?: unknown }; | |
| 70 | try { | |
| 71 | body = (await response.clone().json()) as typeof body; | |
| 72 | } catch { | |
| 73 | return response; | |
| 74 | } | |
| 75 | if (body === null || typeof body !== "object" || !Array.isArray(body.items)) return response; | |
| 76 | const items = (body.items as unknown[]).map((i) => | |
| 77 | i !== null && typeof i === "object" ? Object.fromEntries(cut.names.filter((f) => f in i).map((f) => [f, (i as Record<string, unknown>)[f]])) : {}, | |
| 78 | ); | |
| 79 | const headers = new Headers(response.headers); | |
| 80 | headers.delete("content-length"); | |
| 81 | headers.delete("etag"); | |
| 82 | return new Response(JSON.stringify({ ...body, items }), { status: 200, headers }); | |
| 83 | } | |
| 84 | ||
| 25 | 85 | /** |
| 26 | 86 | * RFC 8288: `Link: <url>; rel="next"` for a cursor list's 200 JSON page that has more, none on the |
| 27 | 87 | * last page. `base` is the public URL built from configuration (`publicUrl`), never a caller |
src/http/server.ts +5 −2
| @@ -558,7 +558,7 @@ import { CAME_FROM_ELSEWHERE, forbiddenPage, notFoundPage, SENT_FROM_ELSEWHERE, | ||
| 558 | 558 | import { targetForShortCode } from "../origins/oauth.ts"; |
| 559 | 559 | import { apiRoutes, oauthCallbackUri } from "./api.ts"; |
| 560 | 560 | import { brokerStart } from "../spawn/origin_broker.ts"; |
| 561 | import { pageParamRefused, withLinkNext } from "./cursor_lists.ts"; | |
| 561 | import { pageParamRefused, takeFields, withFields, withLinkNext } from "./cursor_lists.ts"; | |
| 562 | 562 | import { inNamespace } from "../core/proposal_token.ts"; |
| 563 | 563 | import { inContribNamespace } from "../core/contribute_token.ts"; |
| 564 | 564 | import { takesOutside } from "../actions/contribute_token.ts"; |
| @@ -3497,6 +3497,8 @@ async function answer( | ||
| 3497 | 3497 | const byNumber = pageParamRefused(matched.pattern, url.searchParams); |
| 3498 | 3498 | if (byNumber !== undefined) return withRateHeaders(byNumber, verdict); |
| 3499 | 3499 | } |
| 3500 | const cutTo = isApiPath && routeMethod === "GET" ? takeFields(matched.pattern, url) : undefined; | |
| 3501 | if (cutTo instanceof Response) return withRateHeaders(cutTo, verdict); | |
| 3500 | 3502 | |
| 3501 | 3503 | const themeCookie = cookieValue(request, "forge_theme") ?? ""; |
| 3502 | 3504 | if (!isApiPath) { |
| @@ -3573,6 +3575,7 @@ async function answer( | ||
| 3573 | 3575 | ) { |
| 3574 | 3576 | return withRateHeaders(pageNotFoundAsJson(url.origin), verdict); |
| 3575 | 3577 | } |
| 3576 | const linked = isApiPath && routeMethod === "GET" ? await withLinkNext(matched.pattern, publicUrl(request, app.config.url), response) : response; | |
| 3578 | const cut = cutTo === undefined ? response : await withFields(cutTo, response); | |
| 3579 | const linked = isApiPath && routeMethod === "GET" ? await withLinkNext(matched.pattern, publicUrl(request, app.config.url), cut) : cut; | |
| 3577 | 3580 | return withRateHeaders(noindex ? withHeader(linked, "x-robots-tag", "noindex") : linked, verdict); |
| 3578 | 3581 | } |
test/api-fields.test.ts added +126
| @@ -0,0 +1,126 @@ | ||
| 1 | /** | |
| 2 | * `?fields=a,b` on a cursor list keeps only those keys and the cursor; unknown names are a 422; the | |
| 3 | * contract names it once (#14673). | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, describe, 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 { createRepo } from "../src/actions/repos.ts"; | |
| 10 | import { createApp, type App } from "../src/app.ts"; | |
| 11 | import { FIELDS_REF, openapi, pagesByCursor, ROUTES } from "../src/contract/openapi.ts"; | |
| 12 | import { createIssue } from "../src/core/issues.ts"; | |
| 13 | import { createToken } from "../src/core/tokens.ts"; | |
| 14 | import { createUser } from "../src/core/users.ts"; | |
| 15 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 16 | ||
| 17 | describe("fields on cursor lists", () => { | |
| 18 | let dataDir: string; | |
| 19 | let app: App; | |
| 20 | let servers: Servers; | |
| 21 | let headers: Record<string, string>; | |
| 22 | ||
| 23 | beforeAll(async () => { | |
| 24 | dataDir = await mkdtemp(join(tmpdir(), "forge-fields-")); | |
| 25 | app = createApp({ dataDir, port: 0 }); | |
| 26 | servers = await serve(app); | |
| 27 | const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 28 | if (!made.ok) throw new Error(made.error); | |
| 29 | headers = { authorization: `Bearer ${createToken(app.db, made.value.id, "t", "admin").token}` }; | |
| 30 | const lib = await createRepo(app, made.value, { name: "lib", visibility: "public" }); | |
| 31 | if (!lib.ok) throw new Error(String(lib.error)); | |
| 32 | for (let n = 1; n <= 3; n++) createIssue(app.db, { repoId: lib.value.id, authorId: made.value.id, title: `issue ${n}` }); | |
| 33 | }); | |
| 34 | ||
| 35 | afterAll(async () => { | |
| 36 | await servers.stop(); | |
| 37 | await rm(dataDir, { recursive: true, force: true }); | |
| 38 | }); | |
| 39 | ||
| 40 | const get = (q: string) => fetch(`${servers.url}/api/v1/repos/alice/lib/issues?${q}`, { headers }); | |
| 41 | ||
| 42 | test("only the named keys, and the cursor", async () => { | |
| 43 | const res = await get("limit=2&fields=number,title"); | |
| 44 | expect(res.status).toBe(200); | |
| 45 | const body = (await res.json()) as { items: Record<string, unknown>[]; next_cursor: unknown }; | |
| 46 | expect(body.items.length).toBe(2); | |
| 47 | for (const i of body.items) expect(Object.keys(i).sort()).toEqual(["number", "title"]); | |
| 48 | expect(body.next_cursor).not.toBeNull(); | |
| 49 | expect(res.headers.get("link")).toContain('rel="next"'); | |
| 50 | }); | |
| 51 | ||
| 52 | test("an unknown name is a 422 naming the accepted ones", async () => { | |
| 53 | const res = await get("fields=number,nope"); | |
| 54 | expect(res.status).toBe(422); | |
| 55 | const body = (await res.json()) as { error: string; message: string; hint: string }; | |
| 56 | expect(body.error).toBe("invalid_fields"); | |
| 57 | expect(body.message).toContain("nope"); | |
| 58 | expect(body.message).toContain("accepted:"); | |
| 59 | expect(body.message).toContain("title"); | |
| 60 | expect(body.hint).toContain("number"); | |
| 61 | }); | |
| 62 | ||
| 63 | test("a malformed list is a 422; brief still works on issues", async () => { | |
| 64 | expect((await get("fields=a,,b")).status).toBe(422); | |
| 65 | expect((await get("fields=%3Cscript%3E")).status).toBe(422); | |
| 66 | expect((await get("fields=brief")).status).toBe(200); | |
| 67 | }); | |
| 68 | ||
| 69 | const list = (path: string, q: string) => fetch(`${servers.url}/api/v1/repos/alice/lib/${path}?${q}`, { headers }); | |
| 70 | ||
| 71 | test("the Link rel=next of a cut page keeps fields, and page two is cut too", async () => { | |
| 72 | const first = await get("limit=2&fields=number,title"); | |
| 73 | const link = /<([^>]+)>; rel="next"/.exec(first.headers.get("link") ?? "")?.[1]; | |
| 74 | expect(link).toBeDefined(); | |
| 75 | const next = new URL(link!); | |
| 76 | expect(next.searchParams.get("fields")).toBe("number,title"); | |
| 77 | expect(next.searchParams.get("cursor")).not.toBeNull(); | |
| 78 | const second = await get(`${next.search.slice(1)}`); | |
| 79 | const body = (await second.json()) as { items: Record<string, unknown>[] }; | |
| 80 | expect(body.items.length).toBeGreaterThan(0); | |
| 81 | for (const i of body.items) expect(Object.keys(i).sort()).toEqual(["number", "title"]); | |
| 82 | }); | |
| 83 | ||
| 84 | test("names are checked against the declared keys, not the page: empty page, absent optional key", async () => { | |
| 85 | const empty = await list("pulls", "fields=number,nope"); | |
| 86 | expect(empty.status).toBe(422); | |
| 87 | expect(((await empty.json()) as { message: string }).message).toContain("nope"); | |
| 88 | const ok = await list("pulls", "fields=number,mergeable,check"); | |
| 89 | expect(ok.status).toBe(200); | |
| 90 | expect(((await ok.json()) as { items: unknown[] }).items).toEqual([]); | |
| 91 | // issues have no `mergeable`: a declared list, so a 422 whatever the page holds | |
| 92 | expect((await get("fields=mergeable")).status).toBe(422); | |
| 93 | }); | |
| 94 | ||
| 95 | test("a list other than issues goes through the hook", async () => { | |
| 96 | const res = await list("labels", "fields=name,open"); | |
| 97 | expect(res.status).toBe(200); | |
| 98 | expect((await list("labels", "fields=name,nope")).status).toBe(422); | |
| 99 | }); | |
| 100 | ||
| 101 | test("a list that declares no keys takes any well-formed name and keeps those an item has", async () => { | |
| 102 | const res = await list("milestones", "fields=anything"); | |
| 103 | expect(res.status).toBe(200); | |
| 104 | expect((await list("milestones", "fields=a-b")).status).toBe(422); | |
| 105 | }); | |
| 106 | ||
| 107 | test("without fields the page is whole", async () => { | |
| 108 | const body = (await (await get("limit=1")).json()) as { items: Record<string, unknown>[] }; | |
| 109 | expect(Object.keys(body.items[0]!).length).toBeGreaterThan(2); | |
| 110 | }); | |
| 111 | ||
| 112 | test("the contract names the parameter once, shared, and every cursor list refers to it", () => { | |
| 113 | const doc = openapi("https://x.example", "0", "admin") as { | |
| 114 | paths: Record<string, Record<string, { parameters: { $ref?: string; name?: string }[] }>>; | |
| 115 | components: { parameters: Record<string, { name: string }> }; | |
| 116 | }; | |
| 117 | expect(doc.components.parameters.fields?.name).toBe("fields"); | |
| 118 | const lists = ROUTES.filter(pagesByCursor); | |
| 119 | expect(lists.length).toBeGreaterThan(0); | |
| 120 | for (const r of lists) { | |
| 121 | const params = doc.paths[r.path]![r.method]!.parameters; | |
| 122 | expect(params.filter((p) => p.$ref === FIELDS_REF).length, `${r.method} ${r.path}`).toBe(1); | |
| 123 | expect(params.some((p) => p.name === "fields"), `${r.path} declares its own`).toBe(false); | |
| 124 | } | |
| 125 | }); | |
| 126 | }); |
test/openapi.test.ts +1 −2
| @@ -94,8 +94,7 @@ test("listing issues and pulls is described with the query the handlers read", ( | ||
| 94 | 94 | expect(get.security).toEqual([]); |
| 95 | 95 | const q = get.parameters.filter((p: any) => p.in === "query"); |
| 96 | 96 | const base = ["state", "limit", "cursor", "label", "author"]; |
| 97 | expect(q.map((p: any) => p.name)).toEqual(kind === "issues" ? [...base, "fields"] : base); | |
| 98 | if (kind === "issues") expect(q.find((p: any) => p.name === "fields").schema.enum).toEqual(["brief"]); | |
| 97 | expect(q.map((p: any) => p.name)).toEqual(base); // `fields` is the shared $ref parameter (#14673) | |
| 99 | 98 | expect(q.find((p: any) => p.name === "limit").schema.type).toBe("integer"); |
| 100 | 99 | expect(q.find((p: any) => p.name === "state").schema.enum).toEqual(["open", "closed", "all"]); |
| 101 | 100 | expect(get.parameters.filter((p: any) => p.in === "path").length).toBe(2); |
new above
offline
Deleting fields here means the Link next header and next_cursor no longer carry it; paging drops the projection. Preserve it in the next link.