h2lean 0.1.1 → 0.2.0

package/lib/server.js

@@ -34,6 +34,22 @@
 //     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');
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h2lean",
-  "version": "0.1.1",
+  "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": [
@@ -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"
   }