Expose network backends as part of the public API.

[lovelydinosaur]

We should add a Network Backends section to our documentation, which documents our supported network backends.

The sort of functionality that this would allow for includes...

• Network recording / replay.
• In-depth debug tooling.
• Network mocking.
• Custom network behaviour such as handling non-standard SSL or DNS requirements.

For example...

import httpcore
from httpcore.backends.base import NetworkBackend, NetworkStream
from httpcore.backends.sync import SyncBackend


class RecordingNetworkStream(NetworkStream):
    def __init__(self, record_file, stream):
        self.record_file = record_file
        self.stream = stream

    def read(self, max_bytes, timeout=None):
        data = self.stream.read(max_bytes, timeout=timeout)
        self.record_file.write(data)
        return data

    def write(self, buffer, timeout=None):
        self.stream.write(buffer, timeout=timeout)

    def close(self) -> None:
        self.stream.close()

    def start_tls(
        self,
        ssl_context,
        server_hostname=None,
        timeout=None,
    ):
        self.stream = self.stream.start_tls(
            ssl_context, server_hostname=server_hostname, timeout=timeout
        )
        return self

    def get_extra_info(self, info):
        return self.stream.get_extra_info(info)


class RecordingNetworkBackend(NetworkBackend):
    def __init__(self, record_file):
        self.record_file = record_file
        self.backend = SyncBackend()

    def connect_tcp(
        self,
        host,
        port,
        timeout=None,
        local_address=None,
    ) -> NetworkStream:
        stream = self.backend.connect_tcp(
            host, port, timeout=timeout, local_address=local_address
        )
        return RecordingNetworkStream(self.record_file, stream)

    def connect_unix_socket(self, path, timeout=None) -> NetworkStream:
        stream = self.backend.connect_unix_socket(path, timeout=timeout)
        return RecordingNetworkStream(self.record_file, stream)

    def sleep(self, seconds: float) -> None:
        self.backend.sleep(seconds)


with open("network-recording", "wb") as record_file:
    network_backend = RecordingNetworkBackend(record_file)
    with httpcore.ConnectionPool(network_backend=network_backend) as http:
        http.request("GET", "https://www.example.com/")

My expectation is that documenting the network backends as public API would also push us towards a few minor naming/API changes.

Other potential benefits of exposing this API publicly...

• Helping developers understand how httpcore is designed.
• Exposes a set of sync/asyncio/trio network primitives, available to other packages that want to support sync+async network operations.