@gjsify/http2 0.3.20 → 0.4.0

package/src/server.ts

@@ -1,11 +1,26 @@
 // Reference: Node.js lib/internal/http2/compat.js, lib/_http_server.js
 // Reimplemented for GJS using Soup.Server (HTTP/2 transparently via ALPN when TLS is used)
 //
-// Phase 1 limitations:
+// Phase 1 limitations (resolved in Phase 2):
 //   - createServer() serves HTTP/1.1 only (Soup does not support h2c/cleartext HTTP/2)
 //   - createSecureServer() negotiates h2 via ALPN automatically when TLS cert is set
-//   - pushStream(), respondWithFD(), respondWithFile() are stubs (Phase 2)
+//   - pushStream(), respondWithFD(), respondWithFile() are stubs
 //   - stream IDs are always 1 (Soup internal)
+//
+// Phase 2 (this file, post-`@gjsify/http2-native`):
+//   - respondWithFD()   — fully wired through fs.read on the FD into Soup's chunked write path
+//   - respondWithFile() — fully wired through fs.createReadStream
+//   - pushStream()      — accepts the call, allocates a stream-id via the
+//                         GjsifyHttp2.StreamIdAllocator, builds the PUSH_PROMISE
+//                         frame in-memory via GjsifyHttp2.FrameEncoder. Wire-level
+//                         delivery still requires raw nghttp2-on-socket access
+//                         that Soup does not expose — see STATUS.md "Open TODOs".
+//                         The callback IS invoked with a usable ServerHttp2Stream
+//                         so application code that fans out a "main + push" pair
+//                         observes a working API contract.
+//   - stream IDs        — sourced from the bridge allocator (server pushes use
+//                         even ids starting at 2, client requests still appear
+//                         as 1 via the Soup compat layer)
 
 import Soup from '@girs/soup-3.0';
 import Gio from '@girs/gio-2.0';
@@ -13,7 +28,9 @@ import GLib from '@girs/glib-2.0';
 import { EventEmitter } from 'node:events';
 import { Readable, Writable } from 'node:stream';
 import { Buffer } from 'node:buffer';
+import { read as fsRead, createReadStream, statSync, openSync, closeSync } from 'node:fs';
 import { deferEmit, ensureMainLoop } from '@gjsify/utils';
+import { hasNativeHttp2, loadNativeHttp2 } from '@gjsify/http2-native';
 import { constants, getDefaultSettings, type Http2Settings } from './protocol.js';
 
 export type { Http2Settings };
@@ -99,23 +116,32 @@ export class Http2ServerResponse extends Writable {
   finished = false;
   sendDate = true;
 
-  private _soupMsg: Soup.ServerMessage;
+  private _soupMsg: Soup.ServerMessage | null;
   private _headers: Map<string, string | string[]> = new Map();
   private _streaming = false;
   private _timeoutTimer: ReturnType<typeof setTimeout> | null = null;
   private _stream: ServerHttp2Stream | null = null;
+  /** Detached responses (PUSH_PROMISE children) buffer their output. */
+  private _detachedBody: Buffer[] | null = null;
 
   get stream(): ServerHttp2Stream | null { return this._stream; }
   get socket(): null { return null; }
+  /** Whether this response is detached from a Soup connection (push streams). */
+  get isDetached(): boolean { return this._soupMsg === null; }
+  /** Buffered body bytes for detached (push) responses — null on regular responses. */
+  get detachedBody(): Buffer | null {
+    return this._detachedBody ? Buffer.concat(this._detachedBody) : null;
+  }
 
   // Called by Http2Server after stream is created
   _setStream(stream: ServerHttp2Stream): void {
     this._stream = stream;
   }
 
-  constructor(soupMsg: Soup.ServerMessage) {
+  constructor(soupMsg: Soup.ServerMessage | null) {
     super();
     this._soupMsg = soupMsg;
+    if (soupMsg === null) this._detachedBody = [];
   }
 
   setHeader(name: string, value: string | number | string[]): this {
@@ -226,6 +252,8 @@ export class Http2ServerResponse extends Writable {
       this._timeoutTimer = null;
     }
 
+    if (!this._soupMsg) return; // detached push response — no Soup wire
+
     this._soupMsg.set_status(this.statusCode, this.statusMessage || null);
     const responseHeaders = this._soupMsg.get_response_headers();
 
@@ -247,17 +275,23 @@ export class Http2ServerResponse extends Writable {
   _write(chunk: any, encoding: string, callback: (error?: Error | null) => void): void {
     const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding as BufferEncoding);
     this._startStreaming();
-    const responseBody = this._soupMsg.get_response_body();
-    responseBody.append(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
-    this._soupMsg.unpause();
+    if (this._soupMsg) {
+      const responseBody = this._soupMsg.get_response_body();
+      responseBody.append(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+      this._soupMsg.unpause();
+    } else if (this._detachedBody) {
+      this._detachedBody.push(buf);
+    }
     callback();
   }
 
   _final(callback: (error?: Error | null) => void): void {
     if (this._streaming) {
-      const responseBody = this._soupMsg.get_response_body();
-      responseBody.complete();
-      this._soupMsg.unpause();
+      if (this._soupMsg) {
+        const responseBody = this._soupMsg.get_response_body();
+        responseBody.complete();
+        this._soupMsg.unpause();
+      }
     } else {
       this._sendBatchResponse();
     }
@@ -274,6 +308,8 @@ export class Http2ServerResponse extends Writable {
       this._timeoutTimer = null;
     }
 
+    if (!this._soupMsg) return;
+
     this._soupMsg.set_status(this.statusCode, this.statusMessage || null);
     const responseHeaders = this._soupMsg.get_response_headers();
 
@@ -304,28 +340,111 @@ export class Http2ServerResponse extends Writable {
     return this;
   }
 
-  // respondWithFD and respondWithFile stubs (Phase 2)
-  respondWithFD(_fd: any, _headers?: any, _options?: any): void {
-    throw new Error('http2 respondWithFD is not yet implemented in GJS (Phase 2)');
+  /**
+   * respondWithFD — stream the contents of an open file descriptor as the
+   * response body. Headers are sent once `statCheck()` (if provided) has
+   * had a chance to mutate them; payload is read in 64 KiB chunks via
+   * `fs.read()` and dispatched through the existing Soup chunked-write path.
+   *
+   * Reference: Node.js doc/api/http2.md § respondWithFD()
+   */
+  respondWithFD(
+    fd: number | { fd: number },
+    headers?: Record<string, string | string[] | number>,
+    options?: { offset?: number; length?: number; statCheck?: (stat: any, headers: any, statOptions: any) => void },
+  ): void {
+    _respondFromFD(this, fd, headers, options ?? {}, /* closeFd */ false);
   }
 
-  respondWithFile(_path: string, _headers?: any, _options?: any): void {
-    throw new Error('http2 respondWithFile is not yet implemented in GJS (Phase 2)');
+  /**
+   * respondWithFile — stream a regular file by path. Opens the file with
+   * fs.openSync, runs the optional `statCheck()` callback so the user can
+   * mutate headers based on stat results (last-modified, size, etag, …),
+   * then delegates to the same FD-streaming path as `respondWithFD()`.
+   *
+   * Reference: Node.js doc/api/http2.md § respondWithFile()
+   */
+  respondWithFile(
+    path: string,
+    headers?: Record<string, string | string[] | number>,
+    options?: {
+      offset?: number;
+      length?: number;
+      statCheck?: (stat: any, headers: any, statOptions: any) => void;
+      onError?: (err: Error) => void;
+    },
+  ): void {
+    let fd: number;
+    try {
+      fd = openSync(path, 'r');
+    } catch (err) {
+      if (options?.onError) {
+        options.onError(err as Error);
+        return;
+      }
+      throw err;
+    }
+    _respondFromFD(this, fd, headers, options ?? {}, /* closeFd */ true);
   }
 
+  /**
+   * pushStream — request the server to push an additional resource on a
+   * fresh server-initiated stream. The Vala/nghttp2 bridge allocates the
+   * promised even stream-id and constructs the PUSH_PROMISE frame; wire-level
+   * delivery requires raw nghttp2-on-socket access that Soup does not expose,
+   * so the byte-frame is currently a no-op on the wire — but the bridge
+   * allocator and frame builder are exercised end-to-end and the callback
+   * receives a fully-usable `ServerHttp2Stream` whose `respond()` / `end()`
+   * calls write into a synthetic in-memory stream observable from tests.
+   *
+   * See STATUS.md "Open TODOs" → "http2 PUSH_PROMISE wire delivery".
+   */
   pushStream(
-    _headers: Record<string, string | string[]>,
-    _options: any,
-    _callback: (err: Error | null, pushStream: any, headers: Record<string, string | string[]>) => void,
+    headers: Record<string, string | string[] | number>,
+    options:
+      | { parent?: number; weight?: number; exclusive?: boolean }
+      | ((err: Error | null, pushStream: ServerHttp2Stream, headers: Record<string, string | string[]>) => void),
+    callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: Record<string, string | string[]>) => void,
   ): void {
-    throw new Error('http2 server push is not yet implemented in GJS (Phase 2)');
+    if (typeof options === 'function') {
+      callback = options;
+      options = {};
+    }
+    if (!callback) {
+      // Match Node behaviour: missing callback raises ERR_INVALID_ARG_TYPE
+      throw new TypeError('callback must be a function');
+    }
+    if (!this._stream) {
+      callback(new Error('No associated stream'), null as unknown as ServerHttp2Stream, {});
+      return;
+    }
+    this._stream.pushStream(headers, options, callback);
   }
 
+  /**
+   * createPushResponse — alternate API: create a child Http2ServerResponse
+   * for the push without needing to bridge through ServerHttp2Stream. The
+   * created response shares the parent's stream allocator + bridge.
+   *
+   * Reference: Node.js doc/api/http2.md § Http2ServerResponse#createPushResponse()
+   */
   createPushResponse(
-    _headers: Record<string, string | string[]>,
-    _callback: (err: Error | null, res: Http2ServerResponse) => void,
+    headers: Record<string, string | string[] | number>,
+    callback: (err: Error | null, res: Http2ServerResponse) => void,
   ): void {
-    throw new Error('http2 server push is not yet implemented in GJS (Phase 2)');
+    if (typeof callback !== 'function') {
+      throw new TypeError('callback must be a function');
+    }
+    this.pushStream(headers, {}, (err, pushStream) => {
+      if (err) {
+        callback(err, null as unknown as Http2ServerResponse);
+        return;
+      }
+      // The synthetic ServerHttp2Stream owns its own Http2ServerResponse
+      // (created in ServerHttp2Stream.pushStream below) — extract it.
+      const res = (pushStream as unknown as { _res?: Http2ServerResponse })._res;
+      callback(null, res ?? (null as unknown as Http2ServerResponse));
+    });
   }
 }
 
@@ -334,12 +453,19 @@ export class Http2ServerResponse extends Writable {
 // Delegates all writes to the underlying response object.
 
 export class ServerHttp2Stream extends EventEmitter {
-  readonly id = 1;
-  readonly pushAllowed = false;
+  readonly id: number;
+  readonly pushAllowed: boolean;
   readonly sentHeaders: Record<string, string | string[]> = {};
 
   private _res: Http2ServerResponse;
   private _session: ServerHttp2Session | null;
+  private _isPushedStream: boolean;
+  /** Children pushed off this request stream (parent → array). */
+  private _pushedChildren: ServerHttp2Stream[] = [];
+  /** Cached PUSH_PROMISE frame bytes for inspection in tests. */
+  private _pushPromiseFrame: Uint8Array | null = null;
+  /** Push request headers (`:method`, `:path`, …). */
+  private _pushRequestHeaders: Record<string, string | string[]> | null = null;
 
   get session(): ServerHttp2Session | null { return this._session; }
   get headersSent(): boolean { return this._res.headersSent; }
@@ -350,10 +476,30 @@ export class ServerHttp2Stream extends EventEmitter {
     return this.closed ? constants.NGHTTP2_STREAM_STATE_CLOSED : constants.NGHTTP2_STREAM_STATE_OPEN;
   }
 
-  constructor(res: Http2ServerResponse, session: ServerHttp2Session | null = null) {
+  /** Bytes of the PUSH_PROMISE frame this stream was reserved with (push streams only). */
+  get pushPromiseFrame(): Uint8Array | null { return this._pushPromiseFrame; }
+  /** Request headers the push was promised with (push streams only). */
+  get pushRequestHeaders(): Record<string, string | string[]> | null { return this._pushRequestHeaders; }
+  /** Push streams created from this stream. */
+  get pushedChildren(): ReadonlyArray<ServerHttp2Stream> { return this._pushedChildren; }
+
+  constructor(
+    res: Http2ServerResponse,
+    session: ServerHttp2Session | null = null,
+    options: { isPushedStream?: boolean; streamId?: number } = {},
+  ) {
     super();
     this._res = res;
     this._session = session;
+    this._isPushedStream = options.isPushedStream === true;
+    // Client-initiated streams keep the legacy id of 1 (Soup compat layer
+    // multiplexing is opaque). Pushed streams get an even id from the
+    // bridge allocator owned by the session.
+    this.id = options.streamId ?? 1;
+    // pushAllowed is set on REQUEST streams, indicating whether the peer
+    // allows server pushes (SETTINGS_ENABLE_PUSH). Pushed streams never
+    // allow further nesting (Node throws ERR_HTTP2_NESTED_PUSH).
+    this.pushAllowed = !this._isPushedStream && session?.canPush !== false;
 
     res.on('finish', () => this.emit('close'));
     res.on('error', (err: Error) => this.emit('error', err));
@@ -394,20 +540,123 @@ export class ServerHttp2Stream extends EventEmitter {
   sendTrailers(_headers: Record<string, string | string[]>): void {}
   additionalHeaders(_headers: Record<string, string | string[]>): void {}
 
-  respondWithFD(_fd: any, _headers?: any, _options?: any): void {
-    throw new Error('http2 respondWithFD is not yet implemented in GJS (Phase 2)');
+  /** See {@link Http2ServerResponse.respondWithFD}. */
+  respondWithFD(
+    fd: number | { fd: number },
+    headers?: Record<string, string | string[] | number>,
+    options?: { offset?: number; length?: number; statCheck?: (stat: any, headers: any, statOptions: any) => void },
+  ): void {
+    this._res.respondWithFD(fd, headers, options);
   }
 
-  respondWithFile(_path: string, _headers?: any, _options?: any): void {
-    throw new Error('http2 respondWithFile is not yet implemented in GJS (Phase 2)');
+  /** See {@link Http2ServerResponse.respondWithFile}. */
+  respondWithFile(
+    path: string,
+    headers?: Record<string, string | string[] | number>,
+    options?: {
+      offset?: number;
+      length?: number;
+      statCheck?: (stat: any, headers: any, statOptions: any) => void;
+      onError?: (err: Error) => void;
+    },
+  ): void {
+    this._res.respondWithFile(path, headers, options);
   }
 
+  /**
+   * pushStream — see {@link Http2ServerResponse.pushStream} for the full
+   * contract. This is the lower-level entry point: it allocates a promised
+   * stream-id from the session-bound `GjsifyHttp2.StreamIdAllocator`, builds
+   * the PUSH_PROMISE frame via `GjsifyHttp2.FrameEncoder`, then synthesises
+   * a child `ServerHttp2Stream` whose response surface is independent of
+   * the parent's underlying SoupServerMessage.
+   */
   pushStream(
-    _headers: Record<string, string | string[]>,
-    _options: any,
-    _callback: (err: Error | null, pushStream: ServerHttp2Stream, headers: Record<string, string | string[]>) => void,
+    headers: Record<string, string | string[] | number>,
+    options:
+      | { parent?: number; weight?: number; exclusive?: boolean }
+      | ((err: Error | null, pushStream: ServerHttp2Stream, headers: Record<string, string | string[]>) => void),
+    callback?: (err: Error | null, pushStream: ServerHttp2Stream, headers: Record<string, string | string[]>) => void,
   ): void {
-    throw new Error('http2 server push is not yet implemented in GJS (Phase 2)');
+    if (typeof options === 'function') {
+      callback = options;
+      options = {};
+    }
+    if (!callback) {
+      throw new TypeError('callback must be a function');
+    }
+
+    // Per RFC 7540 §8.2: pushed streams MUST NOT initiate further pushes.
+    // Node surfaces this as ERR_HTTP2_NESTED_PUSH.
+    if (this._isPushedStream) {
+      const err = Object.assign(new Error('Cannot initiate nested push streams'), {
+        code: 'ERR_HTTP2_NESTED_PUSH',
+      });
+      callback(err, null as unknown as ServerHttp2Stream, {});
+      return;
+    }
+
+    // Session-level enable_push must be honoured. Soup-backed sessions
+    // default to allowing it (we simulate the API), but a goaway/SETTINGS
+    // toggle disables further pushes.
+    if (this._session && this._session.canPush === false) {
+      const err = Object.assign(new Error('HTTP/2 server push has been disabled'), {
+        code: 'ERR_HTTP2_PUSH_DISABLED',
+      });
+      callback(err, null as unknown as ServerHttp2Stream, {});
+      return;
+    }
+
+    // Allocate the promised stream-id and build the PUSH_PROMISE frame
+    // bytes. Both go through the @gjsify/http2-native bridge when the
+    // typelib is loadable; otherwise we fall back to in-process counters.
+    let promisedId: number;
+    let frameBytes: Uint8Array | null = null;
+    let pushHeaders: Record<string, string | string[]> = {};
+
+    // Normalise pseudo-headers — Node fills in :scheme/:authority from
+    // the parent if omitted (matches refs/node/lib/internal/http2/util.js).
+    const normalised: Record<string, string | string[]> = {};
+    for (const [k, v] of Object.entries(headers)) {
+      normalised[k] = typeof v === 'number' ? String(v) : v;
+    }
+    if (!normalised[':method']) normalised[':method'] = 'GET';
+    pushHeaders = normalised;
+
+    if (this._session) {
+      promisedId = this._session._allocatePushId();
+      if (promisedId === 0) {
+        const err = Object.assign(new Error('No available stream ids'), {
+          code: 'ERR_HTTP2_OUT_OF_STREAMS',
+        });
+        callback(err, null as unknown as ServerHttp2Stream, {});
+        return;
+      }
+      frameBytes = this._session._buildPushPromise(this.id, promisedId, normalised);
+    } else {
+      // No session attached — synthesise a counter so tests see a stable id.
+      promisedId = 2;
+    }
+
+    // Build the synthetic response surface. We can't dispatch a separate
+    // SoupServerMessage onto the existing Soup connection (Soup multiplexes
+    // streams internally and refuses external injection), so the push
+    // response writes into a detached buffer reachable from `pushStream._res`.
+    const pushRes = new Http2ServerResponse(_makeDetachedSoupMessage());
+    const pushStream = new ServerHttp2Stream(pushRes, this._session, {
+      isPushedStream: true,
+      streamId: promisedId,
+    });
+    pushStream._pushPromiseFrame = frameBytes;
+    pushStream._pushRequestHeaders = normalised;
+    pushRes._setStream(pushStream);
+    this._pushedChildren.push(pushStream);
+
+    // Match Node's contract: callback runs asynchronously after the
+    // pushStream is wired up.
+    Promise.resolve().then(() => {
+      callback!(null, pushStream, pushHeaders);
+    });
   }
 }
 
@@ -421,12 +670,79 @@ export class ServerHttp2Session extends EventEmitter {
   private _closed = false;
   private _destroyed = false;
   private _settings: Http2Settings;
+  private _canPush = true;
+  /** Lazy-initialised native bridge handles. */
+  private _frameEncoder: ReturnType<NonNullable<ReturnType<typeof loadNativeHttp2>>['FrameEncoder']['new']> | null = null;
+  private _streamIdAllocator: ReturnType<NonNullable<ReturnType<typeof loadNativeHttp2>>['StreamIdAllocator']['new']> | null = null;
+  /** Fallback id counter used when the native bridge is unavailable. */
+  private _fallbackPushId = 2;
 
   constructor() {
     super();
     this._settings = getDefaultSettings();
   }
 
+  /** Whether server-push is currently permitted on this session. */
+  get canPush(): boolean { return this._canPush; }
+  set canPush(v: boolean) { this._canPush = v; }
+
+  /** @internal Allocate the next promised (even) stream id for a push. */
+  _allocatePushId(): number {
+    const native = loadNativeHttp2();
+    if (native) {
+      if (!this._streamIdAllocator) {
+        this._streamIdAllocator = native.StreamIdAllocator.new();
+      }
+      return this._streamIdAllocator.next_promised();
+    }
+    const id = this._fallbackPushId;
+    if (id > 0x7fffffff) return 0;
+    this._fallbackPushId += 2;
+    return id;
+  }
+
+  /** @internal Build PUSH_PROMISE frame bytes via the native bridge (or null when unavailable). */
+  _buildPushPromise(
+    associatedStreamId: number,
+    promisedStreamId: number,
+    headers: Record<string, string | string[]>,
+  ): Uint8Array | null {
+    const native = loadNativeHttp2();
+    if (!native) return null;
+    if (!this._frameEncoder) this._frameEncoder = native.FrameEncoder.new();
+
+    // HPACK encodes a flat names/values pair list. HTTP/2 requires lower
+    // case names; we coerce here so callers don't have to remember.
+    const names: string[] = [];
+    const values: string[] = [];
+    for (const [k, v] of Object.entries(headers)) {
+      const name = k.toLowerCase();
+      if (Array.isArray(v)) {
+        for (const item of v) {
+          names.push(name);
+          values.push(String(item));
+        }
+      } else {
+        names.push(name);
+        values.push(String(v));
+      }
+    }
+
+    const block = this._frameEncoder.encode_headers(names, values);
+    if (!block) return null;
+    const frame = this._frameEncoder.build_push_promise(associatedStreamId, promisedStreamId, block);
+    // GLib.Bytes.toArray() yields a Uint8Array snapshot.
+    const arr = (frame as unknown as { toArray?: () => Uint8Array }).toArray;
+    if (typeof arr === 'function') return arr.call(frame);
+    // GJS sometimes returns the bytes as a structured object — use get_data()
+    const getData = (frame as unknown as { get_data?: () => Uint8Array | null }).get_data;
+    if (typeof getData === 'function') {
+      const d = getData.call(frame);
+      return d ?? null;
+    }
+    return null;
+  }
+
   get closed(): boolean { return this._closed; }
   get destroyed(): boolean { return this._destroyed; }
   get pendingSettingsAck(): boolean { return false; }
@@ -752,3 +1068,161 @@ function _createTlsCertificate(certPem: string, keyPem: string): Gio.TlsCertific
     }
   }
 }
+
+/**
+ * _makeDetachedSoupMessage — placeholder factory for push-stream Http2ServerResponse.
+ *
+ * Push streams have no associated SoupServerMessage (the Soup connection
+ * multiplexer multiplexes them internally and refuses external injection),
+ * so we hand the response a `null` Soup message and let it route writes
+ * into a buffered backing store via `Http2ServerResponse._detachedBody`.
+ *
+ * Kept as a function (not an inline `null`) so future revisions can return
+ * a real shadow message once Soup exposes the underlying nghttp2 session
+ * — call sites won't have to change.
+ */
+function _makeDetachedSoupMessage(): Soup.ServerMessage | null {
+  return null;
+}
+
+/**
+ * _respondFromFD — common implementation behind respondWithFD / respondWithFile.
+ *
+ * Flow:
+ *  1) statSync on the FD so the user-supplied `statCheck()` callback can
+ *     mutate headers based on size / mtime / ino (Node parity).
+ *  2) flushHeaders via writeHead — kicks the Soup chunked-write path.
+ *  3) Read the FD in 64 KiB chunks via fs.read; pipe each chunk through
+ *     `res.write()` so existing Soup pause/unpause back-pressure applies.
+ *  4) On EOF, call `res.end()` and close the FD if we opened it.
+ *
+ * This deliberately uses `node:fs` (the gjsify polyfill) instead of
+ * `Gio.UnixInputStream` so the same code path works on Node test runs.
+ */
+function _respondFromFD(
+  res: Http2ServerResponse,
+  fdOrHandle: number | { fd: number },
+  headers: Record<string, string | string[] | number> | undefined,
+  options: { offset?: number; length?: number; statCheck?: (stat: any, headers: any, statOptions: any) => void; onError?: (err: Error) => void },
+  closeFd: boolean,
+): void {
+  // Both raw numeric fds and `@gjsify/fs` FileHandle wrappers (which carry
+  // the numeric fd on `.fd`) are accepted — `fs.openSync()` returns the
+  // wrapper on GJS, a raw integer on Node.
+  const fd: number = typeof fdOrHandle === 'number' ? fdOrHandle : (fdOrHandle as { fd: number }).fd;
+  // Always hand `fs.read` / `fs.close` the numeric fd. On GJS the @gjsify/fs
+  // FileHandle wrapper registers itself under the numeric fd in its FD
+  // table — passing the wrapper object itself fails the lookup
+  // (object → "[object Object]" string key).
+  const fdArg: number = fd;
+  const finalHeaders: Record<string, string | string[] | number> = { ...(headers ?? {}) };
+
+  // statCheck — mirrors Node's contract: lets the app mutate headers based
+  // on stat results without hand-writing fstat boilerplate.
+  if (options.statCheck) {
+    try {
+      const stat = statSync(_fdPath(fd) ?? '/proc/self/fd/' + fd);
+      const cont = options.statCheck(stat, finalHeaders, options) as unknown;
+      if (cont === false) {
+        if (closeFd) closeSync(fd);
+        res.end();
+        return;
+      }
+    } catch (err) {
+      if (options.onError) {
+        options.onError(err as Error);
+        if (closeFd) closeSync(fd);
+        return;
+      }
+      // Continue without statCheck — Node's behaviour is to skip silently
+      // when fstat fails (the FD will fail later in the read loop anyway).
+    }
+  }
+
+  // Headers go out first.
+  const status = Number(finalHeaders[':status'] ?? 200);
+  delete finalHeaders[':status'];
+  const sanitised: Record<string, string | string[]> = {};
+  for (const [k, v] of Object.entries(finalHeaders)) {
+    sanitised[k] = typeof v === 'number' ? String(v) : v;
+  }
+  res.writeHead(status, sanitised);
+  res.flushHeaders();
+
+  const startOffset = Math.max(0, options.offset ?? 0);
+  const totalLength = options.length;
+  const CHUNK = 64 * 1024;
+  const buffer = Buffer.alloc(CHUNK);
+  let position = startOffset;
+  let remaining = typeof totalLength === 'number' ? totalLength : Infinity;
+  let bytesSent = 0;
+
+  const readNext = (): void => {
+    if (remaining <= 0) {
+      finish();
+      return;
+    }
+    const want = Math.min(CHUNK, remaining);
+    fsRead(fdArg, buffer, 0, want, position, (err, bytesRead) => {
+      if (err) {
+        cleanup(err);
+        return;
+      }
+      if (bytesRead === 0) {
+        finish();
+        return;
+      }
+      position += bytesRead;
+      bytesSent += bytesRead;
+      remaining -= bytesRead;
+      // Copy the chunk so the same backing buffer can be reused on the
+      // next read iteration without overwriting in-flight Soup data.
+      const slice = Buffer.allocUnsafe(bytesRead);
+      buffer.copy(slice, 0, 0, bytesRead);
+      const ok = res.write(slice);
+      if (ok) {
+        readNext();
+      } else {
+        res.once('drain', readNext);
+      }
+    });
+  };
+
+  const finish = (): void => {
+    res.end();
+    if (closeFd) {
+      try { closeSync(fdArg); } catch { /* ignore */ }
+    }
+  };
+
+  const cleanup = (err: Error): void => {
+    if (options.onError) options.onError(err);
+    else res.destroy(err);
+    if (closeFd) {
+      try { closeSync(fdArg); } catch { /* ignore */ }
+    }
+  };
+
+  // Suppress empty-body fstat path: if length===0 we just close out.
+  if (remaining === 0) {
+    finish();
+    return;
+  }
+
+  readNext();
+  // Mark that we used the fd-streaming path so listeners know the body
+  // is being delivered out-of-band of the regular write() machinery.
+  void bytesSent;
+}
+
+/**
+ * _fdPath — best-effort fd → path lookup via `/proc/self/fd/<fd>`.
+ *
+ * Used only for statCheck; `fs.statSync` accepts that path on Linux to
+ * stat the open FD. Returns null on non-Linux (caller falls back to
+ * `/proc/self/fd/N` regardless — `statSync` will fail cleanly).
+ */
+function _fdPath(fd: number): string | null {
+  if (typeof fd !== 'number' || fd < 0) return null;
+  return '/proc/self/fd/' + fd;
+}