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

The OpenAPI description lists every error answer once as a shared schema, and a test fails when a route returns one it does not name #14628

Merged opened this

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

Merged

scout/forge:scout/14592-the-openapi-description-lists-every-erro → main 4 commits fork 7 threads · 7 unresolved

  • Merged. scout/14592-the-openapi-description-lists-every-erro was merged into main as c2c8da3.

Review

Sign in to review this change.
401 files changed +622 −78
src/contract/openapi.ts +58 −7
@@ -50,6 +50,53 @@ const PAGE_REFUSAL = "page or offset was sent: this list pages by cursor, pass n
5050 export const readsJsonBody = (r: Pick<Route, "method" | "body">): boolean => r.method !== "get" && r.method !== "delete" && r.body !== undefined;
5151
5252 const CROSS_ORIGIN_REFUSAL = "403: the request came from a browser page on another origin; send it without an `Origin` header or with a token";
53 /**
54 * The one shape of every error answer, named once; each route's non-2xx responses point at it
55 * (#14592).
56 */
57 export const ERROR_SCHEMA = {
58 type: "object",
59 required: ["error", "message"],
60 properties: {
61 error: { type: "string", description: "A stable code." },
62 message: { type: "string", description: "What went wrong, in words." },
63 hint: { type: "string", description: "What to do next." },
64 },
65 } as const;
66
67 /**
68 * The refusals many routes answer alike, written once under `components.responses` and pointed
69 * at: a route names which it answers in `refuses`, and every write answers 403 to a page on
70 * another origin. A route's own `errorStatus` words win over these.
71 */
outdated

Shape-derived statuses (401/403/422/404 on every route) are declared whether or not the route answers them. This makes the test pass by construction and the doc inaccurate. Derive from the route's real refusals, or have a test fail on declared-but-never-answered codes.

72 export const SHARED_REFUSALS = {
73 401: ["Unauthorized", "`unauthorized`: no valid credential; sign in or send a token"],
74 403: ["Forbidden", `\`forbidden\`: the caller may not do this; or \`cross_origin\`: ${CROSS_ORIGIN_REFUSAL.replace("403: ", "")}`],
75 404: ["NotFound", "`not_found`: missing, or not yours to see"],
76 422: ["Invalid", "A field is missing or not valid: `message` names it"],
77 } as const satisfies Record<number, readonly [string, string]>;
78
79 const REFUSED = "Refused: `error` names which refusal; `message` and `hint` say what to change";
80
81 function errorAnswer(description: string) {
82 return { description, content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } };
83 }
84
85 const sharedRef = (name: string) => ({ $ref: `#/components/responses/${name}` });
86
87 /** The shared refusals a route answers, by status code, each a pointer into components. */
88 function sharedRefusals(r: Route): Record<string, { $ref: string }> {
89 const codes = new Set<number>([...(r.refuses ?? []), ...(r.method === "get" ? [] : [403])]);
90 return Object.fromEntries([...codes].sort().map((c) => [String(c), sharedRef(SHARED_REFUSALS[c as keyof typeof SHARED_REFUSALS][0])]));
91 }
92
93 const sharedResponses = () => ({
94 ...Object.fromEntries(Object.values(SHARED_REFUSALS).map(([name, words]) => [name, errorAnswer(words)])),
95 Refused: errorAnswer(REFUSED),
96 PageRefused: errorAnswer(PAGE_REFUSAL),
97 NotJson: errorAnswer(JSON_REFUSAL),
98 });
99
53100 const JSON_REFUSAL = "400 { error, message, hint }: the body is not JSON; the message names the first bad token and its byte offset";
54101
55102 /** A route's operationId, and the name of the file that holds it. */
@@ -101,8 +148,8 @@ export function openapi(origin: string, version: string, role: Role): Record<str
101148 for (const r of rows) {
102149 const refusals = {
103150 ...(pagesByCursor(r) ? { invalid_query: PAGE_REFUSAL } : {}),
104 ...(readsJsonBody(r) ? { invalid_json: JSON_REFUSAL } : {}),
105 ...(r.method !== "get" ? { cross_origin: CROSS_ORIGIN_REFUSAL } : {}),
151 ...(readsJsonBody(r) ? { invalid_json: "400" } : {}),
152 ...(r.method !== "get" ? { cross_origin: "403" } : {}),
106153 ...r.refusals,
107154 };
108155 const params = [...r.path.matchAll(/\{(\w+)\}/g)].map((m) => ({
@@ -168,15 +215,17 @@ export function openapi(origin: string, version: string, role: Role): Record<str
168215 },
169216 }),
170217 },
171 ...Object.fromEntries((r.alsoStatus ?? []).map((c) => [String(c), { description: "Done" }])),
172 ...(pagesByCursor(r) ? { "400": { description: PAGE_REFUSAL } } : readsJsonBody(r) ? { "400": { description: JSON_REFUSAL } } : {}),
173 ...Object.fromEntries(Object.entries(r.errorStatus ?? {}).map(([c, d]) => [c, { description: d }])),
218 ...Object.fromEntries((r.alsoStatus ?? []).map((c) => [String(c), c >= 400 ? sharedRef("Refused") : c === 304 ? { description: "Not modified: the If-None-Match sent is still current; no body" } : { description: "Done" }])),
219 ...(pagesByCursor(r) ? { "400": sharedRef("PageRefused") } : readsJsonBody(r) ? { "400": sharedRef("NotJson") } : {}),
220 ...sharedRefusals(r),
221 ...Object.fromEntries(Object.entries(r.errorStatus ?? {}).map(([c, d]) => [c, errorAnswer(d)])),
174222 default: {
175 description:
176 "An error: { error, message }; `error` is a stable code" +
223 ...errorAnswer(
224 "An error: { error, message, hint }; `error` is a stable code" +
177225 (Object.keys(refusals).length === 0
178226 ? ""
179227 : `. Refusals: ${Object.entries(refusals).map(([c, w]) => `\`${c}\` (${w})`).join("; ")}`),
228 ),
180229 },
181230 },
182231 };
@@ -195,6 +244,8 @@ export function openapi(origin: string, version: string, role: Role): Record<str
195244 security: [{ token: [] }],
196245 paths,
197246 components: {
247 schemas: { Error: ERROR_SCHEMA },
248 responses: sharedResponses(),
198249 securitySchemes: {
199250 token: { type: "http", scheme: "bearer" },
200251 // RFC 6749 §4.1 authorization code (with PKCE), §6 refresh; the token endpoint serves both
src/contract/openapi/routes/deleteApiV1AdminInvitesId.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "Revoke an invite link by id (admin scope); 404 when there is none",
77 auth: true,
88 role: "admin",
9 refuses: [404],
910 };
src/contract/openapi/routes/deleteApiV1AdminRunnersId.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 status: 204,
11 refuses: [404],
1112 };
src/contract/openapi/routes/deleteApiV1AgentsUsername.ts +1 −1
@@ -1,3 +1,3 @@
11 import type { Route } from "../shared.ts";
22
3 export const route: Route = { method: "delete", path: "/api/v1/agents/{username}", summary: "Remove an agent (an admin token, or a person's session); answers {}", auth: true, role: "member", refusals: { forbidden: "a token below admin scope", not_found: "no such agent" } };
3 export const route: Route = { method: "delete", path: "/api/v1/agents/{username}", summary: "Remove an agent (an admin token, or a person's session); answers {}", auth: true, role: "member", refusals: { forbidden: "a token below admin scope", not_found: "no such agent" }, refuses: [401] };
src/contract/openapi/routes/deleteApiV1BoardsSlug.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "Delete a board; answers { deleted: true }",
77 auth: true,
88 role: "admin",
9 refuses: [401, 404],
910 };
src/contract/openapi/routes/deleteApiV1CodesId.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "admin",
99 refusals: { not_found: "the token is not a person who administers the forge (404)", no_such_code: "no code has this id, or it was already revoked (404)" },
10 refuses: [404],
1011 };
src/contract/openapi/routes/deleteApiV1ConversationFilesId.ts +1
@@ -11,4 +11,5 @@ export const route: Route = {
1111 not_found: "no such unsent attachment of yours (404)",
1212 forbidden: "the request is cross-origin, or the token may only read",
1313 },
14 refuses: [401, 404],
1415 };
src/contract/openapi/routes/deleteApiV1ConversationQueueId.ts +1
@@ -11,4 +11,5 @@ export const route: Route = {
1111 not_found: "no such waiting message of yours (404)",
1212 forbidden: "the request is cross-origin, or the token may only read",
1313 },
14 refuses: [401, 404],
1415 };
src/contract/openapi/routes/deleteApiV1FeaturesSlug.ts +1
@@ -11,4 +11,5 @@ export const route: Route = {
1111 forbidden: "you are not a site admin (403)",
1212 not_absorbed: "the app is not absorbed (409)",
1313 },
14 refuses: [401, 404],
1415 };
src/contract/openapi/routes/deleteApiV1OrgsOrgTeamsTeam.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 role: "member",
99 status: 204,
1010 refusals: { not_found: "no such team" },
11 refuses: [401, 404],
1112 };
src/contract/openapi/routes/deleteApiV1OrgsOrgTeamsTeamMembersUsername.ts +1
@@ -11,4 +11,5 @@ export const route: Route = {
1111 not_found: "no such team, or the user is not in it",
1212 last_owner: "409, an organisation keeps at least one owner; make someone else an owner first",
1313 },
14 refuses: [401, 404],
1415 };
src/contract/openapi/routes/deleteApiV1ReposOwnerName.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 refusals: { not_found: "404: no such repository, or the caller is not its admin", delete_failed: "500: the repository could not be removed" },
10 refuses: [401, 404],
1011 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameApp.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "delete", path: `${REPO}/app`, summary: "Turn the app off (admin scope); answers {}", auth: true, role: "member" };
3 export const route: Route = { method: "delete", path: `${REPO}/app`, summary: "Turn the app off (admin scope); answers {}", auth: true, role: "member", refuses: [401, 404] };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameAppDomainsHost.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "delete", path: `${REPO}/app/domains/{host}`, summary: "Remove a domain from the app (admin scope); answers {}", auth: true, role: "member" };
3 export const route: Route = { method: "delete", path: `${REPO}/app/domains/{host}`, summary: "Remove a domain from the app (admin scope); answers {}", auth: true, role: "member", refuses: [401, 404] };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameAppEnvVar.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 query: { scope: "string" },
10 refuses: [401, 404],
1011 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBranchesBranch.ts +1
@@ -14,4 +14,5 @@ export const route: Route = {
1414 unknown_branch: "no such branch (404)",
1515 origin_refused: "a mirror's origin refused the deletion",
1616 },
17 refuses: [401, 404],
1718 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBuildsLabel.ts +1
@@ -14,4 +14,5 @@ export const route: Route = {
1414 moved: "409: the pin changed while it was being deleted",
1515 git_failed: "422: git refused the change",
1616 },
17 refuses: [401, 404],
1718 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameBuildsLabelShotsFile.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 query: { at: "string" },
1010 status: 204,
1111 refusals: { ...SHOT_REFUSALS, no_such_shot: "404: the pin has no screenshot by that name" },
12 refuses: [401, 404],
1213 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameCrewUsername.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 refusals: { no_such_agent: "`username` names no one on the crew" },
10 refuses: [401, 404],
1011 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameDeskId.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "delete", path: `${REPO}/desk/{id}`, summary: "Clear a note (rw scope, repository writer who is its author, or a site admin); answers 204 with no body, 404 when there is no such note, 403 not_yours for another's", auth: true, role: "member", status: 204, refusals: { not_yours: "403: only the note's author or an admin clears it" } };
3 export const route: Route = { method: "delete", path: `${REPO}/desk/{id}`, summary: "Clear a note (rw scope, repository writer who is its author, or a site admin); answers 204 with no body, 404 when there is no such note, 403 not_yours for another's", auth: true, role: "member", status: 204, refusals: { not_yours: "403: only the note's author or an admin clears it" }, refuses: [401, 404] };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameDropFile.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "Remove a dropped file (rw scope, a writer's); 404 no such file, or not yours to see",
77 auth: true,
88 role: "member",
9 refuses: [401, 404],
910 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameEgressGrants.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 body: { destination: "string" },
10 refuses: [401, 404],
1011 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameHooksId.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "delete", path: `${REPO}/hooks/{id}`, summary: "Remove a webhook (admin scope); answers {}, 404 when it is not there", auth: true, role: "member" };
3 export const route: Route = { method: "delete", path: `${REPO}/hooks/{id}`, summary: "Remove a webhook (admin scope); answers {}, 404 when it is not there", auth: true, role: "member", refuses: [401, 404] };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameIssuesNumberDependenciesBlocker.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "Stop an issue waiting for another",
77 auth: true,
88 role: "member",
9 refuses: [401, 404],
910 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameLabelsId.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "delete", path: `${REPO}/labels/{id}`, summary: "Remove a label by id (admin scope, repository admin); answers 204 with no body, 404 when the repository has no such label", auth: true, role: "member", status: 204 };
3 export const route: Route = { method: "delete", path: `${REPO}/labels/{id}`, summary: "Remove a label by id (admin scope, repository admin); answers 204 with no body, 404 when the repository has no such label", auth: true, role: "member", status: 204, refuses: [401, 404] };
src/contract/openapi/routes/deleteApiV1ReposOwnerNameMilestonesNumberWatch.ts +1
@@ -11,4 +11,5 @@ export const route: Route = {
1111 forbidden: "403: only a person watches a milestone",
1212 not_found: "404: no such repository, or it is not readable, or the number is no milestone",
1313 },
14 refuses: [401, 404],
1415 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePromptsId.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "delete", path: `${REPO}/prompts/{id}`, summary: "Remove a prompt source (admin scope); answers {}", auth: true, role: "member" };
3 export const route: Route = { method: "delete", path: `${REPO}/prompts/{id}`, summary: "Remove a prompt source (admin scope); answers {}", auth: true, role: "member", refuses: [401, 404] };
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePullsNumberHold.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "member",
1010 refusals: { forbidden: "you are an agent, or you cannot write the repository (403)" },
11 refuses: [401, 404],
1112 };
src/contract/openapi/routes/deleteApiV1ReposOwnerNamePullsNumberThreadsAnchorResolve.ts +1
@@ -10,4 +10,5 @@ export const route: Route = {
1010 not_found: "the pull has no thread at `anchor` (404)",
1111 forbidden: "you neither wrote the thread's comments nor can write to the repository (403)",
1212 },
13 refuses: [401, 404],
1314 };
src/contract/openapi/routes/deleteApiV1SecretsScopeName.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 role: "member",
99 query: { ref: "string" },
1010 refusals: { not_found: "no such secret or scope owner", invalid_scope: "the scope is not one the forge keeps secrets for" },
11 refuses: [401, 404],
1112 };
src/contract/openapi/routes/deleteApiV1TimersKey.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 refusals: { not_found: "404: no pending timer has that key", unauthorized: "401: not an app's own token" },
10 refuses: [401],
1011 };
src/contract/openapi/routes/deleteApiV1TokensId.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 role: "member",
99 status: 204,
1010 refusals: { forbidden: "the caller holds a bearer token, which cannot manage tokens" },
11 refuses: [401, 404],
1112 };
src/contract/openapi/routes/deleteApiV1UserKeysId.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 role: "member",
99 status: 204,
1010 refusals: { unauthorized: "401: no valid credentials were sent", forbidden: "403: the token scope is below rw, or a browser session sent a cross-origin request", not_found: "404: none of your keys has this id" },
11 refuses: [401, 404],
1112 };
src/contract/openapi/routes/deleteApiV1UserOriginAppsId.ts +1
@@ -12,4 +12,5 @@ export const route: Route = {
1212 forbidden: "403: a cross-origin browser request, or a token without admin scope",
1313 not_found: "404: no such application of yours",
1414 },
15 refuses: [401, 404],
1516 };
src/contract/openapi/routes/deleteApiV1UserOriginsId.ts +1
@@ -11,4 +11,5 @@ export const route: Route = {
1111 auth: true,
1212 role: "member",
1313 refusals: { unauthorized: U, forbidden: F, not_found: NF },
14 refuses: [401, 404],
1415 };
src/contract/openapi/routes/deleteApiV1UserPinsOwnerName.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 role: "member",
99 status: 204,
1010 refusals: { unauthorized: "401: no valid credentials were sent", forbidden: "403: the token scope is below rw, or a browser session sent a cross-origin request", not_found: "404: no such repository, or it is not readable by the caller" },
11 refuses: [401, 404],
1112 };
src/contract/openapi/routes/getApiV1AdminBillingFunnel.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminCapacity.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminCrawlers.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminInvites.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 query: { limit: limitTo(OFFSET_LIMIT_MAX), cursor: "string" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminKpisProbe.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminLimits.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminMachinesMachineDisks.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge, or the machine has no readings" },
11 refuses: [401],
1112 };
src/contract/openapi/routes/getApiV1AdminPeople.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 auth: true,
1010 role: "admin",
1111 query: { limit: limitTo(OFFSET_LIMIT_MAX), cursor: "string" },
12 refuses: [404],
1213 };
src/contract/openapi/routes/getApiV1AdminProfile.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge", busy: "a sample is already running" },
11 refuses: [403, 404],
1112 };
src/contract/openapi/routes/getApiV1AdminQuotas.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminRequests.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "The strangers waiting for an account, oldest first (a forge admin's, read scope; anyone else gets 404); answers { items: [{ username, note, source, state, askedAt, decidedAt }], next_cursor }",
77 auth: true,
88 role: "admin",
9 refuses: [404],
910 };
src/contract/openapi/routes/getApiV1AdminRunners.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 "The enrolled runners, each with when it last asked for work (seenAt, milliseconds; 0 for never); answers { items, next_cursor }",
88 auth: true,
99 role: "admin",
10 refuses: [404],
1011 };
src/contract/openapi/routes/getApiV1AdminShield.ts +1
@@ -10,4 +10,5 @@ export const route: Route = {
1010 not_found: "the token is not a forge admin (404)",
1111 not_admin: "the person's role may not administer the forge (403)",
1212 },
13 refuses: [404],
1314 };
src/contract/openapi/routes/getApiV1AdminSubscriptions.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_admin: "the caller is not a forge admin (403)" },
11 refuses: [401],
1112 };
src/contract/openapi/routes/getApiV1AdminTeams.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminTrafficProbe.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge, or the scope names no app" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1AdminTrafficVisitors.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "admin",
1010 refusals: { not_found: "the token is not a person who administers the forge" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1Agents.ts +1 −1
@@ -1,3 +1,3 @@
11 import type { Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: "/api/v1/agents", summary: "List the crew's agents; answers { items, next_cursor: null }; needs a signed-in caller, anonymous gets 401", auth: true, role: "member" };
3 export const route: Route = { method: "get", path: "/api/v1/agents", summary: "List the crew's agents; answers { items, next_cursor: null }; needs a signed-in caller, anonymous gets 401", auth: true, role: "member", refuses: [401] };
src/contract/openapi/routes/getApiV1AgentsUsername.ts +9 −1
@@ -1,3 +1,11 @@
11 import type { Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: "/api/v1/agents/{username}", summary: "Read one agent; the brief, model and budget show to those who may see them", auth: false, role: "anonymous", refusals: { not_found: "no such agent, or not yours to see" } };
3 export const route: Route = {
4 method: "get",
outdated

An anonymous, auth:false route should not need a 401. Fix the route's role/auth in the contract or the test call, don't document the status to quiet the test.

5 path: "/api/v1/agents/{username}",
6 summary: "Read one agent; the brief, model and budget show to those who may see them; needs a signed-in caller, anonymous gets 401",
7 auth: true,
8 role: "member",
9 refusals: { not_found: "no such agent, or not yours to see" },
10 refuses: [401, 404],
11 };
src/contract/openapi/routes/getApiV1AppTemplates.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "member",
1010 refusals: {},
11 refuses: [401],
1112 };
src/contract/openapi/routes/getApiV1Asked.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 role: "member",
1010 query: { show: "string", order: "string", repo: "string" },
1111 refusals: { invalid_show: "show is all, unshipped or flagged", invalid_order: ORDER_WORDS },
12 refuses: [401],
1213 };
src/contract/openapi/routes/getApiV1Asks.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "What asks the caller, ranked, with the week's measure (ro scope; never cached)",
77 auth: true,
88 role: "member",
9 refuses: [401],
910 };
src/contract/openapi/routes/getApiV1AsksAdmin.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 refusals: {
1010 unauthorized: "no valid credentials were sent",
1111 },
12 refuses: [401],
1213 };
src/contract/openapi/routes/getApiV1Boards.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "List the owner's boards; answers { boards: [{ slug, title, range, refresh, panels }] }. Site admin people only",
77 auth: true,
88 role: "admin",
9 refuses: [401],
910 };
src/contract/openapi/routes/getApiV1BoardsPins.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "List the owner's pinned panels in order; answers { pins: [{ slug, title, panel }] }",
77 auth: true,
88 role: "admin",
9 refuses: [401],
910 };
src/contract/openapi/routes/getApiV1BoardsSlug.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "Read one board: { slug, title, range, refresh, panels: [{ title, chart, query, w, h }] }",
77 auth: true,
88 role: "admin",
9 refuses: [401, 404],
910 };
src/contract/openapi/routes/getApiV1BoardsSlugPanelsId.ts +1
@@ -13,4 +13,5 @@ export const route: Route = {
1313 invalid_window: "from, to or step is not a window (422)",
1414 bad_query: "the panel's query cannot run (400)",
1515 },
16 refuses: [401, 404],
1617 };
src/contract/openapi/routes/getApiV1BoardsSources.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "List the sources a board query reads; answers { sources: [{ name, time, columns, docs? }] }",
77 auth: true,
88 role: "admin",
9 refuses: [401],
910 };
src/contract/openapi/routes/getApiV1CloudAccounts.ts +1
@@ -10,4 +10,5 @@ export const route: Route = {
1010 forbidden: "a read-only token cannot list cloud accounts",
1111 not_found: "only a forge administrator sees this route",
1212 },
13 refuses: [401],
1314 };
src/contract/openapi/routes/getApiV1Codes.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "admin",
99 refusals: { not_found: "the token is not a person who administers the forge (404)" },
10 refuses: [404],
1011 };
src/contract/openapi/routes/getApiV1ConversationFilesId.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 refusals: { not_found: "no such attachment (404)" },
10 refuses: [401, 404],
1011 };
src/contract/openapi/routes/getApiV1ConversationTurns.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 role: "member",
1010 query: { limit: limitTo(MAX_PAGE), before: "string", conversation: "string" },
1111 reply: { running: "boolean", turns: "array" },
12 refuses: [401],
1213 };
src/contract/openapi/routes/getApiV1Conversations.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 role: "member",
99 query: { archived: "string" },
1010 reply: { conversations: "array" },
11 refuses: [401],
1112 };
src/contract/openapi/routes/getApiV1ConversationsIdBuild.ts +1
@@ -12,4 +12,5 @@ export const route: Route = {
1212 unauthorized: "sign in (401)",
1313 forbidden: "the request is cross-origin, or the token may only read",
1414 },
15 refuses: [401, 404],
1516 };
src/contract/openapi/routes/getApiV1ConversationsIdBuildVersionsNDiff.ts +1
@@ -12,4 +12,5 @@ export const route: Route = {
1212 unauthorized: "sign in (401)",
1313 forbidden: "the request is cross-origin, or the token may only read",
1414 },
15 refuses: [401, 404],
1516 };
src/contract/openapi/routes/getApiV1Credit.ts +2
@@ -8,4 +8,6 @@ export const route: Route = {
88 auth: true,
99 role: "member",
1010 refusals: { not_found: "no parent funds this forge" },
11 errorStatus: { 404: "`not_found`: no parent funds this forge" },
12 refuses: [401],
1113 };
src/contract/openapi/routes/getApiV1CrewNow.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 refusals: { unauthorized: "no valid credentials were sent" },
10 refuses: [401],
1011 };
src/contract/openapi/routes/getApiV1CrewScorecard.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "admin",
99 refusals: { unauthorized: "no valid credentials were sent", forbidden: "the caller is not a forge admin" },
10 refuses: [401],
1011 };
src/contract/openapi/routes/getApiV1CrewWeek.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "admin",
99 refusals: { unauthorized: "no valid credentials were sent", forbidden: "the caller is not a forge admin" },
10 refuses: [401],
1011 };
src/contract/openapi/routes/getApiV1Features.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 refusals: { not_found: "you are not a site admin" },
10 errorStatus: { 404: "`not_found`: the caller is not a site admin" },
1011 };
src/contract/openapi/routes/getApiV1FeaturesSlug.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: false,
88 role: "anonymous",
99 refusals: { not_found: "no such app, or one you may not read", not_a_feature: "the app's forge.json declares no feature (422)" },
10 refuses: [404],
1011 };
src/contract/openapi/routes/getApiV1FeaturesSlugFeed.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: false,
88 role: "anonymous",
99 refusals: { not_found: "no such app, or one you may not read", not_a_feature: "the app's forge.json declares no feature (422)" },
10 refuses: [404],
1011 };
src/contract/openapi/routes/getApiV1Feed.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 role: "member",
1010 query: { limit: limitTo(FEED_LIMIT_MAX), cursor: "string", before: "string" },
1111 refusals: { invalid_limit: "limit is not a whole number from 1 to 50 (422)", invalid_cursor: "the cursor was not issued here (422)" },
12 refuses: [401],
1213 };
src/contract/openapi/routes/getApiV1FeedChips.ts +1
@@ -6,4 +6,5 @@ export const route: Route = {
66 summary: "The chips the caller switched off, kinds of post and people (ro scope; never cached); answers { kinds, people }",
77 auth: true,
88 role: "member",
9 refuses: [401],
910 };
src/contract/openapi/routes/getApiV1FeedLikes.ts +2
@@ -7,4 +7,6 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 query: { item: "string", app: "string", before: "string" },
10 errorStatus: { 422: "`item`, `app` or `before` is not valid: `message` names it" },
11 refuses: [401],
1012 };
src/contract/openapi/routes/getApiV1Flags.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: true,
99 role: "member",
1010 refusals: { forbidden: "the token is not a person who administers the forge" },
11 refuses: [401, 403],
1112 };
src/contract/openapi/routes/getApiV1FleetGraph.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 role: "member",
99 query: { repo: "string" },
1010 refusals: { invalid_selection: "`repo` is not a list of owner/name" },
11 refuses: [401],
1112 };
src/contract/openapi/routes/getApiV1FleetOps.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 role: "member",
1010 query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" },
1111 refusals: { invalid_limit: "limit is not a whole number from 1 to 200 (422)" },
12 refuses: [401],
1213 };
src/contract/openapi/routes/getApiV1FleetOpsId.ts +1 −1
@@ -1,3 +1,3 @@
11 import type { Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: "/api/v1/fleet/ops/{id}", summary: "Read one fleet operation and what it changed", auth: false, role: "anonymous" };
3 export const route: Route = { method: "get", path: "/api/v1/fleet/ops/{id}", summary: "Read one fleet operation and what it changed", auth: false, role: "anonymous", refuses: [404] };
src/contract/openapi/routes/getApiV1FleetRows.ts +1
@@ -12,4 +12,5 @@ export const route: Route = {
1212 invalid_sort: "sort is not a column of the kind (422)",
1313 },
1414 reply: { kind: "string", columns: "array", items: "array" },
15 errorStatus: { 422: "The kind, sort or filter is not valid: `message` names the field" },
1516 };
src/contract/openapi/routes/getApiV1Forge.ts +9 −1
@@ -1,3 +1,11 @@
11 import type { Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: "/api/v1/forge", summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent", auth: false, role: "anonymous", refusals: { not_found: "404: this forge was not spawned" } };
3 export const route: Route = {
4 method: "get",
5 path: "/api/v1/forge",
6 summary: "A spawned forge's word about itself: { claimed, lastActivityAt, link? }; lastActivityAt, link ({ state, revokedAt, usedAt }) are null or absent, as is madeFrom ({ template, at }), unless the parent's secret is sent",
7 auth: false,
8 role: "anonymous",
9 refusals: { not_found: "404: this forge was not spawned" },
10 errorStatus: { 404: "`not_found`: this forge was not spawned" },
11 };
src/contract/openapi/routes/getApiV1ForgeEconomics.ts +1
@@ -10,4 +10,5 @@ export const route: Route = {
1010 not_found: "the token is not a person who administers the forge (404)",
1111 not_admin: "the person's role may not administer the forge (403)",
1212 },
13 refuses: [404],
1314 };
src/contract/openapi/routes/getApiV1ForgeView.ts +1
@@ -7,4 +7,5 @@ export const route: Route = {
77 auth: true,
88 role: "member",
99 refusals: { unauthorized: "no valid credentials were sent" },
10 refuses: [401],
1011 };
src/contract/openapi/routes/getApiV1Keeper.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 refusals: {
1010 forbidden: "the release history is for the forge's administrators and its repository's readers",
1111 },
12 errorStatus: { 403: "`forbidden`: the release history is for the forge's administrators and its repository's readers" },
1213 };
src/contract/openapi/routes/getApiV1OffersReceipt.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: false,
99 role: "anonymous",
1010 refusals: { not_found: "404: no offer has this receipt" },
11 refuses: [404],
1112 };
src/contract/openapi/routes/getApiV1OrgsOrg.ts +1 −1
@@ -1,3 +1,3 @@
11 import type { Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: "/api/v1/orgs/{org}", summary: "Read one organization's public profile plus `teams`, the teams the caller may see: all for an org admin, only their own for a member, [] for a stranger or anonymous caller", auth: false, role: "anonymous" };
3 export const route: Route = { method: "get", path: "/api/v1/orgs/{org}", summary: "Read one organization's public profile plus `teams`, the teams the caller may see: all for an org admin, only their own for a member, [] for a stranger or anonymous caller", auth: false, role: "anonymous", refuses: [404] };
src/contract/openapi/routes/getApiV1OrgsOrgTeams.ts +1 −1
@@ -1,4 +1,4 @@
11 import { type Route, limitTo } from "../shared.ts";
22 import { LIST_LIMIT_MAX } from "../../../core/issues.ts";
33
4 export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams", summary: "List an organization's teams; answers { items, next_cursor }, paged by `limit` and `cursor`: all for an org admin, only the caller's own teams for a member, [] for a stranger or anonymous caller; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" } };
4 export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams", summary: "List an organization's teams; answers { items, next_cursor }, paged by `limit` and `cursor`: all for an org admin, only the caller's own teams for a member, [] for a stranger or anonymous caller; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] };
src/contract/openapi/routes/getApiV1OrgsOrgTeamsTeamMembers.ts +1 −1
@@ -1,4 +1,4 @@
11 import { type Route, limitTo } from "../shared.ts";
22 import { LIST_LIMIT_MAX } from "../../../core/issues.ts";
33
4 export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams/{team}/members", summary: "List a team's members as public profiles; answers { items, next_cursor }, paged by `limit` and `cursor`; 404 when the caller may not see the team; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" } };
4 export const route: Route = { method: "get", path: "/api/v1/orgs/{org}/teams/{team}/members", summary: "List a team's members as public profiles; answers { items, next_cursor }, paged by `limit` and `cursor`; 404 when the caller may not see the team; the 200 carries a weak etag of the exact JSON and cache-control private, no-cache, and a repeat sending If-None-Match gets 304 with no body once access is checked", auth: false, role: "anonymous", alsoStatus: [304], query: { limit: limitTo(LIST_LIMIT_MAX), cursor: "string" }, refuses: [404] };
src/contract/openapi/routes/getApiV1PacksName.ts +1 −1
@@ -1,3 +1,3 @@
11 import type { Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: "/api/v1/packs/{name}", summary: "One curated pack: { name, title, pitch, brief, shown } (shown: the public repos on this forge), and for a person admin also repos, left_out and the history of who changed what and when", auth: false, role: "anonymous", refusals: { not_found: "404: no such pack" } };
3 export const route: Route = { method: "get", path: "/api/v1/packs/{name}", summary: "One curated pack: { name, title, pitch, brief, shown } (shown: the public repos on this forge), and for a person admin also repos, left_out and the history of who changed what and when", auth: false, role: "anonymous", refusals: { not_found: "404: no such pack" }, refuses: [404] };
src/contract/openapi/routes/getApiV1PassportHealth.ts +1
@@ -8,4 +8,5 @@ export const route: Route = {
88 auth: false,
99 role: "anonymous",
1010 refusals: { unauthorized: "the passport is missing, malformed, expired, or not for this audience and scope (always 401)" },
11 errorStatus: { 401: "`unauthorized`: the passport is missing, malformed, expired, or not for this audience and scope" },
1112 };
src/contract/openapi/routes/getApiV1ReachAsks.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 refusals: {
1010 unauthorized: "no valid credentials were sent",
1111 },
12 refuses: [401],
1213 };
src/contract/openapi/routes/getApiV1ReposOwnerName.ts +1
@@ -9,4 +9,5 @@ export const route: Route = {
99 auth: false,
1010 role: "anonymous",
1111 refusals: { not_found: "404: no such repository, or it is not readable by the caller" },
12 refuses: [404],
1213 };
src/contract/openapi/routes/getApiV1ReposOwnerNameApp.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: `${REPO}/app`, summary: "Read the repository's app: its settings, environments and state", auth: false, role: "anonymous" };
3 export const route: Route = { method: "get", path: `${REPO}/app`, summary: "Read the repository's app: its settings, environments and state", auth: false, role: "anonymous", refuses: [404] };
src/contract/openapi/routes/getApiV1ReposOwnerNameAppDomains.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: `${REPO}/app/domains`, summary: "List the app's own domains (admin scope); answers { items, next_cursor }", auth: true, role: "member" };
3 export const route: Route = { method: "get", path: `${REPO}/app/domains`, summary: "List the app's own domains (admin scope); answers { items, next_cursor }", auth: true, role: "member", refuses: [401, 404] };

301 more files not shown.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs