Breaking Change #47887: Add new connectionFactory property to HttpClient

[Brian Quinlan]

Discussion here: https://github.com/dart-lang/sdk/issues/47887

Change

I propose that we add a new connectionFactory property to HttpClient with a signature like:

void connectionFactory=(
  Future<ConnectionTask<Socket>> f(
    Uri url, String? proxyHost, int? proxyPort)?
)

This would allow users to customise socket creation (e.g. for communication with dockerd/snapd over Unix domain sockets). Full details in the design doc.

The non-breaking alternative would be to make connectionFactory an argument to the HttpClient constructor.

Rationale

The HttpClient API already has multiple attributes that accept functions e.g.

void findProxy=(
  String f(Uri url)?)

void badCertificateCallback=(
  bool callback(
    X509Certificate cert,
    String host,
    int port
  )?
)

and implementing this as a constructor argument would be inconsistent with the rest of the API. Also, parameterizing all future functionality as constructor arguments does not seem scalable.

Impact

All classes that implements HttpClient (without extends Mock or equivalent noSuchMethod implementation) will need to be updated.

I suspect that there are not many implementations of HttpClient outside of mocks.

Mitigation

Users must implement the connectionFactory property.