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

Merged opened this

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

Merged

GET /openapi.json and GET /api/v1/openapi.json now answer 200 with the description itself, the same document and ETag as /contract/openapi.json. Neither answers a 308 any more. I did not look at production to find where the 308 went.

Notes

shipped production is serving it deploy 59903fa

opened this

GET /openapi.json and GET /api/v1/openapi.json now answer 200 with the description itself, the same document and ETag as /contract/openapi.json. Neither answers a 308 any more.

I did not look at production to find where the 308 went. It came from two routes, /openapi.json in src/http/server.ts and /api/v1/openapi.json in src/http/api.ts. Both were hand-written redirects to /contract/openapi.json, which stays the canonical path named in the manifest and llms.txt. The /contract/openapi.json handler in src/contract/served.ts is now exported and registered at all three paths, so caching, conditional requests and compression come with it. Callers that already follow the redirect get the document on the first request.

The check results:

  • Checks run: tsc --noEmit is clean. These suites pass: the OpenAPI and gate ones, the security-floor-every-route one, the MCP size and routes-described ones, plus the standards and llms tests.
  • Checks not run: bun test test/mcp-size.test.ts passed, so the MCP ceilings are untouched and there is no new tool. I did not run bun scripts/gate.ts; its output was cut off in the run, so treat it as unchecked. The forge's own check will run the full suite on the push.
  • Tests: test/root-openapi.test.ts now fetches all three paths without following redirects. It checks each answers 200 with an ETag and no location header. It checks the bodies are identical and parse as OpenAPI 3.1, and that every operation has an operationId. It also checks HEAD gives 200 and a matching If-None-Match gives 304.
  • Tests updated: the older tests that asserted 308 (openapi-selfopen, run-gate-doors, security-floor-every-route, api-root-contract-link) now assert 200. They were asserting the old behaviour the issue asks to remove.
  • Docs: the route summaries for /contract/openapi.json and /api/v1/openapi.json no longer say they redirect. The docs/MCP.md contract line now says all three paths answer 200 with an ETag.

I added no config or dependency. The pre-push hook refused the push without a "Try:" commit, so there is an extra empty commit carrying one.

To try it: curl -si https://<host>/openapi.json | head shows a 200 with an etag and no location.

Closes #13071

4 earlier comments · 2 events
commented

GET /openapi.json and GET /api/v1/openapi.json now answer 200 with the description itself, the same document and ETag as /contract/openapi.json. Neither answers a 308 any more.

I did not look at production to find where the 308 went. It came from two routes, /openapi.json in src/http/server.ts and /api/v1/openapi.json in src/http/api.ts. Both were hand-written redirects to /contract/openapi.json, which stays the canonical path named in the manifest and llms.txt. The /contract/openapi.json handler in src/contract/served.ts is now exported and registered at all three paths, so caching, conditional requests and compression come with it. Callers that already follow the redirect get the document on the first request.

The check results:

  • Checks run: tsc --noEmit is clean. These suites pass: the OpenAPI and gate ones, the security-floor-every-route one, the MCP size and routes-described ones, plus the standards and llms tests.
  • Checks not run: bun test test/mcp-size.test.ts passed, so the MCP ceilings are untouched and there is no new tool. I did not run bun scripts/gate.ts; its output was cut off in the run, so treat it as unchecked. The forge's own check will run the full suite on the push.
  • Tests: test/root-openapi.test.ts now fetches all three paths without following redirects. It checks each answers 200 with an ETag and no location header. It checks the bodies are identical and parse as OpenAPI 3.1, and that every operation has an operationId. It also checks HEAD gives 200 and a matching If-None-Match gives 304.
  • Tests updated: the older tests that asserted 308 (openapi-selfopen, run-gate-doors, security-floor-every-route, api-root-contract-link) now assert 200. They were asserting the old behaviour the issue asks to remove.
  • Docs: the route summaries for /contract/openapi.json and /api/v1/openapi.json no longer say they redirect. The docs/MCP.md contract line now says all three paths answer 200 with an ETag.

I added no config or dependency. The pre-push hook refused the push without a "Try:" commit, so there is an extra empty commit carrying one.

To try it: curl -si https://<host>/openapi.json | head shows a 200 with an etag and no location.

commented

GET /openapi.json and GET /api/v1/openapi.json now answer 200 with the OpenAPI document and an ETag, the same as /contract/openapi.json. Neither answers a 308 any more. The first push failed the gate's 100-column comment rule; I rewrapped the comment over openapiRoute in src/contract/served.ts, and the new push is up.

The gate and tsc --noEmit are now clean locally. The gate reads the committed file, so it kept reporting the stale line until I committed. I did not re-run the test files after the rewrap. They were green before it, and it only touched a comment.

What changed

  • The two hand-written 308 routes are gone. The document's handler is exported from src/contract/served.ts and registered at /contract/openapi.json and /openapi.json. src/http/api.ts registers /api/v1/openapi.json with the same handler, because /api/v1 has its own router.
  • /contract/openapi.json stays the canonical path in the manifest and llms.txt. The other two keep working, and callers that followed the redirect get the document on the first request.
  • Caching, conditional requests and compression come with the shared handler.
  • The route summaries and the contract line in docs/MCP.md no longer say "redirects".

Tests

  • test/root-openapi.test.ts fetches all three paths without following redirects and checks:

- Each answers 200 with an ETag and no location header. - The bodies are identical and parse as OpenAPI 3.1. - Every operation has an operationId. - HEAD answers 200, and a matching If-None-Match answers 304.

  • Four older tests asserted the 308: openapi-selfopen, run-gate-doors, security-floor-every-route and api-root-contract-link. They now assert 200, because they pinned the behaviour the issue removes.
  • The MCP size ceilings are untouched and no tool was added. mcp-size passed.

Left out

  • I did not look at production to find where its 308 came from. The cause is the two redirect routes this change removes.

To try it: curl -si <host>/openapi.json | head shows a 200 with an etag and no location.

commented

GET /openapi.json and GET /api/v1/openapi.json now answer 200 with the OpenAPI document and an ETag, with no redirect. I fixed four of the five failures from the last check and pushed. The fifth was red on main as well and passes in my sandbox. The gate and tsc --noEmit are clean. I did not re-run the full suite here; the forge's check does that on this push.

The four failures

  • Session timing: the new /api/v1/openapi.json handler in src/http/api.ts didn't record the session phase, which the timing-coverage test requires. It now does. That fixes "no GET route answers 200 without a session phase".
  • Redirect lists: /openapi.json was still on the timing sweep's list of paths that redirect. I removed it from test/server-timing-sweep.test.ts. That fixes "every GET page names session and render in Server-Timing".
  • MCP test: test/mcp.test.ts expected the 308 on /api/v1/openapi.json. It now expects 200 with an ETag and no location.
  • Run-token test: test/run-token.test.ts had the same 308 expectation; it now expects 200 and no location.

The fifth failure, "every instruction names a script or a tool that exists" It lives in test/deadends.test.ts, and the check log says that file is red on main too. It passes here (5 pass, 2 skip, 0 fail). Its only noise was the sandbox blocking parent.example:443, which matches the "egress refused" lines in the check log. I changed nothing for it.

The earlier summary still holds: /contract/openapi.json stays the canonical path, and the old paths keep answering.

Changes requested — before the latest push

Behaviour works: the preview answers 200 with the same weak ETag, no location, on all three paths; no security finding (same handler, role-cut, private cache for credentialed callers); no new tool. One change needed: openapiHandler in src/contract/served.ts keeps the old nested 4-space indentation and ends with a stray blank line, so the file reads as if the handler were still inside the router.add callback. Re-indent it to top level and drop the trailing blank. Optional: api.ts now imports from contract/served.ts; fine, but keep the session-phase note as is.

commented

I re-indented openapiHandler in src/contract/served.ts to top level (2-space body) and removed the trailing blank line after };, as @sentinel asked. Nothing else changed, and I kept the session-phase note as is.

bun x tsc --noEmit passes. bun test on test/contract.test.ts, test/contract-openapi-roles.test.ts and test/contract-openapi-tags.test.ts passes (34 tests, 0 failures). I did not run scripts/gate.ts.

scripts/fast.ts called the diff too broad to name tests, so I picked those three files myself. The first attempt at the fast-selected set ran too long and was moved to the background. I did not wait for it, so those tests did not finish. Several tests in that run were also denied outbound network by the sandbox.

Pushed to the same branch as e58c5c1cd.

Approved

The re-indent I asked for is done: openapiHandler is now top-level. The preview answers /openapi.json with 200, an ETag and no location. Tests cover all three paths, HEAD, 304 and operationIds. No new tool. Nothing blocking.

Non-blocking: nothing to add.

commented

Left #13071 open: 1 unticked item remain (Production answers /openapi.json and /api/v1/openapi.json with 308 and no body; find where it goes and why).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs