Repository navigation
Commit 9822b05
fix(hono): on a createHonoApp host a HEAD is answered as its GET, so HEAD /api/v1/mcp/skill no longer answers 405 Allow: GET (#24286)
Fixes #24245
Clause-②: no
Basis for the Clause-② line: the fix removes a refusal the published
HTTP contract already rules out. `IHttpServer`'s unmatched-request
contract names `@objectstack/http-conformance` as its validator, and
that suite pins "answers HEAD from GET routes without a body"
(`packages/qa/http-conformance/src/adapter.test.ts:144`), as RFC 9110
§9.3.2 does. No export moves. Every request whose answer changes is a
`HEAD` on a `createHonoApp` host, and it now gets its `GET` answer's
status and headers with no body. No `GET` answer moved (measured,
below).
## What changed
- `packages/adapters/hono/src/index.ts` (the home): a module-private
`dispatchedMethod(method)` maps `HEAD` to `GET` and leaves every other
verb as sent.
- The `${prefix}/*` catch-all hands `dispatch()`
`dispatchedMethod(method)`. Before, it handed the raw `c.req.method`,
which reads `HEAD` even though Hono routed the request as `GET`.
- The auth arm's `/auth/config` branch compares
`dispatchedMethod(method)`. A `HEAD` there was forwarded to better-auth
and answered `404`, while `plugin-auth`'s `GET` mount answers it on the
standalone server. This is the same defect class in the same file, and
it is fixed under the bounded in-place exemption (same class,
mechanical, file in this claim's surface, same gate family).
- Only the verb moves. `{ request: c.req.raw }` is still the client's
`HEAD` request, as the standalone mounts hand theirs. Hono drops the
body itself.
- `packages/runtime/src/domains/approvals.ts`: the `/approvals/act`
domain decides "is this a `HEAD`" from the forwarded request's own
method (`request?.method === 'HEAD'`), not from the dispatcher's verb.
This edit is required by the change above. Without it, the hosted `HEAD`
reached the approvals member as the raw `HEAD` and answered `405` with
`Allow: GET, POST`. Measured: `hono-approvals-act.conformance.test.ts`'s
HEAD pin went red with only the catch-all change, because the hosted
door answered `405` where the self-hosted door answered `200`. The
docblocks that said the two methods are always equal now say where they
differ.
- Tests and a changeset (`@objectstack/hono` patch,
`@objectstack/runtime` patch).
## Where the fix lives, and why (measured)
Measured in process on base `53ef75243`, with a `LiteKernel`, fake
`auth` / `mcp` / `analytics` / `protocol` slots, and both doors:
- the hosted door: `createHonoApp` driven through `app.request`, with
`HttpDispatcher.prototype.dispatch` wrapped to record the verb it
received and its answer;
- the standalone door: `HonoServerPlugin` on a real socket with
`createDispatcherPlugin`.
The run covered 34 paths × `GET`/`HEAD` × anonymous/signed in.
- **A1 (confirmed).** `handleMcpSkillRequest` answers `405` + `Allow:
GET` for every method that is not `GET`
(`packages/runtime/src/domains/mcp.ts`, the `method !== 'GET'` branch).
- **A2 (confirmed).** On the hosted door, `dispatch()` received `HEAD`
on every `HEAD` row.
- **A3 (confirmed).** The standalone door answered every `HEAD` row
exactly as its `GET` row. Its transport routes a `HEAD` to the `GET`
mount, and the mount hands `dispatch()` a literal `'GET'`.
- **A4 (answered: Hono drops it).** `hono` 4.13.12 `hono-base`
re-dispatches a `HEAD` as `GET` and wraps the answer in `new
Response(null, …)`. Every `HEAD` answer through `app.request` had an
empty body, at base and at head.
**Why the catch-all and not the `mcp` domain.** The shape is not the
`mcp` domain's. The dispatcher decides a verb by comparing it with
`'GET'` in many places: a domain's `methods` filter (`/health`,
`/ready`), a domain's branches (`m === 'GET'`), the discovery root, and
the share-link floor's public-`GET` exemption. Through the hosted door,
13 of 68 `HEAD` rows answered differently from their `GET`, across 7
route families (table below). A domain-level `HEAD`-as-`GET` would close
one of them and leave a dialect to repeat in every other domain. The
catch-all is the one producer of the raw `HEAD` on this host. Mapping it
there gives both compositions the same `dispatch()` input: the verb
`GET`, beside a request whose method is `HEAD`.
**The PM's two checks:**
- A path that serves no `GET` keeps its `GET` answer for `HEAD`. For
`/keys` and `/actions/task/close`, signed in, that is `405` + `Allow:
POST`; anonymous, `401 UNAUTHENTICATED`. These answers are unchanged
from base, on both doors. A `HEAD` there runs only the domain's refusal.
No `GET` is served on such a path.
- Anonymous floor order: at head, every anonymous `HEAD` row gets the
anonymous `GET` answer. At base one row did not: the public `GET
/share-links/:token/resolve` answered `501` (no service in this boot),
and its `HEAD` answered `401`.
**Side effects of `GET` dispatch.** A domain that forwards the request
to a member still hands over the client's `HEAD`. The `/mcp` transport
was handed `HEAD` on both doors, before and after. The `/approvals/act`
member is handed a `GET` built by the domain, as before. A domain keyed
on the dispatcher's verb now runs its `GET` branch for a `HEAD`, which
is what the standalone server already does for the same request.
### `HEAD` on the hosted door, base → head (no `GET` row moved;
standalone unchanged)
| caller | path | `GET` | `HEAD` at base | `HEAD` at head |
|---|---|---|---|---|
| anonymous + signed in | `/mcp/skill` | `200` | `405`, `Allow: GET` |
`200` |
| anonymous + signed in | `/health`, `/ready` | `200` | `404
ROUTE_NOT_FOUND` | `200` |
| anonymous + signed in | `/environments/env_m` (scoped root) | `200` |
`404 ROUTE_NOT_FOUND` | `200` |
| signed in | `/analytics/meta` | `200` | `404` (domain `handled:
false`) | `200` |
| signed in | `/ai/agents` | `200` | `501` | `200` |
| signed in | `/data/account`, `/data/account/r1` | `503` (no data
service) | `404` (domain `handled: false`) | `503` |
| anonymous | `/share-links/tok/resolve` | `501` (public) | `401` |
`501` |
| anonymous (auth service present) | `/auth/config` | `200` | `404` |
`200` (unit pin) |
### Other `GET`-serving domains with the same shape
The card asks for these by name. All of them reach `dispatch()` through
the same catch-all, so this change closes them too:
- **Measured above:** `/health`, `/ready` (`methods: ['GET']`); the
discovery root under `/environments/:id`; `analytics`
(`/analytics/meta`); `ai` (`/ai/agents`); `data` (the reads);
`share-links` (the public resolve floor); and the auth arm's
`/auth/config`.
- **Read in code, not measured:** their services were absent from the
measuring boot, and each one's service-absence answer comes before its
verb check, so both verbs answered alike there. These domains decide
reads by `=== 'GET'`:
- `i18n` (`m !== 'GET'` is not handled);
- `automation` (its `GET` faces);
- `notifications`;
- `packages` (its `GET` faces);
- `security` (`suggested-bindings`);
- `share-links` (its other `GET` faces);
- `meta` (the `!method || method === 'GET'` reads).
## Tests
- New `packages/adapters/hono/src/hono-head-dispatched-as-get.test.ts`
(4 cases; the dispatcher is this package's stub):
- `HEAD /mcp/skill` reaches `dispatch()` as `GET` beside the client's
`HEAD` request, and its answer is the `GET` answer's status and headers
with an empty body. The fixture is the skill domain's real result shape.
- A refused `GET` (`405`, `Allow: POST`, `METHOD_NOT_ALLOWED`,
`httpStatus` 405) gets the same status and headers on `HEAD`, with no
body.
- Every other verb (`GET POST PUT PATCH DELETE OPTIONS`) reaches
`dispatch()` as sent.
- `HEAD /auth/config` gets the public config's status and headers with
no body, and better-auth is not asked.
- New
`packages/qa/http-conformance/src/hono-head-as-get.conformance.test.ts`
(24 cases). It uses the real `HttpDispatcher` and the real
`createHonoApp` pipeline (`app.request`), beside the standalone server:
- 12 rows, each asserting: the `GET` status, plus `code` and
`httpStatus` for a refused `GET`; `HEAD` status and headers equal to the
`GET`'s; empty `HEAD` body; and the `Allow` value (`POST` on the two
`405` rows, absent otherwise).
- For the 10 rows both doors serve, the hosted `HEAD` status and `Allow`
equal the standalone `HEAD`'s.
- `HEAD /mcp/skill` carries the skill's `content-type`,
`content-disposition` and `cache-control` on both doors.
- Only the verb moves: the `/mcp` transport is handed `HEAD` on both
doors.
- `packages/runtime/src/domains/approvals-act.test.ts`: new case. A
`HEAD` request dispatched as `GET` is still forwarded to the member as a
`GET`, and is answered with no body.
- PR #24244's standalone pins, run and green:
-
`packages/runtime/src/mcp-skill-method-not-allowed.hono.integration.test.ts`
- `actions-every-verb.hono.integration.test.ts`
- `keys-every-verb.hono.integration.test.ts`
- `notifications-every-verb.hono.integration.test.ts`
- `dispatcher-body-after-anonymous-floor.hono.integration.test.ts` and
`http-dispatcher.mcp.test.ts` (7 files, 291 tests).
- Controls kept green: `hono-approvals-act.conformance.test.ts` (its
`HEAD` pin holds both doors equal),
`hono-webhooks-redeliver.conformance.test.ts` (`HEAD` stays `404`) and
`hono-meta-item-read-gate.conformance.test.ts`.
- Package runs:
- `@objectstack/hono` `test`: 10 files, 211 tests, exit 0. `typecheck`:
exit 0. Both at `379b734a2`.
- `@objectstack/http-conformance` `test`: 16 files, 214 tests, exit 0.
`typecheck`: exit 0. Both at `379b734a2`.
- `@objectstack/runtime` `test`: 416 files, 6548 passed and 19 skipped,
exit 0. `typecheck`: exit 0. Both at `0a5693634`; no runtime file
changed after that commit.
- The merge of `origin/main` at `4f14775b4` brought only
`scripts/pm/dispatch-gates*`.
### One-time ablations (fix committed first,
`scripts/ablation-replace.mjs`, wrap mode, restore proven: blob equals
`HEAD` and `git diff HEAD` is empty)
1. **`dispatchedMethod`.** Mutated `return method === 'HEAD' ? 'GET' :
method;` to `return method;`. Anchor count 1 → 0; blob `4f962dbb6cfd` →
`aa3f8f87edab`. The subject resolves from source in both suites (the
hono package itself, and the http-conformance alias of
`@objectstack/hono` to `src`), so no build leg.
- Hono unit: 3 failed, 1 passed. The every-other-verb control stays
green.
- Conformance: 13 failed, 11 passed. The 11 are the controls: non-`GET`
paths, anonymous-floor rows that matched at base, and the `/mcp` verb
row.
- Restored to `4f962dbb6cfd`.
2. **The approvals key.** Mutated `if (request?.method === 'HEAD') {` to
`if (method === 'HEAD') {`. Blob `67a8a4b44bf3` → `ab7e441de94c`.
- `approvals-act.test.ts`: 1 failed, 12 passed (`expected 'HEAD' to be
'GET'`).
- Restored.
- The conformance leg of the same mutation was read before the runtime
rebuild: `hono-approvals-act`'s `HEAD` pin was red, with the hosted door
at `405` and `Allow: GET, POST`. The rebuilt `dist` then went green.
## Gates
The gate list is derived by `node scripts/pm/dispatch-gates.mjs
--commands --repo objectstack-ai/objectstack` (no paths) at the final
head `4f14775b4`. It gives 66 commands, the same list as at `0a5693634`
and at `379b734a2`.
- **All 66 run at `4f14775b4`: all exit 0.** Each exit code was captured
before any pipe. These include:
- `pnpm check:dispatcher-error-vocabulary`
- `pnpm check:error-status-conformance` ("every derivable runtime status
is documented, and every documented status is reachable")
- `pnpm check:route-envelope`
- `pnpm check:nul-bytes` (OK, no raw control bytes)
- `pnpm check:changeset-gate-self-tests`
- `node scripts/check-changeset-no-major.mjs --base origin/main`
- `pnpm check:cross-package-test-inputs`
- `pnpm check:test-source-alias`
- `pnpm check:type-check-coverage` and `pnpm check:type-check-debt`
- `pnpm check:dual-build-cjs-loads`
- **`--ran` reconciliation:** `66 derived famil(ies) accounted for, 66
run, 0 NOT-MEASURED (a DERIVED zero, all 66 recorded an exit code and
none of them is 3)`.
- **First pass at `0a5693634`:** two commands exited 3 as prerequisite
refusals, not measured failures. Both were re-run:
- `check-plugin-teardown-shape --self-test` needed its pinned fixture
commit, which was fetched.
- `check:dual-build-cjs-loads` needed every workspace `dist`.
- **ESLint over the changed files:** `pnpm exec eslint
--no-inline-config` over the five changed source and test files, exit 0,
no output. The repo-wide `pnpm lint` is CI's.
- **Not run locally:** `@objectstack/runtime`'s `test:repo` project
(CI's `Test Core`). The diff edits no test in that project.
- **CI:** the PR's check-runs are the reading for every family CI owns.
## Acceptance notes
- **A finding, reported to the PM, not fixed here.** On a
`createHonoApp` host, `GET /api/v1/mcp/skill` serves the skill as an SSE
frame of a JSON string: the body is `data: "# skill"` followed by a
blank line, not the markdown. The `content-type` is doubled
(`text/markdown; charset=utf-8, text/markdown; charset=utf-8`) and
`cache-control` reads `no-cache, no-store`. The cause is `toResponse`'s
`events` stream arm in `packages/adapters/hono/src/index.ts`: it
SSE-frames every event unless `vercelDataStream` is set, and it merges
its own capitalised headers with the domain's lowercase ones.
`packages/runtime/src/domains/mcp.ts` says string events are "written
verbatim" on every adapter. The standalone server serves the raw
markdown with `cache-control: no-store` (PR #24244's pin). This change
does not touch it, and the new pins assert only `toContain` on those two
headers and a non-empty `GET` body, so nothing pins the defect.
- The auth arm's legacy fallback `dispatcher.handleAuth(path, method,
…)` still passes the raw verb. The auth domain does not read it
(`_method`), so no answer differs, and it is unchanged.
- A `HEAD` on a `GET` whose answer is an `events` stream still runs the
stream's producer; Hono discards the body. The standalone server does
the same for the same request, since it runs the `GET` handler too.
Noted, not changed.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01SYEJqDL3NXxrJRBVqaMu9T)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent e15897c commit 9822b05
6 files changed
Lines changed: 469 additions & 9 deletions
File tree
- .changeset
- packages
- adapters/hono/src
- qa/http-conformance/src
- runtime/src/domains
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
537 | 537 | | |
538 | 538 | | |
539 | 539 | | |
| 540 | + | |
| 541 | + | |
| 542 | + | |
| 543 | + | |
| 544 | + | |
| 545 | + | |
| 546 | + | |
| 547 | + | |
| 548 | + | |
| 549 | + | |
| 550 | + | |
| 551 | + | |
| 552 | + | |
| 553 | + | |
| 554 | + | |
| 555 | + | |
| 556 | + | |
| 557 | + | |
| 558 | + | |
| 559 | + | |
| 560 | + | |
| 561 | + | |
| 562 | + | |
| 563 | + | |
| 564 | + | |
| 565 | + | |
| 566 | + | |
| 567 | + | |
| 568 | + | |
| 569 | + | |
| 570 | + | |
| 571 | + | |
| 572 | + | |
| 573 | + | |
540 | 574 | | |
541 | 575 | | |
542 | 576 | | |
| |||
916 | 950 | | |
917 | 951 | | |
918 | 952 | | |
919 | | - | |
| 953 | + | |
| 954 | + | |
| 955 | + | |
| 956 | + | |
920 | 957 | | |
921 | 958 | | |
922 | 959 | | |
| |||
1060 | 1097 | | |
1061 | 1098 | | |
1062 | 1099 | | |
1063 | | - | |
| 1100 | + | |
| 1101 | + | |
1064 | 1102 | | |
1065 | 1103 | | |
1066 | 1104 | | |
| |||
0 commit comments