fix(firestore): use pooled HTTP/2 connections by default to fix slow/failing concurrent requests

[demolaf]

Fixes #297.

Dart's Firestore client used dart:io's HttpClient, which only speaks HTTP/1.1 — meaning every concurrent request opened its own TCP+TLS connection. At high concurrency (thousands of simultaneous requests), this caused connection-storm failures (ClientException, HandshakeException) and made Dart significantly slower than Node, whose Firestore client multiplexes many concurrent operations over a small pool of HTTP/2 connections.

This PR makes pooled HTTP/2 the default transport for all production Firestore traffic, with no configuration required:

• New ClientPool<T>, mirroring nodejs-firestore's ClientPool (dev/src/pool.ts): packs load onto the most-full connection under a 100-stream cap (matching Node's default) rather than spreading evenly, opens a new connection once existing ones are full, stops routing new work to a connection once it's shown a connection-level failure, garbage collects idle connections past a configurable threshold, and drains in-flight operations gracefully before shutting down.
• Http2ClientPool wraps ClientPool<ClientTransportConnection> as a plain http.BaseClient; googleapis_auth's existing token-refresh logic wraps it via baseClient:, so credential handling is unchanged.
• The local emulator path stays on plain HTTP/1.1, matching nodejs-firestore's own REST-mode behavior for the emulator (its gRPC mode uses HTTP/2, but this SDK is REST-only, so gRPC's behavior isn't the right comparison).

Benchmark

Concurrency	Run 1	Run 2	Run 3
3000	2438.35ms	1602.67ms	1245.91ms
5000	2460.53ms	2199.92ms	2111.67ms
10000	7195.02ms	1518.93ms	2180.65ms

[gemini-code-assist]

Code Review

This pull request introduces a custom HTTP/2 client pool (Http2ClientPool) to multiplex Firestore requests over shared HTTP/2 connections in production, bringing the Dart SDK closer to the Node.js implementation. While the addition of HTTP/2 support is a great performance improvement, several critical issues were identified in the review: HTTP/2 header keys must be lowercased to prevent protocol errors; the statusCompleter and bodyController must be properly closed on stream completion or error to prevent hanging requests; socket leaks must be avoided by destroying the socket if HTTP/2 negotiation fails; and failed connections must be cleaned up from the pool to prevent memory leaks.

[demolaf]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces HTTP/2 connection pooling by default for the Firestore client to address slow and failing requests under high concurrency. It implements a custom ClientPool and Http2ClientPool to manage and reuse HTTP/2 connections, and adds corresponding unit tests. The reviewer provided several actionable suggestions to improve robustness and performance: linking the cancellation of the response stream to the underlying HTTP/2 stream subscription to prevent resource leaks, wrapping resource cleanup in a try-catch block to handle failures safely, running connection collection unawaited to avoid adding latency to requests, and properly awaiting the termination of the connection pool during client shutdown to prevent hangs.

[gemini-code-assist]

Awaiting _collectIfIdle inside the finally block blocks the completion of the run call (and thus the user's Firestore request) until the idle connection is fully destroyed. Since connection cleanup is a background task, we should run it unawaited to avoid adding unnecessary latency to the user's request.

Suggested change

	if (_terminated) {
	_maybeCompleteDrain();
	} else {
	await _collectIfIdle(pooled);
	}
	if (_terminated) {
	_maybeCompleteDrain();
	} else {
	unawaited(_collectIfIdle(pooled));
	}

[github-actions]

Coverage Report

✅ Coverage 74.86% meets 40% threshold

Total Coverage: 74.86%
Lines Covered: 5254/7018

Package Breakdown

Package	Coverage
firebase_admin_sdk	72.66%
google_cloud_firestore	77.28%

Minimum threshold: 40%

[brianquinlan]

@demolaf

Would it make sense for the Client interface to live in package:http2?

[demolaf]

@brianquinlan this makes sense, do we land this first and open a new issue/PR on dart-lang/http repo or vice versa?

[brianquinlan]

I would love to see a PR on the dart-lang/http repo. I'm going to be out next week so maybe @natebosch can review