[jjohnson-hdb]

Next.js apps now render when Harper serves them over HTTP/2 (http.http2: true on the secure port). Before this, every page returned a 500 and every compressed asset reset its stream, because Next.js's request handler assumes Node's HTTP/1 request/response objects and Harper hands the plugin node:http2 compatibility objects. HTTP/2 is what Chromium needs before it acts on 103 Early Hints, so this was blocking Early Hints for Next.js sites served directly from Harper.

The plugin's serve() in src/plugin.ts now runs each request/response pair through the adapter (imported here) before calling Next.js. The adapter is the new adaptHttp2ForNext in src/http2Compat.ts. For HTTP/2 only, it does three things:

• hands Next.js an HTTP/1-shaped copy of the request headers. The copy has Object.prototype, because Next.js calls headers.hasOwnProperty(). It drops the :path, :method, :authority and :scheme pseudo-headers, because Next.js passes every header name to Headers.append(), which rejects them, so route handlers threw. It shadows the headers getter instead of editing the original, because url and method read that object. A __proto__ header is kept as an own property;
• fills host from :authority when the client sent no host, because Next.js's Server Actions origin check reads host;
• adds an instance-level _implicitHeader() for the compression middleware Next.js bundles. It writes the head only while headers are unsent.

HTTP/1 requests return before any of this runs.

For the human reviewer

1. Requirement: does this belong in the plugin? Next.js doesn't support node:http2 compatibility objects in a custom server. Harper uses createSecureServer with allowHTTP1 when http.http2 is on. The plugin's serve() is the one place the two meet. Two alternatives were considered:

   • normalizing in Harper, which would change request objects for every component;
   • patching Http2ServerRequest/Http2ServerResponse prototypes globally, which would change every node:http2 user in the process.

   If Harper later normalizes these objects, this adapter becomes a harmless no-op. Declining the fix leaves a compatibility gap for Next.js sites on http.http2: true.

2. The response is patched in place; the request gets a headers copy. _implicitHeader is set on the response instance and Harper's _nodeRequest identity is kept. The headers are copied because deleting the pseudo-headers from the original breaks req.url and req.method. The trade-off is one object allocation per HTTP/2 request, and Harper's RequestHeaders, which wraps the original object, does not see the filled host. HTTP/1 pays nothing.

3. When host and :authority disagree, the client's host wins. The adapter only fills host when it's absent. The alternatives are to prefer :authority (as Node's req.authority does) or to reject the mismatch, which RFC 9113 §8.3.1 allows. The risk is an intermediary that routes on :authority passing a different host into Next.js's redirects and absolute URLs. Each option is a one-line change.

4. Only the next-16 fixture runs over HTTP/2 end to end. Next.js 14 and 15 bundle the same compression middleware, and the adapter is version-independent. Covering them means adding an http option to each of those fixtures.

One review finding was judged unfounded and left as it is: that instanceof could fail across VM realms. Node built-ins are shared across the process, and the integration test passes on the default loader. The earlier setPrototypeOf question no longer applies, because the copy replaces the prototype swap.

Verification

• Unit, node --test dist/http2Compat.test.js: 10/10 pass. The tests in the new src/http2Compat.test.ts use a real node:http2 server and Next.js 16's own bundled compression. They show that:

  • headers gain hasOwnProperty;
  • the pseudo-headers are gone, url and method still work, and Next.js 16's own fromNodeOutgoingHttpHeaders accepts the result;
  • host is filled from :authority, and a host the client sent is kept;
  • a __proto__ header is copied as a header, not a prototype;
  • gzip and uncompressed responses both complete and decode;
  • _implicitHeader doesn't throw after a client reset;
  • an unadapted pair still reproduces all three failures;
  • HTTP/1 requests are untouched.

  With the adapter turned into a no-op, the positive tests fail.

• Integration, new integrationTests/next-16-http2.pw.ts. It starts Harper with http: { http2: true, mtls: false }, which binds the secure port. With the fix, all four tests pass: the home page returns 200 gzipped over HTTP/2, a hashed static chunk returns 200, a route handler returns its JSON over HTTP/2, and HTTP/1.1 on the same secure port still returns 200. On base, the page and asset tests fail with Protocol error (the stream reset) and the HTTP/1.1 control passes. With the adapter as first pushed (c041944), the route-handler test fails with a 500. integrationTests/fixture.ts gains the http option and passes it into Harper's config.

• Real app. The a homepage build (Next.js 16, webpack) was served through node:http2 with this adapter. The home page, an RSC request, guest-home, a JS chunk and a CSS file all return the same status over HTTP/2 as over HTTP/1.1, gzipped, with no handler errors. On Harper Fabric stage with http.http2: true, the same build returned 500 or INTERNAL_ERROR before the fix.

• Full suites.

  • npm test: 156/156 pass at 1f387cd.
  • npm run test:integration: 46 passed at 1f387cd, with freshly installed fixtures.
  • cluster.pw.ts did not run: its Docker rig couldn't bind port 29925, which an unrelated local container already holds. That's an environment conflict, not a test failure.

• Review of the fix commits. Codex and Gemini reviewed cb0026a and 1f387cd before push, with a Harper-domain adjudication, over two rounds against this branch. It converged with one disputed nit: the fixture route stays JavaScript, like the rest of fixtures/next-16. The footers below record the original review at c041944.

Related PRs: #62 overlaps (edits the same request handler in src/plugin.ts; whichever lands second needs a rebase)
Complexity: medium

_{🤖 Generated by Claude Opus 5.5; posted via @Ethan-Arrowood.}

_{Review-Coverage: authored=claude; ran=codex,gemini; adjudicated=domain; declined=cursor-grok,cursor-composer; rounds=2; full=2 @ c041944}

_{Human-Review-Need: 3 (decisions: host-vs-authority-precedence, per-instance-vs-prototype-shim, compensate-in-plugin-vs-harper) @ c041944}

[gemini-code-assist]

Code Review

This pull request introduces HTTP/2 compatibility support for Next.js by adapting incoming HTTP/2 request and response objects to match the HTTP/1.1 structures expected by Next.js. It includes new integration and unit tests to verify the compatibility. The feedback suggests two improvements: avoiding the performance overhead of Object.setPrototypeOf by using Object.defineProperty to add hasOwnProperty directly to the headers object, and safely handling cases where the :authority header is an array before assigning it to headers.host.

[github-actions]

🎉 This PR is included in version 2.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀