Skip to content

Document flow-control changes from remote settings #1337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ac1982 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document flow-control changes from remote settings #1337

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/source/advanced-usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,24 @@ blocked. The user should use :meth:`local_flow_control_window
<h2.connection.H2Connection.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 <h2.settings.SettingCodes.INITIAL_WINDOW_SIZE>`.
This produces a :class:`RemoteSettingsChanged
<h2.events.RemoteSettingsChanged>` event, not a :class:`WindowUpdated
<h2.events.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
<h2.connection.H2Connection.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
~~~~~~~~~~~~~~~~~

Expand Down
7 changes: 5 additions & 2 deletions src/h2/events.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down