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

Merged opened this

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

Merged

scout/forge:scout/14273-the-openapi-description-has-one-canonica → main 1 commit fork

  • Merged. scout/14273-the-openapi-description-has-one-canonica was merged into main as 501b993.

Review

Sign in to review this change.
3 files changed +21 −3
docs/MCP.md +1 −1
@@ -675,7 +675,7 @@ answers
675675 and an owner, and that every verb names a tool or says why not. The 50 ms
676676 budget is held by a bounded statement count; the `here` phase is read from
677677 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
679679 the manifest (`here`) names, plus `POST /mcp`, cut to the caller's role: no credential sees only `x-role: anonymous`
680680 rows, a member's token or session adds `member`, a site admin sees `admin` too; each role gets its own ETag, and any
681681 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) => {
9393 etag: hit.etag,
9494 vary: "accept-encoding, authorization, cookie",
9595 };
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 };
98100 // Encoded once per build at the slow, small level, not per request.
99101 const encoding = negotiate(ctx.request.headers.get("accept-encoding"));
100102 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 ()
4242 const again = await fetch(`${servers.url}/openapi.json`, { headers: { "if-none-match": etag }, redirect: "manual" });
4343 expect(again.status).toBe(304);
4444 });
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs