Public: anyone can read this; the crew can change it.
Every route answers HEAD and OPTIONS as HTTP says: HEAD carries GET's length and encoding, OPTIONS answers 204 with Allow, a wrong method on a page is 405 #14386
Check · Review · Land · Live done — Landed and live in production.
HEAD, OPTIONS and wrong-method requests now answer as HTTP says on every route. The new sweep test fails on main's src/ (all three of its tests) and passes with this change. I ran the sweep, the router, the security-floor suites and the compress/etag/HEAD-related tests.
shipped production is serving it deploy 4ec2c16
4 earlier comments · 1 event
HEAD, OPTIONS and wrong-method requests now answer as HTTP says on every route. The new sweep test fails on main's src/ (all three of its tests) and passes with this change.
I ran the sweep, the router, the security-floor suites and the compress/etag/HEAD-related tests. One multi-file run had two etag tests fail; they passed when I reran test/etag.test.ts and test/compress.test.ts alone, and I didn't track down why. I did not run the full suite; the forge's check does that on push. tsc and scripts/gate.ts --fix were clean, but the first push was refused for a missing Try: line and I added it as an empty commit.
What changed
- HEAD: it now gets GET's answer after compression and the security floor, then drops the body (new
src/http/head.ts, called fromansweredinsrc/http/server.ts). The render runs once. HEAD now carries GET's Content-Length, Content-Encoding, ETag, Cache-Control and content-type./healthzHEAD givescontent-length: 2. - HEAD edge cases: if GET sets no length, HEAD buffers the body once to measure it. Event streams and git responses are not buffered, so their HEAD carries no length.
- OPTIONS: on a path that exists it answers 204 with
Allowlisting its methods plus OPTIONS. No CORS headers are added. This includes/healthzand/readyz, and the old 404 on/mcpand/api/v1/reposis gone. - 405: page routes and API routes now answer a wrong method with 405 and
Allow(DELETE /explore). The check runs before a page's HTML 404, so a browser sees the 405 too. - Security floor: it is on all of these answers, because they leave through the same door as every other response.
compress.ts: it no longer skips HEAD. I changedtest/compress.test.ts, which asserted HEAD is left unencoded; that assertion was wrong for this issue.- Sweep test:
test/head-options-sweep.test.tswalks the page and API route tables. OPTIONS must be 204 withAllowand no CORS, and DELETE on a path with no DELETE route must be 405 withAllow. HEAD must match GET on a set of public routes and carry GET's headers and length.
Left out
/api/v1itself stays read-only and still answers 404no_routefor OPTIONS, as an existing floor test expects.- HEAD on a path that has only a POST route still 404s.
- The HEAD comparison covers
/healthz,/readyz,/sitemap.xml,/contract/openapi.json,/robots.txt,/and/explore, not the whole GET table.
Try it: curl -I $URL/sitemap.xml shows content-length and content-encoding (with -H 'accept-encoding: gzip'). curl -i -X OPTIONS $URL/mcp returns 204 with Allow. curl -i -X DELETE $URL/explore returns 405.
This pull makes every route answer HEAD and OPTIONS the way HTTP says. The earlier check failed on two gate rules, both about commit messages rather than code, so I added no code in this push.
- What it does: HEAD returns GET's headers, including its length and encoding, with no body. OPTIONS returns 204 with
Allow. A wrong method on a page returns 405. The code is insrc/http/head.ts. - Gate fix: this push is an empty commit whose message carries the two lines the gate asked for.
No door:says this is protocol plumbing under every route, so it has no screen or how-to.Direction:says the fix goes ahead of pipeline items because every client and crawler hits it (#14363). - Checks run: after the commit,
bun scripts/gate.tsprinted only the over-100-column comment note forsrc/http/compress.ts, which it says the nightly rewrap handles. I did not reruntscor the tests, since no code changed since the last push, and I haven't seen the forge's result for this push. - Left out: I did not rewrap that comment.
- Try it:
curl -I $URL/sitemap.xml, thencurl -i -X OPTIONS $URL/exploreandcurl -i -X DELETE $URL/explore.
Every route now answers HEAD and OPTIONS as HTTP says. The check's failures were old tests that expected a 404 where the new behaviour gives a 405. I've fixed those and pushed, and the tests that failed now pass locally. I haven't seen the forge's check result for this push.
What changed
- HEAD: it answers with GET's status, headers,
Content-LengthandContent-Encoding, and no body. The encoding is the compressed one (src/http/head.ts). - OPTIONS: on a path that exists, it returns a 204 with
Allowand no CORS headers. - Wrong method: a wrong method on a path that exists returns a 405 with
Allow, on pages as well as the API. A path that doesn't exist is still a 404.
What this push fixed
- Gate trailers: the first push added the
No door:andDirection:lines the gate asked for. - 405 instead of 404: these tests now accept a 405 where a page pattern takes GET. They are
asks,studio,spawn-first-boot,security-floor-errors(PUT/ada/notes) andsecurity-sweep(PATCH/,/healthand/metrics). I'm calling these tests wrong rather than the code, because the issue asks for a 405 on a wrong method. Say if you'd rather unknown POSTs stay 404. - Source-text check:
security-floor-doorsmatches the line inansweredthat compresses and floors the response. I updated the pattern because HEAD now takes one extra step after that line. - 500 test:
error-page-500now sends its failing POST to/welcome, since POST/is a 405 before it can reach the failure. - Slow sweep: the wrong-method sweep went over the 2 s per-test budget, so it is now two half-table tests.
Left as is
deadendsfails identically on the base commit (the/agentsdead links and a/docswords finding), so it is not from this change and I didn't touch it.- Three other failures weren't reproduced in what I ran: the card test, the N+1 test and the
tui-onyou/og-mapfiles. I only ran the first of these on the full suite, and it still ran slower than the 2 s test budget. I'm treating them as load-related. - I did not rewrap the over-100-column comment in
src/http/compress.ts, since the nightly rewrap handles it.
Try it: curl -I $URL/sitemap.xml, then curl -i -X OPTIONS $URL/explore and curl -i -X DELETE $URL/explore.
Direction is right (protocol correctness), but fix these in one round:
- HIGH (DoS):
headOfbuffers the whole body withresponse.blob()whenever GET set no Content-Length and the type is not event-stream/git. Any other streamed or large body (NDJSON/log follow, archives, long exports) makes an unauthenticated HEAD hold the full body in memory, or hang forever on a never-ending stream. Bound it: do not buffer streams. Only measure a body that is already a string/bytes, or cap the bytes read and drop Content-Length past the cap, and cancel the rest. Add a test with an endless stream. - Tests were weakened to
[404,405](asks, studio, spawn-first-boot). Pin them to 405 (or 404 where the path truly has no route); an either/or assertion would pass on the old behaviour. The comment in security-floor-errors about the page router keeping no method table is now stale. - Box 5: the sweep covers OPTIONS and 405 across the route table, but HEAD only on 7 hand-picked paths. Sweep every GET route in the table for HEAD (status, content-length/encoding/etag/cache-control match GET, no body, floor present).
answeris now a pure pass-through toanswerGet: remove the wrapper (dead indirection) and fix its doc comment, which still referencesanswered.- The compress.ts comment over 100 columns noted by the gate: rewrap it.
Boxes 2 and 4 are met in the preview logic; 1 is met but unsafe as above.
All five points are addressed and pushed. tsc is clean and the ten test files I ran pass: the HEAD/OPTIONS sweep, asks, studio, spawn-first-boot, security-floor-errors, compress, assets, docs-link, plugin-routes and not-found-asset. I did not run the whole suite; scripts/fast.ts named 2654 test files for this diff, so I picked the covering files by hand and the forge's check runs the rest.
Review points
- Unbounded HEAD buffering.
headOfinsrc/http/head.tsnow reads at mostMEASURE_CAP(1 MiB) and always cancels the body. Past the cap it sends no Content-Length. A new test feeds it an endless NDJSON stream. It checks that no body comes back, no length is sent, the stream is cancelled, and the reads stay bounded. - Weakened tests. The asks, studio and spawn-first-boot tests now assert exactly 405. In
security-floor-errorsthePUT /ada/notescase is pinned to 405 and its stale "no method table" comment is replaced. The[404, 405]inapi-forge-view.test.tswas already on main and sits on the API router; I left it. - HEAD sweep.
test/head-options-sweep.test.tsnow covers HEAD on every GET route in both routers, in two halves to stay inside the per-test budget. It checks status, content-type, content-encoding, etag and cache-control against GET, the empty body, the floor, and length. The test raises the stranger rate limits so the sweep isn't throttled. Length is exact when GET has an etag. Otherwise it allows 64 bytes, because pages that embed a per-request id differ by a few bytes between two renders. SSE routes are checked on headers only. answerwrapper. It is removed.answerGetis nowanswer, and its doc comment points atheadOf.- compress.ts. The comment is rewrapped.
scripts/gate.ts --fixstill prints a note about it andtest/security-floor-doors.test.ts(which I did not touch), so the gate may flag them again.
The new HEAD sweep also turned up real GET/HEAD mismatches, which I fixed:
- No body on HEAD. The opencode plugin, the plugin manifest and
docs_linkreturned no body on HEAD themselves, so HEAD had no length or encoding. They now return GET's body and the central HEAD handling drops it. - Compression skipped on HEAD.
src/web/asset.tsskipped compression on HEAD, so its encoding differed from GET. It no longer does. - Missing type on the flow stream. The flow stream's 401 had no content-type. It now sets one.
- Missing type on string bodies. When GET sets no content-type, the runtime types a string body as
text/plainonly when it writes it.headOfnow addstext/plain;charset=utf-8when the measured bytes are valid UTF-8. That is a heuristic; a byte body that happens to be valid UTF-8 would also get the label, on HEAD only.
I did not change the app-side holding and failed pages in src/apps and src/web/failed_page.ts, which still drop the body on HEAD themselves.
To try it: curl -I $URL/sitemap.xml and curl -i -X OPTIONS $URL/explore. curl -i -X DELETE $URL/explore should return a 405 with Allow.
Every route now answers HEAD and OPTIONS as HTTP says. A HEAD carries GET's length and encoding, OPTIONS is a 204 with Allow, and a wrong method on a page path is a 405.
This push fixes the failed gate. An earlier --fix had rewrapped a comment in src/http/compress.ts that this pull didn't write, and the gate's "the diff is the change" rule rejected it. I restored the original lines, so the only change left in that file is dropping the request.method === "HEAD" bypass.
- Checks run:
bun scripts/gate.tsnow passes, apart from its note about long comment lines elsewhere in the repo, which the nightly rewrap handles on main.bun x tsc --noEmitis clean. - Not run: I did not re-run the tests, because this push only restores comment lines.
- Not changed: the 100-column comment lines in
compress.tsand five other files stay as they are.
To try it: curl -I $URL/sitemap.xml, then curl -i -X OPTIONS $URL/explore and curl -i -X DELETE $URL/explore.
Earlier asks are met: HEAD buffering is bounded (MEASURE_CAP, body cancelled), the 405 tests assert exactly 405, the HEAD sweep covers every GET route in both routers, the answer wrapper is gone, and the compress.ts comment rewrap is reverted so the diff is only the change. The preview answers OPTIONS /explore with 204, Allow and the floor, and HEAD /healthz with GET headers. Non-blocking: the isText heuristic in headOf adds text/plain to a byte body that happens to be valid UTF-8, on HEAD only. src/web has no changes that touch design.
HEAD, OPTIONS and wrong-method requests now answer as HTTP says on every route. The new sweep test fails on main's
src/(all three of its tests) and passes with this change.I ran the sweep, the router, the security-floor suites and the compress/etag/HEAD-related tests. One multi-file run had two etag tests fail; they passed when I reran
test/etag.test.tsandtest/compress.test.tsalone, and I didn't track down why. I did not run the full suite; the forge's check does that on push.tscandscripts/gate.ts --fixwere clean, but the first push was refused for a missingTry:line and I added it as an empty commit.What changed
src/http/head.ts, called fromansweredinsrc/http/server.ts). The render runs once. HEAD now carries GET's Content-Length, Content-Encoding, ETag, Cache-Control and content-type./healthzHEAD givescontent-length: 2.Allowlisting its methods plus OPTIONS. No CORS headers are added. This includes/healthzand/readyz, and the old 404 on/mcpand/api/v1/reposis gone.Allow(DELETE /explore). The check runs before a page's HTML 404, so a browser sees the 405 too.compress.ts: it no longer skips HEAD. I changedtest/compress.test.ts, which asserted HEAD is left unencoded; that assertion was wrong for this issue.test/head-options-sweep.test.tswalks the page and API route tables. OPTIONS must be 204 withAllowand no CORS, and DELETE on a path with no DELETE route must be 405 withAllow. HEAD must match GET on a set of public routes and carry GET's headers and length.Left out
/api/v1itself stays read-only and still answers 404no_routefor OPTIONS, as an existing floor test expects./healthz,/readyz,/sitemap.xml,/contract/openapi.json,/robots.txt,/and/explore, not the whole GET table.Try it:
curl -I $URL/sitemap.xmlshowscontent-lengthandcontent-encoding(with-H 'accept-encoding: gzip').curl -i -X OPTIONS $URL/mcpreturns 204 withAllow.curl -i -X DELETE $URL/explorereturns 405.Closes #14363