From 46a83d6fce6dbfe819f499e7ef94b6c1e4819992 Mon Sep 17 00:00:00 2001 From: AC Date: Wed, 14 Oct 2026 15:46:52 +0800 Subject: [PATCH] Document flow-control changes from remote settings --- docs/source/advanced-usage.rst | 18 ++++++++++++++++++ src/h2/events.py | 7 +++++-- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/source/advanced-usage.rst b/docs/source/advanced-usage.rst index d238c48b6..18047a139 100644 --- a/docs/source/advanced-usage.rst +++ b/docs/source/advanced-usage.rst @@ -291,6 +291,24 @@ blocked. The user should use :meth:`local_flow_control_window ` to check all blocked streams to see if more data is available. + +A peer can also change stream windows by sending a ``SETTINGS`` frame with a +new :data:`INITIAL_WINDOW_SIZE `. +This produces a :class:`RemoteSettingsChanged +` event, not a :class:`WindowUpdated +` event. If ``INITIAL_WINDOW_SIZE`` appears in the +event's ``changed_settings``, h2 has already adjusted the existing stream +windows by the difference between the old and new setting values. The +connection window is unchanged. + +Applications waiting to send data should therefore also handle this settings +change and recheck :meth:`local_flow_control_window +` for each blocked stream. +An increase can unblock streams, but the connection window may still prevent +sending. A decrease can make a stream's window negative; wait for a positive +available window before sending a non-empty ``DATA`` payload on that stream. +New streams use the new initial window size. + Auto Flow Control ~~~~~~~~~~~~~~~~~ diff --git a/src/h2/events.py b/src/h2/events.py index e3accea76..c1891ff28 100644 --- a/src/h2/events.py +++ b/src/h2/events.py @@ -323,11 +323,14 @@ def __repr__(self) -> str: @dataclass(**kw_only) class WindowUpdated(Event): """ - The WindowUpdated event is fired whenever a flow control window changes - size. HTTP/2 defines flow control windows for connections and streams: this + The WindowUpdated event is fired when a WINDOW_UPDATE frame is received. + HTTP/2 defines flow control windows for connections and streams: this event fires for both connections and streams. The event carries the ID of the stream to which it applies (set to zero if the window update applies to the connection), and the delta in the window size. + + Changes to stream windows caused by SETTINGS_INITIAL_WINDOW_SIZE are + reported by :class:`RemoteSettingsChanged`, not this event. """ stream_id: int