quic: add initial RTT option to session options

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>

Author: jasnell

doc/api/quic.md

@@ -2741,6 +2741,23 @@ added: v23.8.0
 Specifies the maximum number of milliseconds a TLS handshake is permitted to take
 to complete before timing out.
 
+#### `sessionOptions.initialRtt`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {bigint|number}
+***Default:**`0` (use ngtcp2 default of 333ms)
+
+Specifies the initial round-trip time estimate in milliseconds. This value is
+used for probe timeout (PTO) computation, initial pacing, and early loss
+detection before the first actual RTT sample is collected from the connection.
+The default of 333ms is appropriate for the general internet. For low-latency
+environments such as loopback or same-rack deployments, setting a value closer
+to the actual RTT (e.g., `1`) avoids unnecessarily conservative initial
+behavior.
+
 #### `sessionOptions.keepAlive`
 
 <!-- YAML

lib/internal/quic/quic.js

@@ -404,6 +404,9 @@ const endpointRegistry = new SafeSet();
  * @property {ArrayBufferView} [token] An opaque address validation token
  * previously received from the server via `onnewtoken` (client only).
  * @property {bigint|number} [handshakeTimeout] The handshake timeout
+ * @property {bigint|number} [initialRtt] The initial round-trip time estimate in milliseconds.
+ * Used for PTO computation and initial pacing before the first RTT sample. Default uses
+ * ngtcp2's built-in default of 333ms. Set lower for low-latency environments.
  * @property {bigint|number} [keepAlive] The keep-alive timeout in milliseconds. When set,
  * PING frames will be sent automatically to prevent idle timeout.
  * @property {bigint|number} [maxStreamWindow] The maximum stream window
@@ -4875,6 +4878,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  maxPayloadSize,
  unacknowledgedPacketThreshold =0,
  handshakeTimeout,
+ initialRtt,
  keepAlive,
  maxStreamWindow,
  maxWindow,
@@ -4982,6 +4986,7 @@ function processSessionOptions(options, config = kEmptyObject) {
  maxPayloadSize,
  unacknowledgedPacketThreshold,
  handshakeTimeout,
+ initialRtt,
  keepAlive,
  maxStreamWindow,
  maxWindow,

src/quic/bindingdata.h

@@ -93,6 +93,7 @@ class SessionManager;
 V(groups, "groups") \
 V(handshake_timeout, "handshakeTimeout") \
 V(http3_alpn, &NGHTTP3_ALPN_H3[1]) \
+V(initial_rtt, "initialRtt") \
 V(keep_alive_timeout, "keepAlive") \
 V(initial_max_data, "initialMaxData") \
 V(initial_max_stream_data_bidi_local, "initialMaxStreamDataBidiLocal") \

src/quic/session.cc

@@ -513,6 +513,12 @@ Session::Config::Config(Environment* env,
  options.handshake_timeout == UINT64_MAX
  ? UINT64_MAX
  : options.handshake_timeout * NGTCP2_MILLISECONDS;
+
+// The initial_rtt option is in milliseconds; ngtcp2 expects nanoseconds.
+// A value of 0 leaves the ngtcp2 default (333ms) unchanged.
+if (options.initial_rtt > 0)
+ settings.initial_rtt = options.initial_rtt * NGTCP2_MILLISECONDS;
+
  settings.max_stream_window = options.max_stream_window;
  settings.max_window = options.max_window;
  settings.ack_thresh = options.unacknowledged_packet_threshold;
@@ -604,10 +610,11 @@ Maybe<Session::Options> Session::Options::From(Environment* env,
 
 if (!SET(version) || !SET(min_version) || !SET(preferred_address_strategy) ||
  !SET(transport_params) || !SET(tls_options) || !SET(qlog) ||
- !SET(handshake_timeout) || !SET(keep_alive_timeout) ||
- !SET(max_stream_window) || !SET(max_window) || !SET(max_payload_size) ||
- !SET(unacknowledged_packet_threshold) || !SET(cc_algorithm) ||
- !SET(draining_period_multiplier) || !SET(max_datagram_send_attempts)) {
+ !SET(handshake_timeout) || !SET(initial_rtt) ||
+ !SET(keep_alive_timeout) || !SET(max_stream_window) || !SET(max_window) ||
+ !SET(max_payload_size) || !SET(unacknowledged_packet_threshold) ||
+ !SET(cc_algorithm) || !SET(draining_period_multiplier) ||
+ !SET(max_datagram_send_attempts)) {
 return Nothing<Options>();
  }
 
@@ -726,6 +733,12 @@ std::string Session::Options::ToString() const {
  res += prefix + "handshake timeout: " + std::to_string(handshake_timeout) +
 " nanoseconds";
  }
+if (initial_rtt > 0) {
+ res += prefix + "initial rtt: " + std::to_string(initial_rtt) +
+" milliseconds";
+ } else {
+ res += prefix + "initial rtt: <default>";
+ }
  res += prefix + "max stream window: " + std::to_string(max_stream_window);
  res += prefix + "max window: " + std::to_string(max_window);
  res += prefix + "max payload size: " + std::to_string(max_payload_size);

src/quic/session.h

@@ -163,6 +163,15 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
 staticconstexpruint64_tDEFAULT_HANDSHAKE_TIMEOUT = 10'000;
 uint64_t handshake_timeout = DEFAULT_HANDSHAKE_TIMEOUT;
 
+// The initial round-trip time estimate in milliseconds. ngtcp2 uses this
+// for PTO computation, initial pacing, and early loss detection before
+// the first RTT sample is collected. The default of 0 uses ngtcp2's
+// built-in default of 333ms, which is appropriate for the general
+// internet. For low-latency environments (e.g., loopback or same-rack
+// deployments), setting a value closer to the actual RTT avoids
+// unnecessarily conservative initial behavior.
+uint64_t initial_rtt = 0;
+
 // The keep-alive timeout in milliseconds. When set to a non-zero value,
 // ngtcp2 will automatically send PING frames to keep the connection alive
 // before the idle timeout fires. Set to 0 to disable (default).

test/parallel/test-quic-session-initial-rtt.mjs

@@ -0,0 +1,60 @@
+// Flags: --experimental-quic --experimental-stream-iter --no-warnings
+
+// Test: initialRtt session option is accepted and the session functions
+// correctly with a custom initial RTT estimate.
+
+import{hasQuic,skip,mustCall}from'../common/index.mjs';
+importassertfrom'node:assert';
+
+const{ ok }=assert;
+
+if(!hasQuic){
+skip('QUIC is not enabled');
+}
+
+const{ listen, connect }=awaitimport('../common/quic.mjs');
+const{ bytes }=awaitimport('stream/iter');
+
+constencoder=newTextEncoder();
+constpayload=encoder.encode('hello rtt');
+constserverDone=Promise.withResolvers();
+
+// Use a low initialRtt (1ms) to simulate a low-latency environment.
+// The session should complete successfully and the smoothed RTT in
+// stats should converge to a value well below the default 333ms.
+constserverEndpoint=awaitlisten(mustCall((serverSession)=>{
+serverSession.onstream=mustCall(async(stream)=>{
+constdata=awaitbytes(stream);
+ok(data.byteLength>0);
+stream.writer.endSync();
+awaitstream.closed;
+serverSession.close();
+serverDone.resolve();
+});
+}),{
+initialRtt: 1,// 1ms
+});
+
+constclientSession=awaitconnect(serverEndpoint.address,{
+initialRtt: 1,// 1ms
+});
+awaitclientSession.opened;
+
+conststream=awaitclientSession.createBidirectionalStream({
+body: payload,
+});
+
+forawait(const_ofstream){/* drain */}// eslint-disable-line no-unused-vars
+awaitstream.closed;
+awaitserverDone.promise;
+
+// After data exchange, the smoothed RTT should have converged to a
+// realistic value. On loopback it should be well under 10ms (10,000,000ns).
+// The stat is in nanoseconds.
+constsmoothedRtt=clientSession.stats.smoothedRtt;
+ok(smoothedRtt>0n,'smoothedRtt should be non-zero after data exchange');
+ok(smoothedRtt<10_000_000n,
+`smoothedRtt should be under 10ms on loopback, got ${smoothedRtt}ns`);
+
+awaitclientSession.close();
+awaitserverEndpoint.close();