grpc 1.72.0 → 1.78.1

data/src/core/ext/transport/chttp2/transport/flow_control.cc

@@ -23,20 +23,24 @@
 
 #include <algorithm>
 #include <cmath>
+#include <cstdint>
 #include <ostream>
 #include <string>
 #include <tuple>
 #include <vector>
 
-#include "absl/log/check.h"
-#include "absl/log/log.h"
-#include "absl/strings/str_cat.h"
-#include "absl/strings/str_format.h"
-#include "absl/strings/str_join.h"
 #include "src/core/ext/transport/chttp2/transport/http2_settings.h"
+#include "src/core/ext/transport/chttp2/transport/http2_settings_manager.h"
 #include "src/core/lib/experiments/experiments.h"
 #include "src/core/lib/resource_quota/memory_quota.h"
+#include "src/core/util/grpc_check.h"
 #include "src/core/util/useful.h"
+#include "absl/log/log.h"
+#include "absl/status/status.h"
+#include "absl/strings/str_cat.h"
+#include "absl/strings/str_format.h"
+#include "absl/strings/str_join.h"
+#include "absl/strings/string_view.h"
 
 namespace grpc_core {
 namespace chttp2 {
@@ -95,6 +99,26 @@ std::ostream& operator<<(std::ostream& out, const FlowControlAction& action) {
   return out << action.DebugString();
 }
 
+std::string FlowControlAction::ImmediateUpdateReasons() const {
+  std::string result;
+  if (send_stream_update_ == Urgency::UPDATE_IMMEDIATELY) {
+    absl::StrAppend(&result, "send_stream_update,");
+  }
+  if (send_transport_update_ == Urgency::UPDATE_IMMEDIATELY) {
+    absl::StrAppend(&result, "send_transport_update,");
+  }
+  if (send_initial_window_update_ == Urgency::UPDATE_IMMEDIATELY) {
+    absl::StrAppend(&result, "send_initial_window_update,");
+  }
+  if (send_max_frame_size_update_ == Urgency::UPDATE_IMMEDIATELY) {
+    absl::StrAppend(&result, "send_max_frame_size_update,");
+  }
+  if (preferred_rx_crypto_frame_size_update_ == Urgency::UPDATE_IMMEDIATELY) {
+    absl::StrAppend(&result, "preferred_rx_crypto_frame_size_update,");
+  }
+  return result;
+}
+
 TransportFlowControl::TransportFlowControl(absl::string_view name,
                                            bool enable_bdp_probe,
                                            MemoryOwner* memory_owner)
@@ -332,7 +356,7 @@ void StreamFlowControl::SentUpdate(uint32_t announce) {
   TransportFlowControl::IncomingUpdateContext tfc_upd(tfc_);
   pending_size_ = std::nullopt;
   tfc_upd.UpdateAnnouncedWindowDelta(&announced_window_delta_, announce);
-  CHECK_EQ(DesiredAnnounceSize(), 0u);
+  GRPC_CHECK_EQ(DesiredAnnounceSize(), 0u);
   std::ignore = tfc_upd.MakeAction();
 }
 
@@ -380,9 +404,21 @@ FlowControlAction StreamFlowControl::UpdateAction(FlowControlAction action) {
   return action;
 }
 
+void StreamFlowControl::IncomingUpdateContext::HackIncrementPendingSize(
+    int64_t pending_size) {
+  GRPC_CHECK_GE(pending_size, 0);
+  if (sfc_->pending_size_.has_value()) {
+    int64_t final_size = Clamp(sfc_->pending_size_.value() + pending_size,
+                               int64_t{0}, kMaxWindowUpdateSize);
+    *sfc_->pending_size_ = final_size;
+  } else {
+    sfc_->pending_size_ = pending_size;
+  }
+}
+
 void StreamFlowControl::IncomingUpdateContext::SetPendingSize(
     int64_t pending_size) {
-  CHECK_GE(pending_size, 0);
+  GRPC_CHECK_GE(pending_size, 0);
   sfc_->pending_size_ = pending_size;
 }
 

data/src/core/ext/transport/chttp2/transport/flow_control.h

@@ -23,26 +23,25 @@
 #include <limits.h>
 #include <stdint.h>
 
+#include <algorithm>
 #include <iosfwd>
 #include <optional>
 #include <string>
 #include <utility>
 
-#include "absl/functional/function_ref.h"
-#include "absl/log/check.h"
-#include "absl/status/status.h"
-#include "absl/strings/string_view.h"
+#include "src/core/channelz/property_list.h"
 #include "src/core/ext/transport/chttp2/transport/http2_settings.h"
+#include "src/core/ext/transport/chttp2/transport/http2_settings_manager.h"
 #include "src/core/lib/debug/trace.h"
 #include "src/core/lib/resource_quota/memory_quota.h"
 #include "src/core/lib/transport/bdp_estimator.h"
+#include "src/core/util/grpc_check.h"
 #include "src/core/util/time.h"
-
-namespace grpc {
-namespace testing {
-class TrickledCHTTP2;  // to make this a friend
-}  // namespace testing
-}  // namespace grpc
+#include "absl/functional/function_ref.h"
+#include "absl/log/log.h"
+#include "absl/status/status.h"
+#include "absl/strings/str_cat.h"
+#include "absl/strings/string_view.h"
 
 namespace grpc_core {
 namespace chttp2 {
@@ -57,15 +56,18 @@ static constexpr const uint32_t kMaxInitialWindowSize = (1u << 30);
 static constexpr const int64_t kMaxWindowDelta = (1u << 20);
 static constexpr const int kDefaultPreferredRxCryptoFrameSize = INT_MAX;
 
-// TODO(ctiller): clean up when flow_control_fixes is enabled by default
-static constexpr uint32_t kFrameSize = 1024 * 1024;
-static constexpr const uint32_t kMinInitialWindowSize = 128;
+// TODO(tjagtap) [PH2][P2][BDP] Remove this static sleep when the BDP code is
+// done. This needs to be dynamic.
+constexpr Duration kFlowControlPeriodicUpdateTimer = Duration::Seconds(8);
 
 class TransportFlowControl;
 class StreamFlowControl;
 
 enum class StallEdge { kNoChange, kStalled, kUnstalled };
 
+#define GRPC_HTTP2_FLOW_CONTROL_DLOG \
+  DLOG_IF(INFO, GRPC_TRACE_FLAG_ENABLED(http2_ph2_transport))
+
 // Encapsulates a collections of actions the transport needs to take with
 // regard to flow control. Each action comes with urgencies that tell the
 // transport how quickly the action must take place.
@@ -74,10 +76,10 @@ class GRPC_MUST_USE_RESULT FlowControlAction {
   enum class Urgency : uint8_t {
     // Nothing to be done.
     NO_ACTION_NEEDED = 0,
-    // Initiate a write to update the initial window immediately.
+    // Initiate a write to send updates immediately.
     UPDATE_IMMEDIATELY,
-    // Push the flow control update into a send buffer, to be sent
-    // out the next time a write is initiated.
+    // Queue the flow control update, to be sent out the next time a write is
+    // initiated.
     QUEUE_UPDATE,
   };
 
@@ -92,12 +94,67 @@ class GRPC_MUST_USE_RESULT FlowControlAction {
   Urgency preferred_rx_crypto_frame_size_update() const {
     return preferred_rx_crypto_frame_size_update_;
   }
+
+  // Returns true if any action has UPDATE_IMMEDIATELY urgency.
+  bool AnyUpdateImmediately() const {
+    return send_stream_update_ == Urgency::UPDATE_IMMEDIATELY ||
+           send_transport_update_ == Urgency::UPDATE_IMMEDIATELY ||
+           send_initial_window_update_ == Urgency::UPDATE_IMMEDIATELY ||
+           send_max_frame_size_update_ == Urgency::UPDATE_IMMEDIATELY ||
+           preferred_rx_crypto_frame_size_update_ ==
+               Urgency::UPDATE_IMMEDIATELY;
+  }
+
+  std::string ImmediateUpdateReasons() const;
+
+  // Returns the value of SETTINGS_INITIAL_WINDOW_SIZE that we will send to the
+  // peer.
   uint32_t initial_window_size() const { return initial_window_size_; }
+  // Returns the value of SETTINGS_MAX_FRAME_SIZE that we will send to the peer.
   uint32_t max_frame_size() const { return max_frame_size_; }
+  // Returns the value of GRPC_PREFERRED_RECEIVE_CRYPTO_FRAME_SIZE that we will
+  // send to the peer.
   uint32_t preferred_rx_crypto_frame_size() const {
     return preferred_rx_crypto_frame_size_;
   }
 
+  FlowControlAction& test_only_set_send_initial_window_update(Urgency u,
+                                                              uint32_t update) {
+    return set_send_initial_window_update(u, update);
+  }
+  FlowControlAction& test_only_set_send_max_frame_size_update(Urgency u,
+                                                              uint32_t update) {
+    return set_send_max_frame_size_update(u, update);
+  }
+  FlowControlAction& test_only_set_preferred_rx_crypto_frame_size_update(
+      Urgency u, uint32_t update) {
+    return set_preferred_rx_crypto_frame_size_update(u, update);
+  }
+
+  static const char* UrgencyString(Urgency u);
+  std::string DebugString() const;
+
+  void AssertEmpty() { GRPC_CHECK(*this == FlowControlAction()); }
+
+  bool operator==(const FlowControlAction& other) const {
+    return send_stream_update_ == other.send_stream_update_ &&
+           send_transport_update_ == other.send_transport_update_ &&
+           send_initial_window_update_ == other.send_initial_window_update_ &&
+           send_max_frame_size_update_ == other.send_max_frame_size_update_ &&
+           (send_initial_window_update_ == Urgency::NO_ACTION_NEEDED ||
+            initial_window_size_ == other.initial_window_size_) &&
+           (send_max_frame_size_update_ == Urgency::NO_ACTION_NEEDED ||
+            max_frame_size_ == other.max_frame_size_) &&
+           (preferred_rx_crypto_frame_size_update_ ==
+                Urgency::NO_ACTION_NEEDED ||
+            preferred_rx_crypto_frame_size_ ==
+                other.preferred_rx_crypto_frame_size_);
+  }
+
+ private:
+  friend class StreamFlowControl;
+  friend class TransportFlowControl;
+
   FlowControlAction& set_send_stream_update(Urgency u) {
     send_stream_update_ = u;
     return *this;
@@ -125,27 +182,6 @@ class GRPC_MUST_USE_RESULT FlowControlAction {
     return *this;
   }
 
-  static const char* UrgencyString(Urgency u);
-  std::string DebugString() const;
-
-  void AssertEmpty() { CHECK(*this == FlowControlAction()); }
-
-  bool operator==(const FlowControlAction& other) const {
-    return send_stream_update_ == other.send_stream_update_ &&
-           send_transport_update_ == other.send_transport_update_ &&
-           send_initial_window_update_ == other.send_initial_window_update_ &&
-           send_max_frame_size_update_ == other.send_max_frame_size_update_ &&
-           (send_initial_window_update_ == Urgency::NO_ACTION_NEEDED ||
-            initial_window_size_ == other.initial_window_size_) &&
-           (send_max_frame_size_update_ == Urgency::NO_ACTION_NEEDED ||
-            max_frame_size_ == other.max_frame_size_) &&
-           (preferred_rx_crypto_frame_size_update_ ==
-                Urgency::NO_ACTION_NEEDED ||
-            preferred_rx_crypto_frame_size_ ==
-                other.preferred_rx_crypto_frame_size_);
-  }
-
- private:
   Urgency send_stream_update_ = Urgency::NO_ACTION_NEEDED;
   Urgency send_transport_update_ = Urgency::NO_ACTION_NEEDED;
   Urgency send_initial_window_update_ = Urgency::NO_ACTION_NEEDED;
@@ -161,6 +197,7 @@ std::ostream& operator<<(std::ostream& out, const FlowControlAction& action);
 
 // Implementation of flow control that abides to HTTP/2 spec and attempts
 // to be as performant as possible.
+// This class manages the flow control at a connection level.
 class TransportFlowControl final {
  public:
   explicit TransportFlowControl(absl::string_view name, bool enable_bdp_probe,
@@ -169,16 +206,19 @@ class TransportFlowControl final {
 
   bool bdp_probe() const { return enable_bdp_probe_; }
 
-  // returns an announce if we should send a transport update to our peer,
-  // else returns zero; writing_anyway indicates if a write would happen
+  // Returns a non-zero announce if we should send a transport update to our
+  // peer, else returns zero; writing_anyway indicates if a write would happen
   // regardless of the send - if it is false and this function returns non-zero,
-  // this announce will cause a write to occur
+  // the caller can send a flow control update.
   uint32_t DesiredAnnounceSize(bool writing_anyway) const;
-  // notify that we've actually sent a stream window update
-  // (should be DesiredAnnounceSize())
+
+  // Call to update transport flow control state after sending a transport
+  // WINDOW_UPDATE with `announce` size. `announce` should be value returned
+  // by `DesiredAnnounceSize`.
   void SentUpdate(uint32_t announce);
 
-  // Older API: combines getting the DesiredAnnounceSize() with SentUpdate()
+  // Convenience method that combines `DesiredAnnounceSize` and `SentUpdate`.
+  // Call to get window increment and update state in one go.
   uint32_t MaybeSendUpdate(bool writing_anyway) {
     uint32_t n = DesiredAnnounceSize(writing_anyway);
     SentUpdate(n);
@@ -186,28 +226,41 @@ class TransportFlowControl final {
   }
 
   // Track an update to the incoming flow control counters - that is how many
-  // tokens we report to our peer that we're willing to accept.
-  // Instantiators *must* call MakeAction before destruction of this value.
+  // tokens we report to our peer for the data that we are willing to accept.
+  // Instantiators *must* call MakeAction before destruction of this object.
   class IncomingUpdateContext {
    public:
     explicit IncomingUpdateContext(TransportFlowControl* tfc) : tfc_(tfc) {}
-    ~IncomingUpdateContext() { CHECK_EQ(tfc_, nullptr); }
+    ~IncomingUpdateContext() { GRPC_CHECK_EQ(tfc_, nullptr); }
 
     IncomingUpdateContext(const IncomingUpdateContext&) = delete;
     IncomingUpdateContext& operator=(const IncomingUpdateContext&) = delete;
+    IncomingUpdateContext(IncomingUpdateContext&&) = delete;
+    IncomingUpdateContext& operator=(IncomingUpdateContext&&) = delete;
 
     // Reads the flow control data and returns an actionable struct that will
-    // tell chttp2 exactly what it needs to do
+    // tell the transport exactly what it needs to do.
     FlowControlAction MakeAction() {
       return std::exchange(tfc_, nullptr)->UpdateAction(FlowControlAction());
     }
 
-    // Notify of data receipt. Returns OkStatus if the data was accepted,
-    // else an error status if the connection should be closed.
+    // We have received data from the wire.
+    // We check if this data is within our flow control limits or not.
+    // If it exceeds the limit, we send an error.
+    // RFC9113 : A receiver MAY respond with a stream error or connection
+    // error of type FLOW_CONTROL_ERROR if it is unable to accept a frame.
+    //
+    // This function updates transport window for received data.
+    // Call this ONLY IF stream is not available (e.g. already closed) AND
+    // transport window must be updated to remain in sync with peer.
+    // If stream IS available, call RecvData() on
+    // StreamFlowControl::IncomingUpdateContext instead.
     absl::Status RecvData(
         int64_t incoming_frame_size, absl::FunctionRef<absl::Status()> stream =
                                          []() { return absl::OkStatus(); });
 
+   private:
+    friend class StreamFlowControl;
     // Update a stream announce window delta, keeping track of how much total
     // positive delta is present on the transport.
     void UpdateAnnouncedWindowDelta(int64_t* delta, int64_t change) {
@@ -221,7 +274,6 @@ class TransportFlowControl final {
       }
     }
 
-   private:
     TransportFlowControl* tfc_;
   };
 
@@ -230,9 +282,14 @@ class TransportFlowControl final {
   class OutgoingUpdateContext {
    public:
     explicit OutgoingUpdateContext(TransportFlowControl* tfc) : tfc_(tfc) {}
-    void StreamSentData(int64_t size) { tfc_->remote_window_ -= size; }
 
-    // we have received a WINDOW_UPDATE frame for a transport
+    OutgoingUpdateContext(const OutgoingUpdateContext&) = delete;
+    OutgoingUpdateContext& operator=(const OutgoingUpdateContext&) = delete;
+    OutgoingUpdateContext(OutgoingUpdateContext&&) = delete;
+    OutgoingUpdateContext& operator=(OutgoingUpdateContext&&) = delete;
+
+    // Call this function when a transport-level WINDOW_UPDATE frame is received
+    // from peer to increase remote window.
     void RecvUpdate(uint32_t size) { tfc_->remote_window_ += size; }
 
     // Finish the update and check whether we became stalled or unstalled.
@@ -246,43 +303,50 @@ class TransportFlowControl final {
     }
 
    private:
+    friend class StreamFlowControl;
+    void StreamSentData(int64_t size) { tfc_->remote_window_ -= size; }
+
     TransportFlowControl* tfc_;
     const bool was_stalled_ = tfc_->remote_window_ <= 0;
   };
 
   // Call periodically (at a low-ish rate, 100ms - 10s makes sense)
   // to perform more complex flow control calculations and return an action
-  // to let chttp2 change its parameters
+  // to let the transport change its parameters.
+  // TODO(tjagtap) [PH2][P2] Plumb with PH2 flow control.
   FlowControlAction PeriodicUpdate();
 
-  int64_t target_window() const;
-  int64_t target_frame_size() const { return target_frame_size_; }
-  int64_t target_preferred_rx_crypto_frame_size() const {
-    return target_preferred_rx_crypto_frame_size_;
+  int64_t test_only_target_window() const { return target_window(); }
+  int64_t test_only_target_frame_size() const { return target_frame_size(); }
+  int64_t test_only_target_preferred_rx_crypto_frame_size() const {
+    return target_preferred_rx_crypto_frame_size();
   }
 
   BdpEstimator* bdp_estimator() { return &bdp_estimator_; }
 
-  uint32_t acked_init_window() const { return acked_init_window_; }
-  uint32_t queued_init_window() const { return target_initial_window_size_; }
-  uint32_t sent_init_window() const { return sent_init_window_; }
+  uint32_t test_only_acked_init_window() const { return acked_init_window(); }
+  uint32_t test_only_sent_init_window() const { return sent_init_window(); }
 
+  // Call after you prepare and queue a settings frame to send to the peer.
   void FlushedSettings() { sent_init_window_ = queued_init_window(); }
 
+  // Updates the initial window size that we have acknowledged from the peer.
+  // This affects stream-level flow control for data received from the peer.
+  // If the new value differs from target_initial_window_size_, we return an
+  // action to send an update to the peer with our target.
   FlowControlAction SetAckedInitialWindow(uint32_t value);
 
+  void set_target_initial_window_size(uint32_t value) {
+    target_initial_window_size_ =
+        std::min(value, Http2Settings::max_initial_window_size());
+  }
+
   // Getters
   int64_t remote_window() const { return remote_window_; }
-  int64_t announced_window() const { return announced_window_; }
+  int64_t test_only_announced_window() const { return announced_window(); }
 
-  int64_t announced_stream_total_over_incoming_window() const {
-    return announced_stream_total_over_incoming_window_;
-  }
-
-  void RemoveAnnouncedWindowDelta(int64_t delta) {
-    if (delta > 0) {
-      announced_stream_total_over_incoming_window_ -= delta;
-    }
+  int64_t test_only_announced_stream_total_over_incoming_window() const {
+    return announced_stream_total_over_incoming_window();
   }
 
   // A snapshot of the flow control stats to export.
@@ -302,6 +366,23 @@ class TransportFlowControl final {
     double bdp_bw_est;
 
     std::string ToString() const;
+    channelz::PropertyList ChannelzProperties() const {
+      return channelz::PropertyList()
+          .Set("target_window", target_window)
+          .Set("target_frame_size", target_frame_size)
+          .Set("target_preferred_rx_crypto_frame_size",
+               target_preferred_rx_crypto_frame_size)
+          .Set("acked_init_window", acked_init_window)
+          .Set("queued_init_window", queued_init_window)
+          .Set("sent_init_window", sent_init_window)
+          .Set("remote_window", remote_window)
+          .Set("announced_window", announced_window)
+          .Set("announced_stream_total_over_incoming_window",
+               announced_stream_total_over_incoming_window)
+          .Set("bdp_accumulator", bdp_accumulator)
+          .Set("bdp_estimate", bdp_estimate)
+          .Set("bdp_bw_est", bdp_bw_est);
+    }
   };
 
   Stats stats() const {
@@ -324,7 +405,28 @@ class TransportFlowControl final {
   }
 
  private:
+  friend class StreamFlowControl;
+
+  void RemoveAnnouncedWindowDelta(int64_t delta) {
+    if (delta > 0) {
+      announced_stream_total_over_incoming_window_ -= delta;
+    }
+  }
+
   double TargetInitialWindowSizeBasedOnMemoryPressureAndBdp() const;
+  int64_t target_window() const;
+  int64_t target_frame_size() const { return target_frame_size_; }
+  int64_t target_preferred_rx_crypto_frame_size() const {
+    return target_preferred_rx_crypto_frame_size_;
+  }
+  uint32_t acked_init_window() const { return acked_init_window_; }
+  uint32_t queued_init_window() const { return target_initial_window_size_; }
+  uint32_t sent_init_window() const { return sent_init_window_; }
+  int64_t announced_window() const { return announced_window_; }
+  int64_t announced_stream_total_over_incoming_window() const {
+    return announced_stream_total_over_incoming_window_;
+  }
+
   static void UpdateSetting(absl::string_view name, int64_t* desired_value,
                             uint32_t new_desired_value,
                             FlowControlAction* action,
@@ -378,20 +480,50 @@ class StreamFlowControl final {
     explicit IncomingUpdateContext(StreamFlowControl* sfc)
         : tfc_upd_(sfc->tfc_), sfc_(sfc) {}
 
+    IncomingUpdateContext(const IncomingUpdateContext&) = delete;
+    IncomingUpdateContext& operator=(const IncomingUpdateContext&) = delete;
+    IncomingUpdateContext(IncomingUpdateContext&&) = delete;
+    IncomingUpdateContext& operator=(IncomingUpdateContext&&) = delete;
+
     FlowControlAction MakeAction() {
       return sfc_->UpdateAction(tfc_upd_.MakeAction());
     }
 
-    // we have received data from the wire
+    // We have received data from the wire.
+    // We check if this data is within our flow control limits or not.
+    // If it exceeds the limit, we send an error.
+    // RFC9113 : A receiver MAY respond with a stream error or connection
+    // error of type FLOW_CONTROL_ERROR if it is unable to accept a frame.
+    //
+    // Updates stream and transport window for received data on an active
+    // stream. Calling this updates BOTH windows; do not call
+    // TransportFlowControl::IncomingUpdateContext::RecvData() separately.
     absl::Status RecvData(int64_t incoming_frame_size);
 
-    // the application is asking for a certain amount of bytes
+    // Informs flow control that the application needs at least
+    // `min_progress_size` bytes to make progress on reading the current stream.
+    // An example usage of this would be, say we receive the first 1000 bytes of
+    // a 2000 byte gRPC message, we can call SetMinProgressSize(1000)
+    // TODO(tjagtap) [PH2][P2] Plumb with PH2 flow control.
     void SetMinProgressSize(int64_t min_progress_size) {
       sfc_->min_progress_size_ = min_progress_size;
     }
 
+    // Informs flow control that `pending_size` bytes are buffered and waiting
+    // for application to read. Call this when a complete message is assembled
+    // but not yet pulled by the application. This helps flow control decide
+    // whether to send a WINDOW_UPDATE to the peer.
+    // TODO(tjagtap) [PH2][P1] Plumb with PH2 flow control.
     void SetPendingSize(int64_t pending_size);
 
+    // This is a hack in place till SetPendingSize is fully plumbed. This hack
+    // function just pretends that the application needs more bytes. Since we
+    // dont actually know how many bytes the application needs, we just want to
+    // refill the used up tokens. The only way to refill used up tokens is to
+    // call this function for each DATA frame.
+    // TODO(tjagtap) [PH2][P1] Remove hack after SetPendingSize is plumbed.
+    void HackIncrementPendingSize(int64_t pending_size);
+
    private:
     TransportFlowControl::IncomingUpdateContext tfc_upd_;
     StreamFlowControl* const sfc_;
@@ -403,10 +535,18 @@ class StreamFlowControl final {
    public:
     explicit OutgoingUpdateContext(StreamFlowControl* sfc)
         : tfc_upd_(sfc->tfc_), sfc_(sfc) {}
-    // we have received a WINDOW_UPDATE frame for a stream
+
+    OutgoingUpdateContext(const OutgoingUpdateContext&) = delete;
+    OutgoingUpdateContext& operator=(const OutgoingUpdateContext&) = delete;
+    OutgoingUpdateContext(OutgoingUpdateContext&&) = delete;
+    OutgoingUpdateContext& operator=(OutgoingUpdateContext&&) = delete;
+
+    // Call this when a WINDOW_UPDATE frame is received from peer for this
+    // stream, to increase send window.
     void RecvUpdate(uint32_t size) { sfc_->remote_window_delta_ += size; }
-    // we have sent data on the wire, we must track this in our bookkeeping for
-    // the remote peer's flow control.
+
+    // Call this after sending a DATA frame for this stream, to decrease send
+    // window based on `outgoing_frame_size`.
     void SentData(int64_t outgoing_frame_size) {
       tfc_upd_.StreamSentData(outgoing_frame_size);
       sfc_->remote_window_delta_ -= outgoing_frame_size;
@@ -417,14 +557,17 @@ class StreamFlowControl final {
     StreamFlowControl* const sfc_;
   };
 
-  // returns an announce if we should send a stream update to our peer, else
-  // returns zero
+  // Returns a non-zero announce if we should send a stream update to our
+  // peer, else returns zero;
   uint32_t DesiredAnnounceSize() const;
-  // notify that we've actually sent a stream window update
-  // (should be DesiredAnnounceSize())
+
+  // Call after sending stream-level WINDOW_UPDATE to peer to update internal
+  // state. Argument should be value previously returned by
+  // `DesiredAnnounceSize`.
   void SentUpdate(uint32_t announce);
 
-  // Older API: combines getting the DesiredAnnounceSize() with SentUpdate()
+  // Convenience method that combines `DesiredAnnounceSize` and `SentUpdate`.
+  // Call to get window increment and update state in one go.
   uint32_t MaybeSendUpdate() {
     uint32_t n = DesiredAnnounceSize();
     SentUpdate(n);
@@ -432,8 +575,10 @@ class StreamFlowControl final {
   }
 
   int64_t remote_window_delta() const { return remote_window_delta_; }
-  int64_t announced_window_delta() const { return announced_window_delta_; }
-  int64_t min_progress_size() const { return min_progress_size_; }
+  int64_t test_only_announced_window_delta() const {
+    return announced_window_delta_;
+  }
+  int64_t test_only_min_progress_size() const { return min_progress_size_; }
 
   // A snapshot of the flow control stats to export.
   struct Stats {
@@ -447,13 +592,32 @@ class StreamFlowControl final {
 
   Stats stats() const {
     Stats stats;
-    stats.min_progress_size = min_progress_size();
+    stats.min_progress_size = min_progress_size_;
     stats.remote_window_delta = remote_window_delta();
-    stats.announced_window_delta = announced_window_delta();
+    stats.announced_window_delta = announced_window_delta_;
     stats.pending_size = pending_size_;
     return stats;
   }
 
+  void ReportIfStalled(bool is_client, uint32_t stream_id,
+                       const Http2Settings& peer_settings) const {
+    if (remote_window_delta() + peer_settings.initial_window_size() <= 0 ||
+        tfc_->remote_window_ == 0) {
+      GRPC_HTTP2_FLOW_CONTROL_DLOG
+          << "PH2 " << (is_client ? "CLIENT" : "SERVER")
+          << " Flow Control Stalled :"
+          << " Settings { peer initial window size="
+          << peer_settings.initial_window_size()
+          << "}, Transport {remote_window=" << tfc_->remote_window()
+          << ", transport announced_window=" << tfc_->announced_window()
+          << "}, Stream {stream_id=" << stream_id
+          << ", remote_window_delta=" << remote_window_delta()
+          << ", remote_window_delta() + peer_settings.initial_window_size() ="
+          << (remote_window_delta() + peer_settings.initial_window_size())
+          << " }";
+    }
+  }
+
  private:
   TransportFlowControl* const tfc_;
   int64_t min_progress_size_ = 0;