h2lean 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 <div align="center">
 
-<img src="assets/banner.svg" alt="h2lite banner" width="720">
+<img src="assets/banner.svg" alt="h2lean banner" width="720">
 
 ### The pure-JavaScript HTTP/2 stack for Node.js
 
 **Drop-in replacement for `node:http2` — without the nghttp2 C layer.**
 
-[![npm](https://img.shields.io/badge/npm-v0.1.0-cb3837)](https://www.npmjs.com/package/h2lite)
+[![npm](https://img.shields.io/badge/npm-v0.1.0-cb3837)](https://www.npmjs.com/package/h2lean)
 [![node](https://img.shields.io/badge/node-%E2%89%A520-339933)](https://nodejs.org)
 [![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -19,7 +19,7 @@ Up to **8× less CPU per request** and **6.8× more requests per second** than `
 
 ## 📑 Table of Contents
 
-- ⚡ [Why h2lite?](#-why-h2lite)
+- ⚡ [Why h2lean?](#-why-h2lean)
 - 🏎️ [Performance](#️-performance)
 - 🔌 [Compatibility — Drop-in Replacement](#-compatibility--drop-in-replacement)
 - 📦 [Installation](#-installation)
@@ -37,18 +37,18 @@ Up to **8× less CPU per request** and **6.8× more requests per second** than `
 - 🤝 [Contributing](#-contributing)
 - ⚖️ [License](#️-license)
 
-## ⚡ Why h2lite?
+## ⚡ Why h2lean?
 
 Node's native `node:http2` (stable since v10.10.0) has a fundamental architectural constraint: every HTTP/2 frame crosses the JS ↔ C++ boundary between V8 and bundled nghttp2. Frame dispatch, HPACK encoding/decoding, and flow-control bookkeeping all pay for that crossing — on every single frame of every single request.
 
-**h2lite removes the crossing entirely.** The entire protocol — frame parsing, HPACK (RFC 7541), flow control, connection state machines — lives in pure JavaScript, tuned item by item against measured data ([OPTIMIZATION.md](./OPTIMIZATION.md), 35 numbered techniques). Zero native code, zero runtime dependencies.
+**h2lean removes the crossing entirely.** The entire protocol — frame parsing, HPACK (RFC 7541), flow control, connection state machines — lives in pure JavaScript, tuned item by item against measured data ([OPTIMIZATION.md](./OPTIMIZATION.md), 35 numbered techniques). Zero native code, zero runtime dependencies.
 
 The result is a library that keeps `node:http2`'s exact public surface while spending dramatically less CPU per request. Perfect for:
 
 - 🧩 **Microservices** — header-heavy service-to-service traffic is where the gap is widest
 - 📡 **gRPC servers** — many small streams, all header-bound
 - 🤖 **AI backends** — long-lived streams, high connection counts, every CPU cycle matters
-- 🔁 **Behind a reverse proxy** — pair h2lite with an HTTP/2-terminating edge and stop paying for HTTP/1.1
+- 🔁 **Behind a reverse proxy** — pair h2lean with an HTTP/2-terminating edge and stop paying for HTTP/1.1
 
 ## 🏎️ Performance
 
@@ -61,14 +61,14 @@ Every number below is `node`'s own per-request CPU time (μs/req, read inside th
 | node:http (HTTP/1.1) | 9.11 | 111,816 | 1.21× |
 | uWebSockets C++ (HTTP/1.1) | 4.87 | 203,283 | 2.27× |
 | node:http2 (stream API) | 7.30 | 171,835 | 1.52× |
-| **h2lite (stream API)** | **1.38** | **765,149** | **8.01×** |
-| **h2lite (compat API)** | **2.85** | **367,275** | **3.88×** |
+| **h2lean (stream API)** | **1.38** | **765,149** | **8.01×** |
+| **h2lean (compat API)** | **2.85** | **367,275** | **3.88×** |
 
-**Server, with response body:** 16 kB — **2.50× less CPU** than `node:http2` ([PERFORMANCE.md](./PERFORMANCE.md)). 256 kB — parity, as expected: the work is body-bound, and h2lite does not win by cutting corners.
+**Server, with response body:** 16 kB — **2.50× less CPU** than `node:http2` ([PERFORMANCE.md](./PERFORMANCE.md)). 256 kB — parity, as expected: the work is body-bound, and h2lean does not win by cutting corners.
 
-**Client, same-server paired measurement** (`h2lite.connect()` vs `node:http2.connect()`, driven against nghttpd):
+**Client, same-server paired measurement** (`h2lean.connect()` vs `node:http2.connect()`, driven against nghttpd):
 
-| Workload | node client μs/req | h2lite client μs/req | Advantage |
+| Workload | node client μs/req | h2lean client μs/req | Advantage |
 |---|--:|--:|---|
 | Headers only | 12.08 | **3.61** | 3.35× |
 | 16 kB | 19.66 | **11.73** | 1.68× |
@@ -78,11 +78,11 @@ Every number below is `node`'s own per-request CPU time (μs/req, read inside th
 
 ## 🔌 Compatibility — Drop-in Replacement
 
-Compatibility target is the **public surface** of `node:http2`: names, argument shapes, event orders, wire-visible frame sequences, `rstCode`/`goawayCode` numbers — verified differentially. The test suite runs the **same application scripts** against both `node:http2` and h2lite and compares the transcripts ([test/diff-harness.js](./test/diff-harness.js)); [h2spec](https://github.com/summerwind/h2spec) conformance is 146/146 — the same verdict node's own HTTP/2 receives.
+Compatibility target is the **public surface** of `node:http2`: names, argument shapes, event orders, wire-visible frame sequences, `rstCode`/`goawayCode` numbers — verified differentially. The test suite runs the **same application scripts** against both `node:http2` and h2lean and compares the transcripts ([test/diff-harness.js](./test/diff-harness.js)); [h2spec](https://github.com/summerwind/h2spec) conformance is 146/146 — the same verdict node's own HTTP/2 receives.
 
 ```diff
 - const http2 = require('node:http2');
-+ const http2 = require('h2lite');
++ const http2 = require('h2lean');
 
   const server = http2.createServer((req, res) => {
     res.end('hello world');
@@ -97,7 +97,7 @@ Where behavior deliberately differs from node, it is **documented, measured, and
 ## 📦 Installation
 
 ```bash
-npm install h2lite
+npm install h2lean
 ```
 
 Requires Node.js **≥ 20** (verified against v26.12.1). Zero runtime dependencies — `lib/` imports nothing but `node:` builtins.
@@ -109,12 +109,12 @@ Requires Node.js **≥ 20** (verified against v26.12.1). Zero runtime dependenci
 The compat API feels like HTTP/1.1 but speaks HTTP/2 — this is what replaces `node:http2` in an existing application:
 
 ```javascript
-const http2 = require('h2lite');
+const http2 = require('h2lean');
 
 const server = http2.createServer((req, res) => {
   // req is an Http2ServerRequest, res is an Http2ServerResponse
   res.writeHead(200, { 'content-type': 'text/plain' });
-  res.end('hello from h2lite');
+  res.end('hello from h2lean');
 });
 
 server.listen(8080);
@@ -125,7 +125,7 @@ server.listen(8080);
 Maximum throughput: skip the compat objects entirely and work with streams and header maps:
 
 ```javascript
-const http2 = require('h2lite');
+const http2 = require('h2lean');
 
 const server = http2.createServer();
 
@@ -140,7 +140,7 @@ server.listen(8081);
 ### Secure server (h2s / TLS)
 
 ```javascript
-const http2 = require('h2lite');
+const http2 = require('h2lean');
 
 const server = http2.createSecureServer({
   key: require('fs').readFileSync('key.pem'),
@@ -160,7 +160,7 @@ TLS decisions stay delegated to `node:tls` — ALPN is pinned to `h2` exactly th
 ### Client — `connect()`
 
 ```javascript
-const http2 = require('h2lite');
+const http2 = require('h2lean');
 
 const session = http2.connect('http://localhost:8080');
 
@@ -179,20 +179,20 @@ Works over `https://…` too — the client speaks both h2c and h2s.
 
 ### Fastify and other frameworks
 
-Any framework that lets you hand it a server instance takes h2lite in two lines. Fastify's [`serverFactory`](https://fastify.dev/docs/latest/Reference/Server/#serverfactory):
+Any framework that lets you hand it a server instance takes h2lean in two lines. Fastify's [`serverFactory`](https://fastify.dev/docs/latest/Reference/Server/#serverfactory):
 
 ```javascript
 const Fastify = require('fastify');
-const h2lite = require('h2lite');
+const h2lean = require('h2lean');
 
 const fastify = Fastify({
   http2: true,
   serverFactory: (handler) => {
-    return h2lite.createServer((req, res) => handler(req, res));
+    return h2lean.createServer((req, res) => handler(req, res));
   }
 });
 
-fastify.get('/', async () => ({ hello: 'from h2lite under Fastify' }));
+fastify.get('/', async () => ({ hello: 'from h2lean under Fastify' }));
 fastify.listen({ port: 8080 });
 ```
 
@@ -203,16 +203,16 @@ If a framework requires `node:http2` internally and offers no injection point, p
 ```javascript
 // patch.js — require this first: node -r ./patch.js app.js
 const nodeHttp2 = require('node:http2');
-const h2lite = require('h2lite');
+const h2lean = require('h2lean');
 
-nodeHttp2.createServer = h2lite.createServer;
-nodeHttp2.createSecureServer = h2lite.createSecureServer;
-nodeHttp2.connect = h2lite.connect;
+nodeHttp2.createServer = h2lean.createServer;
+nodeHttp2.createSecureServer = h2lean.createSecureServer;
+nodeHttp2.connect = h2lean.connect;
 ```
 
 ## 🛠️ Advanced Tuning
 
-- ♻️ **Freeze reusable header objects.** `Object.freeze()` on a header set enables h2lite's per-connection response-block cache — the HPACK bytes are encoded once and copied afterwards. Measured **~25% CPU saved** on a headers-only workload ([PERFORMANCE.md](./PERFORMANCE.md)):
+- ♻️ **Freeze reusable header objects.** `Object.freeze()` on a header set enables h2lean's per-connection response-block cache — the HPACK bytes are encoded once and copied afterwards. Measured **~25% CPU saved** on a headers-only workload ([PERFORMANCE.md](./PERFORMANCE.md)):
 
   ```javascript
   const HEADERS = Object.freeze({ ':status': 200, 'content-type': 'application/json' });
@@ -225,18 +225,18 @@ nodeHttp2.connect = h2lite.connect;
 
 ## 🔒 Security
 
-h2lite terminates **untrusted bytes from the internet** and turns them into objects your application trusts — the threat model is treated as the primary design constraint ([SECURITY.md](./SECURITY.md)):
+h2lean terminates **untrusted bytes from the internet** and turns them into objects your application trusts — the threat model is treated as the primary design constraint ([SECURITY.md](./SECURITY.md)):
 
-- 🛡️ **Every denial-of-service limit matches nghttp2** (the engine inside node) or was measured against a live node server — a peer's budget against node is its budget against h2lite: SETTINGS-entry cap (CVE-2020-11080), CONTINUATION cap (CVE-2024-28182), rapid-reset budget (CVE-2023-44487), outbound staging, parked-stream and history bounds.
-- 🚫 **Request-smuggling defense by construction** (RFC 9113 §10.3): field names must be lower-case tokens, values may not carry NUL/CR/LF, connection-specific fields are refused in both directions — all refused at encode time, *before a single octet reaches the wire*. h2lite is stricter than node here, deliberately and measurably.
+- 🛡️ **Every denial-of-service limit matches nghttp2** (the engine inside node) or was measured against a live node server — a peer's budget against node is its budget against h2lean: SETTINGS-entry cap (CVE-2020-11080), CONTINUATION cap (CVE-2024-28182), rapid-reset budget (CVE-2023-44487), outbound staging, parked-stream and history bounds.
+- 🚫 **Request-smuggling defense by construction** (RFC 9113 §10.3): field names must be lower-case tokens, values may not carry NUL/CR/LF, connection-specific fields are refused in both directions — all refused at encode time, *before a single octet reaches the wire*. h2lean is stricter than node here, deliberately and measurably.
 - ✅ **Verified, not assumed:**
-  - **300+ differential tests** — application scripts run against both `node:http2` and h2lite, transcripts compared;
+  - **300+ differential tests** — application scripts run against both `node:http2` and h2lean, transcripts compared;
   - **h2spec 146/146** — full RFC 9113/7541 conformance, same verdict as node's own HTTP/2 (`npm run spec`);
   - **mutation-tested guards** — every defensive limit is rewritten in place and proven to fail the suite ([tools/mutate-guards.js](./tools/mutate-guards.js)).
 
 ## ⚠️ Not Implemented — Said Loudly
 
-Two APIs are absent, and both fail **loudly** with `ERR_H2LITE_NOT_IMPLEMENTED` — never a silent wrong answer:
+Two APIs are absent, and both fail **loudly** with `ERR_H2LEAN_NOT_IMPLEMENTED` — never a silent wrong answer:
 
 - **Server push** — removed from browsers in 2022 and considered obsolete; the safer replacement is [Early Hints (103)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/103).
 - **`performServerHandshake`** — no known use case outside node's own tests.

package/index.js

@@ -1,4 +1,4 @@
-// h2lite -- a pure-JS HTTP/2 library with a node:http2-shaped API.
+// h2lean -- a pure-JS HTTP/2 library with a node:http2-shaped API.
 //
 // Servers: h2c and h2s (prior-knowledge, ALPN 'h2'), the `stream` and compat
 // (`request`) APIs. Client: `connect()` + `session.request()` over h2c and h2s

package/lib/client-session.js

@@ -561,7 +561,7 @@ class ClientHttp2Session extends EventEmitter {
   // is up (internal/http2/core.js setupHandle -> nextTick(emit, 'connect')) and
   // submits the request then, so the request goes out in the first flight. Measured
   // against a raw server that delays its SETTINGS by 200 ms: node's request HEADERS
-  // arrive at 5 ms, while h2lite's used to arrive at 225 ms -- after the SETTINGS it
+  // arrive at 5 ms, while h2lean's used to arrive at 225 ms -- after the SETTINGS it
   // was waiting for -- which is a round trip on every session's first request
   // (tools/probe-client-first.js).
   //
@@ -1795,7 +1795,7 @@ class ClientHttp2Session extends EventEmitter {
     // state.pendingStreams.forEach((stream) => stream.destroy(cancel))) so an
     // application can tell "my request was never sent" from "the connection broke
     // under it". Measured on a TLS handshake failure: node answers a queued request
-    // with stream error ERR_HTTP2_STREAM_CANCEL before the session error, h2lite used
+    // with stream error ERR_HTTP2_STREAM_CANCEL before the session error, h2lean used
     // to leave it silent.
     if (this._queuedReq !== null && this._queuedReq.length > 0) {
       for (const r of this._queuedReq) {

package/lib/client-stream.js

@@ -4,7 +4,7 @@
 // `internal/http2/core.js`. Two shapes are load-bearing for a drop-in:
 //  * it is a `stream.Duplex` with `allowHalfOpen: true`, so ending the request
 //    body (writable) does not close the response (readable). node's `Http2Stream`
-//    extends Duplex (core.js:2128); h2lite's SERVER stream is an EventEmitter
+//    extends Duplex (core.js:2128); h2lean's SERVER stream is an EventEmitter
 //    (AGENTS.md 10) but a client stream the application `.pipe()`s and reads
 //    `:status` off has to be a real Duplex or the common
 //    `req.pipe(server).pipe(res)` idiom breaks.

package/lib/client.js

@@ -1,7 +1,7 @@
 // connect(): the client front door. Mirrors node's `connect(authority, options,
 // listener)` in internal/http2/core.js -- same argument juggling, same
 // authority/protocol/port derivation, same `createConnection` override -- so that
-// `require('h2lite').connect(url)` is a drop-in for `require('node:http2').connect(url)`.
+// `require('h2lean').connect(url)` is a drop-in for `require('node:http2').connect(url)`.
 //
 // Both transports are supported: h2c over `net`, and h2s over `tls.connect` the
 // way core.js initializeTLSOptions builds it -- the ALPN list is forced to ['h2']
@@ -19,8 +19,8 @@ const tls = require('node:tls');
 const { ClientHttp2Session } = require('./client-session');
 
 function notImplemented(what) {
-  const err = new Error(`h2lite: not implemented: ${what}`);
-  err.code = 'ERR_H2LITE_NOT_IMPLEMENTED';
+  const err = new Error(`h2lean: not implemented: ${what}`);
+  err.code = 'ERR_H2LEAN_NOT_IMPLEMENTED';
   return err;
 }
 

package/lib/compat.js

@@ -5,22 +5,22 @@
 //
 // Deliberate differences from node, all of them loud rather than silent:
 //   * req.pause()/read() only affect the local Readable. The flow-control window
-//     is still replenished, because h2lite releases stream credit as the buffered
+//     is still replenished, because h2lean releases stream credit as the buffered
 //     body is consumed and connection credit in half-window steps, neither of them
 //     per read(). A paused request buffers in memory instead of slowing the peer down.
-//   * res.cork()/uncork() are absent, not no-ops: h2lite already coalesces every
+//   * res.cork()/uncork() are absent, not no-ops: h2lean already coalesces every
 //     frame produced in one turn of the loop into a single write().
 //   * res.write() returning false is honest backpressure, and 'drain' is emitted
 //     when the send window reopens.
-//   * createPushResponse() throws ERR_H2LITE_NOT_IMPLEMENTED (no server push in
+//   * createPushResponse() throws ERR_H2LEAN_NOT_IMPLEMENTED (no server push in
 //     v1) instead of failing later with a protocol error.
 //   * res 'finish' means the local half of the stream was closed, which for
-//     h2lite happens as the frames are queued for the socket; node reports it
+//     h2lean happens as the frames are queued for the socket; node reports it
 //     when the stream closes, which is later. A response the peer cut short
 //     reports 'finish' on both stacks.
 //   * the order of the teardown events differs: node reports the request's
 //     events (its 'end', its 'aborted', its 'close') before the response's
-//     ('finish', then 'close'), h2lite reports the response's first. Every
+//     ('finish', then 'close'), h2lean reports the response's first. Every
 //     event fires on both stacks -- measured against a live node server over
 //     the four shapes of bench/micro/probe-teardown-order.js, the sets are equal -- and
 //     only their order within the teardown turn differs. One pair is not a
@@ -108,7 +108,7 @@ function describeType(value) {
 // rewrite is refused loudly instead of silently corrupting another request.
 function assertWritable(headers) {
   if (Object.isFrozen(headers)) {
-    throw err('ERR_H2LITE_FROZEN_HEADERS',
+    throw err('ERR_H2LEAN_FROZEN_HEADERS',
       'req.headers is frozen because the server was created with shareHeaders:true');
   }
 }
@@ -396,7 +396,7 @@ function onResponseClose() {
   res.writable = false;
   // node emits 'finish' and 'close' together, when the stream closes
   // (internal/http2/compat, onStreamCloseResponse), so a response the peer cut
-  // short still reports 'finish'. h2lite emits 'finish' when the application
+  // short still reports 'finish'. h2lean emits 'finish' when the application
   // ends the response, which is the same event one turn earlier; this covers
   // the case where the application never got that far.
   if (!res._state.finishEmitted) {
@@ -651,7 +651,7 @@ class Http2ServerResponse extends Stream {
       // either. A merged copy was built here until the header path was measured:
       // it bought nothing (OPTIMIZATION.md item 25) -- the map is never frozen
       // and the HPACK block cache -- which is keyed by the identity of a frozen
-      // object -- cannot use it. h2lite's own stream.sentHeaders is that map;
+      // object -- cannot use it. h2lean's own stream.sentHeaders is that map;
       // node's server-side getter
       // returns undefined, because its respond() never sets the field.
       stream.respond(this._headers, {
@@ -770,7 +770,7 @@ class Http2ServerResponse extends Stream {
     }
 
     if (this._trailerNames > 0) {
-      // node sends the trailers from the 'wantTrailers' callback; h2lite closes
+      // node sends the trailers from the 'wantTrailers' callback; h2lean closes
       // the local side as soon as the application says so, so the recorded
       // trailers go out here, carrying END_STREAM with them
       stream.sendTrailers(this._trailers);
@@ -802,7 +802,7 @@ class Http2ServerResponse extends Stream {
   }
 
   createPushResponse(headers, callback) {
-    const e = err('ERR_H2LITE_NOT_IMPLEMENTED', 'h2lite v1 does not implement server push');
+    const e = err('ERR_H2LEAN_NOT_IMPLEMENTED', 'h2lean v1 does not implement server push');
     if (typeof callback !== 'function') {
       throw e;
     }

package/lib/fast-timer.js

@@ -4,10 +4,10 @@
 //
 // This file is deliberately a byte-for-byte copy of that source, with no local
 // changes, so that it can be lifted out into a standalone npm package and have
-// h2lite require it instead. Any deviation here would make that extraction a
+// h2lean require it instead. Any deviation here would make that extraction a
 // merge rather than a move, and would break the upstream tests that come with it.
 //
-// What h2lite uses it for: one shared 499 ms clock for all idle/keep-alive
+// What h2lean uses it for: one shared 499 ms clock for all idle/keep-alive
 // timeouts, instead of one libuv timer handle per connection. See
 // Http2Session.setTimeout() in lib/session.js.
 

package/lib/headers.js

@@ -160,7 +160,7 @@ function nameCacheSize() {
 // A field whose value carries one is ignored (NGHTTP2_ERR_IGN_HTTP_HEADER) and the
 // stream lives -- the request is served, without the field.
 //
-// The OUTBOUND check is h2lite's own, and stricter than node's: node does not look at
+// The OUTBOUND check is h2lean's own, and stricter than node's: node does not look at
 // an outbound value at all and puts a CR on the wire (bench/micro/probe-out-value-matrix.js --
 // every one of the fifteen characters tried is accepted, and the CR arrives in the
 // HEADERS frame). Refusing here is the mitigation the CVE-2020-8287 class needs: the

package/lib/hpack.js

@@ -1,4 +1,4 @@
-// HPACK codec (RFC 7541) for h2lite.
+// HPACK codec (RFC 7541) for h2lean.
 //
 // Deliberate choices, all CPU-driven:
 //  * field names are interned, so a repeated name costs no new string and the

package/lib/server.js

@@ -6,10 +6,10 @@
 // documentation:
 //   * node's Http2Server has close, setTimeout and updateSettings -- and NOTHING else: no
 //     sessionTimeout, no closeIdleSessions, no sessions getter, no settings property. node keeps
-//     the settings updateSettings merges in a private options object; h2lite keeps them in the
+//     the settings updateSettings merges in a private options object; h2lean keeps them in the
 //     public `settings` field it also builds sessions from, which is a third name node does not
 //     have. The extras implemented here are additive, not substitutions:
-//       server.sessions          -- the live session set, kept because h2lite tracks sessions
+//       server.sessions          -- the live session set, kept because h2lean tracks sessions
 //                                   in it and node keeps the same set under a symbol;
 //       server.closeIdleSessions() -- documented by node for years and gone in 26; the
 //                                   keep-alive policy it served is session.setTimeout() plus
@@ -26,14 +26,30 @@
 //   * closing a connection is not the same MOMENT on the two stacks, and one event depends on it.
 //     node's session survives close() until its graceful close completes (internal/http2/core.js:
 //     handle.ongracefulclosecomplete -> kMaybeDestroy), so it can still read -- and report -- the
-//     peer's answer to the GOAWAY we just sent. h2lite destroys the session as soon as that GOAWAY
+//     peer's answer to the GOAWAY we just sent. h2lean destroys the session as soon as that GOAWAY
 //     is written (lib/session.js: close() -> _maybeFinishClose), but its socket stays readable
 //     until the write is flushed, so the answer is read there too. The two therefore disagree
 //     about ONE event -- the 'goaway' the peer's answer produces -- and only inside a window:
 //     measured with tools/probe-goaway-echo.js, node's outcome moves with the load (40 of 40
-//     rounds on an idle machine, 26 of 40 and 29 of 30 in two loaded runs) while h2lite reports
+//     rounds on an idle machine, 26 of 40 and 29 of 30 in two loaded runs) while h2lean reports
 //     the echo in every round of every run. test/event-order.test.js drops the echo outside its
 //     'goaway' scenario for that reason.
+//   * allowHTTP1 + http1Options (both createSecureServer options, per node's docs): when the
+//     fallback is live, node serves HTTP/1.1 from the SAME object -- _http_server's private
+//     storeHTTPOptions() writes the HTTP/1 options into private fields of the Http2SecureServer
+//     and http's _connectionListener is bound to it -- so one emitter and one listener list
+//     carry both protocols. Those symbols are not reachable from node:http, so the fallback
+//     here is an embedded http.Server that never listens, fed the sockets the ALPN verdict
+//     hands it, with a newListener mirror (node's own setupCompat hook) carrying the
+//     application's request/upgrade/clientError/... listeners onto it. Three written-down
+//     consequences of that model: a removeListener does not unmirror (node has no such seam);
+//     the embedded server's own idle-connection bookkeeping never starts, because its
+//     'listening' never fires, so the handed-off sockets are tracked here and close() shuts
+//     the idle keep-alive ones down while letting a response in flight finish (node waits
+//     through net.Server's own bookkeeping); and an unknownProtocol socket -- no ALPN, no
+//     allowHTTP1 -- is answered with node's 403 text instead of being destroyed silently,
+//     which is what node does (core.js connectionListener) and what this file used to claim
+//     wrong: no ALPN is not h2 prior knowledge, and it never became a session on node.
 'use strict';
 
 const net = require('node:net');
@@ -41,17 +57,17 @@ const tls = require('node:tls');
 const { Http2Session, OUR_DEFAULTS } = require('./session');
 const { onServerStream, Http2ServerRequest, Http2ServerResponse } = require('./compat');
 
-const kCompat = Symbol('h2lite.compatListener');
+const kCompat = Symbol('h2lean.compatListener');
 // The transport's own close/on, captured before the shared API overrides them:
 // net.Server and tls.Server are unrelated base classes and JS has only single
 // inheritance, so the shared behaviour is mixed onto the prototype the same way
 // node's own core does it, with the overridden methods kept reachable by symbol.
-const kTransportClose = Symbol('h2lite.transportClose');
-const kTransportOn = Symbol('h2lite.transportOn');
+const kTransportClose = Symbol('h2lean.transportClose');
+const kTransportOn = Symbol('h2lean.transportOn');
 
 function notImplemented(what) {
-  const err = new Error(`h2lite v1 does not implement ${what}`);
-  err.code = 'ERR_H2LITE_NOT_IMPLEMENTED';
+  const err = new Error(`h2lean v1 does not implement ${what}`);
+  err.code = 'ERR_H2LEAN_NOT_IMPLEMENTED';
   return err;
 }
 
@@ -76,6 +92,21 @@ function initHttp2Server(server, options) {
   };
   server._sessions = new Set();
   server[kCompat] = null;
+  // node validates this as uint32 and defaults it to 10000 (initializeOptions, core.js);
+  // it bounds how long an unknown-protocol socket may sit after the 403 text.
+  if (opts.unknownProtocolTimeout !== undefined &&
+      (!Number.isInteger(opts.unknownProtocolTimeout) || opts.unknownProtocolTimeout < 0)) {
+    const err = new RangeError(`Invalid unknownProtocolTimeout: ${opts.unknownProtocolTimeout}`);
+    err.code = 'ERR_OUT_OF_RANGE';
+    throw err;
+  }
+  server._sessionOptions.unknownProtocolTimeout = opts.unknownProtocolTimeout ?? 10000;
+  // allowHTTP1 has nothing to negotiate over a plain socket (no ALPN, so the branch
+  // that would consume it is unreachable -- the same reason node's cleartext server
+  // ignores it), and http1Options is accepted here only so that the option bag a
+  // caller builds for node keeps working verbatim. The live HTTP/1 machinery is
+  // built, when allowHTTP1 is set, in initHttp1Fallback below.
+  server._http1 = null;
 }
 
 // Turns an accepted socket -- plain or already decrypted -- into a session.
@@ -132,7 +163,13 @@ function applyHttp2ServerApi(proto) {
     // followed by closeAllSessions(this) (internal/http2/core): the listening socket goes away
     // right away and its callback is net.Server's own. Waiting for the session set to empty first
     // was ours, and it made close(cb) a promise that a session which cannot drain never keeps --
-    // 'close' then depended on every connection finishing.
+    // 'close' then depended on every connection finishing. When the HTTP/1 fallback is live,
+    // node also runs httpServerPreClose() (closeIdleConnections + the checker interval); the
+    // public-API equivalent here shuts the idle keep-alive sockets down and lets the active
+    // responses finish, see closeHttp1().
+    if (this._http1) {
+      closeHttp1(this);
+    }
     proto[kTransportClose].call(this, cb);
     for (const session of [...this._sessions]) {
       session.close();
@@ -204,28 +241,145 @@ class Http2Server extends net.Server {
   }
 }
 
-// node's h2s server insists on h2 and overwrites whatever ALPNProtocols the
-// application passed: a peer offering only http/1.1 is refused by the handshake
-// itself, with the TLS alert no_application_protocol, rather than after it. The
-// list is therefore fixed here too, and the ALPN check in secureConnection below
-// stays as the guard for contexts installed later through setSecureContext().
+// node's h2s server fixes the ALPN list the way initializeTLSOptions (core.js) does:
+// ['h2'] -- with 'http/1.1' added when allowHTTP1 asks for the fallback -- and an
+// options.ALPNCallback keeps the application's list out of reach. A peer offering only
+// http/1.1 without allowHTTP1 is therefore still refused by the handshake itself, with
+// the TLS alert no_application_protocol, rather than after it. The ALPN check in
+// secureConnection below stays as the guard for contexts installed later through
+// setSecureContext().
 function alpnOptions(options) {
   const opts = { ...(options || {}) };
-  opts.ALPNProtocols = ['h2'];
+  if (!opts.ALPNCallback) {
+    opts.ALPNProtocols = ['h2'];
+    if (opts.allowHTTP1 === true) {
+      opts.ALPNProtocols.push('http/1.1');
+    }
+  }
   return opts;
 }
 
+// The events an HTTP/1 connection produces that an application registers on the h2
+// server. node serves both protocols from ONE emitter (http's _connectionListener is
+// bound to the Http2SecureServer itself), so a listener sees both kinds of request;
+// the mirror below is what makes one 'request' handler keep working here, where the
+// fallback lives on an embedded server instead.
+const HTTP1_MIRROR = new Set([
+  'request', 'checkContinue', 'checkExpectation', 'upgrade', 'connect', 'clientError'
+]);
+
+// node's fallback is a mixin: _http_server's private storeHTTPOptions() writes the
+// HTTP/1 options into private fields of the Http2SecureServer itself, so there is no
+// second server object and no second listener list. Those symbols are not reachable
+// from node:http, so the fallback here is a real http.Server that never listens and
+// receives the sockets the ALPN verdict hands it. Consequences written down in the
+// header comment: the mirror is one-way (removeListener does not unmirror), and the
+// embedded server's own connection bookkeeping never starts because 'listening' never
+// fires -- the handed-off sockets are tracked here instead.
+function initHttp1Fallback(server, opts) {
+  const http = require('node:http');
+  // DEP0202 (doc/api/deprecations.md): the top-level Http1IncomingMessage and
+  // Http1ServerResponse names migrate into http1Options.
+  const http1Options = { ...(opts.http1Options || {}) };
+  if (opts.Http1IncomingMessage !== undefined && http1Options.IncomingMessage === undefined) {
+    http1Options.IncomingMessage = opts.Http1IncomingMessage;
+  }
+  if (opts.Http1ServerResponse !== undefined && http1Options.ServerResponse === undefined) {
+    http1Options.ServerResponse = opts.Http1ServerResponse;
+  }
+  server._http1 = new http.Server(http1Options);
+  server._http1Sockets = new Set();
+  server._http1Active = 0;
+  server._http1Closing = false;
+  server.on('newListener', (event, listener) => {
+    if (HTTP1_MIRROR.has(event)) {
+      server._http1.on(event, listener);
+    }
+  });
+  // Per-socket activity, so close() can tell an idle keep-alive socket (destroy it,
+  // the way closeIdleConnections does on node) from one with a response in flight.
+  server._http1.on('request', (req, res) => {
+    server._http1Active++;
+    req.socket._h2leanActive = true;
+    res.once('finish', () => {
+      server._http1Active--;
+      req.socket._h2leanActive = false;
+      if (server._http1Closing && server._http1Active === 0) {
+        for (const socket of server._http1Sockets) {
+          socket.destroy();
+        }
+      }
+    });
+  });
+}
+
+function handOffHttp1(server, socket) {
+  server._http1Sockets.add(socket);
+  socket.once('close', () => server._http1Sockets.delete(socket));
+  server._http1.emit('connection', socket);
+}
+
+// The public-API equivalent of node's httpServerPreClose(): the idle keep-alive
+// sockets go away right away, a response in flight is allowed to finish, and when the
+// last one finishes the sockets it was talking on go too. node's mixin waits through
+// net.Server's own connection bookkeeping instead; that bookkeeping is exactly what
+// the embedded-server model cannot reach.
+function closeHttp1(server) {
+  server._http1Closing = true;
+  for (const socket of [...server._http1Sockets]) {
+    if (!socket._h2leanActive) {
+      socket.destroy();
+    }
+  }
+}
+
+function unknownProtocol(server, socket) {
+  if (server.emit('unknownProtocol', socket)) {
+    return;
+  }
+  // core.js connectionListener: with no listener, the socket is told in a format it
+  // might understand why it got nothing, and an unref'd timer bounds how long a peer
+  // that never closes can hold it.
+  socket.end('HTTP/1.0 403 Forbidden\r\n' +
+             'Content-Type: text/plain\r\n\r\n' +
+             'Missing ALPN Protocol, expected `h2` to be available.\n' +
+             'If this is a HTTP request: The server was not ' +
+             'configured with the `allowHTTP1` option or a ' +
+             'listener for the `unknownProtocol` event.\n');
+  const timer = setTimeout(() => {
+    if (!socket.destroyed) {
+      socket.destroy();
+    }
+  }, server._sessionOptions.unknownProtocolTimeout);
+  timer.unref();
+  socket.once('close', () => clearTimeout(timer));
+}
+
 class Http2SecureServer extends tls.Server {
   constructor(options) {
-    super(alpnOptions(options));
-    initHttp2Server(this, options);
+    const opts = options || {};
+    super(alpnOptions(opts));
+    initHttp2Server(this, opts);
+    if (opts.allowHTTP1 === true) {
+      initHttp1Fallback(this, opts);
+    }
     this.on('secureConnection', (socket) => {
-      // node's rule: 'h2' negotiated, or no ALPN at all -- which is h2 with prior
-      // knowledge carried over a TLS connection. Anything else is dropped without
-      // ever becoming a session.
+      // node's connectionListener (core.js): 'h2' negotiated becomes a session;
+      // 'http/1.1' -- or no ALPN at all, which is NOT h2 prior knowledge, whatever an
+      // older comment here claimed -- goes to the HTTP/1 fallback when allowHTTP1 is
+      // set, and otherwise to 'unknownProtocol', with the 403 text when nobody
+      // listens. Measured on node 26 in this session: a no-ALPN client speaking
+      // HTTP/1.1 is served by the fallback under allowHTTP1 and receives the 403
+      // without it.
       const alpn = socket.alpnProtocol;
-      if (alpn === 'h2' || alpn === false) {
+      if (alpn === 'h2') {
         attachSession(this, socket);
+      } else if (alpn === 'http/1.1' || alpn === false) {
+        if (this._http1) {
+          handOffHttp1(this, socket);
+        } else {
+          unknownProtocol(this, socket);
+        }
       } else {
         socket.destroy();
       }

package/lib/session.js

@@ -84,7 +84,7 @@ const MAX_SHAPES = 128;
 // v26.12.1 with tools/probe-inbound-limits.js: a 4-field block whose names and values total 46
 // octets is REFUSED under a limit of 48 (46 + 4*32 = 174), and for a 5-field block the line
 // between served and refused falls between 87 and 93 decoded octets (250 - 5*32 = 90). The
-// plain sum of the field octets is what h2lite compared, and it is 128 entry octets away from
+// plain sum of the field octets is what h2lean compared, and it is 128 entry octets away from
 // node's verdict for a four-field request: three of the measured blocks were served that node
 // refuses. test/inbound-limits.test.js pins both sides of the line.
 const ENTRY_OVERHEAD = 32;
@@ -139,7 +139,7 @@ const OPT_NO_END_STREAM = { endStream: false };
 // How long the teardown waits for the goodbye to reach the peer before the socket is
 // taken away anyway. The FIN is queued behind whatever we wrote, so a peer that stopped
 // reading would hold it forever -- node does not have that problem because its data sits
-// inside nghttp2 until the window allows it, while h2lite hands it to the socket. The
+// inside nghttp2 until the window allows it, while h2lean hands it to the socket. The
 // wait itself is what makes the difference between a closed connection and a reset
 // (h2spec's http2/7), so it gets a bound of its own: one second is three orders of
 // magnitude longer than the flush takes when the peer is reading.
@@ -1146,7 +1146,7 @@ class Http2Session extends EventEmitter {
         // RFC 9113 5.5: "Implementations MUST discard frames that have unknown or unsupported
         // types." Measured on a live node server with tools/probe-inbound-limits.js: type 10
         // (ALTSVC, RFC 7807), type 99 and type 0xff with a 4 KiB payload all leave the
-        // connection up and the next request served, and h2lite answers the same. Answering a
+        // connection up and the next request served, and h2lean answers the same. Answering a
         // fatal error here would break every extension frame a peer has not told us about.
         // What is NOT ignored is a frame that interrupts a field block -- 5.5 forbids those
         // outright, and that is the case above.
@@ -1225,7 +1225,7 @@ class Http2Session extends EventEmitter {
   // block fragment"), so the block ends where the padding starts. Feeding the
   // padding to the HPACK decoder is what a server must not do: the padding is
   // not part of the block, and a block that ends with eight zero octets decodes
-  // as a literal header with no name and no value -- which is what h2lite
+  // as a literal header with no name and no value -- which is what h2lean
   // answered to a valid padded HEADERS with GOAWAY(COMPRESSION_ERROR), while node
   // served the request (measured: tools/probe-hdr-pad.js, "the RFC shape: pad
   // length, block, padding"; the same frame is what h2spec's generic/3.2 sends,
@@ -1329,7 +1329,7 @@ class Http2Session extends EventEmitter {
     }
     // No maxHeaderListSize test here, although this is where the octets are counted: the limit
     // is about the size of the header LIST, which is only known once the block is decoded, and
-    // h2lite applies it there (_processHeaders). Measured against node, an over-limit block
+    // h2lean applies it there (_processHeaders). Measured against node, an over-limit block
     // arriving in one HEADERS frame gets RST_STREAM(ENHANCE_YOUR_CALM) and the connection
     // stays up; a check on the compressed length here made it GOAWAY(PROTOCOL_ERROR) instead,
     // which turns one bad request into an error for every other client on the session. The
@@ -1696,7 +1696,7 @@ class Http2Session extends EventEmitter {
     // closed the message with its own END_STREAM is a connection error of type STREAM_CLOSED
     // whichever fields the block holds -- measured on node (probe cases U3, U9), where the second
     // block is not a valid request at all and the verdict is still GOAWAY(STREAM_CLOSED). 5.1 reads a
-    // frame on a closed stream as "MAY ... treat ... as a connection error", and h2lite takes that
+    // frame on a closed stream as "MAY ... treat ... as a connection error", and h2lean takes that
     // option for BOTH the still-present (half-closed(remote)) and the just-closed (_ended) shape: a
     // stream error would be the other reading of half-closed(remote), but node does not make that
     // distinction and h2spec's half-closed(remote) HEADERS check waits for the error, not the silence
@@ -1917,7 +1917,7 @@ class Http2Session extends EventEmitter {
         return undefined;
       }
       // RFC 9113 5.1 and 8.2: the peer already closed the message with its END_STREAM, so a DATA
-      // that follows it names a stream that has nothing left to receive. h2lite ends the connection
+      // that follows it names a stream that has nothing left to receive. h2lean ends the connection
       // with STREAM_CLOSED -- the discretion 5.1 grants a closed stream ("MAY ... treat ... as a
       // connection error") and what h2spec's closed checks wait for; a silent discard is legal by
       // the letter but the conformance tool times out on it, and this is the just-closed id (it left
@@ -1959,7 +1959,7 @@ class Http2Session extends EventEmitter {
       // connection ends. RFC 9113 6.1 reads a DATA on a stream outside "open"/"half-closed(local)"
       // as a stream error of type STREAM_CLOSED, and h2spec's half-closed(remote) DATA and 6.1 checks
       // accept the reset, the GOAWAY, or a closed connection -- but node makes no present/closed
-      // distinction and answers the connection error below on BOTH stacks, so h2lite keeps node's
+      // distinction and answers the connection error below on BOTH stacks, so h2lean keeps node's
       // verdict here rather than the stream error (which regressed the tool's DATA echo). Leaving it
       // is the honest call: it is node's deviation, the parity rule keeps it, and 5.1's closed-state
       // read is the discretionary one ("MAY ... treat ... as a connection error"). The arms that
@@ -2228,7 +2228,7 @@ class Http2Session extends EventEmitter {
 
   _onGoaway(buf, start, len) {
     // node begins this handler with `if (session.destroyed) return;`, because its nghttp2 handle
-    // can report a frame after the session was destroyed. h2lite cannot: _dispatch() answers with
+    // can report a frame after the session was destroyed. h2lean cannot: _dispatch() answers with
     // `this._open` and the read batch stops at the frame that destroyed the session, so a
     // destroyed session has no frames left to reach. That stop is what is tested -- in
     // test/goaway.test.js, 'the read batch stops at the frame that destroyed the session' -- and
@@ -2306,7 +2306,7 @@ class Http2Session extends EventEmitter {
     // that had already closed), our flush-per-read-batch put a WINDOW_UPDATE(sid 0) on the wire in
     // front of the frame the tool was waiting for, where node sent nothing at all. Measured on a
     // 640 KiB upload (tools/probe-conn-credit.js): node releases the connection window in steps of
-    // 32768 octets -- half the 65535 it advertises -- and the same threshold here takes h2lite's
+    // 32768 octets -- half the 65535 it advertises -- and the same threshold here takes h2lean's
     // cadence from one frame per read batch to the same half-window steps, at the same throughput.
     // A peer that keeps sending is therefore credited before its window can run out, so the
     // anti-deadlock rule that this counter exists for still holds; below the threshold the bytes
@@ -2483,7 +2483,7 @@ class Http2Session extends EventEmitter {
   // That is exactly what a peer's GOAWAY does -- destroy(new ERR_HTTP2_SESSION_ERROR(code),
   // NO_ERROR) -- and the measurement below is what made the distinction visible: the application
   // is told WHY (the code that arrived) while the peer is told goodbye with NO_ERROR, because
-  // this side did not fail. A number as the first argument is h2lite's own convenience, used by
+  // this side did not fail. A number as the first argument is h2lean's own convenience, used by
   // the socket handlers and _fatal(): destroy with this GOAWAY code and nothing to report.
   destroy(error = NO_ERROR, code) {
     if (this.destroyed) {
@@ -2527,7 +2527,7 @@ class Http2Session extends EventEmitter {
     // node's teardown shape (internal/http2/core.js, finishSessionClose): the socket is
     // ended first and the destroy waits for the write to be flushed, so the GOAWAY queued
     // above reaches the peer and the connection ends with a FIN instead of a reset.
-    // h2lite used to destroy the socket outright, which threw that GOAWAY away and closed
+    // h2lean used to destroy the socket outright, which threw that GOAWAY away and closed
     // the connection with a reset whenever the write had not reached the OS yet -- under
     // load that is what h2spec's http2/7 reads as a failure ("connection reset by peer"
     // where node's "connection closed" passes), measured in bench/micro/probe-goaway-ping.js.

package/lib/stream.js

@@ -20,7 +20,7 @@
 //     the same promise node:http2 makes.
 //   * a response the application never started is started for it: the first write()
 //     sends HEADERS{:status 200} before the DATA, as node does. An end() with no body at
-//     all is the one shape where h2lite answers (200, empty DATA/ES) and node says nothing
+//     all is the one shape where h2lean answers (200, empty DATA/ES) and node says nothing
 //     -- measured, and recorded in AGENTS.md section 10.
 'use strict';
 
@@ -177,10 +177,10 @@ class Http2Stream extends EventEmitter {
       cb = encoding; encoding = null;
     }
     if (!this.headersSent) {
-      // A body takes the auto-respond of write() above; an empty end() is where h2lite and node
+      // A body takes the auto-respond of write() above; an empty end() is where h2lean and node
       // part company, and the split is written down in AGENTS.md section 10: node puts NOTHING on
       // the wire for `end()` before respond() -- no HEADERS, no DATA, no END_STREAM, and
-      // headersSent stays false -- while h2lite answers a plain 200 rather than leave a stream
+      // headersSent stays false -- while h2lean answers a plain 200 rather than leave a stream
       // that no peer will ever see an answer on.
       this.respond({ ':status': 200 });
     }
@@ -189,7 +189,7 @@ class Http2Stream extends EventEmitter {
     // A stream that still owes a trailer block must not close the stream with its body.
     // RFC 9113 6.1 puts a trailing HEADERS before END_STREAM, and node's frame sequence
     // shows the placement: HEADERS/EH DATA HEADERS/ES/EH for a body, and no DATA at all
-    // for an empty one -- where h2lite used to send DATA/ES first and then a trailer block
+    // for an empty one -- where h2lean used to send DATA/ES first and then a trailer block
     // that no peer could still read. The application-level half-close happens here (that
     // is what emits 'wantTrailers'), the wire-level one happens in sendTrailers().
     const oweTrailers = this._waitForTrailers;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h2lean",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pure-JavaScript HTTP/2 for Node.js — a drop-in node:http2 replacement (server and client, h2c and TLS) with zero dependencies",
   "main": "index.js",
   "files": [
@@ -9,7 +9,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/MakeNodeGreatAgain/h2lite.git"
+    "url": "git+https://github.com/MakeNodeGreatAgain/h2lean.git"
   },
   "keywords": [
     "http2",
@@ -45,6 +45,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.14.0",
+    "fastify": "^5.12.8",
     "fast-xml-parser": "^5.12.0",
     "uWebSockets.js": "github:uNetworking/UWebSockets.js#v20.70.0"
   }