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

The OpenAPI document describes accepting and dismissing a report, confirming a wait, a milestone's limb and proposal tokens #5176

Parked opened this
Closed without merging

scout/forge:scout/5115-the-openapi-document-describes-accepting → main 5 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +100 −0
src/contract/openapi/routes/index.ts +5
@@ -163,11 +163,14 @@ export { route as postApiV1ReposOwnerNameHooks } from "./postApiV1ReposOwnerName
163163 export { route as postApiV1ReposOwnerNameIssues } from "./postApiV1ReposOwnerNameIssues.ts";
164164 export { route as postApiV1ReposOwnerNameIssuesNumberComments } from "./postApiV1ReposOwnerNameIssuesNumberComments.ts";
165165 export { route as postApiV1ReposOwnerNameIssuesNumberDependencies } from "./postApiV1ReposOwnerNameIssuesNumberDependencies.ts";
166 export { route as postApiV1ReposOwnerNameIssuesNumberDependenciesBlockerConfirm } from "./postApiV1ReposOwnerNameIssuesNumberDependenciesBlockerConfirm.ts";
166167 export { route as postApiV1ReposOwnerNameIssuesNumberPrivate } from "./postApiV1ReposOwnerNameIssuesNumberPrivate.ts";
167168 export { route as postApiV1ReposOwnerNameMakeItYours } from "./postApiV1ReposOwnerNameMakeItYours.ts";
169 export { route as postApiV1ReposOwnerNameMilestonesNumberLimb } from "./postApiV1ReposOwnerNameMilestonesNumberLimb.ts";
168170 export { route as postApiV1ReposOwnerNameOriginReconnect } from "./postApiV1ReposOwnerNameOriginReconnect.ts";
169171 export { route as postApiV1ReposOwnerNamePlan } from "./postApiV1ReposOwnerNamePlan.ts";
170172 export { route as postApiV1ReposOwnerNamePrompts } from "./postApiV1ReposOwnerNamePrompts.ts";
173 export { route as postApiV1ReposOwnerNameProposalTokens } from "./postApiV1ReposOwnerNameProposalTokens.ts";
171174 export { route as postApiV1ReposOwnerNamePulls } from "./postApiV1ReposOwnerNamePulls.ts";
172175 export { route as postApiV1ReposOwnerNamePullsNumberApproveHere } from "./postApiV1ReposOwnerNamePullsNumberApproveHere.ts";
173176 export { route as postApiV1ReposOwnerNamePullsNumberChecks } from "./postApiV1ReposOwnerNamePullsNumberChecks.ts";
@@ -175,6 +178,8 @@ export { route as postApiV1ReposOwnerNamePullsNumberMerge } from "./postApiV1Rep
175178 export { route as postApiV1ReposOwnerNamePullsNumberReviews } from "./postApiV1ReposOwnerNamePullsNumberReviews.ts";
176179 export { route as postApiV1ReposOwnerNamePullsNumberThreadsAnchorResolve } from "./postApiV1ReposOwnerNamePullsNumberThreadsAnchorResolve.ts";
177180 export { route as postApiV1ReposOwnerNameReports } from "./postApiV1ReposOwnerNameReports.ts";
181 export { route as postApiV1ReposOwnerNameReportsIdAccept } from "./postApiV1ReposOwnerNameReportsIdAccept.ts";
182 export { route as postApiV1ReposOwnerNameReportsIdDismiss } from "./postApiV1ReposOwnerNameReportsIdDismiss.ts";
178183 export { route as postApiV1ReposOwnerNameRunsIdCancel } from "./postApiV1ReposOwnerNameRunsIdCancel.ts";
179184 export { route as postApiV1ReposOwnerNameSpend } from "./postApiV1ReposOwnerNameSpend.ts";
180185 export { route as postApiV1ReposOwnerNameSync } from "./postApiV1ReposOwnerNameSync.ts";
src/contract/openapi/routes/postApiV1ReposOwnerNameIssuesNumberDependenciesBlockerConfirm.ts added +15
@@ -0,0 +1,15 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: `${REPO}/issues/{number}/dependencies/{blocker}/confirm`,
6 summary:
7 "Confirm that an issue may go ahead although its blocker closed as dropped or split (rw scope; a person who writes, never the crew); answers 204",
8 auth: true,
9 status: 204,
10 refusals: {
11 not_found: "no such issue or blocker, or not yours to see (422)",
12 unauthorized: "no account (422)",
13 forbidden: "not a person who writes to the repository, or a crew member (422)",
outdated

Nit: the handler answers this through respondAccess(confirmed.error, 422), so a refusal comes back with status 422. Consider noting "(422)" as the other rows do.

14 },
15 };
src/contract/openapi/routes/postApiV1ReposOwnerNameMilestonesNumberLimb.ts added +16
@@ -0,0 +1,16 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: `${REPO}/milestones/{number}/limb`,
6 summary:
7 "Act on a whole limb: defer, resume, close, raise, lower, replan or takeback. A dry run unless `dryRun` is false (ro scope); applied needs an admin token and answers 201 with the receipt, undone at /api/v1/fleet/ops/{id}/undo",
8 auth: true,
9 body: { action: "string", dryRun: "boolean", reason: "string", pillar: "string", under: "string" },
10 refusals: {
11 bad_action: "action is not defer, resume, close, raise, lower, replan or takeback (422)",
12 not_found: "no such repository or milestone, or not yours to see",
13 unauthorized: "no account",
14 forbidden: "the caller may not act on this limb",
15 },
16 };
src/contract/openapi/routes/postApiV1ReposOwnerNameProposalTokens.ts added +17
@@ -0,0 +1,17 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: `${REPO}/proposal-tokens`,
6 summary:
7 "Hand a child its own narrow credential to propose pulls to this repository (rw scope; a writer's); answers 201 with the token, whose secret shows once",
8 auth: true,
9 status: 201,
10 body: { child: "string", origin: "string", childRepo: "string" },
11 refusals: {
12 invalid_child: "child is not an acceptable name",
13 invalid_origin: "origin is not an acceptable origin",
14 too_large: "the body is over its byte limit (413)",
15 not_found: "no such repository, or not one the caller writes to",
16 },
17 };
src/contract/openapi/routes/postApiV1ReposOwnerNameReportsIdAccept.ts added +17
@@ -0,0 +1,17 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: `${REPO}/reports/{id}/accept`,
6 summary:
7 "Accept a waiting report as an issue labelled outside (rw scope; a writer who is not on the crew); answers 201 with the issue; `title` rewords it, the marker stays",
8 auth: true,
9 status: 201,
10 body: { title: "string" },
11 refusals: {
12 not_found: "no such repository or report, or not yours to decide",
13 forbidden: "not a person who writes to the repository",
14 decided: "the report was already accepted or dismissed (409)",
15 mirrored: "the repository mirrors an origin (409)",
16 },
17 };
src/contract/openapi/routes/postApiV1ReposOwnerNameReportsIdDismiss.ts added +13
@@ -0,0 +1,13 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: `${REPO}/reports/{id}/dismiss`,
6 summary: "Dismiss a waiting report (rw scope; a writer who is not on the crew); answers { id, state: \"dismissed\" }",
7 auth: true,
8 refusals: {
9 not_found: "no such repository or report, or not yours to decide",
10 forbidden: "not a person who writes to the repository",
11 decided: "the report was already accepted or dismissed (409)",
12 },
13 };
test/openapi.test.ts +17
@@ -236,6 +236,23 @@ test("an app's routes are described, and env values are never read back", () =>
236236 expect(doc.paths[`${A}/{env}/redeploy`].post.responses["202"]).toBeDefined();
237237 });
238238
239 test("triage, confirming a wait, a limb and proposal tokens are described", () => {
240 const doc = openapi("https://f.test", "1") as any;
241 const R = "/api/v1/repos/{owner}/{name}";
242 for (const [path, status] of [
243 [`${R}/reports/{id}/accept`, "201"],
244 [`${R}/reports/{id}/dismiss`, "200"],
245 [`${R}/issues/{number}/dependencies/{blocker}/confirm`, "204"],
246 [`${R}/milestones/{number}/limb`, "200"],
247 [`${R}/proposal-tokens`, "201"],
248 ] as const) {
249 const op = doc.paths[path]?.post;
250 expect(op, path).toBeDefined();
251 expect(op.security, path).toBeDefined();
252 expect(op.responses[status], `${path} ${status}`).toBeDefined();
253 }
254 });
255
239256 test("mirroring and forking from an origin, its job and stream, and origin apps are described", () => {
240257 const doc = openapi("https://f.test", "1") as any;
241258 const want: [string, string][] = [

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs