Tracker: Hono on Perry — runtime-agnostic app.fetch contract working end-to-end

[proggeramlug]

Goal

Hono's runtime-agnostic value proposition is that the same (req: Request) => Promise<Response> code runs unchanged on Workers, Bun, Deno, Node, Lambda. We want Perry to be one of those runtimes — same Hono app, swap only the adapter import. Today the contract breaks at multiple layers; this tracker pins down the precise set of issues to close and the acceptance test for "done".

Current state, mapped

Layer	Status	Tracking
Hono compiles via compilePackages: ["hono"]	✅ done	#421 (closed v0.5.613)
new Hono(), app.get/app.post/etc. route registration	✅ done	(covered by #421)
app.fetch(req) dispatches into route handlers	✅ partial — runs, but throws on first header access	#1649
new Request(url, { headers }) — req.headers is a Headers instance	❌ returns numeric handle	#1649
new Response(body) — res.text() / res.arrayBuffer()	✅ works for string bodies	—
new Response(body) — res.body is ReadableStream | null	❌ returns numeric handle	#1650
hono/jsx — <Component/> evaluates to a JSXNode; c.html(<Comp/>) renders	❌ evaluates to undefined	#1653
hono/jsx/server, hono/jsx/streaming module imports	❌ throw undefined	(covered by #1653)
HTTP listener path A — @hono/node-server works unchanged	❌ blocked on node:http2 exports + node:http link gap	#1651, #1652
HTTP listener path B — @hono/perry-server adapter exists	❌ not shipped (deferred from #487)	#1654
HTTP listener path C — perry-ext-fastify direct	✅ works	(already shipped)
Streaming via hono/streaming	❌ depends on Response.body fix	(covered by #1650)
WebSocket upgrade via Server.on('upgrade', …)	✅ shipped per #577 Phase 4; not exercised by Hono	—

Decision: which HTTP listener does the architecture commit to?

Two viable end-states; tracker leaves both open and recommends shipping both.

• Path A — @hono/node-server on Perry's node:http(s) / http2. Identical user code to Node. Blocked on node:http2 module is missing named exports (Http2ServerRequest, Http2ServerResponse, constants) #1651 + node:http.createServer FFI symbols undefined in default Perry binary (follow-up to #589) #1652. Once landed, Perry users do exactly what Node users do.
• Path B — @hono/perry-server, Perry-org-owned package. Wraps perry-ext-fastify in ~100 LOC. Blocked on Web Fetch: Request.headers is a numeric handle, not a Headers instance — breaks every Hono adapter #1649 (and benefits from Web Fetch: Response.body is a numeric handle, not a ReadableStream | null #1650). Once landed, Perry users do import { serve } from '@hono/perry-server' — same shape as @hono/bun, @hono/deno, etc., and a place to absorb perry-ext-fastify quirks centrally.

Path B is the closer-in deliverable (smaller scope, Perry-org owns it end-to-end). Path A is the longer-term "no Perry-specific import" win.

Out of scope (explicitly)

• Dynamic imports (await import(...)) — call-site workarounds exist; not on the critical path for the runtime-agnostic Hono contract.
• Full Express compatibility shim — explicitly out per Compile hono end-to-end via perry.compilePackages #421; Hono + Fastify cover the modern TS backend space, full Express is a tarpit.

Acceptance for "Hono on Perry is done"

Single 30-line program serves real HTTP traffic, identical to Node:

```typescript
import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { serve } from '@hono/perry-server' // ← only Perry-specific line

const Layout = (props: { title: string; children: any }) => (

<title>{props.title}</title>{props.children} )

const app = new Hono()
app.use('*', logger())
app.get('/', (c) => c.html(

hello

))
app.get('/api/echo', (c) => c.json({ q: Object.fromEntries(new URL(c.req.url).searchParams) }))
app.post('/api/echo', async (c) => c.json({ body: await c.req.json() }))

serve({ fetch: app.fetch, port: 3000 }, ({ port }) => {
console.log(`listening :${port}`)
})
```

```bash
perry compile app.tsx -o app
./app &
curl -sS http://127.0.0.1:3000/ # → real HTML
curl -sS http://127.0.0.1:3000/api/echo?k=v # → {"q":{"k":"v"}}
curl -sS -X POST -H 'content-type: application/json' -d '{"x":1}'
http://127.0.0.1:3000/api/echo # → {"body":{"x":1}}
```

The same source file, with import { serve } from '@hono/node-server' instead, must produce byte-for-byte identical responses under node --import tsx app.tsx. That's the acceptance bar — runtime-agnostic in fact, not in marketing.

Sub-issues

• Web Fetch: Request.headers is a numeric handle, not a Headers instance — breaks every Hono adapter #1649 — Request.headers is a numeric handle, not a Headers instance (CRITICAL: blocks every adapter)
• Web Fetch: Response.body is a numeric handle, not a ReadableStream | null #1650 — Response.body is a numeric handle, not ReadableStream | null (blocks streaming; .text/.arrayBuffer already work)
• node:http2 module is missing named exports (Http2ServerRequest, Http2ServerResponse, constants) #1651 — node:http2 missing named exports (Http2ServerRequest, Http2ServerResponse, constants) — blocks Path A
• node:http.createServer FFI symbols undefined in default Perry binary (follow-up to #589) #1652 — node:http.createServer FFI symbols undefined in default build (Link gap: hono + node:http combination drops Web Fetch FFIs (js_headers_new / js_response_new) #589 follow-up) — blocks Path A
• hono/jsx: <Component/> evaluates to undefined under Perry native compile #1653 — hono/jsx <Component/> evaluates to undefined; hono/jsx/server/hono/jsx/streaming imports throw — blocks JSX templating
• Ship @hono/perry-server adapter package (#487 follow-through) #1654 — Ship @hono/perry-server adapter package — Path B deliverable

Related (already closed)

• Compile hono end-to-end via perry.compilePackages #421 — Compile hono end-to-end via perry.compilePackages (closed v0.5.613)
• Hono acceptance: @hono/perry-server adapter (4th acceptance bullet of #421) #487 — @hono/perry-server adapter (closed "as a side effect" of Implement node:http / node:https / node:http2 + WebSocket upgrade for npm-ecosystem HTTP server compat #577; in practice still needed → Ship @hono/perry-server adapter package (#487 follow-through) #1654)
• Implement node:http / node:https / node:http2 + WebSocket upgrade for npm-ecosystem HTTP server compat #577 — Implement node:http / node:https / node:http2 + WS upgrade (closed v0.5.691; named-export and link surfaces still gappy → node:http2 module is missing named exports (Http2ServerRequest, Http2ServerResponse, constants) #1651, node:http.createServer FFI symbols undefined in default Perry binary (follow-up to #589) #1652)
• Link gap: hono + node:http combination drops Web Fetch FFIs (js_headers_new / js_response_new) #589 — Link gap: hono + node:http drops Web Fetch FFIs (closed; symptom persists → node:http.createServer FFI symbols undefined in default Perry binary (follow-up to #589) #1652)

[proggeramlug]

Status update — sub-issues landed, tracker stays open

All six sub-issues are fixed and merged (PR #1660 = #1649/#1650/#1651/#1652; PR #1665 = #1653/#1654):

Sub-issue	State	Notes
#1649 Request.headers	✅ closed	verified against real hono@4.10 — app.fetch + c.req.headers.get(...) work
#1650 Response.body	✅ closed	real ReadableStream; residuals → #1670
#1651 node:http2 constants	✅ closed
#1652 node:http link	✅ closed
#1653 hono/jsx render	✅ closed	<Component/> → HTML; submodule imports → #1671
#1654 @hono/perry-server	✅ closed	shipped in packages/hono-perry-server

Why the tracker stays open

I exercised the acceptance program against the real hono package and the runtime-agnostic end-to-end isn't byte-for-byte yet — there are blockers beyond the six primitives:

1. Object.fromEntries(new URL(c.req.url).searchParams) produces no output — URLSearchParams iteration is broken (.get() works, iteration doesn't). Blocks the /api/echo?k=v line. → URLSearchParams iteration (Object.fromEntries / for-of / spread) produces no output #1668
2. hono@4.12 trips security: refuse dynamic stdlib dispatch (obj[runtimeVar]()) #503 (dynamic path[runtimeVar]() inside hono) and won't compile; only hono@4.10 compiles today. The acceptance should pin a version or security: refuse dynamic stdlib dispatch (obj[runtimeVar]()) #503 needs a compilePackages allowance.
3. c.html(<Layout/>) with real hono is unverified — Perry renders JSX with its own js_jsx (producing a Perry JSX node), and whether hono's c.html stringifies that node to HTML in-context hasn't been confirmed end-to-end.
4. hono/jsx/server / hono/jsx/streaming imports → hono/jsx/server + hono/jsx/streaming module imports under Perry-native (follow-up to #1653) #1671.

What does work against real hono@4.10: new Hono(), route registration, app.fetch(req), c.req.headers.get, and c.json(...) round-trip byte-for-byte with Node. The next concrete step toward closing this tracker is #1668 (the /api/echo query route).

[proggeramlug]

E2E re-test on main (7371549, after #1686)

Good progress — #1686 closed two of the three blockers I flagged, and the JSX path now works against real hono@4.10:

✅ Now working (byte-for-byte vs Node where Node can baseline):

• new Hono() + routing + app.fetch, c.req.headers.get, c.json(...)
• GET /api/echo?k=v → {"q":{"k":"v","a":"b"}} (URLSearchParams iteration fixed, URLSearchParams iteration (Object.fromEntries / for-of / spread) produces no output #1668)
• c.html(<Layout title="hi"><h1>hello</h1></Layout>) → body renders exact HTML <html><head><title>hi</title></head><body><h1>hello</h1></body></html> (the hono/jsx: <Component/> evaluates to undefined under Perry native compile #1653 JSX node round-trips through real hono's c.html)

❌ Still blocking the full acceptance:

1. await c.req.json() (POST body) → Request.text()/.json() return 0 instead of the body. → Web Fetch: Request.text() / Request.json() / Request.arrayBuffer() return 0 instead of the body #1688
2. c.html(...) response content-type reads back empty (res.headers.get('content-type') → '') — expected text/html; charset=UTF-8.
3. hono/jsx/server / hono/jsx/streaming module imports still fail to link → hono/jsx/server + hono/jsx/streaming module imports under Perry-native (follow-up to #1653) #1671 (reopened scope; fix: URLSearchParams iteration (#1668), Web Streams inline property + for-await (#1670), hono/jsx submodule imports (#1671) #1686 didn't fully cover it).

Not yet exercised end-to-end: serve() + hono/logger + live curl (deferred until the POST-body path lands, since the acceptance program needs it).

Next concrete step: #1688 (Request body methods).