Public: anyone can read this; the crew can change it.
The OpenAPI description has one canonical URL: /api/v1/openapi.json and /openapi.json send readers to /contract/openapi.json #14345
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14273-the-openapi-description-has-one-canonica → main 1 commit fork
3 files
changed +21
−3
docs/MCP.md +1 −1
| @@ -675,7 +675,7 @@ answers | ||
| 675 | 675 | and an owner, and that every verb names a tool or says why not. The 50 ms |
| 676 | 676 | budget is held by a bounded statement count; the `here` phase is read from |
| 677 | 677 | Server-Timing and bounded at the flake floor (`WALL_CLOCK_FLOOR_MS`). |
| 678 | - **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 | |
| 678 | - **Contract.** `GET /contract/openapi.json` is the one URL to name (the aliases `/openapi.json` and `/api/v1/openapi.json` answer the same 200 document and ETag, none redirects, and carry `Link: <…/contract/openapi.json>; rel="canonical"`; `servers` is the request's origin, bearer `token` is the default `security`, open routes say `security: []`) is OpenAPI 3.1 for the routes | |
| 679 | 679 | the manifest (`here`) names, plus `POST /mcp`, cut to the caller's role: no credential sees only `x-role: anonymous` |
| 680 | 680 | rows, a member's token or session adds `member`, a site admin sees `admin` too; each role gets its own ETag, and any |
| 681 | 681 | answer but the anonymous one is `cache-control: private` (`vary: authorization, cookie`). It also describes planning: `GET …/map`, `POST …/plan`, |
src/contract/served.ts +4 −2
| @@ -93,8 +93,10 @@ export const openapiHandler: Handler = (ctx) => { | ||
| 93 | 93 | etag: hit.etag, |
| 94 | 94 | vary: "accept-encoding, authorization, cookie", |
| 95 | 95 | }; |
| 96 | if (holds(ctx.request, hit.etag)) return new Response(null, { status: 304, headers }); | |
| 97 | const type = { "content-type": "application/json", ...headers }; | |
| 96 | const canon = ctx.url.pathname === "/contract/openapi.json" ? {} : { link: `<${ctx.url.origin}/contract/openapi.json>; rel="canonical"` }; | |
| 97 | if (holds(ctx.request, hit.etag)) return new Response(null, { status: 304, headers: { ...canon, ...headers } }); | |
| 98 | // The two aliases answer the same bytes, and say where the document lives. | |
| 99 | const type = { "content-type": "application/json", ...canon, ...headers }; | |
| 98 | 100 | // Encoded once per build at the slow, small level, not per request. |
| 99 | 101 | const encoding = negotiate(ctx.request.headers.get("accept-encoding")); |
| 100 | 102 | if (encoding !== null) { |
test/root-openapi.test.ts +16
| @@ -42,3 +42,19 @@ test("HEAD answers 200 too, and a matching If-None-Match answers 304", async () | ||
| 42 | 42 | const again = await fetch(`${servers.url}/openapi.json`, { headers: { "if-none-match": etag }, redirect: "manual" }); |
| 43 | 43 | expect(again.status).toBe(304); |
| 44 | 44 | }); |
| 45 | ||
| 46 | test("#14273: the aliases name the canonical URL; the canonical does not, and each keeps its 304", async () => { | |
| 47 | for (const path of ["/openapi.json", "/api/v1/openapi.json"]) { | |
| 48 | const res = await fetch(`${servers.url}${path}`, { redirect: "manual" }); | |
| 49 | expect(res.status).toBe(200); | |
| 50 | expect(res.headers.get("link")).toBe(`<${servers.url}/contract/openapi.json>; rel="canonical"`); | |
| 51 | const again = await fetch(`${servers.url}${path}`, { headers: { "if-none-match": res.headers.get("etag")! }, redirect: "manual" }); | |
| 52 | expect(again.status).toBe(304); | |
| 53 | expect(again.headers.get("link")).toContain('rel="canonical"'); | |
| 54 | } | |
| 55 | const canon = await fetch(`${servers.url}/contract/openapi.json`, { redirect: "manual" }); | |
| 56 | expect(canon.headers.get("link")).toBeNull(); | |
| 57 | expect(canon.headers.get("content-encoding")).toBe("br"); | |
| 58 | const again = await fetch(`${servers.url}/contract/openapi.json`, { headers: { "if-none-match": canon.headers.get("etag")! }, redirect: "manual" }); | |
| 59 | expect(again.status).toBe(304); | |
| 60 | }); |
new above
offline