quic: add reusePort option to QuicEndpoint

jasnell · sxa · commit c20aa4c47b9d · 2026-06-18T21:12:33.000+01:00
Signed-off-by: James M Snell <jasnell@gmail.com> Assisted-by: Opencode:Opus 4.6 PR-URL: #63267 Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
diff --git a/doc/api/quic.md b/doc/api/quic.md
@@ -1023,6 +1023,23 @@ added: v23.8.0
 
 When `true`, indicates that the endpoint should bind only to IPv6 addresses.
 
+#### `endpointOptions.reusePort`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {boolean}
+* Default: `false`
+
+When `true`, allows multiple endpoints (across separate processes) to bind to
+the same address and port. The kernel will load-balance incoming UDP datagrams
+across all sockets bound with this option. This enables horizontal scaling of
+QUIC servers by running multiple Node.js processes on the same port.
+
+Supported on Linux 3.9+ and DragonFlyBSD 3.6+. On unsupported platforms, the
+bind will fail with an error.
+
 #### `endpointOptions.maxConnectionsPerHost`
 
 <!-- YAML
diff --git a/lib/internal/quic/quic.js b/lib/internal/quic/quic.js
@@ -195,6 +195,7 @@ const onSessionHandshakeChannel = dc.channel('quic.session.handshake');
  * @property {string|SocketAddress} [address] The local address to bind to
  * @property {bigint|number} [addressLRUSize] The size of the address LRU cache
  * @property {boolean} [ipv6Only] Use IPv6 only
+ * @property {boolean} [reusePort] Enable SO_REUSEPORT for multi-process load balancing
  * @property {bigint|number} [maxConnectionsPerHost] The maximum number of connections per host
  * @property {bigint|number} [maxConnectionsTotal] The maximum number of total connections
  * @property {bigint|number} [maxRetries] The maximum number of retries
@@ -1559,6 +1560,7 @@ class QuicEndpoint {
       udpTTL,
       validateAddress,
       ipv6Only,
+      reusePort,
       cc,
       resetTokenSecret,
       tokenSecret,
@@ -1592,6 +1594,7 @@ class QuicEndpoint {
       udpTTL,
       validateAddress,
       ipv6Only,
+      reusePort,
       cc,
       resetTokenSecret,
       tokenSecret,
diff --git a/src/quic/bindingdata.h b/src/quic/bindingdata.h
@@ -84,6 +84,7 @@ class Packet;
   V(initial_max_streams_bidi, "initialMaxStreamsBidi")                         \
   V(initial_max_streams_uni, "initialMaxStreamsUni")                           \
   V(ipv6_only, "ipv6Only")                                                     \
+  V(reuse_port, "reusePort")                                                   \
   V(keylog, "keylog")                                                          \
   V(keys, "keys")                                                              \
   V(logstream, "LogStream")                                                    \
diff --git a/src/quic/endpoint.cc b/src/quic/endpoint.cc
@@ -191,7 +191,7 @@ Maybe<Endpoint::Options> Endpoint::Options::From(Environment* env,
       !SET(max_connections_per_host) || !SET(max_connections_total) ||
       !SET(max_stateless_resets) || !SET(address_lru_size) ||
       !SET(max_retries) || !SET(validate_address) ||
-      !SET(disable_stateless_reset) || !SET(ipv6_only) ||
+      !SET(disable_stateless_reset) || !SET(ipv6_only) || !SET(reuse_port) ||
 #ifdef DEBUG
       !SET(rx_loss) || !SET(tx_loss) ||
 #endif
@@ -262,6 +262,7 @@ std::string Endpoint::Options::ToString() const {
   res += prefix + "reset token secret: " + reset_token_secret.ToString();
   res += prefix + "token secret: " + token_secret.ToString();
   res += prefix + "ipv6 only: " + boolToString(ipv6_only);
+  res += prefix + "reuse port: " + boolToString(reuse_port);
   res += prefix +
          "udp receive buffer size: " + std::to_string(udp_receive_buffer_size);
   res +=
@@ -376,6 +377,7 @@ int Endpoint::UDP::Bind(const Options& options) {
   int flags = 0;
   if (options.local_address->family() == AF_INET6 && options.ipv6_only)
     flags |= UV_UDP_IPV6ONLY;
+  if (options.reuse_port) flags |= UV_UDP_REUSEPORT;
   int err = uv_udp_bind(&impl_->handle_, options.local_address->data(), flags);
   int size;
 
diff --git a/src/quic/endpoint.h b/src/quic/endpoint.h
@@ -140,6 +140,12 @@ class Endpoint final : public AsyncWrap, public Packet::Listener {
     // flag on the underlying uv_udp_t.
     bool ipv6_only = false;
 
+    // When true, multiple endpoints (across separate processes) can bind to
+    // the same address:port and the kernel will load-balance incoming UDP
+    // datagrams across them. This sets the UV_UDP_REUSEPORT flag on the
+    // underlying uv_udp_t. Supported on Linux 3.9+ and DragonFlyBSD 3.6+.
+    bool reuse_port = false;
+
     uint32_t udp_receive_buffer_size = 0;
     uint32_t udp_send_buffer_size = 0;
 
