fix(h2-transport): return a real node-fetch Response and unref idle sessions

Making HTTP/2 the default surfaced two behaviors of the H2 transport that
only mattered once non-opt-in clients used it:

- `createH2Fetch` returned a bespoke `H2Response`, so `.asResponse()` no longer
  satisfied `instanceof Response` — breaking the generated resource tests that
  assert the raw response is a node-fetch `Response`. Adapt the internal
  `H2Response` to a real node-fetch `Response` at the fetch boundary (streaming
  preserved: the web `ReadableStream` body is consumed as a Node `Readable`).
- Pooled H2 sessions kept the event loop alive, so a short script (and Jest)
  would hang on exit instead of terminating like the HTTP/1.1 transport. Unref
  idle sessions and ref them only while a request is in flight.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Reflex

src/lib/h2-transport/index.ts

@@ -17,9 +17,15 @@
 
 import { Readable } from 'node:stream';
 import { H2Pool, type H2PoolOptions } from './pool';
+import type { H2Response } from './response';
 import { MultipartBody } from '../../_shims/MultipartBody';
+import { Response } from 'node-fetch';
 import { type Fetch } from '../../core';
 
+// Statuses that must not carry a body per the Fetch spec; node-fetch's Response
+// rejects a non-null body for these.
+const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
+
 const MIN_NODE_MAJOR = 18;
 
 function checkNodeVersion(): void {
@@ -63,6 +69,25 @@ async function normalizeBody(body: unknown): Promise<string | Buffer | null> {
   return String(body);
 }
 
+/**
+ * Adapt an internal {@link H2Response} to a standard node-fetch `Response`, so
+ * callers get the same type the default (HTTP/1.1) transport returns — including
+ * `instanceof Response`. Body streaming is preserved: the H2 body is a web
+ * `ReadableStream`, which node-fetch consumes as a Node `Readable`.
+ */
+function toFetchResponse(h2: H2Response): Response {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of h2.headers.entries()) headers[key] = value;
+
+  const body = NULL_BODY_STATUSES.has(h2.status) ? null : Readable.fromWeb(h2.body as any);
+  const response = new Response(body as any, { status: h2.status, headers });
+
+  // node-fetch derives `url` from the request internals it never saw; expose the
+  // real request URL (`Response.url` is a prototype getter, shadowed here).
+  Object.defineProperty(response, 'url', { value: h2.url, configurable: true });
+  return response;
+}
+
 /**
  * Build a fetch adapter backed by native HTTP/2 connection pools.
  *
@@ -109,7 +134,8 @@ export function createH2Fetch(options?: H2PoolOptions): H2Fetch {
     }
 
     const pool = getPool(parsed.origin);
-    return pool.request(path, method.toUpperCase(), reqHeaders, body, signal) as any;
+    const h2resp = await pool.request(path, method.toUpperCase(), reqHeaders, body, signal);
+    return toFetchResponse(h2resp) as any;
   }) as H2Fetch;
 
   h2Fetch.close = async () => {

src/lib/h2-transport/session.ts

@@ -79,6 +79,10 @@ export class H2Session {
         // Enlarge the session-level flow-control window so the server can push
         // large responses without stalling on WINDOW_UPDATE round trips.
         session.setLocalWindowSize(DEFAULT_INITIAL_WINDOW_SIZE);
+        // An idle pooled session must not keep the process alive; each in-flight
+        // request re-refs the socket (see `request`) and it is unref'd again once
+        // the stream count returns to zero.
+        session.unref();
         resolve();
       });
 
@@ -140,6 +144,9 @@ export class H2Session {
 
       const stream = this._session!.request(h2Headers);
       this._activeStreams++;
+      // Keep the process alive while this request is outstanding; idle sessions
+      // are unref'd (see `connect` and `cleanup`).
+      this._session!.ref();
 
       let settled = false;
       let cleaned = false;
@@ -155,6 +162,7 @@ export class H2Session {
           stream.on('error', () => {});
           stream.destroy();
           this._activeStreams--;
+          if (this._activeStreams === 0) this._session?.unref();
           reject(createAbortError());
           return;
         }
@@ -165,6 +173,7 @@ export class H2Session {
         if (cleaned) return;
         cleaned = true;
         this._activeStreams--;
+        if (this._activeStreams === 0) this._session?.unref();
         if (signal) signal.removeEventListener('abort', onAbort);
         if (this._state === SessionState.DRAINING && this._activeStreams === 0) {
           this._close();

tests/lib/h2-transport/integration.test.ts

@@ -1,3 +1,4 @@
+import { Readable } from 'node:stream';
 import { createH2Fetch } from '../../../src/lib/h2-transport/index';
 import { cleanupCerts, testTls } from './helpers/certs';
 import { defaultHandler, startTestServer, TestServer } from './helpers/testServer';
@@ -35,7 +36,9 @@ describe('integration through createH2Fetch', () => {
     } as any)) as any;
     expect(r.headers.get('content-type')).toBe('text/event-stream');
 
-    const reader = r.body.getReader();
+    // `Response.body` is a node-fetch Node `Readable`; wrap it as a web stream
+    // to exercise incremental `getReader()` consumption.
+    const reader = Readable.toWeb(r.body).getReader();
     const decoder = new TextDecoder();
     let buf = '';
     while (true) {