quic: add stream idle timeout

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

Author: jasnell

doc/api/quic.md

@@ -1679,6 +1679,11 @@ added: v23.8.0
 
 * Type: {bigint}
 
+### `sessionStats.streamsIdleTimedOut`
+
+* Type: {bigint} The total number of peer-initiated streams destroyed by the
+  stream idle timeout. Read only.
+
 ## Class: `QuicError`
 
 <!-- YAML
@@ -3050,6 +3055,23 @@ reported as lost via the `ondatagramstatus` callback.
 
 This option is immutable after session creation.
 
+#### `sessionOptions.streamIdleTimeout`
+
+* Type: {bigint|number}
+* **Default:** `30000` (30 seconds)
+
+The maximum time in milliseconds that a peer-initiated stream can be idle
+(no data received) before it is automatically destroyed. This protects
+against slowloris-style attacks where a remote peer opens streams but never
+sends data, holding server resources indefinitely. Only peer-initiated
+streams are checked — locally-initiated streams are the application's
+responsibility. Set to `0` to disable.
+
+The idle check runs as part of the normal send processing loop, so it adds
+no additional timers or event loop overhead. The
+`session.stats.streamsIdleTimedOut` counter tracks how many streams have been
+destroyed by this mechanism.
+
 #### `sessionOptions.maxDatagramSendAttempts`
 
 * Type: {number}

lib/internal/quic/quic.js

@@ -436,6 +436,7 @@ const endpointRegistry = new SafeSet();
  * @property {number} [drainingPeriodMultiplier] Multiplier applied to the
  *   draining period (3 * PTO) used by ngtcp2. Range `3..255`.
  *   **Default:** `3`.
+ * @property {bigint|number} [streamIdleTimeout] Time in ms before idle peer-initiated streams are destroyed
  * @property {number} [maxDatagramSendAttempts] Maximum number of times a
  *   datagram is retried before being abandoned. Range `1..255`.
  *   **Default:** `5`.
@@ -922,6 +923,17 @@ setCallbacks({
     // from QuicError::ToV8Value. Convert to a proper Node.js Error.
     if (error !== undefined) {
       error = convertQuicError(error);
+    } else if (this[kOwner] && !this[kOwner].destroyed) {
+      // The stream is closing cleanly, but it may have been reset by the
+      // peer (ReceiveStreamReset) or locally (resetStream). The C++ side
+      // records the reset code in state.resetCode. If set, surface the
+      // reset as the close error so stream.closed rejects -- the reset
+      // was an abnormal termination even if the session closed cleanly.
+      const resetCode = getQuicStreamState(this[kOwner]).resetCode;
+      if (resetCode !== undefined && resetCode > 0n) {
+        error = new ERR_QUIC_APPLICATION_ERROR(
+          resetCode, `stream reset with code ${resetCode}`);
+      }
     }
     debug(`stream ${this[kOwner].id} closed callback with error: ${error}`);
     this[kOwner][kFinishClose](error);
@@ -5015,6 +5027,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     datagramDropPolicy = 'drop-oldest',
     drainingPeriodMultiplier = 3,
     maxDatagramSendAttempts = 5,
+    streamIdleTimeout,
     verifyPeer = 'auto',
     // HTTP/3 application-specific options. Nested under `application`
     // to separate protocol-specific settings from transport-level ones.
@@ -5136,6 +5149,7 @@ function processSessionOptions(options, config = kEmptyObject) {
     datagramDropPolicy,
     drainingPeriodMultiplier,
     maxDatagramSendAttempts,
+    streamIdleTimeout,
     application,
     onerror,
     onstream,

lib/internal/quic/stats.js

@@ -101,6 +101,7 @@ const {
   IDX_STATS_SESSION_DATAGRAMS_SENT,
   IDX_STATS_SESSION_DATAGRAMS_ACKNOWLEDGED,
   IDX_STATS_SESSION_DATAGRAMS_LOST,
+  IDX_STATS_SESSION_STREAMS_IDLE_TIMED_OUT,
   IDX_STATS_SESSION_COUNT,
 
   IDX_STATS_STREAM_CREATED_AT,
@@ -169,6 +170,7 @@ assert(IDX_STATS_SESSION_DATAGRAMS_RECEIVED !== undefined);
 assert(IDX_STATS_SESSION_DATAGRAMS_SENT !== undefined);
 assert(IDX_STATS_SESSION_DATAGRAMS_ACKNOWLEDGED !== undefined);
 assert(IDX_STATS_SESSION_DATAGRAMS_LOST !== undefined);
+assert(IDX_STATS_SESSION_STREAMS_IDLE_TIMED_OUT !== undefined);
 assert(IDX_STATS_STREAM_CREATED_AT !== undefined);
 assert(IDX_STATS_STREAM_OPENED_AT !== undefined);
 assert(IDX_STATS_STREAM_RECEIVED_AT !== undefined);
@@ -689,6 +691,13 @@ class QuicSessionStats {
     return this.#handle[this.#offset + IDX_STATS_SESSION_DATAGRAMS_LOST];
   }
 
+  /** @type {bigint} */
+  get streamsIdleTimedOut() {
+    assertIsQuicSessionStats(this);
+    return this.#handle[this.#offset +
+                         IDX_STATS_SESSION_STREAMS_IDLE_TIMED_OUT];
+  }
+
   toString() {
     return JSONStringify(this.toJSON());
   }
@@ -726,6 +735,7 @@ class QuicSessionStats {
       datagramsSent,
       datagramsAcknowledged,
       datagramsLost,
+      streamsIdleTimedOut,
     } = this;
     return {
       __proto__: null,
@@ -762,6 +772,7 @@ class QuicSessionStats {
       datagramsSent: `${datagramsSent}`,
       datagramsAcknowledged: `${datagramsAcknowledged}`,
       datagramsLost: `${datagramsLost}`,
+      streamsIdleTimedOut: `${streamsIdleTimedOut}`,
     };
   }
 
@@ -807,6 +818,7 @@ class QuicSessionStats {
       datagramsSent,
       datagramsAcknowledged,
       datagramsLost,
+      streamsIdleTimedOut,
     } = this;
 
     return `QuicSessionStats ${inspect({
@@ -841,6 +853,7 @@ class QuicSessionStats {
       datagramsSent,
       datagramsAcknowledged,
       datagramsLost,
+      streamsIdleTimedOut,
     }, opts)}`;
   }
 

src/quic/application.cc

@@ -724,8 +724,11 @@ class DefaultApplication final : public Session::Application {
 
   void EarlyDataRejected() override {
     // Destroy all open streams — ngtcp2 has already discarded their
-    // internal state when it rejected the early data.
-    session().DestroyAllStreams(QuicError::ForApplication(0));
+    // internal state when it rejected the early data. Use the
+    // application's internal error code since this is an error
+    // condition (code 0 would be treated as a clean close).
+    session().DestroyAllStreams(
+        QuicError::ForApplication(GetInternalErrorCode()));
     if (!session().is_destroyed()) {
       session().EmitEarlyDataRejected();
     }

src/quic/bindingdata.h

@@ -113,6 +113,7 @@ class SessionManager;
   V(max_connections_total, "maxConnectionsTotal")                              \
   V(max_datagram_frame_size, "maxDatagramFrameSize")                           \
   V(max_datagram_send_attempts, "maxDatagramSendAttempts")                     \
+  V(stream_idle_timeout, "streamIdleTimeout")                                  \
   V(max_field_section_size, "maxFieldSectionSize")                             \
   V(max_header_length, "maxHeaderLength")                                      \
   V(max_header_pairs, "maxHeaderPairs")                                        \

src/quic/data.cc

@@ -365,12 +365,12 @@ std::optional<int> QuicError::get_crypto_error() const {
 
 MaybeLocal<Value> QuicError::ToV8Value(Environment* env) const {
   if ((type() == Type::TRANSPORT && code() == NGTCP2_NO_ERROR) ||
-      (type() == Type::APPLICATION && code() == NGHTTP3_H3_NO_ERROR) ||
+      (type() == Type::APPLICATION &&
+       (code() == 0 || code() == NGHTTP3_H3_NO_ERROR)) ||
       type() == Type::IDLE_CLOSE) {
-    // Note that we only return undefined for *known* no-error application
-    // codes. It is possible that other application types use other specific
-    // no-error codes, but since we don't know which application is being used,
-    // we'll just return the error code value for those below.
+    // Application code 0 is the default no-error code for raw QUIC
+    // applications (DefaultApplication::GetNoErrorCode() returns 0).
+    // NGHTTP3_H3_NO_ERROR (0x100) is the HTTP/3 no-error code.
     // Idle close is always clean — the session timed out normally.
     return Undefined(env->isolate());
   }

src/quic/http3.cc

@@ -177,10 +177,13 @@ class Http3ApplicationImpl final : public Session::Application {
     // When 0-RTT is rejected, destroy the nghttp3 connection and all
     // open streams — ngtcp2 has discarded their internal state.
     // Reset started_ so Start() is called again via on_receive_rx_key
-    // at 1RTT to recreate the nghttp3 connection.
+    // at 1RTT to recreate the nghttp3 connection. Use the
+    // application's internal error code since this is an error
+    // condition (code 0 would be treated as a clean close).
     conn_.reset();
     started_ = false;
-    session().DestroyAllStreams(QuicError::ForApplication(0));
+    session().DestroyAllStreams(
+        QuicError::ForApplication(GetInternalErrorCode()));
     if (!session().is_destroyed()) {
       session().EmitEarlyDataRejected();
     }

src/quic/session.cc

@@ -174,7 +174,8 @@ uint64_t MaxDatagramPayload(uint64_t max_frame_size) {
   V(DATAGRAMS_RECEIVED, datagrams_received)                                    \
   V(DATAGRAMS_SENT, datagrams_sent)                                            \
   V(DATAGRAMS_ACKNOWLEDGED, datagrams_acknowledged)                            \
-  V(DATAGRAMS_LOST, datagrams_lost)
+  V(DATAGRAMS_LOST, datagrams_lost)                                            \
+  V(STREAMS_IDLE_TIMED_OUT, streams_idle_timed_out)
 
 #define NO_SIDE_EFFECT true
 #define SIDE_EFFECT false
@@ -617,7 +618,8 @@ Maybe<Session::Options> Session::Options::From(Environment* env,
       !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(max_datagram_send_attempts) ||
+      !SET(stream_idle_timeout)) {
     return Nothing<Options>();
   }
 
@@ -2811,24 +2813,36 @@ void Session::ShutdownStream(stream_id id, QuicError error) {
   DCHECK(!is_destroyed());
   Debug(this, "Shutting down stream %" PRIi64 " with error %s", id, error);
   SendPendingDataScope send_scope(this);
-  ngtcp2_conn_shutdown_stream(*this,
-                              0,
-                              id,
-                              error.type() == QuicError::Type::APPLICATION
-                                  ? error.code()
-                                  : application().GetNoErrorCode());
+  // STOP_SENDING and RESET_STREAM frames carry application-level error
+  // codes (RFC 9000 §19.4, §19.5). Map the QuicError to an appropriate
+  // application code: APPLICATION errors pass through directly; transport
+  // no-error maps to the application's no-error code; any other error
+  // maps to the application's internal error code.
+  error_code code;
+  if (error.type() == QuicError::Type::APPLICATION) {
+    code = error.code();
+  } else if (error.code() == NGTCP2_NO_ERROR) {
+    code = application().GetNoErrorCode();
+  } else {
+    code = application().GetInternalErrorCode();
+  }
+  ngtcp2_conn_shutdown_stream(*this, 0, id, code);
 }
 
-void Session::ShutdownStreamWrite(stream_id id, QuicError code) {
+void Session::ShutdownStreamWrite(stream_id id, QuicError error) {
   DCHECK(!is_destroyed());
-  Debug(this, "Shutting down stream %" PRIi64 " write with error %s", id, code);
+  Debug(this, "Shutting down stream %" PRIi64 " write with error %s",
+        id, error);
   SendPendingDataScope send_scope(this);
-  ngtcp2_conn_shutdown_stream_write(*this,
-                                    0,
-                                    id,
-                                    code.type() == QuicError::Type::APPLICATION
-                                        ? code.code()
-                                        : application().GetNoErrorCode());
+  error_code code;
+  if (error.type() == QuicError::Type::APPLICATION) {
+    code = error.code();
+  } else if (error.code() == NGTCP2_NO_ERROR) {
+    code = application().GetNoErrorCode();
+  } else {
+    code = application().GetInternalErrorCode();
+  }
+  ngtcp2_conn_shutdown_stream_write(*this, 0, id, code);
 }
 
 void Session::StreamDataBlocked(stream_id id) {
@@ -3027,6 +3041,41 @@ void Session::UpdateDataStats() {
       std::max(STAT_GET(Stats, max_bytes_in_flight), info.bytes_in_flight));
 }
 
+void Session::CheckStreamIdleTimeout(uint64_t now) {
+  if (is_destroyed()) return;
+  uint64_t timeout = options().stream_idle_timeout;
+  if (timeout == 0) return;
+
+  uint64_t timeout_ns = timeout * NGTCP2_MILLISECONDS;
+  auto all_streams = streams();
+
+  for (const auto& [id, stream] : all_streams) {
+    if (!stream) continue;
+
+    // Only check peer-initiated streams. Locally-initiated streams
+    // that haven't been written to are the application's concern.
+    if (ngtcp2_conn_is_local_stream(*this, id)) continue;
+
+    uint64_t last_activity = stream->last_activity_timestamp();
+    if (last_activity > 0 && (now - last_activity) > timeout_ns) {
+      Debug(this,
+            "Stream %" PRId64 " idle timeout exceeded, destroying",
+            id);
+      // Notify the peer before destroying. ShutdownStream sends both
+      // STOP_SENDING and RESET_STREAM as appropriate, using the
+      // application's no-error code for non-APPLICATION errors (since
+      // these frames carry application-level error codes per RFC 9000).
+      // Without this, the peer's stream sits orphaned until the
+      // session closes.
+      auto error = QuicError::ForTransport(NGTCP2_ERR_PROTO,
+                                           "stream idle timeout");
+      ShutdownStream(id, error);
+      stream->Destroy(error);
+      STAT_INCREMENT(Stats, streams_idle_timed_out);
+    }
+  }
+}
+
 void Session::SendConnectionClose() {
   // Method is a non-op if the session is already destroyed or the
   // endpoint cannot send. Note: we intentionally do NOT check
@@ -3111,6 +3160,8 @@ void Session::OnTimeout() {
   if (is_destroyed()) return;
   if (NGTCP2_OK(ret) && !is_in_closing_period() && !is_in_draining_period()) {
     application().SendPendingData();
+    if (is_destroyed()) return;
+    CheckStreamIdleTimeout(uv_hrtime());
     return;
   }
   if (is_destroyed()) return;
@@ -3157,6 +3208,15 @@ void Session::UpdateTimer() {
   auto timeout = (expiry - now) / NGTCP2_MILLISECONDS;
   Debug(this, "Updating timeout to %zu milliseconds", timeout);
 
+  // If a stream idle timeout is configured, ensure the timer fires at
+  // least that often so CheckStreamIdleTimeout runs. Without this, an
+  // idle session with idle streams might not fire the timer until the
+  // connection idle timeout, which could be much longer.
+  uint64_t stream_idle = options().stream_idle_timeout;
+  if (stream_idle > 0 && timeout > stream_idle) {
+    timeout = stream_idle;
+  }
+
   // If timeout is zero here, it means our timer is less than a millisecond
   // off from expiry. Let's bump the timer to 1.
   impl_->timer_.Update(timeout == 0 ? 1 : timeout);

src/quic/session.h

@@ -227,6 +227,14 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
     // 10.2 requires at least 3x PTO. Range: 3-255. Default: 3.
     uint8_t draining_period_multiplier = 3;
 
+    // The amount of time (in milliseconds) that a stream can be idle
+    // (no data received) before it is automatically destroyed. This
+    // protects against slowloris-style attacks where a peer opens streams
+    // but never sends data, holding server resources indefinitely.
+    // Only applies to peer-initiated streams. Set to 0 to disable.
+    static constexpr uint64_t DEFAULT_STREAM_IDLE_TIMEOUT = 30'000;
+    uint64_t stream_idle_timeout = DEFAULT_STREAM_IDLE_TIMEOUT;
+
     // An optional NEW_TOKEN from a previous connection to the same
     // server. When set, the token is included in the Initial packet
     // to skip address validation. Client-side only.
@@ -569,6 +577,7 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
   // Has to be called after certain operations that generate packets.
   void UpdatePacketTxTime();
   void UpdateDataStats();
+  void CheckStreamIdleTimeout(uint64_t now);
   void UpdatePath(const PathStorage& path);
 
   void ProcessPendingBidiStreams();

src/quic/streams.cc

@@ -1270,7 +1270,8 @@ void Stream::NotifyStreamOpened(stream_id id) {
       // Headers were enqueued while the application was not yet known
       // (headers_supported == 0), and the negotiated application does
       // not support headers. This is a fatal mismatch.
-      Destroy(QuicError::ForApplication(0));
+      Destroy(QuicError::ForApplication(
+          session().application().GetInternalErrorCode()));
       return;
     }
     decltype(pending_headers_queue_) queue;
@@ -1347,6 +1348,11 @@ Session& Stream::session() const {
   return *session_;
 }
 
+uint64_t Stream::last_activity_timestamp() const {
+  uint64_t ts = stats()->received_at;
+  return ts != 0 ? ts : stats()->created_at;
+}
+
 bool Stream::is_local_unidirectional() const {
   return direction() == Direction::UNIDIRECTIONAL &&
          ngtcp2_conn_is_local_stream(*session_, id());
@@ -1625,6 +1631,7 @@ void Stream::EndReadable(std::optional<uint64_t> maybe_final_size) {
 
 void Stream::Destroy(QuicError error) {
   if (stats()->destroyed_at != 0) return;
+
   // Record the destroyed at timestamp before notifying the JavaScript side
   // that the stream is being destroyed.
   STAT_RECORD_TIMESTAMP(Stats, destroyed_at);