quico 0.2.0 → 0.3.0

package/index.js

@@ -18,6 +18,7 @@ import { Agent, globalAgent } from './src/agent.js';
 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';
 
 export {
   createServer,
@@ -29,7 +30,8 @@ export {
   ServerResponse,
   ClientRequest,
   createSecureContext,
-  WebTransport
+  WebTransport,
+  createQuicServer
 };
 
 export default {
@@ -42,5 +44,6 @@ export default {
   ServerResponse,
   ClientRequest,
   createSecureContext,
-  WebTransport
+  WebTransport,
+  createQuicServer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quico",
-  "version": "0.2.0",
+  "version": "0.3.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.2.0"
+    "lemon-tls": "^0.4.1"
   }
 }

package/src/agent.js

@@ -158,7 +158,7 @@ class Agent extends EventEmitter {
     var conn = this._h3Pool[key];
     if (!conn) return null;
     var state = conn.quic ? conn.quic.state : 'closed';
-    if (state === 'closed' || state === 'draining') {
+    if (state === 'closed' || state === 'draining' || state === 'closing') {
       delete this._h3Pool[key];
       return null;
     }
@@ -173,6 +173,14 @@ class Agent extends EventEmitter {
         if (this._h3Pool[key] === conn) delete this._h3Pool[key];
       });
     }
+    // RFC 9114 §5.2: once the peer sends GOAWAY it won't accept new requests, so
+    // stop reusing this connection for new ones. In-flight requests keep running
+    // on it; they just won't be joined by new requests (which open a fresh conn).
+    if (conn.h3 && typeof conn.h3.on === 'function') {
+      conn.h3.on('goaway', () => {
+        if (this._h3Pool[key] === conn) delete this._h3Pool[key];
+      });
+    }
   }
 
 

package/src/client.js

@@ -209,8 +209,13 @@ function request(url, options, callback) {
         headers: Object.assign({}, headers)
       };
 
-      // Check Agent for existing QUIC connection (multiplexing)
+      // Check Agent for existing QUIC connection (multiplexing).
+      // With an agent, the connection's lifecycle is owned by the pool
+      // (sweep / idle timer / agent.destroy), so signal h3_client not to
+      // auto-close it when this request finishes — otherwise the first
+      // request would tear down a connection still pooled for reuse.
       if (agent) {
+        h3Opts._managed = true;
         var existing = agent.getH3Connection(hostname, port);
         if (existing) h3Opts._connection = existing;
       }

package/src/crypto.js

@@ -60,8 +60,16 @@ var INITIAL_SALTS = {
 // ============================================================
 
 /**
- * Derive Initial encryption keys from the client DCID.
- * direction: 'read' = client keys, 'write' = server keys
+ * Derive an Initial-packet secret + keys from the client's original DCID.
+ *
+ * `direction` selects WHICH endpoint's Initial secret to derive — it is NOT
+ * "the keys I read/write with" in the obvious sense:
+ *   'read'  → the client's secret  (TLS label "client in")
+ *   'write' → the server's secret  (TLS label "server in")
+ * Each role then maps these to its own read/write keys: a client WRITES with
+ * the "client in" secret and READS with "server in"; a server is the mirror.
+ * So callers pass 'read' to get the client-side keys and 'write' for the
+ * server-side keys, and assign them to initial_read / initial_write per role.
  */
 function quic_derive_init_secrets(client_dcid, version, direction) {
   var hashName = 'sha256';
@@ -237,8 +245,10 @@ function expandPacketNumber(truncated, pnLen, largestReceived) {
 
 function decode_packet_number(array, offset, pnLength) {
   var value = 0;
+  // Use *256 (not <<8): a 4-byte packet number whose leading byte has the high
+  // bit set would overflow JS's 32-bit signed bitwise math and go negative.
   for (var i = 0; i < pnLength; i++) {
-    value = (value << 8) | array[offset + i];
+    value = value * 256 + array[offset + i];
   }
   return value;
 }
@@ -354,8 +364,13 @@ function encrypt_quic_packet(packetType, encodedFrames, writeKey, writeIv, write
 
 /**
  * Decrypt a QUIC packet (raw bytes → plaintext frames).
+ *
+ * `ownCid` is the connection ID by which the receiver is addressed. It is used
+ * ONLY for short (1-RTT) headers, which carry no DCID-length field — the
+ * receiver must already know its own CID length to locate the packet number.
+ * Long headers encode the DCID length on the wire, so `ownCid` is ignored there.
  */
-function decrypt_quic_packet(array, readKey, readIv, readHp, dcid, largestPn) {
+function decrypt_quic_packet(array, readKey, readIv, readHp, ownCid, largestPn) {
   if (!(array instanceof Uint8Array)) throw new Error('Invalid input');
 
   var firstByte = array[0];
@@ -405,7 +420,7 @@ function decrypt_quic_packet(array, readKey, readIv, readHp, dcid, largestPn) {
 
   } else {
     // Short Header
-    var dcidLen = dcid.length;
+    var dcidLen = ownCid.length;
     pnOffset = 1 + dcidLen;
 
     pnLength = remove_header_protection(array, pnOffset, readHp, true);

package/src/h3.js

@@ -13,10 +13,12 @@
  */
 
 import {
+  DEBUG,
   Emitter,
   concatUint8Arrays,
   writeVarInt,
-  readVarInt
+  readVarInt,
+  wt_stream_header
 } from './utils.js';
 
 
@@ -156,26 +158,30 @@ function huffDecode(buf) {
 //  QPACK parse/build helpers
 // ============================================================
 
-function decodeQpackVarInt(buf, prefixBits, pos) {
+// Read a QPACK/HPACK prefixed integer at buf[pos]. Returns { value, next } or
+// null if the buffer ends mid-integer (truncated). Used by both the header
+// block parser and the encoder-instruction parser.
+function readPrefixedInt(buf, prefixBits, pos) {
+  if (pos >= buf.length) return null;
   var max = (1 << prefixBits) - 1;
   var value = buf[pos] & max;
   pos++;
   if (value < max) return { value: value, next: pos };
   var m = 0;
-  while (true) {
+  while (pos < buf.length) {
     var byte = buf[pos++];
     value += (byte & 0x7f) << m;
-    if ((byte & 0x80) === 0) break;
+    if ((byte & 0x80) === 0) return { value: value, next: pos };
     m += 7;
   }
-  return { value: value, next: pos };
+  return null; // truncated mid-integer
 }
 
 function parseQpackHeaderBlock(buf, dynamicTable, baseIndex) {
   var pos = 0;
-  var ric = decodeQpackVarInt(buf, 8, pos); pos = ric.next;
+  var ric = readPrefixedInt(buf, 8, pos); if (!ric) return {}; pos = ric.next;
   var postBase = (buf[pos] & 0x80) !== 0;
-  var db = decodeQpackVarInt(buf, 7, pos); pos = db.next;
+  var db = readPrefixedInt(buf, 7, pos); if (!db) return {}; pos = db.next;
   var bi = postBase ? ric.value + db.value : ric.value - db.value;
 
   var headers = {};
@@ -185,7 +191,7 @@ function parseQpackHeaderBlock(buf, dynamicTable, baseIndex) {
     if ((byte & 0x80) === 0x80) {
       // Indexed
       var fromStatic = (byte & 0x40) !== 0;
-      var idx = decodeQpackVarInt(buf, 6, pos); pos = idx.next;
+      var idx = readPrefixedInt(buf, 6, pos); if (!idx) break; pos = idx.next;
       if (fromStatic && idx.value < QPACK_STATIC.length) {
         headers[QPACK_STATIC[idx.value][0]] = QPACK_STATIC[idx.value][1];
       } else if (!fromStatic && dynamicTable) {
@@ -198,9 +204,9 @@ function parseQpackHeaderBlock(buf, dynamicTable, baseIndex) {
     } else if ((byte & 0xc0) === 0x40) {
       // Literal with name ref
       var fromStatic = (byte & 0x10) !== 0;
-      var nameIdx = decodeQpackVarInt(buf, 4, pos); pos = nameIdx.next;
+      var nameIdx = readPrefixedInt(buf, 4, pos); if (!nameIdx) break; pos = nameIdx.next;
       var valH = (buf[pos] & 0x80) !== 0;
-      var valLen = decodeQpackVarInt(buf, 7, pos); pos = valLen.next;
+      var valLen = readPrefixedInt(buf, 7, pos); if (!valLen) break; pos = valLen.next;
       var valBytes = buf.slice(pos, pos + valLen.value); pos += valLen.value;
       var value = valH ? huffDecode(valBytes) : new TextDecoder().decode(valBytes);
 
@@ -216,11 +222,11 @@ function parseQpackHeaderBlock(buf, dynamicTable, baseIndex) {
     } else if ((byte & 0xe0) === 0x20) {
       // Literal with literal name
       var nameH = (byte & 0x08) !== 0;
-      var nameLen = decodeQpackVarInt(buf, 3, pos); pos = nameLen.next;
+      var nameLen = readPrefixedInt(buf, 3, pos); if (!nameLen) break; pos = nameLen.next;
       var nameBytes = buf.slice(pos, pos + nameLen.value); pos += nameLen.value;
       var name = nameH ? huffDecode(nameBytes) : new TextDecoder().decode(nameBytes);
       var valH = (buf[pos] & 0x80) !== 0;
-      var valLen = decodeQpackVarInt(buf, 7, pos); pos = valLen.next;
+      var valLen = readPrefixedInt(buf, 7, pos); if (!valLen) break; pos = valLen.next;
       var valBytes = buf.slice(pos, pos + valLen.value); pos += valLen.value;
       var value = valH ? huffDecode(valBytes) : new TextDecoder().decode(valBytes);
       headers[name] = value;
@@ -421,22 +427,13 @@ function parseQpackEncoderInstructions(chunks, fromOffset) {
   var pos = 0;
   var instructions = [];
 
+  // Thin wrapper over the shared readPrefixedInt that advances the local `pos`
+  // and returns the value (or null on truncation), preserving call-site usage.
   function safeVarInt(prefixBits) {
-    if (pos >= combined.length) return null;
-    var max = (1 << prefixBits) - 1;
-    var value = combined[pos] & max;
-    var startPos = pos;
-    pos++;
-    if (value < max) return value;
-    var m = 0;
-    while (pos < combined.length) {
-      var b = combined[pos++];
-      value += (b & 0x7f) << m;
-      if ((b & 0x80) === 0) return value;
-      m += 7;
-    }
-    pos = startPos;
-    return null;
+    var r = readPrefixedInt(combined, prefixBits, pos);
+    if (!r) return null;
+    pos = r.next;
+    return r.value;
   }
 
   while (pos < combined.length) {
@@ -624,8 +621,8 @@ function H3Connection(options) {
     var encId   = context.isServer ? 7 : 6;
     var decId   = context.isServer ? 11 : 10;
 
-    console.log('[h3] sendControlStreams ctrl=' + ctrlId + ' enc=' + encId + ' dec=' + decId);
-    console.log('[h3] SETTINGS hex: ' + Array.from(controlFrame).map(function(b){ return b.toString(16).padStart(2,'0'); }).join(' '));
+    if (DEBUG) console.log('[h3] sendControlStreams ctrl=' + ctrlId + ' enc=' + encId + ' dec=' + decId);
+    if (DEBUG) console.log('[h3] SETTINGS hex: ' + Array.from(controlFrame).map(function(b){ return b.toString(16).padStart(2,'0'); }).join(' '));
 
     // Send type byte + SETTINGS together as one chunk (some implementations need this)
     var ctrlData = new Uint8Array(1 + controlFrame.byteLength);
@@ -637,6 +634,17 @@ function H3Connection(options) {
   }
 
 
+  // ---- Graceful shutdown: GOAWAY (RFC 9114 §5.2) ----
+
+  function sendGoaway(id) {
+    sendControlStreams();  // idempotent — ensures the control stream + its type byte exist
+    var ctrlId = context.isServer ? 3 : 2;
+    var frame = buildH3Frames([{ frame_type: 0x07, payload: writeVarInt(id || 0) }]);
+    if (DEBUG) console.log('[h3] → GOAWAY id=' + (id || 0));
+    quic.sendStream(ctrlId, frame, false);
+  }
+
+
   // ---- Incoming stream data ----
 
   var _claimedStreams = new Set(); // streams owned by WebTransport (skip H3 processing)
@@ -655,7 +663,7 @@ function H3Connection(options) {
     }
 
     if (_claimedStreams.has(sid)) return; // owned by WebTransport client
-    console.log('[h3] stream ' + streamId + ' data=' + data.byteLength + ' fin=' + fin);
+    if (DEBUG) console.log('[h3] stream ' + streamId + ' data=' + data.byteLength + ' fin=' + fin);
     if (!(streamId in context.streams)) {
       context.streams[streamId] = { chunks: [], from_offset: 0, type: null, fin_received: false };
     }
@@ -671,7 +679,7 @@ function H3Connection(options) {
       // ---- WT stream detection ----
       if (context.local_webtransport && _wtSessions.size > 0) {
         var allData = concatUint8Arrays(s.chunks);
-        console.log('[h3] WT check: stream=' + sid + ' firstByte=0x' + (allData[0] || 0).toString(16) + ' len=' + allData.byteLength + ' sessions=' + Array.from(_wtSessions));
+        if (DEBUG) console.log('[h3] WT check: stream=' + sid + ' firstByte=0x' + (allData[0] || 0).toString(16) + ' len=' + allData.byteLength + ' sessions=' + Array.from(_wtSessions));
         if (allData.byteLength >= 2 && allData[0] === 0x40) {
           var typeResult = readVarInt(allData, 0);
           if (typeResult) {
@@ -689,7 +697,7 @@ function H3Connection(options) {
                 _wtStreams[sid] = { sessionId: sessionId, isBidi: !isUni };
                 delete context.streams[streamId];
 
-                console.log('[h3] WT stream detected: stream=' + sid + ' session=' + sessionId + ' bidi=' + !isUni + ' dataLen=' + remaining.byteLength);
+                if (DEBUG) console.log('[h3] WT stream detected: stream=' + sid + ' session=' + sessionId + ' bidi=' + !isUni + ' dataLen=' + remaining.byteLength);
                 ev.emit('wt_stream', sessionId, sid, remaining, fin, !isUni);
                 if (fin) delete _wtStreams[sid];
                 return;
@@ -739,7 +747,7 @@ function H3Connection(options) {
 
   function processControlStream(s) {
     var ext = extractH3Frames(s.chunks, s.from_offset);
-    console.log('[h3] control: extracted ' + ext.frames.length + ' H3 frames');
+    if (DEBUG) console.log('[h3] control: extracted ' + ext.frames.length + ' H3 frames');
     if (ext.frames.length === 0) return;
     s.from_offset = ext.new_from_offset;
 
@@ -761,7 +769,12 @@ function H3Connection(options) {
         set_context(updates);
 
       } else if (ext.frames[i].frame_type === 0x07) {
-        // GOAWAY — TODO
+        // GOAWAY (RFC 9114 §5.2): the peer will not process requests/pushes
+        // with an identifier >= this value. Surface it so consumers (e.g. the
+        // agent) can stop sending new requests on this connection.
+        var gp = readVarInt(ext.frames[i].payload, 0);
+        if (DEBUG) console.log('[h3] ← GOAWAY id=' + (gp ? gp.value : '?'));
+        ev.emit('goaway', gp ? gp.value : 0);
       }
     }
   }
@@ -801,7 +814,7 @@ function H3Connection(options) {
 
   function processBidiStream(streamId, s) {
     var ext = extractH3Frames(s.chunks, s.from_offset);
-    console.log('[h3] bidi stream ' + streamId + ': extracted ' + ext.frames.length + ' H3 frames, types=' + ext.frames.map(function(f){ return '0x' + f.frame_type.toString(16); }).join(','));
+    if (DEBUG) console.log('[h3] bidi stream ' + streamId + ': extracted ' + ext.frames.length + ' H3 frames, types=' + ext.frames.map(function(f){ return '0x' + f.frame_type.toString(16); }).join(','));
 
     if (ext.frames.length > 0) {
       s.from_offset = ext.new_from_offset;
@@ -836,12 +849,12 @@ function H3Connection(options) {
   function sendHeaders(streamId, headers, fin) {
     var payload = buildQpackHeaderBlock(headers);
     var frame = buildH3Frames([{ frame_type: 1, payload: payload }]);
-    console.log('[h3] sendHeaders stream=' + streamId + ' len=' + frame.byteLength + ' fin=' + !!fin);
+    if (DEBUG) console.log('[h3] sendHeaders stream=' + streamId + ' len=' + frame.byteLength + ' fin=' + !!fin);
     quic.sendStream(streamId, frame, !!fin);
   }
 
   function sendBody(streamId, data, fin) {
-    console.log('[h3] sendBody stream=' + streamId + ' data=' + (data ? data.byteLength : 'null') + ' fin=' + fin);
+    if (DEBUG) console.log('[h3] sendBody stream=' + streamId + ' data=' + (data ? data.byteLength : 'null') + ' fin=' + fin);
     if (data === null || data === undefined) {
       // Just set FIN on the stream (no additional H3 frame needed for empty body)
       quic.sendStream(streamId, new Uint8Array(0), true);
@@ -864,6 +877,7 @@ function H3Connection(options) {
     sendHeaders: sendHeaders,
     sendBody: sendBody,
     sendControlStreams: sendControlStreams,
+    sendGoaway: sendGoaway,
     claimStream: function (streamId) { _claimedStreams.add(Number(streamId)); },
 
     // WebTransport server-side API
@@ -887,12 +901,7 @@ function H3Connection(options) {
       }
 
       // Send WT prefix: VarInt(type) + VarInt(session_id)
-      var typePrefix = writeVarInt(isBidi ? 0x41 : 0x54);
-      var sessionPrefix = writeVarInt(sessionId);
-      var header = new Uint8Array(typePrefix.length + sessionPrefix.length);
-      header.set(typePrefix, 0);
-      header.set(sessionPrefix, typePrefix.length);
-      quic.sendStream(streamId, header, false);
+      quic.sendStream(streamId, wt_stream_header(isBidi, sessionId), false);
 
       _claimedStreams.add(streamId);
       _wtStreams[streamId] = { sessionId: sessionId, isBidi: isBidi };

package/src/h3_client.js

@@ -12,10 +12,10 @@
  *     https://github.com/colocohen/quico
  */
 
-import dgram from 'node:dgram';
 import dns from 'node:dns';
-import { QUICConnection } from './quic_connection.js';
+import { DEBUG } from './utils.js';
 import { H3Connection } from './h3.js';
+import { createQuicClientSocket } from './quic_socket.js';
 
 
 // ============================================================
@@ -38,11 +38,16 @@ function request(options, callback) {
   var path = options.path || '/';
   var method = (options.method || 'GET').toUpperCase();
   var headers = options.headers || {};
-  var rejectUnauthorized = options.rejectUnauthorized !== false;
 
   // Connection reuse: pass _connection = { quic, h3, udpSocket, nextStreamId }
   var existingConn = options._connection || null;
-  var autoClose = existingConn ? false : true;
+  // Auto-close the QUIC connection when this request finishes ONLY when we own
+  // it — i.e. a fresh, standalone connection. Reused connections (existingConn)
+  // and connections whose lifecycle is managed by an external pool
+  // (options._managed, set by the unified client/agent) are left open; closing
+  // them here would tear down a connection still pooled for reuse. Managed
+  // connections are reaped by the agent (sweep/destroy) and the QUIC idle timer.
+  var autoClose = !existingConn && !options._managed;
 
   // ---- Client Request object ----
   var reqBody = [];
@@ -104,9 +109,12 @@ function request(options, callback) {
 
   // ---- Resolve hostname and connect (or reuse existing) ----
   if (existingConn) {
-    // Reuse existing connection — allocate stream ID and send when ready
+    // Reuse existing connection — allocate stream ID and send when ready.
+    // The shared dispatch listeners were installed when the connection was
+    // first created; installSharedHandlers() is idempotent.
     streamId = allocateStreamId(existingConn);
-    setupResponseHandlers();
+    installSharedHandlers(existingConn);
+    setupResponseHandlers(existingConn);
     if (reqFinished) sendRequest();
   } else {
     resolveAndConnect(hostname, port);
@@ -132,60 +140,40 @@ function request(options, callback) {
 
 
   function startConnection(remoteIp, remotePort) {
-    // Create UDP socket
-    var isIPv6 = remoteIp.indexOf(':') >= 0;
-    udpSocket = dgram.createSocket(isIPv6 ? 'udp6' : 'udp4');
+    udpSocket = createQuicClientSocket({
+      remoteIp: remoteIp,
+      remotePort: remotePort,
+      hostname: hostname,
 
-    udpSocket.on('message', function (msg, rinfo) {
-      if (quic) quic.feedDatagram(rinfo.address, rinfo.port, new Uint8Array(msg));
-    });
-
-    udpSocket.on('error', function (err) {
-      emit(reqListeners, 'error', err);
-    });
+      onError: function (err) {
+        emit(reqListeners, 'error', err);
+      },
 
-    // Bind to random port
-    udpSocket.bind(0, function () {
-      // Create QUIC connection (client mode)
-      quic = new QUICConnection({
-        isServer: false,
-        SNICallback: null,
-        hostname: hostname
-      });
-
-      // Send packets via UDP
-      quic.on('packet', function (data) {
-        udpSocket.send(data, remotePort, remoteIp, function (err) {
-          if (err) emit(reqListeners, 'error', err);
-        });
-      });
-
-      // QUIC connected → set up H3
-      quic.on('connect', function () {
-        console.log('[client] QUIC connected');
+      onConnect: function (q, s) {
+        quic = q;
+        udpSocket = s;
+        if (DEBUG) console.log('[client] QUIC connected');
 
         h3 = new H3Connection({ quicConnection: quic, isServer: false });
         connected = true;
 
         // Build connection object for reuse
         var conn = { quic: quic, h3: h3, udpSocket: udpSocket, _nextStreamId: 0 };
+
+        // Install the shared per-connection dispatch listeners ONCE, then
+        // register this request in the connection's stream-handler map.
+        installSharedHandlers(conn);
         streamId = allocateStreamId(conn);
 
         // Store on clientReq so caller (unified client) can reuse
         clientReq._connection = conn;
 
-        setupResponseHandlers();
+        setupResponseHandlers(conn);
 
         // Send request if body is ready
         if (reqFinished) sendRequest();
-      });
-
-      quic.on('close', function () {
-        if (udpSocket) { try { udpSocket.close(); } catch (e) {} }
-      });
-
-      // Start QUIC handshake
-      quic.connect();
+      }
+      // onClose: the helper closes the UDP socket; nothing extra needed here.
     });
   }
 
@@ -202,51 +190,78 @@ function request(options, callback) {
 
 
   /**
-   * Set up HTTP/3 response handlers for this request's streamId.
-   * Works for both new and reused connections.
+   * Install the three HTTP/3 event listeners ONCE per connection. They dispatch
+   * each event to the right request via the connection's stream-handler map
+   * (keyed by stream id), so multiplexing many requests over a single
+   * connection does NOT pile up listeners on the H3 emitter (previously every
+   * request added another set of listeners that were never removed).
+   * Idempotent per connection.
    */
-  function setupResponseHandlers() {
-    // HTTP response headers
-    h3.on('http_headers', function (sid, hdrs) {
-      if (sid !== streamId) return;
-      clientRes.headers = hdrs;
-      clientRes.statusCode = parseInt(hdrs[':status']) || 0;
-      clientRes._headersReceived = true;
-
-      // Fire callback with response
-      if (typeof callback === 'function') {
-        callback(clientRes);
-        callback = null; // only once
-      }
-      emit(reqListeners, 'response', clientRes);
+  function installSharedHandlers(conn) {
+    if (conn._streamHandlers) return;  // already installed for this connection
+    conn._streamHandlers = {};
+    var h3c = conn.h3;
+
+    h3c.on('http_headers', function (sid, hdrs) {
+      var h = conn._streamHandlers[sid];
+      if (h) h.onHeaders(hdrs);
     });
-
-    // HTTP response body
-    h3.on('http_body', function (sid, data) {
-      if (sid !== streamId) return;
-      emit(clientRes, 'data', data);
+    h3c.on('http_body', function (sid, data) {
+      var h = conn._streamHandlers[sid];
+      if (h) h.onBody(data);
+    });
+    h3c.on('http_end', function (sid) {
+      var h = conn._streamHandlers[sid];
+      if (!h) return;
+      delete conn._streamHandlers[sid];  // free per-stream state before dispatch
+      h.onEnd();
     });
+  }
+
 
-    // HTTP response end
-    h3.on('http_end', function (sid) {
-      if (sid !== streamId) return;
-      emit(clientRes, 'end');
-
-      // Auto-close only if we own the connection (not reusing)
-      if (autoClose) {
-        setTimeout(function () {
-          if (quic) quic.close(0, 'done');
-          if (udpSocket) { try { udpSocket.close(); } catch (e) {} }
-        }, 100);
+  /**
+   * Register this request's response handlers in the connection's stream map,
+   * keyed by its streamId. Replaces per-request h3.on(...) registration —
+   * routing is now by map key, so no per-listener streamId check is needed.
+   */
+  function setupResponseHandlers(conn) {
+    conn._streamHandlers[streamId] = {
+      onHeaders: function (hdrs) {
+        clientRes.headers = hdrs;
+        clientRes.statusCode = parseInt(hdrs[':status']) || 0;
+        clientRes._headersReceived = true;
+
+        // Fire callback with response (once)
+        if (typeof callback === 'function') {
+          callback(clientRes);
+          callback = null;
+        }
+        emit(reqListeners, 'response', clientRes);
+      },
+
+      onBody: function (data) {
+        emit(clientRes, 'data', data);
+      },
+
+      onEnd: function () {
+        emit(clientRes, 'end');
+
+        // Auto-close only if we own the connection (see `autoClose` above).
+        if (autoClose) {
+          setTimeout(function () {
+            if (quic) quic.close(0, 'done');
+            if (udpSocket) { try { udpSocket.close(); } catch (e) {} }
+          }, 100);
+        }
       }
-    });
+    };
   }
 
 
   function sendRequest() {
     if (!h3 || !connected) return;
 
-    console.log('[client] sendRequest method=' + method + ' path=' + path + ' stream=' + streamId);
+    if (DEBUG) console.log('[client] sendRequest method=' + method + ' path=' + path + ' stream=' + streamId);
 
     // MUST send control streams (SETTINGS) before any request
     h3.sendControlStreams();