Skip to content

Add manual refill of HTTP/2 stream receive windows - #550

Open
ericmj wants to merge 1 commit into
mainfrom
http2-manual-stream-window
Open

ericmj wants to merge 1 commit into
mainfrom
http2-manual-stream-window

Conversation

@ericmj

@ericmj ericmj commented Nov 17, 2026

Copy link
Copy Markdown
Member

Mint refills a stream's receive window as soon as it parses a DATA frame, so a process that owns the connection and hands body chunks to other processes can't slow the server down for one request. Finch's HTTP/2 pool does this: it calls stream/2 and sends {:data, ref, data} to the caller. The reproducer in sneako/finch#282 streams 1 MB chunks to a callback that sleeps for a second per chunk, and the caller's mailbox grows by about 17,000 messages a second. The pool can't stop calling stream/2 without pausing every request on the connection.

With the new stream_window_refill: :manual connect option, Mint holds back the data bytes of each DATA frame from the stream refill until the caller releases them:

{:ok, conn} = Mint.HTTP2.connect(:https, host, 443, stream_window_refill: :manual)

# after handling {:data, ref, data} from stream/2
{:ok, conn} = Mint.HTTP2.refill_window(conn, ref, byte_size(data))

Padding is still refilled right away since the caller never sees it. The connection window keeps refilling on receipt, so a request whose body isn't consumed stops at its stream window (4 MB by default) and the other requests keep going. Released bytes are batched with the existing :receive_window_update_threshold logic. Releasing data for a completed or unknown request is a no-op, so the release for the last chunk can arrive after {:done, ref}. Releasing more than was received returns {:refill_exceeds_received, unreleased, size}.

This also fixes set_window_size/3, which set the remaining window to the new peak instead of adding the increment it sent. Growing a window mid-response made Mint count the bytes received since the last refill as credit the server still had. When that was more than :receive_window_update_threshold (160 KB by default), the server ran out of window while Mint thought it was above the threshold, and the request stalled. Unreleased bytes count as received, so manual mode made this easier to hit.

Finch needs a matching change to use this: the caller sends the released byte count back to the pool process, which calls refill_window/3.

@ericmj
ericmj marked this pull request as ready for review November 17, 2026 14:30
@coveralls

coveralls commented Nov 17, 2026 •

Copy link
Copy Markdown

Coverage Report for CI Build 541

Coverage increased (+0.2%) to 90.41%

Details

  • Coverage increased (+0.2%) from the base build.
  • Patch coverage: 1 uncovered change across 1 file (35 of 36 lines covered, 97.22%).
  • No coverage regressions found.

Uncovered Changes

File Changed Covered %
lib/mint/http2.ex 36 35 97.22%

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 2075
Covered Lines: 1876
Line Coverage: 90.41%
Coverage Strength: 730.85 hits per line

💛 - Coveralls

Mint refills a stream's receive window as soon as it parses a DATA
frame, so a process that owns the connection and hands body chunks to
other processes can't slow the server down for one request. Finch's
HTTP/2 pool does this: it calls stream/2 and sends {:data, ref, data}
to the caller, so a caller that handles chunks slower than the server
sends them gets an unbounded mailbox (sneako/finch#282). Not calling
stream/2 pauses every request on the connection.

With the new stream_window_refill: :manual connect option, Mint holds
back the data bytes of each DATA frame from the stream refill until the
caller releases them with Mint.HTTP2.refill_window/3. Padding is still
refilled right away since the caller never sees it, and the connection
window keeps refilling on receipt, so a stalled request doesn't block
the others. Released bytes are batched with the existing
:receive_window_update_threshold logic. Releasing data for a completed
or unknown request is a no-op, and releasing more than was received
returns a {:refill_exceeds_received, unreleased, size} error.

set_window_size/3 set the remaining window to the new peak instead of
adding the increment it sent, so growing a window mid-response made Mint
count the bytes received since the last refill as credit the server
still had. When that was more than :receive_window_update_threshold
(160 KB by default) the server ran out of window while Mint thought it
was above the threshold, and the request stalled. Unreleased bytes count
as received, so manual mode made this easier to hit.
@ericmj
ericmj force-pushed the http2-manual-stream-window branch from 963c1d2 to 541cc02 Compare November 17, 2026 16:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants