fix: serve Next.js over Harper's HTTP/2 secure port

[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:

• gives the null-prototype headers Object.prototype, because Next.js calls headers.hasOwnProperty();
• 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 Next.js sites on http.http2: false, without Early Hints in Chromium.

2. The request and response are modified in place, not wrapped. In-place costs one instanceof per request and nothing on HTTP/1, and it keeps Harper's _nodeRequest identity. The trade-off is that later readers of the same headers object see the prototype and the filled host. Next.js already runs with that headers shape on HTTP/1. Easy to reverse.

3. _implicitHeader is private Node API, and only its headersSent guard is emulated. compression calls it on every write because Http2ServerResponse never sets _header, so repeat calls must be no-ops. Setting _header = true, as HTTP/1 does, would avoid the repeat calls; it's a one-line change if preferred. A unit test confirms that calling it after the client resets the stream doesn't throw on Node 24.

4. 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.

5. 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.

Two review findings were judged unfounded and left as they are:

• That instanceof could fail across VM realms: Node built-ins are shared across the process, and the integration test passes on the default loader.
• That setPrototypeOf slows V8 down: these headers objects are already in V8's slower dictionary form, and the suggested alternative would leak an own hasOwnProperty key into Object.entries.

Verification

• Unit, node --test dist/http2Compat.test.js: 8/8 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;
  • host is filled from :authority, and a host the client sent is kept;
  • gzip and uncompressed responses both complete and decode;
  • _implicitHeader doesn't throw after a client reset;
  • an unadapted pair still reproduces both 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 three tests pass: the home page returns 200 gzipped over HTTP/2, a hashed static chunk returns 200, and HTTP/1.1 on the same secure port still returns 200. On base, the two HTTP/2 tests fail with Protocol error (the stream reset) and the HTTP/1.1 control passes. integrationTests/fixture.ts gains the http option and passes it into Harper's config.

• Real app. The Tractor Supply 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: 163/163 pass.
  • npm run test:integration: 37 passed before the review fixes. After them, next-16-http2 and next-16 were rerun and pass 8/8.
  • 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.

Complexity: medium

_{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.