quico 0.2.0 → 0.3.0

package/src/transport.js

@@ -13,6 +13,7 @@
  */
 
 import {
+  DEBUG,
   concatUint8Arrays,
   writeVarInt,
   readVarInt
@@ -142,7 +143,7 @@ function parse_quic_datagram(array) {
       : array.slice(start, end);
 
     if (packets.length > 0) {
-      console.log('[quic] coalesced pkt #' + packets.length + ' type=' + pkt.type + ' offset=' + start + ' len=' + pkt.totalLength + ' firstByte=0x' + array[start].toString(16).padStart(2,'0'));
+      if (DEBUG) console.log('[quic] coalesced pkt #' + packets.length + ' type=' + pkt.type + ' offset=' + start + ' len=' + pkt.totalLength + ' firstByte=0x' + array[start].toString(16).padStart(2,'0'));
     }
 
     packets.push(pkt);
@@ -201,18 +202,25 @@ function encode_quic_frames(frames) {
     } else if (frame.type === 'stream') {
       var typeByte = 0x08;
       var hasOffset = (frame.offset != null && frame.offset > 0);
-      var hasLen = (frame.data && frame.data.length > 0);
       var hasFin = !!frame.fin;
-
+      var dataLen = (frame.data && frame.data.length) ? frame.data.length : 0;
+
+      // ALWAYS emit the LEN field. A STREAM frame without the LEN bit means
+      // "data runs to the end of the packet"; if anything follows it in the
+      // packet (another frame — e.g. a zero-length FIN-only batched with
+      // others — or padding), the peer reads those trailing bytes as stream
+      // data and the offset overshoots the declared final size
+      // (FINAL_SIZE / PROTOCOL_VIOLATION 0xa). An explicit length is always
+      // safe and self-delimiting.
       if (hasOffset) typeByte |= 0x04;
-      if (hasLen) typeByte |= 0x02;
+      typeByte |= 0x02; // LEN — always present
       if (hasFin) typeByte |= 0x01;
 
       parts.push(concatUint8Arrays([
         new Uint8Array([typeByte]),
         writeVarInt(frame.id),
         hasOffset ? writeVarInt(frame.offset) : new Uint8Array(0),
-        hasLen ? writeVarInt(frame.data.length) : new Uint8Array(0),
+        writeVarInt(dataLen),
         frame.data || new Uint8Array(0)
       ]));
 
@@ -315,18 +323,14 @@ function encode_quic_frames(frames) {
       ]));
 
     } else if (frame.type === 'datagram') {
-      if (frame.contextId != null) {
-        parts.push(concatUint8Arrays([
-          new Uint8Array([0x31]),
-          writeVarInt(frame.contextId),
-          frame.data
-        ]));
-      } else {
-        parts.push(concatUint8Arrays([
-          new Uint8Array([0x30]),
-          frame.data
-        ]));
-      }
+      // Emit the 0x30 form (no Length): the datagram data runs to the end of
+      // the packet. QUICO sends each DATAGRAM as the sole/last frame of its
+      // packet, so the length-prefixed 0x31 form is not needed here. (The
+      // parser above accepts both forms on receive.)
+      parts.push(concatUint8Arrays([
+        new Uint8Array([0x30]),
+        frame.data
+      ]));
     }
   }
 
@@ -498,13 +502,21 @@ function parse_quic_frames(buf) {
       frames.push({ type: 'handshake_done' });
 
     } else if (type === 0x30 || type === 0x31) {
-      var contextId = null;
+      // RFC 9221 DATAGRAM frame. The 0x31 form carries an explicit Length
+      // varint and the datagram data is exactly that many bytes; the 0x30 form
+      // has no Length and the data runs to the end of the packet (so a 0x30
+      // DATAGRAM must be the last frame). The optional field is a Length — not
+      // a "context ID" (that draft-era concept was removed before RFC 9221).
+      var data;
       if (type === 0x31) {
-        var cid = safeReadVarInt(); if (!cid) break;
-        contextId = cid.value;
+        var len = safeReadVarInt(); if (!len) break;
+        var end = offset + len.value;
+        if (end > buf.length) break; // truncated / invalid length
+        data = buf.slice(offset, end); offset = end;
+      } else {
+        data = buf.slice(offset); offset = buf.length;
       }
-      var data = buf.slice(offset); offset = buf.length;
-      frames.push({ type: 'datagram', contextId: contextId, data: data });
+      frames.push({ type: 'datagram', data: data });
 
     } else {
       // Unknown frame — stop
@@ -604,24 +616,28 @@ function parse_transport_params(buf, start) {
 
     var id = idVar.value;
 
+    // Safe inner varint: a malformed param could carry an empty/short value,
+    // in which case readVarInt returns null — never dereference .value blindly.
+    function vi(bytes) { var r = readVarInt(bytes, 0); return r ? r.value : 0; }
+
     switch (id) {
       case 0x00: out.original_destination_connection_id = valueBytes; break;
-      case 0x01: out.max_idle_timeout = readVarInt(valueBytes, 0).value; break;
+      case 0x01: out.max_idle_timeout = vi(valueBytes); break;
       case 0x02: out.stateless_reset_token = valueBytes; break;
-      case 0x03: out.max_udp_payload_size = readVarInt(valueBytes, 0).value; break;
-      case 0x04: out.initial_max_data = readVarInt(valueBytes, 0).value; break;
-      case 0x05: out.initial_max_stream_data_bidi_local = readVarInt(valueBytes, 0).value; break;
-      case 0x06: out.initial_max_stream_data_bidi_remote = readVarInt(valueBytes, 0).value; break;
-      case 0x07: out.initial_max_stream_data_uni = readVarInt(valueBytes, 0).value; break;
-      case 0x08: out.initial_max_streams_bidi = readVarInt(valueBytes, 0).value; break;
-      case 0x09: out.initial_max_streams_uni = readVarInt(valueBytes, 0).value; break;
-      case 0x0a: out.ack_delay_exponent = readVarInt(valueBytes, 0).value; break;
-      case 0x0b: out.max_ack_delay = readVarInt(valueBytes, 0).value; break;
+      case 0x03: out.max_udp_payload_size = vi(valueBytes); break;
+      case 0x04: out.initial_max_data = vi(valueBytes); break;
+      case 0x05: out.initial_max_stream_data_bidi_local = vi(valueBytes); break;
+      case 0x06: out.initial_max_stream_data_bidi_remote = vi(valueBytes); break;
+      case 0x07: out.initial_max_stream_data_uni = vi(valueBytes); break;
+      case 0x08: out.initial_max_streams_bidi = vi(valueBytes); break;
+      case 0x09: out.initial_max_streams_uni = vi(valueBytes); break;
+      case 0x0a: out.ack_delay_exponent = vi(valueBytes); break;
+      case 0x0b: out.max_ack_delay = vi(valueBytes); break;
       case 0x0c: out.disable_active_migration = true; break;
-      case 0x0e: out.active_connection_id_limit = readVarInt(valueBytes, 0).value; break;
+      case 0x0e: out.active_connection_id_limit = vi(valueBytes); break;
       case 0x0f: out.initial_source_connection_id = valueBytes; break;
       case 0x10: out.retry_source_connection_id = valueBytes; break;
-      case 0x20: out.max_datagram_frame_size = readVarInt(valueBytes, 0).value; break;
+      case 0x20: out.max_datagram_frame_size = vi(valueBytes); break;
       default:
         if (!out.unknown) out.unknown = [];
         out.unknown.push({ id: id, bytes: valueBytes });

package/src/utils.js

@@ -13,6 +13,16 @@
  */
 
 
+// ============================================================
+//  Debug flag — set QUICO_DEBUG=1 to enable verbose logging.
+//  Read once at module load. Call sites guard with `if (DEBUG)`
+//  so the (expensive) log-string construction is skipped entirely
+//  when debugging is off.
+// ============================================================
+
+var DEBUG = !!(typeof process !== 'undefined' && process.env && process.env.QUICO_DEBUG);
+
+
 // ============================================================
 //  Emitter — lightweight event emitter (single shared copy)
 // ============================================================
@@ -124,10 +134,12 @@ function readVarInt(array, offset) {
       array[offset + 7]
     ) >>> 0;
     var full = BigInt(hi) * 4294967296n + BigInt(lo);
-    if (full <= BigInt(Number.MAX_SAFE_INTEGER)) {
-      return { value: Number(full), byteLength: 8 };
-    }
-    return { value: full, byteLength: 8 };
+    // Always return a Number. QUIC fields (lengths, offsets, IDs, limits) never
+    // legitimately exceed 2^53, and a malicious 8-byte value that does will be
+    // rejected by the parsers' bounds checks anyway. Returning a BigInt here
+    // would throw "Cannot mix BigInt and other types" the moment the value is
+    // combined with a Number offset during parsing.
+    return { value: Number(full), byteLength: 8 };
   }
 
   return null;
@@ -164,6 +176,46 @@ function uint8Equal(a, b) {
 }
 
 
+// ============================================================
+//  WebTransport framing helpers (draft-ietf-webtrans-http3 / RFC 9297)
+//
+//  Both client (webtransport.js) and server (h3.js) build the same
+//  byte layouts, so they live here to avoid duplicating the prefix
+//  construction across the stream and datagram send paths.
+// ============================================================
+
+/**
+ * Build a WebTransport stream header: VarInt(streamType) + VarInt(sessionId) [+ data].
+ * streamType is 0x41 for a bidirectional WT stream, 0x54 for a unidirectional one.
+ * The header prefixes the FIRST chunk on a WT stream (or a lone FIN frame); pass
+ * `data` for "header + payload", omit it for a header-only (e.g. FIN) frame.
+ */
+function wt_stream_header(isBidi, sessionId, data) {
+  var typePrefix = writeVarInt(isBidi ? 0x41 : 0x54);
+  var sessionPrefix = writeVarInt(sessionId);
+  var dataLen = (data && data.byteLength) ? data.byteLength : 0;
+  var out = new Uint8Array(typePrefix.length + sessionPrefix.length + dataLen);
+  out.set(typePrefix, 0);
+  out.set(sessionPrefix, typePrefix.length);
+  if (dataLen) out.set(data, typePrefix.length + sessionPrefix.length);
+  return out;
+}
+
+/**
+ * Build a WebTransport datagram payload: VarInt(quarter_stream_id) + data.
+ * The quarter-stream-id is the session's CONNECT stream id divided by 4
+ * (RFC 9297 §2.1). Pass the session stream id; the division is done here.
+ */
+function wt_datagram_payload(sessionStreamId, data) {
+  var prefix = writeVarInt(Math.floor(sessionStreamId / 4));
+  var dataLen = (data && data.byteLength) ? data.byteLength : 0;
+  var out = new Uint8Array(prefix.length + dataLen);
+  out.set(prefix, 0);
+  if (dataLen) out.set(data, prefix.length);
+  return out;
+}
+
+
 // ============================================================
 //  ACK range helpers (flat [from,to, from,to, ...] format)
 // ============================================================
@@ -280,11 +332,14 @@ function ranges_to_ack_frame(flatRanges, ecnStats, ackDelay) {
 
 
 export {
+  DEBUG,
   Emitter,
   writeVarInt,
   readVarInt,
   concatUint8Arrays,
   uint8Equal,
+  wt_stream_header,
+  wt_datagram_payload,
   ack_frame_to_ranges,
   ranges_to_ack_frame
 };

package/src/webtransport.js

@@ -14,11 +14,10 @@
 
 import { Duplex, Readable, Writable } from 'node:stream';
 import { EventEmitter } from 'node:events';
-import dgram from 'node:dgram';
 import dns from 'node:dns';
-import { QUICConnection } from './quic_connection.js';
 import { H3Connection } from './h3.js';
-import { writeVarInt, readVarInt } from './utils.js';
+import { createQuicClientSocket } from './quic_socket.js';
+import { readVarInt, concatUint8Arrays, wt_stream_header, wt_datagram_payload } from './utils.js';
 
 
 // ============================================================
@@ -101,13 +100,7 @@ class WebTransportBidiStream extends Duplex {
     // First write on this stream: prepend VarInt(0x41) + VarInt(session_id)
     if (!this._prefixSent) {
       this._prefixSent = true;
-      var typePrefix = writeVarInt(0x41);     // WEBTRANSPORT_STREAM bidi type
-      var sessionPrefix = writeVarInt(this._sessionId);
-      var combined = new Uint8Array(typePrefix.length + sessionPrefix.length + chunk.byteLength);
-      combined.set(typePrefix, 0);
-      combined.set(sessionPrefix, typePrefix.length);
-      combined.set(chunk, typePrefix.length + sessionPrefix.length);
-      this._quic.sendStream(this._streamId, combined, false);
+      this._quic.sendStream(this._streamId, wt_stream_header(true, this._sessionId, chunk), false);
     } else {
       this._quic.sendStream(this._streamId, chunk, false);
     }
@@ -118,12 +111,7 @@ class WebTransportBidiStream extends Duplex {
     // Send FIN (with type + session_id prefix if nothing was written yet)
     if (!this._prefixSent) {
       this._prefixSent = true;
-      var typePrefix = writeVarInt(0x41);
-      var sessionPrefix = writeVarInt(this._sessionId);
-      var header = new Uint8Array(typePrefix.length + sessionPrefix.length);
-      header.set(typePrefix, 0);
-      header.set(sessionPrefix, typePrefix.length);
-      this._quic.sendStream(this._streamId, header, true);
+      this._quic.sendStream(this._streamId, wt_stream_header(true, this._sessionId), true);
     } else {
       this._quic.sendStream(this._streamId, new Uint8Array(0), true);
     }
@@ -168,13 +156,7 @@ class WebTransportUniWriteStream extends Writable {
     if (!this._headerSent) {
       this._headerSent = true;
       // Uni stream: VarInt(0x54) (WEBTRANSPORT_STREAM) + VarInt(session_id) + data
-      var typePrefix = writeVarInt(0x54);
-      var sessionPrefix = writeVarInt(this._sessionId);
-      var header = new Uint8Array(typePrefix.length + sessionPrefix.length + chunk.byteLength);
-      header.set(typePrefix, 0);
-      header.set(sessionPrefix, typePrefix.length);
-      header.set(chunk, typePrefix.length + sessionPrefix.length);
-      this._quic.sendStream(this._streamId, header, false);
+      this._quic.sendStream(this._streamId, wt_stream_header(false, this._sessionId, chunk), false);
     } else {
       this._quic.sendStream(this._streamId, chunk, false);
     }
@@ -184,12 +166,7 @@ class WebTransportUniWriteStream extends Writable {
   _final(callback) {
     if (!this._headerSent) {
       this._headerSent = true;
-      var typePrefix = writeVarInt(0x54);
-      var sessionPrefix = writeVarInt(this._sessionId);
-      var header = new Uint8Array(typePrefix.length + sessionPrefix.length);
-      header.set(typePrefix, 0);
-      header.set(sessionPrefix, typePrefix.length);
-      this._quic.sendStream(this._streamId, header, true);
+      this._quic.sendStream(this._streamId, wt_stream_header(false, this._sessionId), true);
     } else {
       this._quic.sendStream(this._streamId, new Uint8Array(0), true);
     }
@@ -350,43 +327,31 @@ class WebTransport extends EventEmitter {
   _startQuic(remoteIp) {
     var self = this;
     var remotePort = this._port;
-    var isIPv6 = remoteIp.indexOf(':') >= 0;
 
-    this._udpSocket = dgram.createSocket(isIPv6 ? 'udp6' : 'udp4');
+    this._udpSocket = createQuicClientSocket({
+      remoteIp: remoteIp,
+      remotePort: remotePort,
+      hostname: this._hostname,
 
-    this._udpSocket.on('message', function (msg, rinfo) {
-      if (self._quic) self._quic.feedDatagram(rinfo.address, rinfo.port, new Uint8Array(msg));
-    });
-
-    this._udpSocket.on('error', function (err) {
-      if (self._state === 'connecting') self._readyReject(err);
-      self.emit('error', err);
-    });
-
-    this._udpSocket.bind(0, function () {
-      self._quic = new QUICConnection({
-        isServer: false,
-        hostname: self._hostname
-      });
-
-      self._quic.on('packet', function (data) {
-        self._udpSocket.send(data, remotePort, remoteIp);
-      });
+      onError: function (err) {
+        if (self._state === 'connecting') self._readyReject(err);
+        self.emit('error', err);
+      },
 
-      self._quic.on('connect', function () {
+      onConnect: function (q, s) {
+        self._quic = q;
+        self._udpSocket = s;
         self._h3 = new H3Connection({ quicConnection: self._quic, isServer: false, enableWebTransport: true });
         self._setupH3Handlers();
         self._sendConnect();
-      });
+      },
 
-      self._quic.on('close', function () {
+      onClose: function () {
         self._state = 'closed';
         self._closedResolve();
         self.emit('close');
-        if (self._udpSocket) { try { self._udpSocket.close(); } catch (e) {} }
-      });
-
-      self._quic.connect();
+        // The helper closes the UDP socket.
+      }
     });
   }
 
@@ -424,7 +389,7 @@ class WebTransport extends EventEmitter {
     });
 
     // Datagrams — QUIC DATAGRAM payload = VarInt(quarter_stream_id) + app data (RFC 9297)
-    this._quic.on('datagram', function (_contextId, rawData) {
+    this._quic.on('datagram', function (rawData) {
       if (!rawData || rawData.byteLength === 0) return;
 
       // Always parse VarInt quarter_stream_id from payload
@@ -484,7 +449,7 @@ class WebTransport extends EventEmitter {
     buf.totalLen += data.byteLength;
 
     // Try to parse prefix
-    var combined = buf.totalLen === data.byteLength ? data : this._combineChunks(buf.chunks, buf.totalLen);
+    var combined = buf.totalLen === data.byteLength ? data : concatUint8Arrays(buf.chunks);
     var isBidi = (streamId & 0x2) === 0;
     var offset = 0;
 
@@ -552,18 +517,6 @@ class WebTransport extends EventEmitter {
     }
   }
 
-  _combineChunks(chunks, totalLen) {
-    if (chunks.length === 1) return chunks[0];
-    var out = new Uint8Array(totalLen);
-    var off = 0;
-    for (var i = 0; i < chunks.length; i++) {
-      out.set(chunks[i], off);
-      off += chunks[i].byteLength;
-    }
-    return out;
-  }
-
-
   // ---- Send CONNECT ----
 
   _sendConnect() {
@@ -660,14 +613,8 @@ class WebTransport extends EventEmitter {
     if (typeof data === 'string') data = Buffer.from(data);
     if (Buffer.isBuffer(data)) data = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
 
-    // Quarter stream ID as context ID (RFC 9297)
-    var contextId = Math.floor(this._sessionId / 4);
-
-    // Build datagram: VarInt(contextId) + payload
-    var contextPrefix = writeVarInt(contextId);
-    var frame = new Uint8Array(contextPrefix.length + data.byteLength);
-    frame.set(contextPrefix, 0);
-    frame.set(data, contextPrefix.length);
+    // Build datagram: VarInt(quarter_stream_id) + payload (RFC 9297)
+    var frame = wt_datagram_payload(this._sessionId, data);
 
     // Send via QUIC DATAGRAM frame
     if (this._quic && this._quic.sendDatagram) {