quico 0.3.0 → 0.4.0

package/index.js

@@ -19,6 +19,7 @@ import { IncomingMessage, ServerResponse, ClientRequest } from './src/streams.js
 import { createSecureContext } from './src/tls_bridge.js';
 import { WebTransport } from './src/webtransport.js';
 import { createQuicServer } from './src/quic_server.js';
+import { createQuicClientSocket } from './src/quic_socket.js';
 
 export {
   createServer,
@@ -31,7 +32,8 @@ export {
   ClientRequest,
   createSecureContext,
   WebTransport,
-  createQuicServer
+  createQuicServer,
+  createQuicClientSocket
 };
 
 export default {
@@ -45,5 +47,6 @@ export default {
   ClientRequest,
   createSecureContext,
   WebTransport,
-  createQuicServer
+  createQuicServer,
+  createQuicClientSocket
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quico",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A pure JavaScript implementation of QUIC, HTTP/3, QPACK, and WebTransport for Node.js",
   "type": "module",
   "main": "index.cjs",
@@ -78,6 +78,6 @@
   ],
   "dependencies": {
     "flat-ranges": "^2.0.0",
-    "lemon-tls": "^0.4.1"
+    "lemon-tls": "^0.6.0"
   }
 }

package/src/agent.js

@@ -56,6 +56,17 @@ class Agent extends EventEmitter {
     // Allows multiplexing multiple requests over one QUIC connection
     this._h3Pool = {};
 
+    // Connections still being ESTABLISHED: "host:port" → [waiter callbacks].
+    // Without this third state the pool only knows "have one" / "don't", so N
+    // requests issued in the same tick each see an empty pool and open N
+    // separate QUIC connections to the same origin — N handshakes, N
+    // congestion controllers, zero multiplexing (the QUIC interop runner's
+    // http3 test flags exactly this: "Expected exactly 1 handshake. Got: 3").
+    // The first request to miss the pool becomes the lead and creates the
+    // entry; requests arriving before it finishes park a callback here and
+    // are replayed once the lead settles.
+    this._h3Pending = {};
+
     // Active HTTP/2 sessions: "host:port" → http2.ClientHttp2Session
     this._h2Pool = {};
 
@@ -165,6 +176,42 @@ class Agent extends EventEmitter {
     return conn;
   }
 
+  /**
+   * Coalesce concurrent connection attempts to one origin.
+   *
+   * Returns false if the caller is the LEAD: no connection exists and nobody
+   * else is establishing one. The lead MUST eventually call
+   * resolveH3Pending(host, port, connOrNull) — on success, failure, or
+   * abandonment — or every later request to this origin parks forever.
+   *
+   * Returns true if the caller was parked as a follower; `cb` fires (with no
+   * arguments) once the lead settles, and the caller should simply retry its
+   * pool lookup: on success the connection is already registered, and on
+   * failure the retry becomes the next lead — serial retry, no thundering
+   * herd.
+   */
+  joinH3Pending(host, port, cb) {
+    var key = host + ':' + (port || 443);
+    if (this._h3Pending[key]) {
+      this._h3Pending[key].push(cb);
+      return true;
+    }
+    this._h3Pending[key] = [];
+    return false;
+  }
+
+  /** Lead's settlement. Registers the connection (if any) BEFORE waking the
+   *  waiters, so their retried pool lookups succeed synchronously. */
+  resolveH3Pending(host, port, conn) {
+    var key = host + ':' + (port || 443);
+    var waiters = this._h3Pending[key] || [];
+    delete this._h3Pending[key];
+    if (conn) this.setH3Connection(host, port, conn);
+    for (var i = 0; i < waiters.length; i++) {
+      try { waiters[i](); } catch (e) { /* a waiter's failure is its own */ }
+    }
+  }
+
   setH3Connection(host, port, conn) {
     var key = host + ':' + (port || 443);
     this._h3Pool[key] = conn;
@@ -262,6 +309,17 @@ class Agent extends EventEmitter {
   destroy() {
     if (this._sweepTimer) { clearInterval(this._sweepTimer); this._sweepTimer = null; }
 
+    // Wake anyone parked on an in-flight connection attempt; their retried
+    // pool lookup will find nothing and proceed (or fail) on its own.
+    for (var key in this._h3Pending) {
+      var waiters = this._h3Pending[key];
+      delete this._h3Pending[key];
+      for (var i = 0; i < waiters.length; i++) {
+        try { waiters[i](); } catch (e) {}
+      }
+    }
+    this._h3Pending = {};
+
     for (var key in this._h3Pool) {
       try { this._h3Pool[key].quic.close(0, 'agent destroy'); } catch (e) {}
     }

package/src/client.js

@@ -206,7 +206,13 @@ function request(url, options, callback) {
         port: port,
         path: path,
         method: method,
-        headers: Object.assign({}, headers)
+        headers: Object.assign({}, headers),
+        // The H2 and HTTPS fallbacks below honour this; dropping it here made
+        // H3 — alone of the three — unable to talk to self-signed or
+        // private-CA servers, and every such request silently fell back to
+        // TCP (or hung when the server was QUIC-only).
+        rejectUnauthorized: options.rejectUnauthorized,
+        ca: options.ca
       };
 
       // Check Agent for existing QUIC connection (multiplexing).
@@ -217,15 +223,36 @@ function request(url, options, callback) {
       if (agent) {
         h3Opts._managed = true;
         var existing = agent.getH3Connection(hostname, port);
-        if (existing) h3Opts._connection = existing;
+        if (existing) {
+          h3Opts._connection = existing;
+        } else if (agent.joinH3Pending &&
+                   agent.joinH3Pending(hostname, port, function () {
+                     // The lead settled. Retry from the top: on success the
+                     // pool lookup now hits and we multiplex on the lead's
+                     // connection; on failure we become the next lead — a
+                     // serial retry, never a thundering herd.
+                     tryH3(onFail);
+                   })) {
+          return; // parked as a follower until the lead settles
+        }
+        // else: we are the LEAD for this origin. _settleH3Pending below MUST
+        // run on every exit path, or followers park forever.
+      }
+
+      var _pendingLead = !!(agent && !h3Opts._connection);
+      function _settleH3Pending(conn) {
+        if (!_pendingLead) return;
+        _pendingLead = false;
+        if (agent.resolveH3Pending) agent.resolveH3Pending(hostname, port, conn);
+        else if (conn) agent.setH3Connection(hostname, port, conn);
       }
 
       var h3Req = h3Request(h3Opts, function (h3Res) {
         if (responded) return;
 
-        // Store connection for future reuse
-        if (agent && h3Req._connection && !h3Opts._connection) {
-          agent.setH3Connection(hostname, port, h3Req._connection);
+        // Register the connection and wake coalesced followers.
+        if (h3Req._connection && !h3Opts._connection) {
+          _settleH3Pending(h3Req._connection);
         }
 
         var res = new IncomingMessage({
@@ -246,6 +273,7 @@ function request(url, options, callback) {
       });
 
       h3Req.on('error', function (err) {
+        _settleH3Pending(null);   // release followers before failing over
         onFail(err);
       });
 
@@ -254,6 +282,7 @@ function request(url, options, callback) {
       h3Req.end();
 
     } catch (err) {
+      if (typeof _settleH3Pending === 'function') _settleH3Pending(null);
       onFail(err);
     }
   }

package/src/crypto.js

@@ -373,6 +373,23 @@ function encrypt_quic_packet(packetType, encodedFrames, writeKey, writeIv, write
 function decrypt_quic_packet(array, readKey, readIv, readHp, ownCid, largestPn) {
   if (!(array instanceof Uint8Array)) throw new Error('Invalid input');
 
+  // Work on a private copy — this function must not mutate its input.
+  //
+  // remove_header_protection XORs the first byte and the packet-number bytes
+  // IN PLACE. That is fine for exactly one decryption attempt, but the key
+  // update path retries this function on the same packet with derived keys
+  // (RFC 9001 §6): the second call re-applies the (unchanged) HP mask to a
+  // header that is already unprotected, re-scrambling it — and reads pnLength
+  // from the scrambled byte, so it may even XOR the wrong number of bytes.
+  // The retry then fails even with the correct keys, every phase-flipped
+  // packet is dropped, and the connection goes permanently deaf in that
+  // direction. Measured against quic-go (which key-updates shortly after
+  // handshake confirmation): ACK processing died at t≈2s, BBR froze mid-
+  // startup, and the sender spent 58s retransmitting one 8 KB band 29 times.
+  //
+  // One ≤1500 B copy per decryption attempt is noise next to the AEAD itself.
+  array = array.slice();
+
   var firstByte = array[0];
   var isShort = (firstByte & 0x80) === 0;
 

package/src/h3_client.js

@@ -34,6 +34,13 @@ function request(options, callback) {
   }
 
   var hostname = options.hostname || options.host || 'localhost';
+  // Certificate verification options, forwarded to the QUIC/TLS layer.
+  // Defaults to verifying (node:tls semantics); without this passthrough the
+  // option dies here and H3 connections can never opt out — which makes the
+  // one transport this library exists for the only one that can't reach a
+  // self-signed or private-CA server (H2/H1.1 fallbacks honour the option).
+  var rejectUnauthorized = options.rejectUnauthorized !== false;
+  var ca = options.ca || null;
   var port = options.port || 443;
   var path = options.path || '/';
   var method = (options.method || 'GET').toUpperCase();
@@ -144,6 +151,8 @@ function request(options, callback) {
       remoteIp: remoteIp,
       remotePort: remotePort,
       hostname: hostname,
+      rejectUnauthorized: rejectUnauthorized,
+      ca: ca,
 
       onError: function (err) {
         emit(reqListeners, 'error', err);

package/src/quic_connection.js

@@ -40,6 +40,14 @@ import {
 
 import { TLSBridge } from './tls_bridge.js';
 
+// Congestion-control tracing on its own switch. QUICO_DEBUG enables per-packet
+// logging, whose synchronous console.log volume is heavy enough to become the
+// bottleneck it is trying to observe (a 2 MB transfer measured 33s with it on,
+// 3s with it off). The [bbr] round line fires only once per RTT — cheap — so
+// it gets a separate flag that leaves the per-packet spam off.
+var DEBUG_BBR = DEBUG ||
+  (typeof process !== 'undefined' && process.env && !!process.env.QUICO_DEBUG_BBR);
+
 
 function QUICConnection(options) {
   if (!(this instanceof QUICConnection)) return new QUICConnection(options);
@@ -279,6 +287,21 @@ function QUICConnection(options) {
     latest_delivery_rate: null, // bytes/sec acked in the most recent ACK sample
     max_delivery_rate: null,    // peak delivery rate ≈ BtlBw (a CC bandwidth input)
     lost_count: 0,              // packets declared lost by expireInFlight (≈ loss)
+
+    // Expired-but-unacknowledged packets ("limbo"). When expireInFlight times a
+    // packet out, its stream spans are parked here instead of being forgotten.
+    // If the ACK then arrives late — which on a queued path it regularly does,
+    // since the expiry timer races the ACK's arrival — the spans are credited
+    // to `delivered` and marked acked, cancelling any not-yet-sent retransmit.
+    //
+    // Without this, a spuriously-expired packet's bytes vanish from delivery
+    // accounting forever: the ACK finds nothing to credit, BtlBw (computed
+    // from `delivered`) reads a collapsing rate, the pacer follows it down,
+    // and the sender relaxes the queue until ACKs beat the timer again — a
+    // relaxation oscillator, measured against quic-go through the interop
+    // simulator as a 114/4-packets-per-second sawtooth and ~21× duplication.
+    //   pn → { t: expiry wall-time, spans: [[sid, from, to], ...] }
+    expired_unacked: {},
     reorder_in_count: 0,        // app packets that arrived below the highest PN seen (network reordering, peer→us)
 
     // --- BBR-lite measurement (Phase 4b, step 1+2 — measure only, no control). ---
@@ -332,6 +355,10 @@ function QUICConnection(options) {
 
     SNICallback: options.SNICallback || null,
     hostname: options.hostname || null,
+    // Client-side peer certificate verification. Defaults to true (node:tls
+    // semantics); set false for self-signed certs, private CAs, or interop.
+    rejectUnauthorized: options.rejectUnauthorized !== false,
+    ca: options.ca || null,
 
     // ALPN protocol(s) to advertise in the TLS handshake.
     // Defaults to ['h3'] (HTTP/3). Other QUIC-based protocols set their own,
@@ -508,11 +535,19 @@ function QUICConnection(options) {
       originalDcid: context.original_dcid,
       localCid: context.my_cids.length > 0 ? context.my_cids[0] : new Uint8Array(0),
       hostname: context.hostname,
-      alpn: context.alpn
+      alpn: context.alpn,
+      rejectUnauthorized: context.rejectUnauthorized,
+      ca: context.ca
     });
 
     tls.on('send', function (epoch, data) { cryptoWrite(epoch, data); });
 
+    // NSS key log lines (Wireshark / SSLKEYLOGFILE). Surfaced on the
+    // connection so an application can persist them without reaching into the
+    // TLS layer. Without this a QUIC capture is undecryptable, which makes
+    // every wire-level bug an order of magnitude harder to diagnose.
+    tls.on('keylog', function (line) { ev.emit('keylog', line); });
+
     // Peer's QUIC transport parameters (parsed from the TLS 0x39 extension). These
     // replace hardcoded defaults: the peer's flow-control limit, ACK-delay scaling,
     // and max ACK delay. Arrives once, during the handshake, before app data flows.
@@ -712,6 +747,20 @@ function QUICConnection(options) {
         context.app_read = { key: next.key, iv: next.iv, hp: readKeys.hp };
         context.app_read_secret = next.secret;
         context.read_key_phase = !context.read_key_phase;
+
+        // RFC 9001 §6.2: a key update is BIDIRECTIONAL. Having accepted the
+        // peer's new phase for reading, we MUST move our send keys to the same
+        // phase before acknowledging anything received under it. Updating only
+        // the read side means our very next ACK — which covers the peer's
+        // new-phase packets — goes out under the OLD keys, and a conforming
+        // peer treats that as KEY_UPDATE_ERROR and kills the connection.
+        // (Measured against quic-go: connection closed ~3s after its routine
+        // post-handshake key update, exactly when our stale-phase ACK landed.)
+        // set_context({key_phase}) drives the existing machinery: it derives
+        // next-generation write keys from app_write_secret and flips the KP
+        // bit used by the encrypt path, so every packet from here on — the
+        // ACK included — is protected under the new phase.
+        set_context({ key_phase: !context.key_phase });
       }
     }
 
@@ -863,6 +912,25 @@ function QUICConnection(options) {
 
     if (ackEliciting) {
       flat_ranges.add(context.pending_ack[space], [packetNumber, packetNumber + 1]);
+
+      // Cap the acknowledged ranges (RFC 9000 §13.2.4 explicitly allows
+      // acking a subset). Under loss, packet-number gaps never close — a lost
+      // PN is gone forever; its DATA returns under a new PN — so every loss
+      // event mints one more range that would otherwise live here for the
+      // rest of the connection. Unpruned, the ACK frame grows with the loss
+      // count until it crosses the MTU and the ACK cannot be sent AT ALL, at
+      // which point the peer (correctly) stalls and idle-times-out. Measured
+      // against a quiche server through the interop simulator: 485 losses in
+      // 7s of line-rate transfer inflated our ACK packets 325B→1017B second
+      // by second, ACKs died at t≈8s, and quiche collected the connection.
+      // Dropping the LOWEST ranges is safe: those packets were received and
+      // have been acknowledged in every ACK frame sent since; anything the
+      // peer still considers unacked it will retransmit as new data under a
+      // fresh, high PN that the surviving ranges cover.
+      var pa = context.pending_ack[space];
+      var MAX_ACK_RANGES = 32;
+      if (pa.length > MAX_ACK_RANGES * 2) pa.splice(0, pa.length - MAX_ACK_RANGES * 2);
+
       var ackFrame = ranges_to_ack_frame(context.pending_ack[space], null, 0);
       if (ackFrame) {
         sendFrames(space, [ackFrame]);
@@ -917,6 +985,7 @@ function QUICConnection(options) {
     var sid = frame.id;
     if (!(sid in context.recv_streams)) {
       context.recv_streams[sid] = { chunks: {}, ranges: [], total_size: 0, flushed_to: 0,
+        fin_emitted: false,   // end-of-stream delivered to the app exactly once
         max_recv_offset: 0,   // highest offset seen — the peer's FC usage on this stream
         local_max_stream_data: context.local_initial_max_stream_data };
     }
@@ -1000,11 +1069,30 @@ function QUICConnection(options) {
       parts.push(skip > 0 ? chunk.subarray(skip) : chunk);
       offset = chunkStart + chunk.byteLength;
     }
-    if (parts.length === 0) return;
+    if (parts.length === 0) {
+      // No bytes to deliver — but the stream may just have COMPLETED. A peer
+      // whose final write ends exactly on a packet boundary closes the stream
+      // with a zero-length FIN-only frame (quic-go does this for any body
+      // that is a multiple of its write-buffer size — a 64 KiB file, say).
+      // That frame stores total_size above and lands here with an empty chunk
+      // map; returning without emitting means the FIN evaporates: no more
+      // frames will ever arrive to re-trigger this flush (retransmits of the
+      // empty frame take this same path), the H3 layer never sees http_end,
+      // and the request above it waits forever. Emit the end-of-stream event
+      // with an empty payload instead — every consumer (h3, hq-interop,
+      // tls_bridge) already guards zero-length data.
+      if (stream.total_size > 0 && offset >= stream.total_size && !stream.fin_emitted) {
+        stream.fin_emitted = true;
+        ev.emit('stream', Number(sid), new Uint8Array(0), true);
+        setTimeout(function () { delete context.recv_streams[sid]; }, 100);
+      }
+      return;
+    }
     var delivered = offset - stream.flushed_to;   // in-order bytes handed to the app now
     stream.flushed_to = offset;
     var data = parts.length === 1 ? parts[0] : concatUint8Arrays(parts);
     var fin = (stream.total_size > 0 && offset >= stream.total_size);
+    if (fin) stream.fin_emitted = true;   // a late FIN-only retransmit must not fire a second end
     ev.emit('stream', Number(sid), data, fin);
     if (fin) setTimeout(function () { delete context.recv_streams[sid]; }, 100);
 
@@ -1135,7 +1223,19 @@ function QUICConnection(options) {
         // (RFC 9002 §5.1). sending_app_pn_in_flight holds data-carrying PNs —
         // the closest signal until sent_packets tracks ack_eliciting per packet
         // (so PING-only packets are not yet used as RTT samples).
-        if (context.sending_app_pn_in_flight.has(largest_pn)) {
+        //
+        // Expired-but-limboed packets ALSO qualify. QUIC packet numbers are
+        // never reused, so a late ACK is unambiguous (no TCP retransmission
+        // ambiguity), and limbo membership proves the packet carried data.
+        // Excluding them creates a self-sealing failure: an expiry timer that
+        // is too short kills packets before their ACKs arrive → the ACKs are
+        // then barred from producing RTT samples → srtt/rttvar keep reflecting
+        // the pre-queue path → the timer never widens → every packet keeps
+        // expiring. The queue-inflated samples these late ACKs carry are
+        // exactly the evidence the timer needs in order to grow past the real
+        // arrival time; one such sample spikes rttvar and ends the spiral.
+        if (context.sending_app_pn_in_flight.has(largest_pn) ||
+            (largest_pn in context.expired_unacked)) {
           var now = Date.now();
           // ACK Delay is microseconds scaled by 2^ack_delay_exponent; use the peer's
           // value (parsed from its transport params; defaults to 3 until then).
@@ -1156,6 +1256,35 @@ function QUICConnection(options) {
           if (pn >= ackedRanges[ri] && pn <= ackedRanges[ri + 1]) { ackedPns.push(pn); break; }
         }
       }
+      // Bytes of [from,to) already recorded as acked — the portion NOT to
+      // credit again. Guards against double-counting when both the original
+      // transmission and a retransmission of the same range end up ACKed
+      // (routine once late ACKs for expired packets are honoured).
+      function ackedOverlap(flat, from, to) {
+        var ov = 0;
+        for (var oi = 0; oi < flat.length; oi += 2) {
+          if (flat[oi] >= to) break;
+          var a = Math.max(from, flat[oi]), b = Math.min(to, flat[oi + 1]);
+          if (b > a) ov += b - a;
+        }
+        return ov;
+      }
+
+      function creditSpan(st, from, to) {
+        var fresh = (to - from) - ackedOverlap(st.acked_ranges, from, to);
+        flat_ranges.add(st.acked_ranges, [from, to]);
+        return fresh > 0 ? fresh : 0;
+      }
+
+      function retireStreamIfComplete(sid, st) {
+        if (st.total_size > 0 && st.acked_ranges.length === 2 &&
+            st.acked_ranges[0] === 0 && st.acked_ranges[1] >= st.total_size) {
+          delete context.send_streams[sid];
+          delete context.remote_max_stream_data_by_sid[sid];
+          delete context.last_stream_blocked_sent[sid];
+        }
+      }
+
       var newlyAckedBytes = 0;   // goodput bytes confirmed by this ACK (for delivery_rate)
       var oldestAckedPn = null;  // smallest newly-acked PN → longest delivery interval
       for (var ai = 0; ai < ackedPns.length; ai++) {
@@ -1165,19 +1294,36 @@ function QUICConnection(options) {
         for (var sid in context.send_streams) {
           var st = context.send_streams[sid];
           if (st.in_flight_ranges && apn in st.in_flight_ranges) {
-            newlyAckedBytes += st.in_flight_ranges[apn][1] - st.in_flight_ranges[apn][0];
-            flat_ranges.add(st.acked_ranges, st.in_flight_ranges[apn]);
+            newlyAckedBytes += creditSpan(st, st.in_flight_ranges[apn][0], st.in_flight_ranges[apn][1]);
             delete st.in_flight_ranges[apn];
-            if (st.total_size > 0 && st.acked_ranges.length === 2 &&
-                st.acked_ranges[0] === 0 && st.acked_ranges[1] >= st.total_size) {
-              delete context.send_streams[sid];
-              delete context.remote_max_stream_data_by_sid[sid];
-              delete context.last_stream_blocked_sent[sid];
-            }
+            retireStreamIfComplete(sid, st);
           }
         }
       }
 
+      // Late ACKs for packets the expiry timer already gave up on. The data
+      // DID arrive — the timer was simply wrong — so: credit the goodput
+      // (repairing the BtlBw signal), mark the spans acked (cancelling any
+      // retransmit that hasn't left yet), and take back the loss we counted.
+      for (var lpn in context.expired_unacked) {
+        var lnum = Number(lpn);
+        var hit = false;
+        for (var ri2 = 0; ri2 < ackedRanges.length; ri2 += 2) {
+          if (lnum >= ackedRanges[ri2] && lnum <= ackedRanges[ri2 + 1]) { hit = true; break; }
+        }
+        if (!hit) continue;
+        var rec = context.expired_unacked[lpn];
+        for (var si2 = 0; si2 < rec.spans.length; si2++) {
+          var sidL = rec.spans[si2][0];
+          var stL = context.send_streams[sidL];
+          if (!stL) continue;   // stream already fully acked via a retransmit
+          newlyAckedBytes += creditSpan(stL, rec.spans[si2][1], rec.spans[si2][2]);
+          retireStreamIfComplete(sidL, stL);
+        }
+        delete context.expired_unacked[lpn];
+        if (context.lost_count > 0) context.lost_count--;   // it wasn't a loss after all
+      }
+
       // Cumulative delivered advances by this ACK's goodput; the delivery clock
       // is the wall-time of this update.
       context.delivered += newlyAckedBytes;
@@ -1295,7 +1441,7 @@ function QUICConnection(options) {
             Math.round(targetRate / context.current_limit_packet_payload),
             1, context.max_limit_packets_per_sec);
         }
-        if (DEBUG && context.bbr_bdp !== null) {
+        if (DEBUG_BBR && context.bbr_bdp !== null) {
           console.log('[bbr] round=' + context.bbr_round_count + ' ' + context.bbr_state +
             ' BtlBw=' + (context.bbr_btlbw * 8 / 1e6).toFixed(2) + 'Mbps' +
             ' RTprop=' + context.bbr_min_rtt + 'ms' +
@@ -1661,7 +1807,21 @@ function QUICConnection(options) {
   // timeout while the peer isn't ACKing, so a dead path isn't flooded.
   function expireInFlight() {
     var now = Date.now();
-    var base = (context.srtt === null) ? 333 : context.srtt + Math.max(4 * context.rttvar, 1);
+    // RFC 9002 §6.2.1: PTO = srtt + max(4·rttvar, granularity) + max_ack_delay.
+    //
+    // The max_ack_delay term is NOT optional. The peer is allowed to sit on an
+    // ACK for up to that long (quic-go uses its full 25ms), so on a stable
+    // 30ms-RTT path the ACK legitimately arrives up to ~55ms after the send —
+    // while srtt + 4·rttvar alone converges to ~31ms as rttvar shrinks. Every
+    // packet then "expires" moments before its ACK lands: the ACK finds the PN
+    // already forgotten, the delivered counter never advances, BtlBw (computed
+    // from delivered) collapses, the pacer follows it down, and the data is
+    // resent anyway. Measured against quic-go through the interop simulator:
+    // each byte crossed the wire ~21×, goodput 54 KB/s on a 10 Mbps link.
+    // With the term restored the same path runs at line rate.
+    var base = (context.srtt === null)
+      ? 333
+      : context.srtt + Math.max(4 * context.rttvar, 1) + context.max_ack_delay;
 
     // Global backoff: while no ACK has arrived, widen the timeout geometrically.
     // Resets the instant an ACK updates last_ack_time.
@@ -1687,6 +1847,13 @@ function QUICConnection(options) {
           expired = (now - context.sending_app_pn_history[idx][0] >= timeout);
         }
         if (expired) {
+          // Park the span before forgetting it, so a late ACK can still be
+          // honoured (see expired_unacked above). Keyed per-PN; a packet that
+          // carried several streams accumulates one span per stream.
+          var limbo = context.expired_unacked[pnum];
+          if (!limbo) limbo = context.expired_unacked[pnum] = { t: now, spans: [] };
+          limbo.spans.push([sid, st.in_flight_ranges[pn][0], st.in_flight_ranges[pn][1]]);
+
           delete st.in_flight_ranges[pn];        // → becomes "missing" again, resent next pass
           // Count the loss once per packet: the Set holds each PN once, so the
           // first stream to expire it returns true; later same-PN deletes (a
@@ -1695,6 +1862,13 @@ function QUICConnection(options) {
         }
       }
     }
+
+    // Bound the limbo table: entries older than ~8 timeouts (min 10s) will
+    // never see their ACK — the peer retires ACK ranges long before that.
+    var limboCutoff = now - Math.max(10000, timeout * 8);
+    for (var lpn in context.expired_unacked) {
+      if (context.expired_unacked[lpn].t < limboCutoff) delete context.expired_unacked[lpn];
+    }
   }
 
 

package/src/quic_server.js

@@ -14,7 +14,11 @@
 
 import dgram from 'node:dgram';
 import { DEBUG, Emitter } from './utils.js';
-import { parse_quic_datagram } from './transport.js';
+import {
+  parse_quic_datagram,
+  is_supported_version,
+  build_version_negotiation
+} from './transport.js';
 import { QUICConnection } from './quic_connection.js';
 import { createSecureContext } from './tls_bridge.js';
 
@@ -116,7 +120,40 @@ function createQuicServer(options) {
     // routing decision covers them all — and the datagram is parsed only once
     // here, handing the parsed packets straight to the connection (previously
     // each packet's raw bytes were re-parsed inside feedDatagram).
-    var connId = findConnectionId(packets[0], addressKey);
+    // ── Version Negotiation (RFC 9000 §6) ──
+    // Must happen before any connection is created. A long-header packet
+    // carrying a version we don't speak gets a Version Negotiation packet in
+    // reply — that is how a client discovers what we support, and how a prober
+    // checks we are alive without completing a handshake.
+    //
+    // Getting this wrong is silent and confusing: without it, findConnectionId
+    // below happily creates a connection for the unknown-version Initial, maps
+    // the address to it, and every subsequent probe is routed into a
+    // connection that cannot do anything with it. The peer sees no reply at
+    // all and concludes the server is down.
+    var firstPkt = packets[0];
+    if (firstPkt.form === 'long' &&
+        firstPkt.type !== 'version_negotiation' &&
+        !is_supported_version(firstPkt.version)) {
+
+      // Anti-amplification (RFC 9000 §14.1): only answer datagrams that are
+      // at least 1200 bytes, so we can't be used to reflect traffic at a
+      // spoofed source. A genuine Initial is always padded to that size.
+      if (data.length < 1200) {
+        if (DEBUG) console.log('[qserver] unsupported version 0x' +
+          firstPkt.version.toString(16) + ' in a short datagram (' +
+          data.length + 'B) — dropping without VN');
+        return;
+      }
+
+      var vn = build_version_negotiation(firstPkt.dcid, firstPkt.scid);
+      if (DEBUG) console.log('[qserver] version 0x' +
+        firstPkt.version.toString(16) + ' unsupported — sending Version Negotiation');
+      sendUdp(fromIp, fromPort, vn);
+      return;
+    }
+
+    var connId = findConnectionId(firstPkt, addressKey);
     if (connId === null) return;  // stray/unmatched non-Initial packet — drop
 
     if (!(connId in connections)) {
@@ -205,28 +242,49 @@ function createQuicServer(options) {
     if (isExternal) {
       // External sockets already bound — wire up incoming messages.
       // Starting the sweep timer is safe here (idempotent check below).
+      // Externally-owned sockets are already bound, so enlarge them here.
+      // The owner may not have done it, and the cost of asking twice is nil.
       if (externalSocket4) {
         externalSocket4.on('message', onUdpMessage);
+        try { externalSocket4.setSendBufferSize(2 * 1024 * 1024); } catch (e) {}
+        try { externalSocket4.setRecvBufferSize(2 * 1024 * 1024); } catch (e) {}
       }
       if (externalSocket6) {
         externalSocket6.on('message', onUdpMessage);
+        try { externalSocket6.setSendBufferSize(2 * 1024 * 1024); } catch (e) {}
+        try { externalSocket6.setRecvBufferSize(2 * 1024 * 1024); } catch (e) {}
       }
       startSweepTimer();
       if (typeof callback === 'function') setImmediate(callback);
       return;
     }
 
+    // Grow the kernel socket buffers once the socket is bound.
+    //
+    // Node's defaults are small. A full send buffer drops the datagram
+    // locally and silently — indistinguishable from network loss, so loss
+    // recovery engages and throughput collapses. See LOSS_PTO_PLAN 7.4: this
+    // is what defeated the third pacer-calibration attempt.
+    //
+    // try/catch because some platforms cap the value and throw; not being
+    // able to enlarge the buffer must not stop the server from listening.
+    function growBuffers(sock) {
+      try { sock.setSendBufferSize(2 * 1024 * 1024); } catch (e) {}
+      try { sock.setRecvBufferSize(2 * 1024 * 1024); } catch (e) {}
+    }
+
     udp4 = dgram.createSocket('udp4');
     udp4.on('message', onUdpMessage);
     udp4.on('error', function (err) { ev.emit('error', err); });
     var host4 = host.indexOf('.') !== -1 ? host : '0.0.0.0';
-    udp4.bind(port, host4);
+    udp4.bind(port, host4, function () { growBuffers(udp4); });
 
     udp6 = dgram.createSocket({ type: 'udp6', ipv6Only: true });
     udp6.on('message', onUdpMessage);
     udp6.on('error', function (err) { ev.emit('error', err); });
     var host6 = host.indexOf(':') !== -1 ? host : '::';
     udp6.bind(port, host6, function () {
+      growBuffers(udp6);
       if (typeof callback === 'function') callback();
     });