quic: add support for future ECN marking

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>

Author: jasnell

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;
  } elseif (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;
  } elseif (result < 0 && result != NGTCP2_ERR_WRITE_MORE) {
 // Fatal error — session already closed by TryWritePendingDatagram.
@@ -600,17 +606,20 @@ void Session::Application::SendPendingData() {
 }
 
 ssize_tSession::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.
 returnngtcp2_conn_writev_stream(*session_,
  &path->path,
-// TODO(@jasnell): ECN blocked on libuv
-nullptr,
+ *pi,
  dest,
  max_packet_size,
  ndatalen,

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_tWriteVStream(PathStorage* path,
+ PacketInfo* pi,
 uint8_t* buf,
 ssize_t* ndatalen,
 size_t max_packet_size,

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 — identical to passing nullptr for the pkt_info parameter.
+classPacketInfofinal {
+public:
+// ECN codepoints as defined by RFC 3168.
+enumclassEcn : 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_{} {}
+explicitPacketInfo(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 { returnstatic_cast<Ecn>(info_.ecn); }
+voidset_ecn(Ecn ecn) { info_.ecn = static_cast<uint32_t>(ecn); }
+
+// Conversion operators for ngtcp2 API calls.
+operatorconst ngtcp2_pkt_info*() const { return &info_; }
+operator ngtcp2_pkt_info*() { return &info_; }
+
+private:
+ ngtcp2_pkt_info info_;
+};
+
 structPathfinal : public ngtcp2_path {
 explicitPath(const SocketAddress& local, const SocketAddress& remote);
 Path(Path&& other) noexcept = default;

src/quic/packet.h

@@ -68,6 +68,8 @@ class Packet final {
 size_tlength() const { return length_; }
 size_tcapacity() const { return capacity_; }
 const SocketAddress& destination() const { return destination_; }
+const PacketInfo& pkt_info() const { return pkt_info_; }
+voidset_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.

src/quic/session.cc

@@ -2103,19 +2103,21 @@ void Session::SetLastError(QuicError&& error) {
 
 boolSession::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);
-returnReadPacket(std::move(store), local_address, remote_address);
+returnReadPacket(std::move(store), local_address, remote_address, pkt_info);
 }
 
 boolSession::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()) returnfalse;
 

src/quic/session.h

@@ -355,7 +355,8 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
 
 boolReceive(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).
 boolReadPacket(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