feat(http2): add a pooled, multiplexed HTTP/2 http.Client by demolaf · Pull Request #1956 · dart-lang/http

demolaf · 2026-07-30T09:43:20Z

Adds Http2Client, a pooled, multiplexed http.Client backed by HTTP/2 connections, plus the ClientPool it's built on — fixes dart:io's HttpClient opening one connection per concurrent request. Ported and generalized from a downstream implementation built for firebase/firebase-admin-dart#305.

ClientPool: most-full-first packing, idle GC, failure retirement, and a lease API so a slot can outlive the call that claimed it
Http2Client: pools per host:port, caps concurrent handshakes globally, multi-host safe (e.g. as googleapis_auth's baseClient)
Never opens more concurrent streams on a connection than the server's SETTINGS_MAX_CONCURRENT_STREAMS allows, and doesn't use a connection at all until that frame has arrived — see Http2Client.settingsTimeout
A request holds its pool slot until the response body ends or is cancelled, so the pool's view matches the number of streams actually open
Retries once when a pooled connection was closed by the peer before reuse
Adds ClientTransportConnection.peerMaxConcurrentStreams. This is a new member on an implementable class, hence the minor version bump

…ecific headers

…fter terminate()

brianquinlan

I'll have more review feedback tomorrow. Also, this PR adds (preliminary) conformance tests: #1960

You might want to add them to this PR.

…xConcurrentStreams

…nknown

demolaf · 2026-08-06T14:12:04Z

@brianquinlan @mosuem I'm deferring the TODOs in the conformance tests to a later PR since this is already quite a lot, sounds good?

brianquinlan · 2026-08-06T17:58:46Z

@@ -0,0 +1,34 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file


Let's make this example more useful for the user. Maybe copy the example from package:cupertino_http or something.

okay, i'll look into this

I added an example showing 100 concurrent requests but it's not really a great example since http/1.1 can handle that faster (if uncapped). The only notable difference would be memory usage since http/1.1 would open TCP+TLS connections per request.

brianquinlan · 2026-08-06T18:02:04Z

+/// `true` accepts a certificate that failed normal verification (expired,
+/// self-signed, wrong host, ...). It exists for tests and trusted private
+/// networks - do not use it to accept arbitrary certificates in production.
+class Http2Client extends BaseClient {


Maybe marks this experimental for now:
https://api.flutter.dev/flutter/meta/experimental-constant.html

that makes sense to do since we still have more pending feature work to do per the conformance tests

brianquinlan · 2026-08-06T18:07:13Z

+
+    List<int>? bodyBytes;
+
+    Future<StreamedResponse> attempt() async {


This is awkward to read. Do we need to define this function, which is only used once?

yeah i agree, it's actually used twice, the initial attempt and then in the .catchError block.

brianquinlan · 2026-08-06T18:30:33Z

+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+


Maybe provide an example on how to use this library. But I like the approach.

brianquinlan · 2026-08-06T20:39:28Z

+
+class _PooledResource<T> {
+  _PooledResource(this.future);
+  final Future<T> future;


I think that these need to be better named/documented:
future refers to the creation of the resource, right?
inFlight refers to the number of concurrent requests of the resource, right?
failed indicates that creating the resource failed, right?

Maybe:
create
inFlightCount
createFailed

And a comment?

This would be more clear if T were ClientConnection but maybe the tests would then be too hard to write.

done, renamed all three. also dropped the generic — ClientPool is ClientConnection-specific now, and the pool tests use a generated MockClientConnection.

brianquinlan · 2026-08-06T21:04:12Z

+  /// its most recent SETTINGS_MAX_CONCURRENT_STREAMS (RFC 7540 6.5.2), or
+  /// `null` if it hasn't advertised a limit.
+  ///
+  /// Deliberately not on [ClientTransportConnection]: that class can only be


@mosuem maybe we should add it there anyway - there are no "implements ClientTransportConnection" on GitHub but we could also bump semver.

Yes, just add it there and bump semver.

done — moved it to ClientTransportConnection and bumped to 3.1.0-wip

…tion

…n a generic one

demolaf added 2 commits July 30, 2026 08:57

feat(http2): add generic ClientPool<T> with unit tests

0b1021f

feat(http2): add Http2Client, a pooled multiplexed http.Client

1e7e56e

demolaf marked this pull request as draft July 30, 2026 09:43

github-actions Bot added the package:http2 label Jul 30, 2026

demolaf added 3 commits July 30, 2026 11:11

feat(http2): expose Http2Client via package:http2/client.dart

894b94c

chore(http2): changelog entry for Http2Client

4a874cb

fix(http2): retry once when a pooled connection was closed by the peer

258830f

demolaf mentioned this pull request Jul 30, 2026

Add a http.Client compatible client #1385

Open

demolaf marked this pull request as ready for review July 30, 2026 13:14

mosuem reviewed Aug 3, 2026

View reviewed changes

demolaf added 4 commits August 3, 2026 17:08

fix(http2): default empty :path to / and strip HTTP/1.x connection-sp…

2c8ae6c

…ecific headers

fix(http2): throw ClientException instead of an internal pool error a…

2376148

…fter terminate()

fix(http2): exclude failed resources from idle-capacity calculation

6955e30

chore(http2): mark ClientPool.opCount @VisibleForTesting

5d1a7f4

brianquinlan reviewed Aug 3, 2026

View reviewed changes

Comment thread pkgs/http2/lib/src/http2_client.dart

demolaf added 15 commits August 4, 2026 10:17

docs(http2): ClientPool.size is used by production code, not just tests

059cf76

refactor(http2): use collection's .sum instead of manual fold sums

84c0d66

style(http2): use braces for single-statement ifs in _sendOverHttp2

0ca6c5c

style(http2): use a case pattern for _maybeCompleteDrain's null check

3279971

test(http2): drop redundant comment on self-signed test cert bypass

659e447

feat(http2): expose peer's SETTINGS_MAX_CONCURRENT_STREAMS via peerMa…

33631c7

…xConcurrentStreams

test(http2): add client conformance tests for Http2Client

168d1e9

fix(http2): cap streams per connection by the server's advertised limit

832cae0

fix(http2): correct response translation and error types in Http2Client

d8d0ba7

fix(http2): make ClientPool.terminate idempotent and snapshot-safe

a47fe1b

fix(http2): don't couple an operation to its resource's teardown

bf3dfb4

feat(http2): give ClientPool an explicit lease API

5e0b38d

fix(http2): hold a pool slot until the response body completes

0ae4a17

fix(http2): don't multiplex onto a connection whose stream limit is u…

a1fef44

…nknown

docs(http2): record the pooling behaviour changes and known isOpen race

92987b6

demolaf added 2 commits August 5, 2026 20:53

style(http2): drop explanatory inline comments

ff10a97

refactor(http2): keep the peer stream limit off the public transport API

7557351

demolaf force-pushed the pooled-http2-client branch from e8b8590 to 39b75f9 Compare August 6, 2026 14:08

brianquinlan reviewed Aug 6, 2026

View reviewed changes

demolaf added 7 commits August 14, 2026 18:17

docs(http2): trim the Http2Client changelog entry

f1df1fe

refactor(http2): make the pool's slot ownership readable

852bb3d

docs(http2): document the pool's API and the SETTINGS wait

1ff257c

feat(http2): expose peerMaxConcurrentStreams on ClientTransportConnec…

4d52e5c

…tion

refactor(http2): fold terminate into close

c2b72e5

docs(http2): make the example demonstrate concurrent multiplexing

e369fd2

refactor(http2): name and document the pool's resource fields

af53e7f

demolaf force-pushed the pooled-http2-client branch from 90b0813 to af53e7f Compare August 14, 2026 17:25

refactor(http2): make ClientPool an HTTP/2 connection pool rather tha…

a05fb28

…n a generic one

demolaf force-pushed the pooled-http2-client branch from a5cea15 to a05fb28 Compare August 14, 2026 18:30

demolaf requested review from brianquinlan and mosuem August 18, 2026 10:17

		@@ -0,0 +1,34 @@
		// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file


		List<int>? bodyBytes;

		Future<StreamedResponse> attempt() async {

Uh oh!

Conversation

demolaf commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brianquinlan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

demolaf commented Aug 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

demolaf commented Jul 30, 2026 •

edited

Loading