quic: add support for future ECN marking

jasnell · aduh95 · commit 9560084560d0 · 2026-05-23T00:05:40.000+02:00
Set up for when libuv eventually supports ECN marking. Pass the ECN marking stuff into ngtcp2. 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/src/quic/application.cc b/src/quic/application.cc
@@ -262,9 +262,12 @@ ssize_t Session::Application::TryWritePendingDatagram(PathStorage* path,
   int accepted = 0;
   int dg_flags = NGTCP2_WRITE_DATAGRAM_FLAG_MORE;
 
+  // PacketInfo for the datagram path. When libuv gains per-socket ECN
+  // marking, the value from ngtcp2 should be forwarded to the send path.
+  PacketInfo dg_pi;
   ssize_t dg_nwrite = ngtcp2_conn_writev_datagram(*session_,
                                                   &path->path,
-                                                  nullptr,
+                                                  dg_pi,
                                                   dest,
                                                   destlen,
                                                   &accepted,
@@ -390,12 +393,14 @@ void Session::Application::SendPendingData() {
   };
 
   // Accumulate a completed packet into the batch.
-  auto enqueue_packet = [&](Packet::Ptr& pkt, size_t len) {
-    Debug(session_, "Enqueuing packet with %zu bytes into batch", len);
-    pkt->Truncate(len);
-    path.CopyTo(&batch_paths[batch_count]);
-    batch[batch_count++] = std::move(pkt);
-  };
+  auto enqueue_packet =
+      [&](Packet::Ptr& pkt, size_t len, const PacketInfo& pi) {
+        Debug(session_, "Enqueuing packet with %zu bytes into batch", len);
+        pkt->Truncate(len);
+        pkt->set_pkt_info(pi);
+        path.CopyTo(&batch_paths[batch_count]);
+        batch[batch_count++] = std::move(pkt);
+      };
 
   // We're going to enter a loop here to prepare and send no more than
   // max_packet_count packets.
@@ -434,8 +439,9 @@ void Session::Application::SendPendingData() {
     }
 
     // Awesome, let's write our packet!
+    PacketInfo pi;
     ssize_t nwrite = WriteVStream(
-        &path, packet->data(), &ndatalen, packet->length(), stream_data);
+        &path, &pi, packet->data(), &ndatalen, packet->length(), stream_data);
 
     // When ndatalen is > 0, that's our indication that stream data was accepted
     // in to the packet. Yay!
@@ -531,7 +537,7 @@ void Session::Application::SendPendingData() {
             if (result > 0) {
               size_t len = result;
               Debug(session_, "Sending packet with %zu bytes", len);
-              enqueue_packet(packet, len);
+              enqueue_packet(packet, len, pi);
               if (++packet_send_count == max_packet_count) return;
             } else if (result < 0) {
               // Any negative result other than NGTCP2_ERR_WRITE_MORE
@@ -568,7 +574,7 @@ void Session::Application::SendPendingData() {
     // is the size of the packet we are sending.
     size_t len = nwrite;
     Debug(session_, "Sending packet with %zu bytes", len);
-    enqueue_packet(packet, len);
+    enqueue_packet(packet, len, pi);
     if (++packet_send_count == max_packet_count) return;
 
     // If there are pending datagrams, try sending them in a fresh packet.
@@ -587,7 +593,7 @@ void Session::Application::SendPendingData() {
           TryWritePendingDatagram(&path, packet->data(), packet->length());
       if (result > 0) {
         Debug(session_, "Sending datagram packet with %zd bytes", result);
-        enqueue_packet(packet, static_cast<size_t>(result));
+        enqueue_packet(packet, static_cast<size_t>(result), PacketInfo());
         if (++packet_send_count == max_packet_count) return;
       } else if (result < 0 && result != NGTCP2_ERR_WRITE_MORE) {
         // Fatal error &mdash; session already closed by TryWritePendingDatagram.
@@ -600,17 +606,20 @@ void Session::Application::SendPendingData() {
 }
 
 ssize_t Session::Application::WriteVStream(PathStorage* path,
+                                           PacketInfo* pi,
                                            uint8_t* dest,
                                            ssize_t* ndatalen,
                                            size_t max_packet_size,
                                            const StreamData& stream_data) {
   DCHECK_LE(stream_data.count, kMaxVectorCount);
   uint32_t flags = NGTCP2_WRITE_STREAM_FLAG_MORE;
   if (stream_data.fin) flags |= NGTCP2_WRITE_STREAM_FLAG_FIN;
+  // The PacketInfo out-param is populated by ngtcp2 with the ECN codepoint
+  // to apply when sending this packet. When libuv gains per-socket ECN
+  // marking, the value should be forwarded to the send path.
   return ngtcp2_conn_writev_stream(*session_,
                                    &path->path,
-                                   // TODO(@jasnell): ECN blocked on libuv
-                                   nullptr,
+                                   *pi,
                                    dest,
                                    max_packet_size,
                                    ndatalen,
diff --git a/src/quic/application.h b/src/quic/application.h
@@ -269,8 +269,11 @@ class Session::Application : public MemoryRetainer {
                                   uint8_t* dest,
                                   size_t destlen);
 
-  // Write the given stream_data into the buffer.
+  // Write the given stream_data into the buffer. The PacketInfo out-param
+  // is populated by ngtcp2 with per-packet metadata (e.g., ECN codepoint)
+  // that should be applied when sending the packet.
   ssize_t WriteVStream(PathStorage* path,
+                       PacketInfo* pi,
                        uint8_t* buf,
                        ssize_t* ndatalen,
                        size_t max_packet_size,
diff --git a/src/quic/data.h b/src/quic/data.h
@@ -19,6 +19,40 @@ namespace node::quic {
 template <typename T>
 concept OneByteType = sizeof(T) == 1;
 
+// Lightweight wrapper around ngtcp2_pkt_info. Insulates the Node.js QUIC
+// code from the ngtcp2 struct layout and provides a clean API boundary
+// for per-packet metadata (currently ECN codepoint; may grow as ngtcp2
+// and libuv evolve).
+//
+// Default-constructed PacketInfo is zero-initialized, which ngtcp2 treats
+// as ECN Not-ECT &mdash; identical to passing nullptr for the pkt_info parameter.
+class PacketInfo final {
+ public:
+  // ECN codepoints as defined by RFC 3168.
+  enum class Ecn : uint32_t {
+    NOT_ECT = 0,  // Not ECN-Capable Transport
+    ECT_1 = 1,    // ECN-Capable Transport(1)
+    ECT_0 = 2,    // ECN-Capable Transport(0)
+    CE = 3,       // Congestion Experienced
+  };
+
+  PacketInfo() : info_{} {}
+  explicit PacketInfo(const ngtcp2_pkt_info& info) : info_(info) {}
+
+  // ECN codepoint for this packet. When libuv gains per-packet ECN
+  // reporting, populate via set_ecn() from the receive metadata
+  // before passing to ReadPacket().
+  Ecn ecn() const { return static_cast<Ecn>(info_.ecn); }
+  void set_ecn(Ecn ecn) { info_.ecn = static_cast<uint32_t>(ecn); }
+
+  // Conversion operators for ngtcp2 API calls.
+  operator const ngtcp2_pkt_info*() const { return &info_; }
+  operator ngtcp2_pkt_info*() { return &info_; }
+
+ private:
+  ngtcp2_pkt_info info_;
+};
+
 struct Path final : public ngtcp2_path {
   explicit Path(const SocketAddress& local, const SocketAddress& remote);
   Path(Path&& other) noexcept = default;
diff --git a/src/quic/packet.h b/src/quic/packet.h
@@ -68,6 +68,8 @@ class Packet final {
   size_t length() const { return length_; }
   size_t capacity() const { return capacity_; }
   const SocketAddress& destination() const { return destination_; }
+  const PacketInfo& pkt_info() const { return pkt_info_; }
+  void set_pkt_info(const PacketInfo& pi) { pkt_info_ = pi; }
   Listener* listener() const { return listener_; }
 
   // Redirect the packet to a different endpoint for cross-endpoint sends
@@ -148,6 +150,7 @@ class Packet final {
   Listener* listener_;
 
   // Touched at send time.
+  PacketInfo pkt_info_;
   SocketAddress destination_;
 
   // Only touched by libuv during uv_udp_send and in the send callback.
diff --git a/src/quic/session.cc b/src/quic/session.cc
@@ -2103,19 +2103,21 @@ void Session::SetLastError(QuicError&& error) {
 
 bool Session::Receive(Store&& store,
                       const SocketAddress& local_address,
-                      const SocketAddress& remote_address) {
+                      const SocketAddress& remote_address,
+                      const PacketInfo& pkt_info) {
   // Convenience wrapper: reads the packet and immediately triggers
   // SendPendingData. Used by paths that need an immediate response
   // (e.g., Endpoint::Connect for client Initial packets).
   // The hot receive path uses ReadPacket() directly with deferred
   // flush via BindingData's uv_check callback.
   SendPendingDataScope send_scope(this);
-  return ReadPacket(std::move(store), local_address, remote_address);
+  return ReadPacket(std::move(store), local_address, remote_address, pkt_info);
 }
 
 bool Session::ReadPacket(Store&& store,
                          const SocketAddress& local_address,
-                         const SocketAddress& remote_address) {
+                         const SocketAddress& remote_address,
+                         const PacketInfo& pkt_info) {
   DCHECK(!is_destroyed());
   impl_->remote_address_ = remote_address;
 
@@ -2137,12 +2139,12 @@ bool Session::ReadPacket(Store&& store,
   int err;
   {
     NgTcp2CallbackScope callback_scope(this);
-    // ECN codepoint (ngtcp2_pkt_info.ecn) is not yet populated because
-    // libuv does not currently deliver per-packet ECN metadata. When
-    // libuv gains ECN receive reporting, the pkt_info should be
-    // populated from the per-packet metadata and passed through here.
+    // The PacketInfo carries per-packet metadata (currently ECN codepoint).
+    // When libuv gains per-packet ECN reporting, the caller should
+    // populate pkt_info from the receive metadata before calling
+    // ReadPacket().
     err = ngtcp2_conn_read_pkt(
-        *this, &path, nullptr, vec.base, vec.len, uv_hrtime());
+        *this, &path, pkt_info, vec.base, vec.len, uv_hrtime());
   }
   if (is_destroyed()) return false;
 
diff --git a/src/quic/session.h b/src/quic/session.h
@@ -355,7 +355,8 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
 
   bool Receive(Store&& store,
                const SocketAddress& local_address,
-               const SocketAddress& remote_address);
+               const SocketAddress& remote_address,
+               const PacketInfo& pkt_info = PacketInfo());
 
   // ReadPacket processes a single inbound packet through ngtcp2 without
   // triggering SendPendingData. This is the building block for batched
@@ -367,7 +368,8 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
   // immediate response).
   bool ReadPacket(Store&& store,
                   const SocketAddress& local_address,
-                  const SocketAddress& remote_address);
+                  const SocketAddress& remote_address,
+                  const PacketInfo& pkt_info = PacketInfo());
 
   // Called by BindingData's flush callback to trigger SendPendingData
   // on this session. Encapsulates the application() access so that
