Skip to content

fix(http2): dispatch requests before SETTINGS up to the recommended 100 - #6203

Open
MIbtehajNasar wants to merge 3 commits into
nodejs:mainfrom
MIbtehajNasar:fix-6202-h2-dispatch-before-settings
Open

MIbtehajNasar wants to merge 3 commits into
nodejs:mainfrom
MIbtehajNasar:fix-6202-h2-dispatch-before-settings

Conversation

@MIbtehajNasar

Copy link
Copy Markdown
Contributor

Fixes #6202

Problem

On a new HTTP/2 connection, undici sends the first request and then holds the rest until it has processed the server's SETTINGS frame. That frame usually arrives within about a millisecond, but if the process is busy right then (for example a server rendering a page), the held requests only leave once it is free. On an already-open connection, requests dispatched together go out together.

This started in 8.2.0 with #5135 (the fix for #5134). Two things held the extra requests until SETTINGS:

  • busy() returned true whenever kRemoteSettings === false && kRunning > 0, allowing only one in-flight request.
  • client[kMaxConcurrentStreams] was unset until SETTINGS arrived, so the dispatch ceiling read as 1.

Fix

Initialize the per-connection stream ceiling to min(maxConcurrentStreams, 100) when the session is created, before SETTINGS arrive, and drop the busy() guard that allowed only one in-flight request until SETTINGS.

This matches the spec and other clients:

  • RFC 9113 §3.4: a client may send frames right after its connection preface.
  • RFC 9113 §6.5.2: SETTINGS_MAX_CONCURRENT_STREAMS has no limit initially, and servers are recommended to allow at least 100.
  • RFC 9113 §8.7: a stream refused with REFUSED_STREAM is safe to retry, which undici already does.
  • Go's client uses an initial limit of 100 until the server's first SETTINGS (x/net/http2: max connections overflow golang/go#39389).

A server that advertises a lower limit (the #5134 case, maxConcurrentStreams: 1) refuses the extra optimistic streams with REFUSED_STREAM; undici retries them once SETTINGS have confirmed the real limit, so they never exceed it. onHttp2RemoteSettings still replaces the optimistic ceiling with the confirmed value, and only falls back to a previously confirmed value (not the optimistic placeholder) on a later SETTINGS frame.

Tests

On a new HTTP/2 connection undici sent the first request and then held
the rest until the server's SETTINGS frame was processed. When the event
loop was busy right after that first request (for example a server
rendering a page), the held requests left only once it freed up, adding
latency that was not present before nodejs#5135.

Initialize the per-connection stream ceiling to min(maxConcurrentStreams,
100) before SETTINGS arrive, as RFC 9113 section 6.5.2 recommends and Go's
client does, and drop the busy() guard that allowed only one in-flight
request until SETTINGS. A server advertising a lower limit refuses the
extra streams with REFUSED_STREAM, which section 8.7 permits retrying and
undici already does.

The existing queue-above-limit test asserted server-side arrival order;
since refused streams are now retried and HTTP/2 gives no cross-stream
ordering guarantee, it asserts on the set of paths instead.

Fixes: nodejs#6202

@mcollina mcollina left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

// limit refuses the extra streams with REFUSED_STREAM, which section 8.7
// permits retrying. onHttp2RemoteSettings replaces this with the confirmed
// limit once SETTINGS arrive.
client[kMaxConcurrentStreams] = Math.min(client[kHTTP2Options].maxConcurrentStreams, 100)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be documented somewhere

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Dispatching a streaming POST before peer SETTINGS can exceed the server’s stream limit and trigger REFUSED_STREAM, causing uploads to fail because their bodies cannot be replayed.

1 open issue
What changed in this PR

This PR addresses #6202 by allowing Undici’s HTTP/2 clients to dispatch multiple requests on a fresh connection before receiving server SETTINGS, reducing startup delays when the event loop is busy.

Changes:

  • Initialize the pre-SETTINGS stream ceiling to the configured limit capped at 100, and remove the single-request gate.
  • Replace the optimistic ceiling with the server-confirmed limit when SETTINGS arrive.
  • Add a worker-thread timing regression test and make the existing low-limit test independent of request arrival order.
File Description
test/​h2c-client.js Adds fresh-connection timing coverage and adjusts low-limit path assertions.
lib/​dispatcher/​client-h2.js Enables optimistic dispatch and distinguishes initial from confirmed stream limits.

Review effort: Balanced

* @param {import('../core/request.js')} request
* @returns {boolean}
*/
busy (request) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems relevant

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, addressed in 1cd9723: before SETTINGS, a request whose body can't be replayed (or that was already retried once) now waits while another request is in flight, so a REFUSED_STREAM can't fail it. The new "Should not dispatch a non-replayable body before SETTINGS while a request is running" test covers a streaming POST against maxConcurrentStreams: 1 and fails without the change.

…INGS

Before the server's SETTINGS arrive, a request dispatched alongside a
running one may be refused with REFUSED_STREAM by a server with a lower
limit, and is only retried if its body can be replayed and it hasn't been
retried already. Keep such requests waiting for SETTINGS while another
request is running, and keep reporting the client busy to a Pool while it
has queued work, so the pool's backpressure is unchanged before SETTINGS.

Document the pre-SETTINGS behavior of maxConcurrentStreams.
@MIbtehajNasar

Copy link
Copy Markdown
Contributor Author

Thanks! Pushed an update:

  • Documented the pre-SETTINGS behavior under maxConcurrentStreams in Client.md and H2CClient.md.
  • Requests whose body can't be replayed (or that were already retried once) now wait for SETTINGS while another request is in flight, so a REFUSED_STREAM from a lower server limit can't fail them. Added a test with a streaming POST against maxConcurrentStreams: 1.
  • The client keeps reporting busy to a Pool while it has queued work before SETTINGS, which fixes the http2-pool-saturation failures after merging main.

@codecov-commenter

codecov-commenter commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.15385% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.72%. Comparing base (322a7ee) to head (1cd9723).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
lib/dispatcher/client-h2.js 96.15% 1 Missing ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##             main    #6203   +/-   ##
=======================================
  Coverage   91.72%   91.72%           
=======================================
  Files         113      113           
  Lines       44835    44858   +23     
=======================================
+ Hits        41124    41148   +24     
+ Misses       3711     3710    -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This branch has not been deployed

No deployments
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.

HTTP/2: requests dispatched together on a new connection are held until the server's SETTINGS frame is read

4 participants