quic: add initial RTT option to session options

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: OpenCode:Opus 4.6

Author: jasnell

doc/api/quic.md

@@ -2743,6 +2743,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 {
     static constexpr uint64_t DEFAULT_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';
+import assert from 'node:assert';
+
+const { ok } = assert;
+
+if (!hasQuic) {
+  skip('QUIC is not enabled');
+}
+
+const { listen, connect } = await import('../common/quic.mjs');
+const { bytes } = await import('stream/iter');
+
+const encoder = new TextEncoder();
+const payload = encoder.encode('hello rtt');
+const serverDone = 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.
+const serverEndpoint = await listen(mustCall((serverSession) => {
+  serverSession.onstream = mustCall(async (stream) => {
+    const data = await bytes(stream);
+    ok(data.byteLength > 0);
+    stream.writer.endSync();
+    await stream.closed;
+    serverSession.close();
+    serverDone.resolve();
+  });
+}), {
+  initialRtt: 1,  // 1ms
+});
+
+const clientSession = await connect(serverEndpoint.address, {
+  initialRtt: 1,  // 1ms
+});
+await clientSession.opened;
+
+const stream = await clientSession.createBidirectionalStream({
+  body: payload,
+});
+
+for await (const _ of stream) { /* drain */ } // eslint-disable-line no-unused-vars
+await stream.closed;
+await serverDone.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.
+const smoothedRtt = 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`);
+
+await clientSession.close();
+await serverEndpoint.close();