HarperFast / HarperFast/harper

h2c UDS mirror: replace http2 compat mode with a core-API Http2Stream adapter (perf)

Open
#1,708 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

Follow-up to #1707 (h2c UDS mirror, #914 evaluation).

The h2c mirror currently uses `http2.createServer`'s compat mode so it can reuse the h1 request handlers unchanged. Live profiling (perf + `--perf-basic-prof`, full httpChain auth→404 workload) shows the compat path costs **18.2 µs_cpu/req vs 10.2 for the h1 mirror (1.79×)**, and the delta is not in Harper's adapter code:

- **Allocation→GC pressure**: scavenge/marking/sweep ≈ 45% of CPU under h2 vs ~27% under h1 (`Scavenger::ScavengeObject` 13.6% vs 1.8%) — compat allocates Http2ServerRequest/Response wrappers + per-stream state per request.
- **Megamorphic ICs** (~5%: `KeyedLoadIC/LoadIC/KeyedStoreIC_Megamorphic`): Harper's request-path functions see two request shapes (IncomingMessage vs Http2ServerRequest), de-optimizing property access across the pipeline. A synthetic compat server with a trivial handler costs only +1–2µs vs h1 — the polymorphism tax in Harper's pipeline is most of the difference.
- `node:internal/http2` per-request header machinery (`processHeader`, `onSessionHeaders`, `prepareResponseHeaders`).

Proposed fix: use the core `Http2Stream` API (`server.on('stream', ...)`) with a lean, shape-stable Harper request adapter (the same pattern as `BunRequest`/`UwsRequest`), bypassing compat objects entirely. Estimated to reclaim most of the 8µs/req gap; worth doing if/when h2 ingress graduates from the experimental flag.

Generated by an LLM (Claude Fable 5) from profiling done in the #1707 spike.

Contributor guide

Open the contributing guide

Research direction

Start by reading the h2c implementation from #1707 and comparing the existing BunRequest and UwsRequest adapter patterns. Trace the server.on('stream') entry point and define the shape-stable Http2Stream adapter; done means h2c works without compat request/response objects and profiling confirms the intended performance improvement.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js
Domain
backend, performance
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.