quic: improve backend quic packet processing

Use a uv_check_t on BindingData to process outbound
pending packet send, and use TrySend for actually sending
packets when possible. Results in an 8% improvement in
req/s and ~24% improvement in p95 latency.

Also sets us up better for future improvements in
libuv if the changes proposed in libuv/libuv#5116
are accepted.

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/bindingdata.cc

@@ -22,6 +22,7 @@ namespace node {
 using mem::kReserveSizeAndAlign;
 using v8::Function;
 using v8::FunctionTemplate;
+using v8::HandleScope;
 using v8::Local;
 using v8::Object;
 using v8::String;
@@ -154,6 +155,16 @@ BindingData& BindingData::Get(Environment* env) {
 
 BindingData::~BindingData() {
   quic_alloc_state.binding = nullptr;
+  if (flush_check_initialized_) {
+    uv_check_stop(&flush_check_);
+    flush_check_started_ = false;
+    // The check handle is closed inline here. Because BindingData destruction
+    // happens during Environment cleanup, the handle will be finalized by
+    // libuv's close phase.
+    uv_close(reinterpret_cast<uv_handle_t*>(&flush_check_), nullptr);
+    flush_check_initialized_ = false;
+  }
+  pending_flush_sessions_.clear();
 }
 
 ngtcp2_mem* BindingData::ngtcp2_allocator() {
@@ -221,6 +232,11 @@ void BindingData::RegisterExternalReferences(
 BindingData::BindingData(Realm* realm, Local<Object> object)
     : BaseObject(realm, object) {
   MakeWeak();
+  CHECK_EQ(uv_check_init(env()->event_loop(), &flush_check_), 0);
+  flush_check_.data = this;
+  // Unref so the check handle doesn't keep the event loop alive on its own.
+  uv_unref(reinterpret_cast<uv_handle_t*>(&flush_check_));
+  flush_check_initialized_ = true;
 }
 
 SessionManager& BindingData::session_manager() {
@@ -230,6 +246,45 @@ SessionManager& BindingData::session_manager() {
   return *session_manager_;
 }
 
+void BindingData::ScheduleSessionFlush(const BaseObjectPtr<Session>& session) {
+  pending_flush_sessions_.push_back(session);
+  if (!flush_check_started_) {
+    uv_check_start(&flush_check_, OnFlushCheck);
+    flush_check_started_ = true;
+  }
+}
+
+void BindingData::OnFlushCheck(uv_check_t* handle) {
+  auto* binding = static_cast<BindingData*>(handle->data);
+  if (binding->pending_flush_sessions_.empty()) {
+    uv_check_stop(&binding->flush_check_);
+    binding->flush_check_started_ = false;
+    return;
+  }
+
+  HandleScope scope(binding->env()->isolate());
+
+  // Swap to a local vector before iterating. SendPendingData may trigger
+  // MakeCallback which runs JS that could cause more packet receives via
+  // re-entry (e.g., a stream data callback that synchronously writes to
+  // another session). Any sessions added during the flush remain in
+  // pending_flush_sessions_ and are picked up on the next check tick.
+  auto sessions = std::move(binding->pending_flush_sessions_);
+  for (auto& session : sessions) {
+    session->pending_flush_ = false;
+    if (!session->is_destroyed()) {
+      session->FlushPendingData();
+    }
+  }
+
+  // If no new sessions were added during the flush, stop the check
+  // to avoid per-tick callback overhead when idle.
+  if (binding->pending_flush_sessions_.empty()) {
+    uv_check_stop(&binding->flush_check_);
+    binding->flush_check_started_ = false;
+  }
+}
+
 void BindingData::MemoryInfo(MemoryTracker* tracker) const {
 #define V(name, _) tracker->TrackField(#name, name##_callback());
 

src/quic/bindingdata.h

@@ -10,9 +10,11 @@
 #include <ngtcp2/ngtcp2_crypto.h>
 #include <node.h>
 #include <node_mem.h>
+#include <uv.h>
 #include <v8.h>
 #include <memory>
 #include <unordered_map>
+#include <vector>
 #include "defs.h"
 
 namespace node::quic {
@@ -201,6 +203,13 @@ class BindingData final
   // routing so that any endpoint can route packets to any session.
   SessionManager& session_manager();
 
+  // Schedule a session for deferred SendPendingData. Sessions are accumulated
+  // during the I/O poll phase (via Endpoint::Receive -> Session::ReadPacket)
+  // and flushed in a uv_check callback immediately after poll completes.
+  // This batches multiple received packets before generating responses,
+  // allowing ngtcp2 to make better ACK coalescing decisions.
+  void ScheduleSessionFlush(const BaseObjectPtr<Session>& session);
+
   std::unordered_map<Endpoint*, BaseObjectPtr<BaseObject>> listening_endpoints;
 
   size_t current_ngtcp2_memory_ = 0;
@@ -247,6 +256,17 @@ class BindingData final
 #undef V
 
   std::unique_ptr<SessionManager> session_manager_;
+
+  // Deferred send flush state. The uv_check_t fires immediately after
+  // the I/O poll phase in the same event loop tick, allowing batched
+  // receive processing: all packets are read during poll, then
+  // SendPendingData is called once per dirty session in the check callback.
+  uv_check_t flush_check_;
+  std::vector<BaseObjectPtr<Session>> pending_flush_sessions_;
+  bool flush_check_started_ = false;
+  bool flush_check_initialized_ = false;
+
+  static void OnFlushCheck(uv_check_t* handle);
 };
 
 JS_METHOD_IMPL(IllegalConstructor);

src/quic/endpoint.cc

@@ -492,6 +492,14 @@ int Endpoint::UDP::Send(Packet::Ptr packet) {
   return err;
 }
 
+int Endpoint::UDP::TrySend(Packet* packet) {
+  DCHECK_NOT_NULL(packet);
+  if (is_closed_or_closing()) return UV_EBADF;
+  uv_buf_t buf = *packet;
+  return uv_udp_try_send(
+      &impl_->handle_, &buf, 1, packet->destination().data());
+}
+
 void Endpoint::UDP::MemoryInfo(MemoryTracker* tracker) const {
   if (impl_) tracker->TrackField("impl", impl_);
 }
@@ -812,6 +820,45 @@ void Endpoint::Send(Packet::Ptr packet) {
   STAT_INCREMENT(Stats, packets_sent);
 }
 
+void Endpoint::SendOrTrySend(Packet::Ptr packet) {
+#ifdef DEBUG
+  if (is_diagnostic_packet_loss(options_.tx_loss)) [[unlikely]] {
+    return;
+  }
+#endif
+
+  if (is_closed() || is_closing() || packet->length() == 0) {
+    return;
+  }
+
+  Debug(this, "TrySend %s", packet->ToString());
+  size_t packet_length = packet->length();
+
+  // Attempt synchronous send. On success (returns number of bytes sent),
+  // the packet is delivered immediately — no callback overhead, no
+  // waiting for the next poll cycle.
+  int err = udp_.TrySend(packet.get());
+  if (err >= 0) {
+    // Synchronous send succeeded. Release the packet immediately.
+    STAT_INCREMENT_N(Stats, bytes_sent, packet_length);
+    STAT_INCREMENT(Stats, packets_sent);
+    // Ptr destructor releases back to arena pool.
+    return;
+  }
+
+  if (err == UV_EAGAIN) {
+    // Socket not writable or async sends are queued. Fall back to the
+    // async path — the packet will be queued and flushed on the next
+    // POLLOUT cycle.
+    Debug(this, "TrySend got EAGAIN, falling back to async Send");
+    return Send(std::move(packet));
+  }
+
+  // Other errors are fatal.
+  Debug(this, "TrySend failed with error %d", err);
+  Destroy(CloseContext::SEND_FAILURE, err);
+}
+
 void Endpoint::SendRetry(const PathDescriptor& options) {
   // Generating and sending retry packets does consume some system resources,
   // and it is possible for a malicious peer to trigger sending a large number
@@ -1128,10 +1175,22 @@ void Endpoint::Receive(const uv_buf_t& buf,
     DCHECK_NOT_NULL(session);
     if (session->is_destroyed()) return;
     size_t len = store.length();
-    if (session->Receive(std::move(store), local_address, remote_address)) {
+    // Use ReadPacket (no SendPendingDataScope) so that multiple packets
+    // received in the same I/O burst are processed before any responses
+    // are generated. The deferred flush via BindingData's uv_check
+    // callback calls SendPendingData once per dirty session after all
+    // packets in the burst have been read.
+    if (session->ReadPacket(std::move(store), local_address, remote_address)) {
       STAT_INCREMENT_N(Stats, bytes_received, len);
       STAT_INCREMENT(Stats, packets_received);
     }
+    // Schedule the session for deferred SendPendingData if it hasn't
+    // been scheduled already in this burst.
+    if (!session->is_destroyed() && !session->pending_flush_) {
+      session->pending_flush_ = true;
+      BindingData::Get(env()).ScheduleSessionFlush(
+          BaseObjectPtr<Session>(session));
+    }
   };
 
   const auto accept = [&](const Session::Config& config, Store&& store) {

src/quic/endpoint.h

@@ -208,6 +208,13 @@ class Endpoint final : public AsyncWrap, public Packet::Listener {
 
   void Send(Packet::Ptr packet);
 
+  // Attempt synchronous send via uv_udp_try_send. If the socket is
+  // writable, the packet is sent immediately and the Ptr is released.
+  // If the socket is not writable (UV_EAGAIN), falls back to the
+  // async Send path. Used by the deferred flush callback to avoid
+  // the one-tick latency of async uv_udp_send.
+  void SendOrTrySend(Packet::Ptr packet);
+
   // Acquire a Packet from the pool. length sets the initial working
   // size (must be <= pool capacity). The slot is always allocated at
   // full capacity to avoid fragmentation.
@@ -281,6 +288,12 @@ class Endpoint final : public AsyncWrap, public Packet::Listener {
     void Close();
     int Send(Packet::Ptr packet);
 
+    // Synchronous send using uv_udp_try_send. Returns 0 on success,
+    // UV_EAGAIN if the socket is not writable or the send queue is
+    // non-empty, or another negative error code on failure.
+    // On success, the caller is responsible for releasing the packet.
+    int TrySend(Packet* packet);
+
     // Returns the local UDP socket address to which we are bound,
     // or fail with an assert if we are not bound.
     SocketAddress local_address() const;

src/quic/session.cc

@@ -2104,13 +2104,21 @@ void Session::SetLastError(QuicError&& error) {
 bool Session::Receive(Store&& store,
                       const SocketAddress& local_address,
                       const SocketAddress& remote_address) {
+  // 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);
+}
+
+bool Session::ReadPacket(Store&& store,
+                         const SocketAddress& local_address,
+                         const SocketAddress& remote_address) {
   DCHECK(!is_destroyed());
   impl_->remote_address_ = remote_address;
 
-  // When we are done processing this packet, we arrange to send any
-  // pending data for this session.
-  SendPendingDataScope send_scope(this);
-
   ngtcp2_vec vec = store;
   Path path(local_address, remote_address);
 
@@ -2125,14 +2133,16 @@ bool Session::Receive(Store&& store,
   // ensures that any deferred destroy waits until all callbacks for this
   // packet have completed. After calling ngtcp2_conn_read_pkt here, we
   // will need to double check that the session is not destroyed before
-  // we try doing anything with it (like updating stats, sending pending
-  // data, etc).
+  // we try doing anything with it (like updating stats, etc).
   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.
     err = ngtcp2_conn_read_pkt(*this,
                                &path,
-                               // TODO(@jasnell): ECN pkt_info blocked on libuv
                                nullptr,
                                vec.base,
                                vec.len,
@@ -2245,6 +2255,17 @@ bool Session::Receive(Store&& store,
   return false;
 }
 
+void Session::FlushPendingData() {
+  DCHECK(!is_destroyed());
+  if (impl_->application_) {
+    // Prefer synchronous sends during the deferred flush to avoid the
+    // one-tick latency of async uv_udp_send from the uv_check callback.
+    prefer_try_send_ = true;
+    application().SendPendingData();
+    prefer_try_send_ = false;
+  }
+}
+
 void Session::Send(Packet::Ptr packet) {
   // Sending a Packet is generally best effort. If we're not in a state
   // where we can send a packet, it's ok to drop it on the floor. The
@@ -2261,6 +2282,16 @@ void Session::Send(Packet::Ptr packet) {
     return;
   }
 
+  // When called from the deferred flush path (uv_check callback),
+  // prefer synchronous send to avoid the one-tick latency of async
+  // uv_udp_send. SendOrTrySend uses uv_udp_try_send first, falling
+  // back to uv_udp_send on EAGAIN.
+  if (prefer_try_send_) {
+    Debug(this, "Session is sending (try_send) %s", packet->ToString());
+    endpoint().SendOrTrySend(std::move(packet));
+    return;
+  }
+
   Debug(this, "Session is sending %s", packet->ToString());
   endpoint().Send(std::move(packet));
 }

src/quic/session.h

@@ -357,6 +357,23 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
                const SocketAddress& local_address,
                const SocketAddress& remote_address);
 
+  // ReadPacket processes a single inbound packet through ngtcp2 without
+  // triggering SendPendingData. This is the building block for batched
+  // receive processing: the caller (Endpoint::Receive) accumulates
+  // dirty sessions and a uv_check callback flushes them after all
+  // packets in the I/O burst have been read.
+  // Receive() is kept as a convenience wrapper that calls ReadPacket()
+  // then triggers SendPendingData (for paths like Connect that need
+  // immediate response).
+  bool ReadPacket(Store&& store,
+                  const SocketAddress& local_address,
+                  const SocketAddress& remote_address);
+
+  // Called by BindingData's flush callback to trigger SendPendingData
+  // on this session. Encapsulates the application() access so that
+  // bindingdata.cc doesn't need the full Application type definition.
+  void FlushPendingData();
+
   void Send(Packet::Ptr packet);
   void Send(Packet::Ptr packet, const PathStorage& path);
   datagram_id SendDatagram(Store&& data);
@@ -572,11 +589,22 @@ class Session final : public AsyncWrap, private SessionTicket::AppData::Source {
   bool in_ngtcp2_callback_scope_ = false;
   bool in_nghttp3_callback_scope_ = false;
   bool destroy_deferred_ = false;
+  // Set when this session is in BindingData's pending_flush_sessions_ vector.
+  // Cleared by the flush callback before calling SendPendingData.
+  // Provides O(1) dedup so a session receiving multiple packets in one I/O
+  // burst is only scheduled for flush once.
+  bool pending_flush_ = false;
+  // When true, Session::Send prefers synchronous delivery via
+  // Endpoint::SendOrTrySend (uv_udp_try_send with async fallback).
+  // Set during FlushPendingData to avoid the one-tick latency of
+  // async-only sends from the uv_check callback.
+  bool prefer_try_send_ = false;
   QuicConnectionPointer connection_;
   std::unique_ptr<TLSSession> tls_session_;
   friend struct NgTcp2CallbackScope;
   friend struct NgHttp3CallbackScope;
   friend class Application;
+  friend class BindingData;
   friend class DefaultApplication;
   friend class Http3ApplicationImpl;
   friend class Endpoint;