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 generic ClientPool<T> 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<T>: most-full-first packing, idle GC, failure retirement, awaitable graceful terminate()
Http2Client: pools per host:port, caps concurrent handshakes globally, multi-host safe (e.g. as googleapis_auth's baseClient)
Retries once when a pooled connection was closed by the peer before reuse
Added unit tests for ClientPool and integration tests for Http2Client covering multi-host pooling, connection-cap dialing, graceful terminate, and the peer-close retry

…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.

brianquinlan · 2026-08-03T23:01:43Z

+/// networks - do not use it to accept arbitrary certificates in production.
+class Http2Client extends BaseClient {
+  Http2Client({
+    this.maxStreamsPerConnection = 100,


Should this default to SETTINGS_MAX_CONCURRENT_STREAMS send by the server?

yes, this should read SETTINGS_MAX_CONCURRENT_STREAMS returned from the server. i'll make that change now

_settingsHandler.peerSettings.maxConcurrentStreams isn't exposed in the public API as of now. So I'll need to add a getter e.g. peerMaxConcurrentStreams on ClientTransportConnection which can then be used in Http2Client.

Kept the getter on ClientConnection rather than ClientTransportConnection

…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

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:18:59Z

+///
+/// Capacity is [maxConcurrentOperations], lowered to whatever limit a
+/// resource reports for itself via `concurrencyLimitOf`.
+class ClientPool<T> {


Would it be more clear if these were not generic? Isn't the type always going to be ClientConnection for all of these T arguments.

Oh, did you do this to make the tests easier to write?

yes that's correct, we could also just use MockClientConnection through mockito.

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.

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

+
+    while (true) {
+      final pooled = _acquire();
+      pooled.inFlight++;


Do you need to decrement this if you call _release without using it?

brianquinlan · 2026-08-06T21:00:20Z

+  /// A request counts as in-flight until its response body ends or is
+  /// cancelled, so a caller holding a response it never reads will hold this
+  /// up. [close] does not await this, so it can never block on that.
+  Future<void> terminate() async {


Can we just make this part of close for now? I think that we need a general solution for async close?

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.

brianquinlan · 2026-08-06T21:10:58Z

+    }
+
+    final died = Completer<void>();
+    final incoming = socket.transform(


Could you add a comment explaining why we need this?

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

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 3 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

updates

39b75f9

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

		@@ -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!

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

demolaf commented Jul 30, 2026 •

edited

Loading