HTTP: add overload action to close idle HTTP connections (#43612)

fishpan1209 · web-flow · commit de4868777365 · 2026-04-15T19:21:48.000-07:00
Commit Message: HTTP: add overload action to close idle HTTP connections Additional Description: This change introduces the "CloseIdleHttpConnections" overload action to proactively terminate idle downstream connections during resource overload. The implementation currently supports QUIC connections only, with HTTP/2 support planned for a follow-up change. A periodic timer is established on worker threads upon action activation to invoke the closing logic across active listeners, guarded by a reloadable runtime feature. For QUIC, a new configuration option is added to enable this behavior, which leverages the session idle list to terminate sessions. Risk Level: low Testing: added overload integration test Docs Changes: Release Notes: Platform Specific Features: [Optional Runtime guard:] [Optional Fixes #Issue] [Optional Fixes commit #PR or SHA] [Optional Deprecated:] [Optional [API Considerations](https://github.com/envoyproxy/envoy/blob/main/api/review_checklist.md):] --------- Signed-off-by: Ting Pan <panting@google.com>
diff --git a/changelogs/current.yaml b/changelogs/current.yaml
@@ -1018,6 +1018,11 @@ new_features:
 - area: ratelimit
   change: |
     Support populating rate limit descriptors from cluster locality metadata.
+- area: http
+  change: |
+    Added a new overload action :ref:`envoy.overload_actions.close_idle_http_connections <config_overload_manager_overload_actions>`
+    that closes idle downstream HTTP connections when the overload action is active. Currently only HTTP/3 idle connections
+    trimming is supported, and HTTP/1 and HTTP/2 support are to be implemented.
 
 - area: contrib
   change: |
diff --git a/docs/root/configuration/operations/overload_manager/overload_manager.rst b/docs/root/configuration/operations/overload_manager/overload_manager.rst
@@ -149,6 +149,12 @@ The following overload actions are supported:
     - Envoy will reset expensive streams to terminate them. See
       :ref:`below <config_overload_manager_reset_streams>` for details on configuration.
 
+  * - envoy.overload_actions.close_idle_http_connections
+    - Envoy will close idle downstream HTTP/3 QUIC connections when the action is active.
+      When the action is *saturated*, connections will be closed aggressively (ignoring the idle timer threshold).
+      When the action is in a *scaled active* state, the idle timer threshold is still respected.
+      Note that this action is currently only supported for HTTP/3 QUIC connections.
+
 .. _config_overload_manager_shrink_heap:
 
 Shrink Heap
diff --git a/envoy/network/connection_handler.h b/envoy/network/connection_handler.h
@@ -127,6 +127,11 @@ class ConnectionHandler {
    */
   virtual const std::string& statPrefix() const PURE;
 
+  /**
+   * Close idle HTTP connections.
+   */
+  virtual void closeIdleHttpConnections(bool is_saturated) PURE;
+
   /**
    * Used by ConnectionHandler to manage listeners.
    */
@@ -172,6 +177,12 @@ class ConnectionHandler {
      */
     virtual void onFilterChainDraining(
         const std::list<const Network::FilterChain*>& draining_filter_chains) PURE;
+
+    // New method for handling idle connection closing
+    virtual void onCloseIdleHttpConnections(bool /*is_saturated*/) {
+      // Default implementation does nothing.
+      // Specific listener types (TCP, QUIC) will override this.
+    }
   };
 
   using ActiveListenerPtr = std::unique_ptr<ActiveListener>;
diff --git a/envoy/server/overload/overload_manager.h b/envoy/server/overload/overload_manager.h
@@ -42,16 +42,20 @@ class OverloadActionNameValues {
   // Overload action to reset streams using excessive memory.
   const std::string ResetStreams = "envoy.overload_actions.reset_high_memory_stream";
 
+  // Overload action to terminate idle downstream HTTP connections.
+  const std::string CloseIdleHttpConnections = "envoy.overload_actions.close_idle_http_connections";
+
   // This should be kept current with the Overload actions available.
   // This is the last member of this class to duplicating the strings with
   // proper lifetime guarantees.
-  const std::array<absl::string_view, 7> WellKnownActions = {StopAcceptingRequests,
+  const std::array<absl::string_view, 8> WellKnownActions = {StopAcceptingRequests,
                                                              DisableHttpKeepAlive,
                                                              StopAcceptingConnections,
                                                              RejectIncomingConnections,
                                                              ShrinkHeap,
                                                              ReduceTimeouts,
-                                                             ResetStreams};
+                                                             ResetStreams,
+                                                             CloseIdleHttpConnections};
 };
 
 using OverloadActionNames = ConstSingleton<OverloadActionNameValues>;
diff --git a/envoy/server/overload/thread_local_overload_state.h b/envoy/server/overload/thread_local_overload_state.h
@@ -49,6 +49,12 @@ using OverloadProactiveResources = ConstSingleton<OverloadProactiveResourceNameV
  */
 class OverloadActionState {
 public:
+  enum class Phase : uint8_t {
+    Inactive,
+    Scaling,
+    Saturated,
+  };
+
   static constexpr OverloadActionState inactive() { return OverloadActionState(UnitFloat::min()); }
 
   static constexpr OverloadActionState saturated() { return OverloadActionState(UnitFloat::max()); }
@@ -57,6 +63,15 @@ class OverloadActionState {
 
   UnitFloat value() const { return action_value_; }
   bool isSaturated() const { return action_value_.value() == UnitFloat::max().value(); }
+  Phase phase() const {
+    if (action_value_ == UnitFloat::min()) {
+      return Phase::Inactive;
+    } else if (action_value_ == UnitFloat::max()) {
+      return Phase::Saturated;
+    } else {
+      return Phase::Scaling;
+    }
+  }
 
 private:
   UnitFloat action_value_;
diff --git a/source/common/listener_manager/connection_handler_impl.cc b/source/common/listener_manager/connection_handler_impl.cc
@@ -309,6 +309,18 @@ void ConnectionHandlerImpl::setListenerRejectFraction(UnitFloat reject_fraction)
   }
 }
 
+void ConnectionHandlerImpl::closeIdleHttpConnections(bool is_saturated) {
+  for (const auto& [tag, listener] : listener_map_by_tag_) {
+    listener->invokeListenerMethod(
+        [is_saturated](Network::ConnectionHandler::ActiveListener& active_listener) {
+          if (active_listener.listener() != nullptr &&
+              !active_listener.listener()->shouldBypassOverloadManager()) {
+            active_listener.onCloseIdleHttpConnections(is_saturated);
+          }
+        });
+  }
+}
+
 Network::InternalListenerOptRef
 ConnectionHandlerImpl::findByAddress(const Network::Address::InstanceConstSharedPtr& address) {
   ASSERT(address->type() == Network::Address::Type::EnvoyInternal);
diff --git a/source/common/listener_manager/connection_handler_impl.h b/source/common/listener_manager/connection_handler_impl.h
@@ -57,6 +57,7 @@ class ConnectionHandlerImpl : public ConnectionHandler,
   void enableListeners() override;
   void setListenerRejectFraction(UnitFloat reject_fraction) override;
   const std::string& statPrefix() const override { return per_handler_stat_prefix_; }
+  void closeIdleHttpConnections(bool is_saturated) override;
 
   // Network::TcpConnectionHandler
   Event::Dispatcher& dispatcher() override { return dispatcher_; }
diff --git a/source/common/quic/active_quic_listener.cc b/source/common/quic/active_quic_listener.cc
@@ -1,15 +1,19 @@
 #include "source/common/quic/active_quic_listener.h"
 
+#include <memory>
 #include <utility>
 #include <vector>
 
+#include "envoy/common/optref.h"
 #include "envoy/extensions/quic/connection_id_generator/v3/envoy_deterministic_connection_id_generator.pb.h"
 #include "envoy/extensions/quic/crypto_stream/v3/crypto_stream.pb.h"
 #include "envoy/extensions/quic/proof_source/v3/proof_source.pb.h"
 #include "envoy/network/exception.h"
+#include "envoy/server/overload/overload_manager.h"
 
 #include "source/common/common/logger.h"
 #include "source/common/config/utility.h"
+#include "source/common/http/session_idle_list.h"
 #include "source/common/http/utility.h"
 #include "source/common/network/socket_option_impl.h"
 #include "source/common/network/udp_listener_impl.h"
@@ -39,7 +43,7 @@ ActiveQuicListener::ActiveQuicListener(
     EnvoyQuicProofSourceFactoryInterface& proof_source_factory,
     QuicConnectionIdGeneratorPtr&& cid_generator, QuicConnectionIdWorkerSelector worker_selector,
     EnvoyQuicConnectionDebugVisitorFactoryInterfaceOptRef debug_visitor_factory,
-    bool reject_new_connections)
+    bool reject_new_connections, bool enable_session_idle_list)
     : Server::ActiveUdpListenerBase(
           worker_index, concurrency, parent, *listen_socket,
           std::make_unique<Network::UdpListenerImpl>(
@@ -91,12 +95,12 @@ ActiveQuicListener::ActiveQuicListener(
       listen_socket_.setSocketOption(IPPROTO_IP, IP_RECVTOS, &optval, optlen);
     }
   }
-  // TODO(panting): Pass in a non-null session_idle_list when configured.
   quic_dispatcher_ = std::make_unique<EnvoyQuicDispatcher>(
       crypto_config_.get(), quic_config, &version_manager_, std::move(connection_helper),
       std::move(alarm_factory), quic::kQuicDefaultConnectionIdLength, parent, *config_, stats_,
       per_worker_stats_, dispatcher, listen_socket_, quic_stat_names, crypto_server_stream_factory_,
-      *connection_id_generator_, debug_visitor_factory, /*session_idle_list=*/nullptr);
+      *connection_id_generator_, debug_visitor_factory,
+      enable_session_idle_list ? std::make_unique<Http::SessionIdleList>(dispatcher) : nullptr);
 
   absl::AnyInvocable<void() &&> on_can_write_cb = [&]() { quic_dispatcher_->OnCanWrite(); };
 
@@ -272,6 +276,10 @@ void ActiveQuicListener::closeConnectionsWithFilterChain(const Network::FilterCh
   quic_dispatcher_->closeConnectionsWithFilterChain(filter_chain);
 }
 
+void ActiveQuicListener::onCloseIdleHttpConnections(bool is_saturated) {
+  quic_dispatcher_->closeIdleQuicConnections(is_saturated);
+}
+
 ActiveQuicListenerFactory::ActiveQuicListenerFactory(
     const envoy::config::listener::v3::QuicProtocolOptions& config, uint32_t concurrency,
     QuicStatNames& quic_stat_names, ProtobufMessage::ValidationVisitor& validation_visitor,
@@ -447,12 +455,21 @@ ActiveQuicListenerFactory::createActiveQuicListener(
     EnvoyQuicCryptoServerStreamFactoryInterface& crypto_server_stream_factory,
     EnvoyQuicProofSourceFactoryInterface& proof_source_factory,
     QuicConnectionIdGeneratorPtr&& cid_generator) {
+  bool enable_session_idle_list = false;
+  for (const auto& action :
+       context_.serverFactoryContext().bootstrap().overload_manager().actions()) {
+    if (action.name() == Server::OverloadActionNames::get().CloseIdleHttpConnections) {
+      enable_session_idle_list = true;
+      break;
+    }
+  }
   return std::make_unique<ActiveQuicListener>(
       runtime, worker_index, concurrency, dispatcher, parent, std::move(listen_socket),
       listener_config, quic_config, kernel_worker_routing, enabled, quic_stat_names,
       packets_to_read_to_connection_count_ratio, crypto_server_stream_factory, proof_source_factory,
       std::move(cid_generator), worker_selector_,
-      makeOptRefFromPtr(connection_debug_visitor_factory_.get()), reject_new_connections_);
+      makeOptRefFromPtr(connection_debug_visitor_factory_.get()), reject_new_connections_,
+      enable_session_idle_list);
 }
 
 } // namespace Quic
diff --git a/source/common/quic/active_quic_listener.h b/source/common/quic/active_quic_listener.h
@@ -42,7 +42,7 @@ class ActiveQuicListener : public Envoy::Server::ActiveUdpListenerBase,
                      QuicConnectionIdGeneratorPtr&& cid_generator,
                      QuicConnectionIdWorkerSelector worker_selector,
                      EnvoyQuicConnectionDebugVisitorFactoryInterfaceOptRef debug_visitor_factory,
-                     bool reject_new_connections = false);
+                     bool reject_new_connections = false, bool enable_session_idle_list = false);
 
   ~ActiveQuicListener() override;
 
@@ -73,6 +73,8 @@ class ActiveQuicListener : public Envoy::Server::ActiveUdpListenerBase,
   void onFilterChainDraining(
       const std::list<const Network::FilterChain*>& draining_filter_chains) override;
 
+  void onCloseIdleHttpConnections(bool is_saturated) override;
+
 protected:
   Event::Dispatcher& dispatcher() { return dispatcher_; }
 
diff --git a/source/common/quic/envoy_quic_dispatcher.cc b/source/common/quic/envoy_quic_dispatcher.cc
@@ -215,6 +215,7 @@ void EnvoyQuicDispatcher::updateListenerConfig(Network::ListenerConfig& new_list
 void EnvoyQuicDispatcher::closeIdleQuicConnections(bool is_saturated) {
   // This method is called from the worker thread, triggered by the
   // Overload Manager.
+  ASSERT(session_idle_list_ != nullptr);
   session_idle_list_->MaybeTerminateIdleSessions(is_saturated);
 }
 
diff --git a/source/server/worker_impl.cc b/source/server/worker_impl.cc
@@ -1,5 +1,6 @@
 #include "source/server/worker_impl.h"
 
+#include <chrono>
 #include <functional>
 #include <memory>
 
@@ -16,6 +17,9 @@ namespace Envoy {
 namespace Server {
 namespace {
 
+constexpr std::chrono::milliseconds kCloseIdleHttpConnectionsInterval =
+    std::chrono::milliseconds(100);
+
 std::unique_ptr<ConnectionHandler> getHandler(Event::Dispatcher& dispatcher, uint32_t index,
                                               OverloadManager& overload_manager,
                                               OverloadManager& null_overload_manager) {
@@ -59,6 +63,10 @@ WorkerImpl::WorkerImpl(ThreadLocal::Instance& tls, ListenerHooks& hooks,
   overload_manager.registerForAction(
       OverloadActionNames::get().ResetStreams, *dispatcher_,
       [this](OverloadActionState state) { resetStreamsUsingExcessiveMemory(state); });
+
+  overload_manager.registerForAction(
+      OverloadActionNames::get().CloseIdleHttpConnections, *dispatcher_,
+      [this](OverloadActionState state) { closeIdleHttpConnectionsCb(state.phase()); });
 }
 
 void WorkerImpl::addListener(absl::optional<uint64_t> overridden_listener,
@@ -125,6 +133,7 @@ void WorkerImpl::stop() {
   // It's possible for the server to cleanly shut down while cluster initialization during startup
   // is happening, so we might not yet have a thread.
   if (thread_) {
+    close_idle_connection_timer_ = nullptr;
     dispatcher_->exit();
     thread_->join();
   }
@@ -186,5 +195,41 @@ void WorkerImpl::resetStreamsUsingExcessiveMemory(OverloadActionState state) {
   reset_streams_counter_.add(streams_reset_count);
 }
 
+void WorkerImpl::closeIdleHttpConnectionsCb(OverloadActionState::Phase phase) {
+  if (close_idle_http_connections_state_ == phase) {
+    return;
+  }
+
+  close_idle_http_connections_state_ = phase;
+
+  // Lazy initialize the timer if it does not exist.
+  if (close_idle_connection_timer_ == nullptr) {
+    close_idle_connection_timer_ = dispatcher_->createTimer([this]() {
+      maybeCloseIdleHttpConnections();
+      ASSERT(close_idle_http_connections_state_ != OverloadActionState::Phase::Inactive);
+      close_idle_connection_timer_->enableTimer(kCloseIdleHttpConnectionsInterval);
+    });
+  }
+
+  if (close_idle_http_connections_state_ != OverloadActionState::Phase::Inactive) {
+    if (!close_idle_connection_timer_->enabled()) {
+      close_idle_connection_timer_->enableTimer(kCloseIdleHttpConnectionsInterval);
+    }
+  } else {
+    ASSERT(close_idle_connection_timer_->enabled());
+    close_idle_connection_timer_->disableTimer();
+  }
+}
+
+void WorkerImpl::maybeCloseIdleHttpConnections() {
+  if (handler_) {
+    // If state is saturated, aggressive closure is triggered (ignoring the
+    // idle timer threshold). Otherwise, it's a "scaled active" state which
+    // respects it.
+    handler_->closeIdleHttpConnections(close_idle_http_connections_state_ ==
+                                       OverloadActionState::Phase::Saturated);
+  }
+}
+
 } // namespace Server
 } // namespace Envoy
diff --git a/source/server/worker_impl.h b/source/server/worker_impl.h
@@ -74,6 +74,8 @@ class WorkerImpl : public Worker, Logger::Loggable<Logger::Id::main> {
   void stopAcceptingConnectionsCb(OverloadActionState state);
   void rejectIncomingConnectionsCb(OverloadActionState state);
   void resetStreamsUsingExcessiveMemory(OverloadActionState state);
+  void closeIdleHttpConnectionsCb(OverloadActionState::Phase phase);
+  void maybeCloseIdleHttpConnections();
 
   ThreadLocal::Instance& tls_;
   ListenerHooks& hooks_;
@@ -83,6 +85,9 @@ class WorkerImpl : public Worker, Logger::Loggable<Logger::Id::main> {
   Stats::Counter& reset_streams_counter_;
   Thread::ThreadPtr thread_;
   WatchDogSharedPtr watch_dog_;
+  Event::TimerPtr close_idle_connection_timer_;
+  OverloadActionState::Phase close_idle_http_connections_state_ =
+      OverloadActionState::Phase::Inactive;
 };
 
 } // namespace Server
diff --git a/test/integration/overload_integration_test.cc b/test/integration/overload_integration_test.cc
@@ -298,6 +298,63 @@ TEST_P(OverloadIntegrationTest, BypassOverloadManagerTest) {
   codec_client_->close();
 }
 
+// TODO: add another test for HTTP2
+TEST_P(OverloadIntegrationTest, CloseIdleQuicConnectionsWhenOverloaded) {
+  if (downstreamProtocol() != Http::CodecType::HTTP3) {
+    return; // only relevant for HTTP/3
+  }
+
+  initializeOverloadManager(
+      TestUtility::parseYaml<envoy::config::overload::v3::OverloadAction>(R"EOF(
+      name: "envoy.overload_actions.close_idle_http_connections"
+      triggers:
+        - name: "envoy.resource_monitors.testonly.fake_resource_monitor"
+          scaled:
+            scaling_threshold: 0.8
+            saturation_threshold: 0.9
+    )EOF"));
+
+  // 1. Establish a QUIC connection
+  codec_client_ = makeHttpConnection(makeClientConnection((lookupPort("http"))));
+  // Wait for the connection to be fully established.
+  test_server_->waitForCounterGe("http.config_test.downstream_cx_http3_total", 1);
+
+  // 2. Send a request and wait for the response to complete.
+  Http::TestRequestHeaderMapImpl request_headers{{":method", "GET"},
+                                                 {":path", "/test/long/url"},
+                                                 {":scheme", "http"},
+                                                 {":authority", "sni.lyft.com"}};
+  auto response = sendRequestAndWaitForResponse(request_headers, 0, default_response_headers_, 0);
+  EXPECT_TRUE(upstream_request_->complete());
+  EXPECT_TRUE(response->complete());
+  EXPECT_EQ("200", response->headers().getStatusValue());
+
+  // At this point, the EnvoyQuicServerSession should have added itself to the
+  // EnvoyQuicDispatcher's idle list.
+
+  // 2. Trigger the overload state
+  updateResource(0.95); // Set pressure to 0.95, above the 0.9 saturation threshold
+  test_server_->waitForGaugeEq("overload.envoy.overload_actions.close_idle_http_connections.active",
+                               1);
+
+  // 3. Advance time to trigger the check_idle_connection_timer (which runs every 100ms).
+  timeSystem().advanceTimeWait(std::chrono::milliseconds(100));
+
+  // 4. Wait for the connection to be closed by the server.
+  ASSERT_TRUE(codec_client_->waitForDisconnect());
+
+  // Check that the close reason was correct (this stat is incremented in
+  // EnvoyQuicDispatcher)
+  test_server_->waitForCounterGe("http.config_test.downstream_cx_destroy", 1);
+
+  codec_client_->close();
+
+  // Deactivate overload state
+  updateResource(0.7);
+  test_server_->waitForGaugeEq("overload.envoy.overload_actions.close_idle_http_connections.active",
+                               0);
+}
+
 class Http2RawFrameOverloadIntegrationTest : public BaseOverloadIntegrationTest,
                                              public Http2RawFrameIntegrationTest,
                                              public testing::Test {
diff --git a/test/mocks/network/mocks.h b/test/mocks/network/mocks.h
diff --git a/test/server/worker_impl_test.cc b/test/server/worker_impl_test.cc

Original file line number	Diff line number	Diff line change
`@@ -215,6 +215,7 @@ void EnvoyQuicDispatcher::updateListenerConfig(Network::ListenerConfig& new_list`
`215`	`215`	`void EnvoyQuicDispatcher::closeIdleQuicConnections(bool is_saturated) {`
`216`	`216`	`// This method is called from the worker thread, triggered by the`
`217`	`217`	`// Overload Manager.`
	`218`	`+ ASSERT(session_idle_list_ != nullptr);`
`218`	`219`	`session_idle_list_->MaybeTerminateIdleSessions(is_saturated);`
`219`	`220`	`}`
`220`	`221`