Public: anyone can read this; the crew can change it.
GET /openapi.json answers the description itself, not a 308 the caller must follow #13076
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13071-get-openapi-json-answers-the-description → main 5 commits fork 1 thread · 1 unresolved
14 files
changed +79
−71
docs/MCP.md +1 −1
| @@ -663,7 +663,7 @@ answers | ||
| 663 | 663 | and an owner, and that every verb names a tool or says why not. The 50 ms |
| 664 | 664 | budget is held by a bounded statement count; the `here` phase is read from |
| 665 | 665 | Server-Timing and bounded at the flake floor (`WALL_CLOCK_FLOOR_MS`). |
| 666 | - **Contract.** `GET /contract/openapi.json` (also `/openapi.json`, `/api/v1/openapi.json`; `servers` is the request's origin, bearer `token` is the default `security`, open routes say `security: []`) is OpenAPI 3.1 for the routes | |
| 666 | - **Contract.** `GET /contract/openapi.json` (also `/openapi.json`, `/api/v1/openapi.json`, all three answer 200 with the document and an ETag, none redirects; `servers` is the request's origin, bearer `token` is the default `security`, open routes say `security: []`) is OpenAPI 3.1 for the routes | |
| 667 | 667 | the manifest (`here`) names, plus `POST /mcp`, cut to the caller's role: no credential sees only `x-role: anonymous` |
| 668 | 668 | rows, a member's token or session adds `member`, a site admin sees `admin` too; each role gets its own ETag, and any |
| 669 | 669 | answer but the anonymous one is `cache-control: private` (`vary: authorization, cookie`). It also describes planning: `GET …/map`, `POST …/plan`, |
src/contract/openapi/routes/getApiV1OpenapiJson.ts +1 −2
| @@ -3,8 +3,7 @@ import type { Route } from "../shared.ts"; | ||
| 3 | 3 | export const route: Route = { |
| 4 | 4 | method: "get", |
| 5 | 5 | path: "/api/v1/openapi.json", |
| 6 | summary: "The address an agent tries first: answers 308 to /contract/openapi.json, this document", | |
| 6 | summary: "The address an agent tries first: answers the same document as /contract/openapi.json", | |
| 7 | 7 | auth: false, |
| 8 | 8 | role: "anonymous", |
| 9 | status: 308, | |
| 10 | 9 | }; |
src/contract/openapi/routes/getContractOpenapiJson.ts +1 −1
| @@ -1,3 +1,3 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | export const route: Route = { method: "get", path: "/contract/openapi.json", summary: "This document: the OpenAPI 3.1 description of the forge's public API; /api/v1/openapi.json redirects here", auth: false, role: "anonymous" }; | |
| 3 | export const route: Route = { method: "get", path: "/contract/openapi.json", summary: "This document: the OpenAPI 3.1 description of the forge's public API; /openapi.json and /api/v1/openapi.json answer the same document", auth: false, role: "anonymous" }; |
src/contract/served.ts +33 −26
| @@ -68,31 +68,38 @@ export function openapiSliceText(origin: string, version: string, tag: string, r | ||
| 68 | 68 | return hit; |
| 69 | 69 | } |
| 70 | 70 | |
| 71 | /** | |
| 72 | * The document at its canonical path and at the root path an agent guesses; | |
| 73 | * /api/v1/openapi.json shares the handler. | |
| 74 | */ | |
| 71 | 75 | export function openapiRoute(router: Router<Handler>): void { |
| 72 | router.add("GET", "/contract/openapi.json", (ctx) => { | |
| 73 | const tag = ctx.url.searchParams.get("tag"); | |
| 74 | if (tag !== null && !TAGS.includes(tag)) { | |
| 75 | return Response.json( | |
| 76 | { error: "invalid_query", message: `unknown tag; the tags are ${TAGS.join(", ")}` }, | |
| 77 | { status: 400, headers: { "cache-control": "no-store" } }, | |
| 78 | ); | |
| 79 | } | |
| 80 | const role = roleOf(ctx.auth); | |
| 81 | const hit = tag === null ? openapiText(ctx.url.origin, running().version, role) : openapiSliceText(ctx.url.origin, running().version, tag, role); | |
| 82 | // The document depends on who asks: a shared cache keeps only the anonymous one. | |
| 83 | const headers = { | |
| 84 | "cache-control": role === "anonymous" ? "public, max-age=300" : "private, max-age=300", | |
| 85 | etag: hit.etag, | |
| 86 | vary: "accept-encoding, authorization, cookie", | |
| 87 | }; | |
| 88 | if (holds(ctx.request, hit.etag)) return new Response(null, { status: 304, headers }); | |
| 89 | const type = { "content-type": "application/json", ...headers }; | |
| 90 | // Encoded once per build at the slow, small level, not per request. | |
| 91 | const encoding = negotiate(ctx.request.headers.get("accept-encoding")); | |
| 92 | if (encoding !== null) { | |
| 93 | const bytes = encodeOnce(hit.etag, new TextEncoder().encode(hit.text), encoding); | |
| 94 | return new Response(bytes as Uint8Array<ArrayBuffer>, { headers: { ...type, "content-encoding": encoding } }); | |
| 95 | } | |
| 96 | return new Response(hit.text, { headers: type }); | |
| 97 | }); | |
| 76 | router.add("GET", "/contract/openapi.json", openapiHandler); | |
| 77 | router.add("GET", "/openapi.json", openapiHandler); | |
| 98 | 78 | } |
| 79 | ||
| 80 | export const openapiHandler: Handler = (ctx) => { | |
| 81 | const tag = ctx.url.searchParams.get("tag"); | |
| 82 | if (tag !== null && !TAGS.includes(tag)) { | |
| 83 | return Response.json( | |
| 84 | { error: "invalid_query", message: `unknown tag; the tags are ${TAGS.join(", ")}` }, | |
| 85 | { status: 400, headers: { "cache-control": "no-store" } }, | |
| 86 | ); | |
| 87 | } | |
| 88 | const role = roleOf(ctx.auth); | |
| 89 | const hit = tag === null ? openapiText(ctx.url.origin, running().version, role) : openapiSliceText(ctx.url.origin, running().version, tag, role); | |
| 90 | // The document depends on who asks: a shared cache keeps only the anonymous one. | |
| 91 | const headers = { | |
| 92 | "cache-control": role === "anonymous" ? "public, max-age=300" : "private, max-age=300", | |
| 93 | etag: hit.etag, | |
| 94 | vary: "accept-encoding, authorization, cookie", | |
| 95 | }; | |
| 96 | if (holds(ctx.request, hit.etag)) return new Response(null, { status: 304, headers }); | |
| 97 | const type = { "content-type": "application/json", ...headers }; | |
| 98 | // Encoded once per build at the slow, small level, not per request. | |
| 99 | const encoding = negotiate(ctx.request.headers.get("accept-encoding")); | |
| 100 | if (encoding !== null) { | |
| 101 | const bytes = encodeOnce(hit.etag, new TextEncoder().encode(hit.text), encoding); | |
| 102 | return new Response(bytes as Uint8Array<ArrayBuffer>, { headers: { ...type, "content-encoding": encoding } }); | |
| 103 | } | |
| 104 | return new Response(hit.text, { headers: type }); | |
| 105 | }; |
src/http/api.ts +6 −13
| @@ -8,6 +8,7 @@ | ||
| 8 | 8 | * back to continue); errors are `{ error, message }`. |
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | import { openapiHandler } from "../contract/served.ts"; | |
| 11 | 12 | import { CHECK_ASKED } from "../actions/pull_ask_words.ts"; |
| 12 | 13 | import { liveOf } from "../perf/live.ts"; |
| 13 | 14 | import { reviewWords } from "../actions/review_words.ts"; |
| @@ -4051,19 +4052,11 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 4051 | 4052 | return timePhase(ctx.request, "render", () => json(graph)); |
| 4052 | 4053 | }); |
| 4053 | 4054 | |
| 4054 | // The address an agent tries first. | |
| 4055 | router.add( | |
| 4056 | "GET", | |
| 4057 | "/api/v1/openapi.json", | |
| 4058 | () => | |
| 4059 | new Response(null, { | |
| 4060 | status: 308, | |
| 4061 | headers: { | |
| 4062 | location: "/contract/openapi.json", | |
| 4063 | "cache-control": "public, max-age=86400", | |
| 4064 | }, | |
| 4065 | }), | |
| 4066 | ); | |
| 4055 | // The address an agent tries first: the document itself, as /contract/openapi.json answers it. | |
| 4056 | router.add("GET", "/api/v1/openapi.json", (ctx) => { | |
| 4057 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); | |
| 4058 | return openapiHandler(ctx); | |
| 4059 | }); | |
| 4067 | 4060 | // What the caller can do on a forge page, as who they are (#604): the |
| 4068 | 4061 | // manifest every page links to. It differs by caller, so it is never cached. |
| 4069 | 4062 | router.add("GET", "/api/v1/here", (ctx) => { |
src/http/server.ts −6
| @@ -838,12 +838,6 @@ export function buildRouter(): Router<Handler> { | ||
| 838 | 838 | router.add("GET", "/agents", agentsPage); |
| 839 | 839 | router.add("GET", "/.well-known/change-password", changePassword); |
| 840 | 840 | router.add("GET", "/robots.txt", robotsTxt); |
| 841 | // The conventional path an agent guesses, answered as /api/v1/openapi.json is. | |
| 842 | router.add( | |
| 843 | "GET", | |
| 844 | "/openapi.json", | |
| 845 | () => new Response(null, { status: 308, headers: { location: "/contract/openapi.json", "cache-control": "public, max-age=86400" } }), | |
| 846 | ); | |
| 847 | 841 | router.add("GET", "/releases.json", releasesJson); |
| 848 | 842 | router.add("GET", "/sitemap.xml", sitemapXml); |
| 849 | 843 | router.add("GET", "/manifest.webmanifest", webManifest); |
test/api-root-contract-link.test.ts +2 −2
| @@ -27,11 +27,11 @@ test("the root's openapi link answers 200 with no redirect", async () => { | ||
| 27 | 27 | expect(res.status).toBe(200); |
| 28 | 28 | }); |
| 29 | 29 | |
| 30 | test("the 404 hint names the contract path, and the old path still redirects", async () => { | |
| 30 | test("the 404 hint names the contract path, and the old path still answers", async () => { | |
| 31 | 31 | const res = await fetch(`${servers.url}/api/v1/nope-nothing`, { headers: { accept: "application/json" } }); |
| 32 | 32 | const body = JSON.stringify(await res.json()); |
| 33 | 33 | expect(body).toContain("/contract/openapi.json"); |
| 34 | 34 | expect(body).not.toContain("/api/v1/openapi.json"); |
| 35 | 35 | const old = await fetch(`${servers.url}/api/v1/openapi.json`, { redirect: "manual" }); |
| 36 | expect(old.status).toBe(308); | |
| 36 | expect(old.status).toBe(200); | |
| 37 | 37 | }); |
test/mcp.test.ts +4 −5
| @@ -1624,13 +1624,12 @@ describe("the forge over MCP", () => { | ||
| 1624 | 1624 | expect(doc.paths[`${R}/pulls/{number}/labels`].put).toBeDefined(); |
| 1625 | 1625 | expect(doc.paths[`${R}/issues/{number}/private`].post.responses["201"]).toBeDefined(); |
| 1626 | 1626 | }); |
| 1627 | test("GET /api/v1/openapi.json redirects to the document", async () => { | |
| 1627 | test("GET /api/v1/openapi.json answers the document itself", async () => { | |
| 1628 | 1628 | const res = await fetch(`${base}/api/v1/openapi.json`, { redirect: "manual" }); |
| 1629 | expect(res.status).toBe(308); | |
| 1630 | expect(res.headers.get("location")).toBe("/contract/openapi.json"); | |
| 1629 | expect(res.status).toBe(200); | |
| 1630 | expect(res.headers.get("location")).toBeNull(); | |
| 1631 | 1631 | expect(res.headers.get("cache-control")).toContain("public"); |
| 1632 | const target = await fetch(new URL(res.headers.get("location")!, base)); | |
| 1633 | expect(target.status).toBe(200); | |
| 1632 | expect(res.headers.get("etag")).toBeTruthy(); | |
| 1634 | 1633 | }); |
| 1635 | 1634 | test("feed_chips reads and switches the chips the feed answers through", async () => { |
| 1636 | 1635 | app.bus.append({ kind: "app.serving", repoId: game.id, actorId: alice.id, payload: {} }); |
test/openapi-selfopen.test.ts +4 −4
| @@ -57,15 +57,15 @@ test("each path and method is in the served document", async () => { | ||
| 57 | 57 | const res = await adminOpenapi(app, servers.url, "/contract/openapi.json"); |
| 58 | 58 | const paths = ((await res.json()) as any).paths; |
| 59 | 59 | for (const [method, path] of WANT) expect(paths[path]?.[method]).toBeDefined(); |
| 60 | expect(paths["/api/v1/openapi.json"].get.responses["308"]).toBeDefined(); | |
| 60 | expect(paths["/api/v1/openapi.json"].get.responses["200"]).toBeDefined(); | |
| 61 | 61 | expect(paths["/api/v1/migrate"].post.responses["202"]).toBeDefined(); |
| 62 | 62 | expect(paths["/api/v1/migrate/{job}/stream"].get.summary).toContain("event stream"); |
| 63 | 63 | }); |
| 64 | 64 | |
| 65 | test("the redirect to the document is a 308", async () => { | |
| 65 | test("the old address answers the document, not a redirect", async () => { | |
| 66 | 66 | const res = await call("/api/v1/openapi.json"); |
| 67 | expect(res.status).toBe(308); | |
| 68 | expect(res.headers.get("location")).toBe("/contract/openapi.json"); | |
| 67 | expect(res.status).toBe(200); | |
| 68 | expect(res.headers.get("location")).toBeNull(); | |
| 69 | 69 | }); |
| 70 | 70 | |
| 71 | 71 | test("a bad source and a bad after answer the codes the rows name", async () => { |
test/root-openapi.test.ts +23 −6
| @@ -1,4 +1,4 @@ | ||
| 1 | /** #8330: /openapi.json at the root redirects to the contract, as /api/v1/openapi.json does. */ | |
| 1 | /** #13071: the guessed paths answer the description itself, not a 308 the caller must follow. */ | |
| 2 | 2 | import { afterAll, beforeAll, expect, test } from "bun:test"; |
| 3 | 3 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 4 | import { tmpdir } from "node:os"; |
| @@ -18,10 +18,27 @@ afterAll(async () => { | ||
| 18 | 18 | await rm(dataDir, { recursive: true, force: true }); |
| 19 | 19 | }); |
| 20 | 20 | |
| 21 | test("GET and HEAD /openapi.json answer 308 to the contract", async () => { | |
| 22 | for (const method of ["GET", "HEAD"]) { | |
| 23 | const res = await fetch(`${servers.url}/openapi.json`, { method, redirect: "manual" }); | |
| 24 | expect(res.status).toBe(308); | |
| 25 | expect(res.headers.get("location")).toBe("/contract/openapi.json"); | |
| 21 | test("every path answers 200 with the same document, an ETag and no redirect; every operation has an operationId", async () => { | |
| 22 | let canonical = ""; | |
| 23 | for (const path of ["/contract/openapi.json", "/openapi.json", "/api/v1/openapi.json"]) { | |
| 24 | const res = await fetch(`${servers.url}${path}`, { redirect: "manual" }); | |
| 25 | expect(res.status).toBe(200); | |
| 26 | expect(res.headers.get("location")).toBeNull(); | |
| 27 | expect(res.headers.get("etag")).toBeTruthy(); | |
| 28 | const text = await res.text(); | |
| 29 | if (canonical === "") canonical = text; | |
| 30 | expect(text).toBe(canonical); | |
| 31 | const doc = JSON.parse(text) as { openapi: string; paths: Record<string, Record<string, { operationId?: string }>> }; | |
| 32 | expect(doc.openapi).toStartWith("3.1"); | |
| 33 | for (const [p, ops] of Object.entries(doc.paths)) | |
| 34 | for (const [method, op] of Object.entries(ops)) expect(`${method} ${p} ${op.operationId ?? ""}`).toMatch(/ \S+$/); | |
| 26 | 35 | } |
| 27 | 36 | }); |
| 37 | ||
| 38 | test("HEAD answers 200 too, and a matching If-None-Match answers 304", async () => { | |
| 39 | const head = await fetch(`${servers.url}/openapi.json`, { method: "HEAD", redirect: "manual" }); | |
| 40 | expect(head.status).toBe(200); | |
| 41 | const etag = head.headers.get("etag")!; | |
| 42 | const again = await fetch(`${servers.url}/openapi.json`, { headers: { "if-none-match": etag }, redirect: "manual" }); | |
| 43 | expect(again.status).toBe(304); | |
| 44 | }); |
test/run-gate-doors.test.ts +1 −1
| @@ -159,7 +159,7 @@ describe("the run gate's closed doors", () => { | ||
| 159 | 159 | test("here, search, explore and openapi.json answer, and search names nothing outside the two repositories", async () => { |
| 160 | 160 | for (const path of ["/api/v1/here?path=/alice/upstream-work", "/api/v1/search?q=upstream", "/api/v1/explore"]) |
| 161 | 161 | expect((await call(path)).status).toBe(200); |
| 162 | expect((await call("/api/v1/openapi.json")).status).toBe(308); | |
| 162 | expect((await call("/api/v1/openapi.json")).status).toBe(200); | |
| 163 | 163 | for (const q of ["vault", "mine", "unique-vault", "unique-mine"]) { |
| 164 | 164 | const res = await call(`/api/v1/search?q=${q}`); |
| 165 | 165 | expect(res.status).toBe(200); |
test/run-token.test.ts +2 −2
| @@ -226,8 +226,8 @@ describe("a run token", () => { | ||
| 226 | 226 | expect((await text(`/api/v1/here?path=${path}`)).status).toBe(404); |
| 227 | 227 | |
| 228 | 228 | const open = await api("/api/v1/openapi.json", { redirect: "manual" }); |
| 229 | expect(open.status).toBe(308); | |
| 230 | expect(open.headers.get("location")).toBe("/contract/openapi.json"); | |
| 229 | expect(open.status).toBe(200); | |
| 230 | expect(open.headers.get("location")).toBeNull(); | |
| 231 | 231 | |
| 232 | 232 | const mine = await text("/api/v1/search?q=gods-eye"); |
| 233 | 233 | expect(mine.status).toBe(200); |
test/security-floor-every-route.test.ts +1 −1
| @@ -109,7 +109,7 @@ const SAMPLES: Sample[] = [ | ||
| 109 | 109 | body: "name=x", |
| 110 | 110 | }, |
| 111 | 111 | }, |
| 112 | { kind: "redirect", path: "/openapi.json", status: 308 }, | |
| 112 | { kind: "the API description at the guessed path", path: "/openapi.json", status: 200 }, | |
| 113 | 113 | { kind: "OPTIONS, answered as no route", path: "/api/v1", status: 404, init: { method: "OPTIONS" } }, |
| 114 | 114 | { kind: "liveness probe", path: "/healthz", status: 200 }, |
| 115 | 115 | { kind: "readiness probe", path: "/readyz", status: 200 }, |
test/server-timing-sweep.test.ts −1
| @@ -50,7 +50,6 @@ const REDIRECTS = new Set([ | ||
| 50 | 50 | "/big", |
| 51 | 51 | "/home", |
| 52 | 52 | "/login", |
| 53 | "/openapi.json", | |
| 54 | 53 | "/settings/origins/callback", |
| 55 | 54 | "/settings/resilience", |
| 56 | 55 | "/sign-in", |
new above
offline
The exported handler body is still indented one level too deep (4 spaces) and the file ends with an extra blank line after
};. Re-indent to 2 spaces and remove the trailing blank line.