quico 0.7.0 → 0.9.0

package/src/quic_server.js

@@ -13,8 +13,10 @@
  */
 
 import dgram from 'node:dgram';
+import dns from 'node:dns';
+import net from 'node:net';
 import crypto from 'node:crypto';
-import { DEBUG, Emitter } from './utils.js';
+import { DEBUG, Emitter, checkedSocketBufferSize, setSocketBuffers } from './utils.js';
 import {
   parse_quic_datagram,
   build_version_negotiation
@@ -118,6 +120,10 @@ function createQuicServer(options) {
   // When socket/socket6 are provided, the UDP layer is owned externally.
   // The caller demuxes packets and feeds them via handlePacket(msg, rinfo).
   // See RFC 9443 for the shared-port multiplexing scheme.
+  // The UDP sockets' buffers (utils.js): 4 MB by default — external ones
+  // too, as before (the demultiplexer that owns them may not have, and
+  // asking twice costs nothing); 0 or false leaves them all at the OS's.
+  var socketBufferSize = checkedSocketBufferSize(options.socketBufferSize, 'socketBufferSize');
   var externalSocket4 = options.socket  || null;
   var externalSocket6 = options.socket6 || null;
 
@@ -201,8 +207,28 @@ function createQuicServer(options) {
   // gave it, with the time, sealed (AES-256-GCM) to the client's IP address
   // under a key of this server's own. It lives seconds, so a key drawn at
   // start is enough: a restart costs only the Retries in flight.
+  //
+  // tokenSecret (node:quic's name, at least 16 bytes) gives the key instead:
+  // servers that pass the same one open each other's tokens. That is what
+  // several servers sharing a port need (one per thread, SO_REUSEPORT): a
+  // client back with a NEW_TOKEN from another port is hashed to another of
+  // them, and without the key its token does not open — no harm, only the
+  // shortcut lost. The AES key is derived from it (SHA-256), so a 16-byte
+  // secret serves as well as a 32-byte one.
   var validateAddress = options.validateAddress === true;
-  var retryTokenKey = crypto.randomBytes(32);
+  var tokenSecret = checkTokenSecret(options.tokenSecret) || crypto.randomBytes(32);
+  var retryTokenKey = tokenKeyOf(tokenSecret);
+
+  function checkTokenSecret(secret) {
+    if (secret === undefined || secret === null) return null;
+    if (!(secret instanceof Uint8Array) || secret.byteLength < 16) {
+      throw new TypeError('tokenSecret must be a Buffer or Uint8Array of at least 16 bytes');
+    }
+    return secret;
+  }
+  function tokenKeyOf(secret) {
+    return crypto.createHash('sha256').update('quico address-validation token key').update(secret).digest();
+  }
   var RETRY_TOKEN_LIFETIME = 10000;   // ms
   // Tokens of two kinds, sealed alike (RFC 9000 §8.1.3): a Retry's, good for
   // seconds and one connection attempt; and a NEW_TOKEN's, given to a client
@@ -478,6 +504,7 @@ function createQuicServer(options) {
       // in length". Shorter ones would also be easy to guess and collide.
       if (firstPkt.dcid.byteLength < 8) return;
       if (connectionCount >= maxConnections) return;
+      if (!accepting) return;
 
       var retry = null, knownAddress = false;
       if (firstPkt.token && firstPkt.token.byteLength > 0) {
@@ -723,8 +750,8 @@ function createQuicServer(options) {
   var SERVER_RUNTIME = ['validateAddress', 'handshakeLoadThreshold', 'maxHandshakesPerAddress', 'earlyData', 'earlyDataMaxAge'];
   var ELSEWHERE = {
     key: 'setSecureContext()', cert: 'setSecureContext()', ca: 'setSecureContext()', pfx: 'setSecureContext()',
-    passphrase: 'setSecureContext()', SNICallback: 'setSecureContext()',
-    ticketKeys: 'setTicketKeys()', ech: 'setEchKeys()', resetTokenSecret: 'setResetTokenSecret()',
+    passphrase: 'setSecureContext()', SNICallback: 'addContext() or setSecureContext()',
+    ticketKeys: 'setTicketKeys()', ech: 'setEchKeys()', resetTokenSecret: 'setResetTokenSecret()', tokenSecret: 'setTokenSecret()',
     transportParams: 'connectionOptions, per connection'
   };
   function optErr(Ctor, code, msg) { var e = new Ctor(msg); e.code = code; return e; }
@@ -805,6 +832,17 @@ function createQuicServer(options) {
   //  UDP send
   // ============================================================
 
+  // A client that has gone away: its port answers our datagrams with ICMP
+  // "port unreachable". Node does not report that on an unconnected UDP
+  // socket; Bun does, as ECONNREFUSED — an 'error' on the socket, or on a
+  // send's callback. It concerns that client alone (its connection ends at
+  // its idle timeout, as any silent peer's), not the socket: taken for a
+  // socket error it closed the server's socket, and with it every other
+  // client of that family (quico PR #12).
+  function isDepartedPeer(err) {
+    return !!err && err.code === 'ECONNREFUSED';
+  }
+
   function sendUdp(toIp, toPort, data) {
     var isV6 = toIp.indexOf(':') >= 0;
     // Prefer external socket (shared mode) over internally-bound socket
@@ -815,7 +853,7 @@ function createQuicServer(options) {
     sendsPending++;
     socket.send(data, toPort, toIp, function (err) {
       sendsPending--;
-      if (err && !closing) ev.emit('error', err);
+      if (err && !closing && !isDepartedPeer(err)) ev.emit('error', err);
       if (closing && sendsPending === 0) closing();
     });
   }
@@ -826,6 +864,11 @@ function createQuicServer(options) {
   // timeout. close() waits for them — not long (SEND_DRAIN_MAX).
   var sendsPending = 0;
   var shutDown = false;
+  // stopAccepting(): no new connection (an Initial for an unknown one is
+  // dropped); those open go on — a graceful close, the layer above deciding
+  // when they end.
+  var accepting = true;
+  var refed = true;
   var closing = null;
   var SEND_DRAIN_MAX = 200;
 
@@ -836,6 +879,7 @@ function createQuicServer(options) {
 
   function listen(listenPort, host, callback) {
     shutDown = false;
+    accepting = true;
     if (typeof host === 'function') { callback = host; host = null; }
     // `|| 443` turned port 0 into 443 — and port 0 is not "no port": it is how
     // a caller asks the OS for a free one (server.js has the same fix).
@@ -855,14 +899,8 @@ function createQuicServer(options) {
       // decrypted a second time and dropped as a duplicate, and every non-QUIC
       // packet — media included, on the hottest path there is — went through
       // the QUIC parser before being discarded.
-      if (externalSocket4) {
-        try { externalSocket4.setSendBufferSize(2 * 1024 * 1024); } catch (e) {}
-        try { externalSocket4.setRecvBufferSize(2 * 1024 * 1024); } catch (e) {}
-      }
-      if (externalSocket6) {
-        try { externalSocket6.setSendBufferSize(2 * 1024 * 1024); } catch (e) {}
-        try { externalSocket6.setRecvBufferSize(2 * 1024 * 1024); } catch (e) {}
-      }
+      if (externalSocket4) setSocketBuffers(externalSocket4, socketBufferSize);
+      if (externalSocket6) setSocketBuffers(externalSocket6, socketBufferSize);
       startSweepTimer();
       if (typeof callback === 'function') setImmediate(callback);
       return;
@@ -875,63 +913,108 @@ function createQuicServer(options) {
     // 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) {}
+    // Not being able to enlarge the buffer must not stop the server from
+    // listening (setSocketBuffers).
+    function growBuffers(sock) { setSocketBuffers(sock, socketBufferSize); }
+
+    // Which addresses: as node:net. An address binds its own family alone —
+    // '127.0.0.1' and '0.0.0.0' IPv4, '::1' IPv6; '::' (and no host) both;
+    // a hostname is looked up once, and each family it has binds its first
+    // address ('localhost': loopback, both families). Every address used to
+    // bind '::' unless it held a ':', and '0.0.0.0' unless it held a '.':
+    // listen(p, '127.0.0.1') answered on every IPv6 interface too, and
+    // listen(p, 'localhost') on every interface of both.
+    if (host === '::') bindFamilies('0.0.0.0', '::');
+    else if (net.isIP(host) === 4) bindFamilies(host, null);
+    else if (net.isIP(host) === 6) bindFamilies(null, host);
+    else {
+      dns.lookup(host, { all: true }, function (err, list) {
+        if (shutDown) return;
+        if (err) { ev.emit('error', err); return; }
+        bindFamilies(firstOf(list, 4), firstOf(list, 6));
+      });
     }
 
-    // Both sockets are attempted, and listening succeeds if EITHER binds.
-    //
-    // The callback used to hang off udp6.bind alone. On a host without IPv6 —
-    // a container, a CI runner, plenty of cloud instances — that bind fails
-    // with EAFNOSUPPORT and the callback is never called: listen() returns, the
-    // v4 socket is up and working, and the caller waits forever for a
-    // 'listening' that cannot arrive. Nothing logs, because the error goes to
-    // the 'error' event that a caller waiting on the callback has not reached
-    // yet.
+    function firstOf(list, family) {
+      for (var i = 0; i < list.length; i++) if (list[i].family === family) return list[i].address;
+      return null;
+    }
+
+    // The families one after the other, IPv4 first: after listen(0) IPv6
+    // takes the port the OS gave IPv4 — one server, one port, the one
+    // address() and Alt-Svc name. Each took a port of its own.
     //
-    // A failure on one family is also not fatal on its own. Only if BOTH fail
-    // is there nothing to listen on, and that is reported as an error.
-    var pending = 2;
-    var bound = 0;
-    var lastErr = null;
-
-    function settle(err) {
-      if (err) lastErr = err;
-      else bound++;
-      if (--pending > 0) return;
-      if (bound === 0) {
-        ev.emit('error', lastErr || new Error('failed to bind UDP on port ' + port));
+    // Listening succeeds when every family binds, but for one the host does
+    // not have (familyMissing: no IPv6 in a container) while another did.
+    // Any other failure fails the listen() — the sockets that bound are
+    // closed, and one 'error' says why. Before, either family binding was
+    // enough: with IPv4's port taken (another server already on it) this
+    // one served IPv6 alone, and nothing said so.
+    function bindFamilies(addr4, addr6) {
+      var steps = [];
+      if (addr4) steps.push([false, addr4]);
+      if (addr6) steps.push([true, addr6]);
+      var errs = [], bound = 0;
+      (function next(i) {
+        if (shutDown) return;
+        if (i === steps.length) { settle(errs, bound); return; }
+        bindOne(steps[i][0], steps[i][1], function (err) {
+          if (!err) bound++;
+          else { errs.push(err); if (!familyMissing(err)) { settle(errs, bound); return; } }
+          next(i + 1);
+        });
+      })(0);
+    }
+
+    function familyMissing(err) { return err.code === 'EAFNOSUPPORT' || err.code === 'EADDRNOTAVAIL'; }
+
+    // The callback used to hang off udp6.bind alone: on a host without IPv6
+    // it was never called, while the IPv4 socket served. It is called once
+    // the families are settled, whichever bound.
+    function settle(errs, bound) {
+      var fatal = null;
+      for (var i = 0; i < errs.length && !fatal; i++) if (!familyMissing(errs[i])) fatal = errs[i];
+      if (!fatal && bound === 0) fatal = errs[0] || new Error('failed to bind UDP on port ' + port);
+      if (fatal) {
+        if (udp4) { try { udp4.close(); } catch (e) {} udp4 = null; }
+        if (udp6) { try { udp6.close(); } catch (e) {} udp6 = null; }
+        ev.emit('error', fatal);
         return;
       }
       if (typeof callback === 'function') callback();
     }
 
-    udp4 = dgram.createSocket('udp4');
-    udp4.on('message', onUdpMessage);
-    udp4.once('error', function (err) {
-      // A bind failure arrives before we are listening; anything later is a
-      // runtime socket error and belongs to the consumer.
-      udp4 = null;
-      settle(err);
-      ev.emit('error', err);
-    });
-    var host4 = host.indexOf('.') !== -1 ? host : '0.0.0.0';
-    udp4.bind(port, host4, function () { growBuffers(udp4); settle(null); });
-
-    udp6 = dgram.createSocket({ type: 'udp6', ipv6Only: true });
-    udp6.on('message', onUdpMessage);
-    udp6.once('error', function (err) {
-      udp6 = null;
-      // No IPv6 on this host is ordinary, not an error the application needs
-      // to see — the v4 socket is serving. Only a total failure is emitted,
-      // from settle() above.
-      settle(err);
-    });
-    var host6 = host.indexOf(':') !== -1 ? host : '::';
-    udp6.bind(port, host6, function () { growBuffers(udp6); settle(null); });
+    // A socket whose bind fails is closed, not only dropped: it stayed open
+    // (no IPv6 on the host, the port taken), an object nothing could close
+    // once `udp4` / `udp6` no longer named it. The failure goes to settle()
+    // alone, which reports one error; it was also emitted here, so a
+    // listen() that failed emitted 'error' twice.
+    //
+    // An error after the bind is a runtime socket error: it belongs to the
+    // consumer, and the socket goes on serving — it is not closed. It was:
+    // the close ran for every error, so on Bun one departed client's
+    // ECONNREFUSED (isDepartedPeer, not reported at all) closed the socket,
+    // and the server answered no one of that family again. And `on`, not
+    // `once`: a second error with no listener left would throw.
+    function bindOne(v6, addr, done) {
+      var sock = dgram.createSocket(v6 ? { type: 'udp6', ipv6Only: true } : 'udp4'), isBound = false;
+      if (v6) udp6 = sock; else udp4 = sock;
+      sock.on('message', onUdpMessage);
+      sock.on('error', function (err) {
+        if (isBound) { if (!isDepartedPeer(err)) ev.emit('error', err); return; }
+        try { sock.close(); } catch (e) {}
+        if (udp4 === sock) udp4 = null;
+        if (udp6 === sock) udp6 = null;
+        done(err);
+      });
+      if (!refed) sock.unref();
+      sock.bind(port, addr, function () {
+        isBound = true;
+        growBuffers(sock);
+        if (port === 0) port = sock.address().port;
+        done(null);
+      });
+    }
 
     startSweepTimer();
   }
@@ -1004,13 +1087,47 @@ function createQuicServer(options) {
   //  External packet API (for shared UDP port scenarios)
   // ============================================================
 
-  // Query whether the given 5-tuple matches an active QUIC connection.
-  // Used by the demuxer to disambiguate byte 0 in range 64-79 between
-  // QUIC short header and TURN ChannelData (RFC 9443). Fresh connections
-  // must be classified by byte 0 range (80-127 or 192+ = QUIC).
-  function hasConnection(rinfo) {
-    var key = rinfo.address + ':' + rinfo.port;
-    return (key in addressMap) && (addressMap[key] in connections);
+  // Query whether a datagram belongs to an active QUIC connection.
+  //
+  // hasConnection(rinfo) — by the address it came from. Used by the demuxer
+  // to disambiguate byte 0 in range 64-79 between QUIC short header and TURN
+  // ChannelData (RFC 9443). Fresh connections must be classified by byte 0
+  // range (80-127 or 192+ = QUIC).
+  //
+  // hasConnection(rinfo, msg) — by the connection ID the datagram is
+  // addressed to, from wherever it came: the answer to "is this one mine"
+  // when several servers share the port (one per thread, SO_REUSEPORT) and a
+  // datagram can reach one that does not hold its connection — a client
+  // whose address changed is hashed to another socket. Asked before
+  // handlePacket: given a short-header packet for an ID it does not know,
+  // handlePacket answers with a Stateless Reset, and that would end a
+  // connection another server holds. The address does not count here: an ID
+  // that leads nowhere is not ours, whatever address sent it.
+  function hasConnection(rinfo, msg) {
+    if (msg === undefined || msg === null) {
+      var key = rinfo.address + ':' + rinfo.port;
+      return (key in addressMap) && (addressMap[key] in connections);
+    }
+    var dcid = datagramDcid(msg);
+    if (!dcid) return false;
+    var k = cidKey(dcid);
+    return (k in cidMap) && (cidMap[k] in connections);
+  }
+
+  // The Destination Connection ID of a datagram's first packet, without
+  // parsing the rest (RFC 9000 §17.2, §17.3; RFC 8999 for any version): a
+  // long header carries its length, a short header ours (SERVER_CID_LEN).
+  // null for one too short to hold it.
+  function datagramDcid(msg) {
+    if (!(msg instanceof Uint8Array) || msg.length < 1) return null;
+    if (msg[0] & 0x80) {
+      if (msg.length < 6) return null;
+      var len = msg[5];
+      if (msg.length < 6 + len) return null;
+      return msg.subarray(6, 6 + len);
+    }
+    if (msg.length < 1 + SERVER_CID_LEN) return null;
+    return msg.subarray(1, 1 + SERVER_CID_LEN);
   }
 
 
@@ -1021,14 +1138,27 @@ function createQuicServer(options) {
   return {
     listen: listen,
     close: close,
+    // node:dgram's address() of the socket listening — after listen(0), the
+    // port the OS gave (both families have it); null when not listening.
+    address: function () {
+      var s = udp4 || udp6 || externalSocket4 || externalSocket6;
+      try { return s ? s.address() : null; } catch (e) { return null; }
+    },
+    stopAccepting: function () { accepting = false; },
+    get connectionCount() { return connectionCount; },
+    // node:dgram's: whether the process may exit while this listens.
+    ref: function () { refed = true; if (udp4) udp4.ref(); if (udp6) udp6.ref(); },
+    unref: function () { refed = false; if (udp4) udp4.unref(); if (udp6) udp6.unref(); },
     on: function (name, fn) { ev.on(name, fn); },
 
     /** Feed an incoming UDP packet when running in external-socket mode.
      *  rinfo must be in Node's dgram format: { address, port, family, size }. */
     handlePacket: onUdpMessage,
 
-    /** Returns true if the 5-tuple matches an active QUIC connection.
-     *  Used by demuxers for routing decisions on shared UDP ports. */
+    /** hasConnection(rinfo): the address matches an active QUIC connection.
+     *  hasConnection(rinfo, msg): the datagram is addressed to one (by its
+     *  connection ID). Used by demuxers for routing decisions on shared UDP
+     *  ports — the second when several servers share it (see above). */
     hasConnection: hasConnection,
 
     /** The session ticket keys — tls.Server's names. A new key applies to
@@ -1059,7 +1189,18 @@ function createQuicServer(options) {
     setOptions: setOptions,
 
     getResetTokenSecret: function () { return resetTokenSecret; },
-    setResetTokenSecret: function (secret) { resetTokenSecret = checkResetTokenSecret(secret) || resetTokenSecret; }
+    setResetTokenSecret: function (secret) { resetTokenSecret = checkResetTokenSecret(secret) || resetTokenSecret; },
+
+    /** The address-validation token secret (Retry, NEW_TOKEN — see
+     *  tokenSecret above). A new one applies from now on; tokens sealed
+     *  under the one before no longer open: a client back with a NEW_TOKEN
+     *  loses its shortcut, and one mid-Retry its attempt (it accepts no
+     *  second Retry). */
+    getTokenSecret: function () { return tokenSecret; },
+    setTokenSecret: function (secret) {
+      var s = checkTokenSecret(secret);
+      if (s) { tokenSecret = s; retryTokenKey = tokenKeyOf(s); }
+    }
   };
 }
 

package/src/quic_socket.js

@@ -16,6 +16,7 @@ import dgram from 'node:dgram';
 import { QUICConnection } from './quic_connection.js';
 import lemonTls from 'lemon-tls';
 import { SUPPORTED_VERSIONS, parseVersionList, versionName } from './quic_version.js';
+import { checkedSocketBufferSize, setSocketBuffers } from './utils.js';
 
 
 /**
@@ -67,6 +68,7 @@ function createQuicClientSocket(opts) {
   // lemon-tls's list. A name it does not know throws here.
   var sigalgs = lemonTls.parseSigalgs(opts.sigalgs);
   var isIPv6 = opts.remoteIp.indexOf(':') >= 0;
+  var socketBufferSize = checkedSocketBufferSize(opts.socketBufferSize, 'socketBufferSize');
   var udpSocket = dgram.createSocket(isIPv6 ? 'udp6' : 'udp4');
   var quic = null;
 
@@ -88,11 +90,9 @@ function createQuicClientSocket(opts) {
     // pacer-calibration attempt (see LOSS_PTO_PLAN 7.4): larger bursts spilled
     // over the buffer and turned a lossless link into a slow one.
     //
-    // Wrapped in try/catch because the call can throw on platforms that cap
-    // the size; failing to enlarge the buffer is not a reason to fail the
-    // connection.
-    try { udpSocket.setSendBufferSize(2 * 1024 * 1024); } catch (e) {}
-    try { udpSocket.setRecvBufferSize(2 * 1024 * 1024); } catch (e) {}
+    // 4 MB by default (utils.js), socketBufferSize where given; failing to
+    // enlarge the buffer is not a reason to fail the connection.
+    setSocketBuffers(udpSocket, socketBufferSize);
 
     // One attempt; after a Version Negotiation, a second in a version the
     // server offered (RFC 9000 §6.2) — once.