punkreq 0.2.0__tar.gz → 0.2.2__tar.gz

{punkreq-0.2.0 → punkreq-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: punkreq
-Version: 0.2.0
+Version: 0.2.2
 Summary: An async HTTP client built on httpunk
 Project-URL: Homepage, https://github.com/gi0baro/punkreq
 Project-URL: Funding, https://github.com/sponsors/gi0baro
@@ -24,11 +24,11 @@ Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.10
-Requires-Dist: httpunk~=0.2.0
+Requires-Dist: httpunk~=0.4.0
 Provides-Extra: brotli
 Requires-Dist: brotli~=1.2.0; extra == 'brotli'
 Provides-Extra: tonio
-Requires-Dist: tonio~=0.9.12; (python_version >= '3.14') and extra == 'tonio'
+Requires-Dist: tonio~=0.9.16; (python_version >= '3.14') and extra == 'tonio'
 Description-Content-Type: text/markdown
 
 # punkreq

{punkreq-0.2.0 → punkreq-0.2.2}/punkreq/_connect.py

@@ -10,7 +10,7 @@ from httpunk.h2.client import H2Connection
 from ._exceptions import ConnectError, UnsupportedProtocol
 
 
-__all__ = ["Connector", "Origin", "create_ssl_context", "origin_for_url"]
+__all__ = ["Connector", "Origin", "connect_errors", "create_ssl_context", "origin_for_url"]
 
 DEFAULT_PORTS = {"http": 80, "https": 443}
 
@@ -82,6 +82,15 @@ def create_ssl_context(verify: VerifyTypes = True, cert: CertTypes | None = None
     return context
 
 
+def connect_errors(backend: typing.Any) -> tuple[type[BaseException], ...]:
+    """What a dial or a TLS handshake fails with on `backend`: the OS and ssl
+    errors, plus the backend's own transport failure. tonio's `ResourceBroken`
+    is a plain `Exception`, not an `OSError`, and its TLS layer raises it in
+    place of the ssl error, so `(OSError, ssl.SSLError)` alone lets a failed
+    handshake on tonio escape as an unmapped exception."""
+    return (OSError, ssl.SSLError, *backend.broken_transport_errors)
+
+
 class Connector:
     """The default connector: dial `origin` and return the protocol-matching,
     un-entered httpunk connection."""
@@ -100,22 +109,32 @@ class Connector:
         self._ssl_context = ssl_context
         self._http1 = http1
         self._http2 = http2
+        if http1 and http2:
+            self.alpn: tuple[str, ...] = ("h2", "http/1.1")
+        elif http2:
+            self.alpn = ("h2",)
+        else:
+            self.alpn = ("http/1.1",)
+        # The ALPN offer is configured on the context ONCE, here: a context is
+        # shared by every dial that uses it (and by `ProxyConnector`'s CONNECT
+        # tunnels, whose `wrap_tls` takes ALPN from the context alone), so the
+        # dial path never mutates it (hyper-util / httpunk `util.connect`
+        # discipline: a caller-supplied context is never touched per connect).
+        if ssl_context is not None:
+            ssl_context.set_alpn_protocols(list(self.alpn))
 
     async def __call__(self, origin: Origin) -> H1Connection | H2Connection:
         try:
             if origin.scheme == "https":
                 return await self._connect_tls(origin)
             return await self._connect_tcp(origin)
-        except (OSError, ssl.SSLError) as exc:
+        except connect_errors(self._backend) as exc:
             raise ConnectError(f"Failed to connect to {origin}: {exc}")
 
     async def _connect_tls(self, origin: Origin) -> H1Connection | H2Connection:
-        if self._http1 and self._http2:
-            alpn: tuple[str, ...] = ("h2", "http/1.1")
-        elif self._http2:
-            alpn = ("h2",)
-        else:
-            alpn = ("http/1.1",)
+        # our context already carries the offer; a backend-created default one
+        # (no context given) is configured per dial
+        alpn = None if self._ssl_context is not None else self.alpn
         stream, selected = await self._backend.connect_tls(
             origin.host, origin.port, alpn=alpn, ssl_context=self._ssl_context
         )

{punkreq-0.2.0 → punkreq-0.2.2}/punkreq/_proxies.py

@@ -10,7 +10,7 @@ from httpunk.h2.client import H2Connection
 from httpunk.util.proxy import Matcher
 
 from ._config import Proxy
-from ._connect import Connector, Origin
+from ._connect import Connector, Origin, connect_errors
 from ._exceptions import ConnectError, ProxyError
 from ._headers import Headers
 from ._urls import URL
@@ -55,89 +55,6 @@ class ProxyConfig:
         return None
 
 
-class TunnelTLSStream:
-    """TLS over an arbitrary bidirectional stream (the CONNECT tunnel), via
-    `ssl.MemoryBIO`. Presents the httpunk stream interface (`receive_some`,
-    `send_all`, `close`, `read_nowait`) so H1/H2 connections sit on it directly."""
-
-    def __init__(
-        self,
-        inner: typing.Any,
-        context: ssl.SSLContext,
-        *,
-        server_hostname: str,
-        closer: typing.Callable[[], None],
-    ) -> None:
-        self._inner = inner
-        self._incoming = ssl.MemoryBIO()
-        self._outgoing = ssl.MemoryBIO()
-        self._ssl = context.wrap_bio(self._incoming, self._outgoing, server_hostname=server_hostname)
-        self._closer = closer
-        self._closed = False
-
-    async def handshake(self) -> None:
-        while True:
-            try:
-                self._ssl.do_handshake()
-                break
-            except ssl.SSLWantReadError:
-                await self._flush()
-                data = await self._inner.receive_some(65536)
-                if not data:
-                    raise ssl.SSLError("connection closed during TLS handshake")
-                self._incoming.write(data)
-        await self._flush()
-
-    def selected_alpn_protocol(self) -> str | None:
-        return self._ssl.selected_alpn_protocol()
-
-    async def _flush(self) -> None:
-        data = self._outgoing.read()
-        if data:
-            await self._inner.send_all(data)
-
-    async def receive_some(self, max_bytes: int = 65536) -> bytes:
-        while True:
-            try:
-                return self._ssl.read(max_bytes)
-            except ssl.SSLWantReadError:
-                await self._flush()
-                raw = await self._inner.receive_some(65536)
-                if not raw:
-                    return b""  # ragged EOF: treated as end-of-stream
-                self._incoming.write(raw)
-            except ssl.SSLZeroReturnError:
-                return b""
-
-    async def send_all(self, data: bytes) -> None:
-        view = memoryview(data)
-        while view:
-            try:
-                sent = self._ssl.write(view)
-            except ssl.SSLWantReadError:
-                raw = await self._inner.receive_some(65536)
-                if not raw:
-                    raise ssl.SSLError("connection closed during TLS write")
-                self._incoming.write(raw)
-                continue
-            await self._flush()
-            view = view[sent:]
-        await self._flush()
-
-    def read_nowait(self, max_bytes: int = 65536) -> bytes:
-        """Decrypted bytes already buffered in the SSL object, without touching
-        the tunnel (the h1 driver's pre-request unexpected-bytes check)."""
-        try:
-            return self._ssl.read(max_bytes)
-        except (ssl.SSLWantReadError, ssl.SSLZeroReturnError):
-            return b""
-
-    def close(self) -> None:
-        if not self._closed:
-            self._closed = True
-            self._closer()
-
-
 class ProxyConnector:
     """Connector that routes each origin through its matched proxy, delegating
     unmatched origins to the direct `Connector`."""
@@ -156,16 +73,9 @@ class ProxyConnector:
         self._http1 = http1
         self._http2 = http2
         self._config = config
+        # the direct connector configures the ALPN offer on `ssl_context` at
+        # construction; `wrap_tls` (the CONNECT tunnel) takes it from the context
         self._direct = Connector(backend=backend, ssl_context=ssl_context, http1=http1, http2=http2)
-        if http1 and http2:
-            alpn: list[str] = ["h2", "http/1.1"]
-        elif http2:
-            alpn = ["h2"]
-        else:
-            alpn = ["http/1.1"]
-        # wrap_bio takes ALPN from the context; the direct dial path sets the
-        # same list on the same context, so this stays consistent
-        ssl_context.set_alpn_protocols(alpn)
 
     async def __call__(self, origin: Origin) -> typing.Any:
         intercept = self._config.matcher.intercept(f"{origin.scheme}://{origin.authority}/")
@@ -175,7 +85,7 @@ class ProxyConnector:
             if origin.scheme == "http":
                 return await self._absolute_form(origin, intercept)
             return await self._tunnel(origin, intercept)
-        except (OSError, ssl.SSLError) as exc:
+        except connect_errors(self._backend) as exc:
             raise ConnectError(f"Failed to connect to {origin} via proxy {intercept.uri}: {exc}")
 
     async def _dial_proxy(self, intercept: typing.Any) -> typing.Any:
@@ -223,18 +133,21 @@ class ProxyConnector:
             self._backend.close_transport(transport)
             raise
 
-        tls = TunnelTLSStream(
-            tunnel,
-            self._ssl_context,
-            server_hostname=origin.host,
-            closer=lambda: self._backend.close_transport(transport),
-        )
+        # The tunnel's IO, and whatever was read past the CONNECT response (the
+        # start of the origin's TLS conversation), go to the backend's TLS layer
+        # (httpunk >= 0.4.0). On a handshake failure the backend closes the
+        # transport itself before raising; `__call__` maps the error.
+        stream, read_buf = tunnel.downcast()
         try:
-            await tls.handshake()
-        except ssl.SSLError as exc:
-            self._backend.close_transport(transport)
-            raise ConnectError(f"TLS handshake with {origin} through the proxy failed: {exc}")
+            tls, selected = await self._backend.wrap_tls(
+                stream, server_hostname=origin.host, ssl_context=self._ssl_context, prefix=read_buf
+            )
+        except TypeError as exc:
+            # the backend refuses the stream at setup (tonio: no TLS over TLS, so an
+            # https:// proxy cannot carry a CONNECT tunnel there)
+            self._backend.close_transport(stream)
+            raise ProxyError(f"Cannot open a TLS tunnel to {origin} via proxy {intercept.uri}: {exc}")
 
-        if tls.selected_alpn_protocol() == "h2" or not self._http1:
+        if selected == "h2" or not self._http1:
             return H2Connection(tls, authority=origin.authority, scheme="https", backend=self._backend)
         return H1Connection(tls, authority=origin.authority, backend=self._backend)

{punkreq-0.2.0 → punkreq-0.2.2}/punkreq/_transport.py

@@ -6,7 +6,14 @@ import typing
 
 import httpunk
 from httpunk import GoAwayError, H2Reason, StreamResetError
-from httpunk.exceptions import ConnectionClosedError, H2Error, H2UserError, HTTPunkError
+from httpunk.exceptions import (
+    ConnectionClosedError,
+    H1IncompleteMessageError,
+    H1UserError,
+    H2Error,
+    H2UserError,
+    HTTPunkError,
+)
 
 from ._config import Timeout
 from ._connect import origin_for_url
@@ -30,6 +37,12 @@ __all__ = ["PoolTransport"]
 
 _MAX_NACK_RETRIES = 2
 
+# The peer went away with our exchange in flight: the transport failed (hyper's
+# `Io`, both protocols), or on h1 it closed cleanly before the response head
+# (hyper's `IncompleteMessage`, httpunk >= 0.3.0 — a sibling under `H1Error`, not
+# a `ConnectionClosedError`). The same "server disconnected" verdict either way.
+_DISCONNECTED = (ConnectionClosedError, H1IncompleteMessageError)
+
 
 def map_httpunk_exception(exc: BaseException, request: Request) -> BaseException:
     """Translate an httpunk (or OS-level) failure into the punkreq hierarchy."""
@@ -39,9 +52,11 @@ def map_httpunk_exception(exc: BaseException, request: Request) -> BaseException
         return exc
     message = str(exc) or type(exc).__name__
     mapped: HTTPError
-    if isinstance(exc, (H2UserError, ValueError)):
+    if isinstance(exc, (H1UserError, H2UserError, ValueError)):
+        # local misuse: hyper's `Kind::User` on h1, the h2 state machine's API
+        # errors, and the `http` crate's constructor validation (`ValueError`)
         mapped = LocalProtocolError(message)
-    elif isinstance(exc, ConnectionClosedError):
+    elif isinstance(exc, _DISCONNECTED):
         mapped = RemoteProtocolError(f"Server disconnected: {message}")
     elif isinstance(exc, (H2Error, HTTPunkError)):
         mapped = RemoteProtocolError(message)
@@ -65,12 +80,17 @@ def _is_retryable_nack(exc: BaseException, reused: bool, replayable: bool) -> bo
         # httpunk >= 0.2.0 (h1): the failure was raised before the request was
         # handed to the body writer — nothing reached the wire and the body
         # was never iterated, so even a streamed body is intact and safe to
-        # resend (hyper's `TrySendError` request give-back; the `reused` gate
-        # mirrors hyper-util's "a fresh connection means we can't retry").
+        # resend (hyper's `try_send_request` give-back, client/conn/http1.rs:
+        # an error "before trying to serialize the request" returns the
+        # message). The `reused` gate is punkreq's own policy: a give-back on a
+        # fresh connection means the origin is failing at dial time, and a
+        # redial would only fail the same way — only an idle keep-alive
+        # connection dying underneath us is a nack worth one more try.
         return reused
-    if isinstance(exc, ConnectionClosedError):
+    if isinstance(exc, _DISCONNECTED):
         # h1 keep-alive race past the writer hand-off: the server closed the
-        # connection as we reused it, but body bytes may have been consumed.
+        # connection as we reused it (EOF before the response head, hyper's
+        # `IncompleteMessage`), but body bytes may have been consumed.
         # Only safe when the connection had served traffic before AND the body
         # replays from memory.
         return reused and replayable
@@ -269,7 +289,7 @@ class PoolTransport:
                 headers=Headers(httpunk_response.headers),
                 stream=stream,
                 request=request,
-                http_version="HTTP/2" if _is_multiplexed(conn) else "HTTP/1.1",
+                http_version=str(httpunk_response.version),  # httpunk.Version, `http::Version` names
             )
 
     def _effective(self, phase: float | None, deadline: float | None, request: Request) -> float | None:

punkreq-0.2.2/punkreq/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

{punkreq-0.2.0 → punkreq-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "punkreq"
-version = "0.2.0"
+version = "0.2.2"
 description = "An async HTTP client built on httpunk"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -32,12 +32,12 @@ classifiers = [
 ]
 
 dependencies = [
-    "httpunk~=0.2.0",
+    "httpunk~=0.4.0",
 ]
 
 [project.optional-dependencies]
 brotli = ["brotli~=1.2.0"]
-tonio = ["tonio~=0.9.12; python_version >= '3.14'"]
+tonio = ["tonio~=0.9.16; python_version >= '3.14'"]
 
 [dependency-groups]
 lint = [
@@ -45,6 +45,7 @@ lint = [
 ]
 test = [
     "pytest>=7.4",
+    "pytest-asyncio>=1.0",
     "trustme>=1.2.1",
 ]
 
@@ -54,6 +55,9 @@ Funding = 'https://github.com/sponsors/gi0baro'
 Source = 'https://github.com/gi0baro/punkreq'
 Issues = 'https://github.com/gi0baro/punkreq/issues'
 
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+
 [tool.hatch.build.targets.sdist]
 include = [
     '/README.md',

punkreq-0.2.2/tests/conftest.py

@@ -0,0 +1,77 @@
+import pytest
+import pytest_asyncio
+import trustme
+from httpunk import Backend
+
+from punkreq import Limits
+from punkreq._pool import ConnectionPool
+from punkreq.asyncio import Client
+from tests.fakes import FakeConnector
+from tests.servers import RawProxy, start_server
+
+
+@pytest.fixture(scope="session")
+def ca():
+    """A throwaway certificate authority for TLS peers."""
+    return trustme.CA()
+
+
+@pytest.fixture
+def make_client():
+    """`(client, connector)`: a Client over a fake connector whose connections
+    answer every request from `handler(request, conn)`."""
+
+    def factory(handler, *, multiplexed=False, **kwargs):
+        connector = FakeConnector(handler, multiplexed=multiplexed)
+        return Client(connector=connector, **kwargs), connector
+
+    return factory
+
+
+@pytest.fixture
+def make_pool():
+    """A ConnectionPool over `connector` on the asyncio backend (or `backend`),
+    with `Limits(**limits)`."""
+
+    def factory(connector, *, backend=None, **limits):
+        return ConnectionPool(connector, backend=backend or Backend.asyncio.create(), limits=Limits(**limits))
+
+    return factory
+
+
+# ----- real peers on the asyncio test's own loop (`@pytest.mark.asyncio` tests only) -----
+
+
+@pytest_asyncio.fixture
+async def echo_server():
+    """`await echo_server(ssl_context=None) -> port`: a JSON echo server on this
+    test's loop; every server started is closed at teardown."""
+    servers = []
+
+    async def start(ssl_context=None):
+        server, port = await start_server(ssl_context=ssl_context)
+        servers.append(server)
+        return port
+
+    yield start
+    for server in servers:
+        server.close()
+        if hasattr(server, "close_clients"):  # 3.13+: `wait_closed` waits for clients too
+            server.close_clients()
+        await server.wait_closed()
+
+
+@pytest_asyncio.fixture
+async def proxy():
+    """`await proxy(connect_status=200) -> RawProxy`: a CONNECT proxy on this
+    test's loop; every proxy started is stopped at teardown."""
+    proxies = []
+
+    async def start(connect_status=200):
+        started = await RawProxy(connect_status).start()
+        proxies.append(started)
+        return started
+
+    yield start
+    for started in proxies:
+        await started.stop()

punkreq-0.2.2/tests/e2e.py

@@ -0,0 +1,79 @@
+"""End-to-end scenarios shared by the asyncio and tonio suites: each takes the
+backend's `Client` class and the peers the suite started, so both backends run
+the same body against their own runtime."""
+
+import pytest
+
+import punkreq
+
+
+async def client_h1_get_and_post_with_keepalive(client_cls, upstream_port):
+    async with client_cls(base_url=f"http://127.0.0.1:{upstream_port}") as client:
+        response = await client.get("/hello", params={"a": "1"})
+        assert response.status_code == 200
+        echo = await response.json()
+        assert echo["method"] == "GET"
+        assert echo["path"] == "/hello?a=1"
+        assert echo["headers"]["host"] == f"127.0.0.1:{upstream_port}"
+        assert echo["headers"]["user-agent"].startswith("python-punkreq/")
+
+        response = await client.post("/items", json={"name": "x"})
+        assert (await response.json())["body"] == '{"name":"x"}'
+        assert client._pool.connection_count == 1  # keep-alive reuse
+
+
+async def client_h2_prior_knowledge(client_cls, upstream_port):
+    async with client_cls(base_url=f"http://127.0.0.1:{upstream_port}", http1=False) as client:
+        first = await client.get("/a")
+        second = await client.get("/b")
+        assert first.http_version == "HTTP/2"
+        assert {(await first.json())["path"], (await second.json())["path"]} == {"/a", "/b"}
+        assert client._pool.connection_count == 1  # one multiplexed connection
+
+
+async def tunnel_https_h1(client_cls, ca, upstream_port, proxy):
+    with ca.cert_pem.tempfile() as ca_path:
+        async with client_cls(proxy=f"http://127.0.0.1:{proxy.port}", verify=ca_path) as client:
+            response = await client.get(f"https://127.0.0.1:{upstream_port}/tunneled")
+            assert response.status_code == 200
+            assert (await response.json())["path"] == "/tunneled"
+            assert response.http_version == "HTTP/1.1"
+            # a second request reuses the tunnel: the h1 send-time peek runs on the wrapped stream
+            response = await client.get(f"https://127.0.0.1:{upstream_port}/again")
+            assert (await response.json())["path"] == "/again"
+            assert client._pool.connection_count == 1
+    assert proxy.connect_targets == [f"127.0.0.1:{upstream_port}"]
+
+
+async def tunnel_https_h2(client_cls, ca, upstream_port, proxy):
+    with ca.cert_pem.tempfile() as ca_path:
+        async with client_cls(proxy=f"http://127.0.0.1:{proxy.port}", verify=ca_path) as client:
+            first = await client.get(f"https://127.0.0.1:{upstream_port}/a")
+            second = await client.get(f"https://127.0.0.1:{upstream_port}/b")
+            assert first.http_version == "HTTP/2"
+            assert {(await first.json())["path"], (await second.json())["path"]} == {"/a", "/b"}
+            assert client._pool.connection_count == 1  # one multiplexed tunnel
+
+
+async def tunnel_handshake_failure_raises_connect_error(client_cls, upstream_port, proxy):
+    """The origin's certificate is not trusted (system store): the backend's TLS
+    layer fails the handshake inside the tunnel and closes it; punkreq reports it
+    as a connect failure, like a failed direct dial."""
+    async with client_cls(proxy=f"http://127.0.0.1:{proxy.port}") as client:
+        with pytest.raises(punkreq.ConnectError, match="via proxy"):
+            await client.get(f"https://127.0.0.1:{upstream_port}/untrusted")
+    assert proxy.connect_targets == [f"127.0.0.1:{upstream_port}"]
+
+
+async def direct_handshake_failure_raises_connect_error(client_cls, upstream_port):
+    """The same on a direct dial: whatever the backend raises for a failed
+    handshake surfaces as punkreq's `ConnectError`."""
+    async with client_cls() as client:
+        with pytest.raises(punkreq.ConnectError):
+            await client.get(f"https://127.0.0.1:{upstream_port}/untrusted")
+
+
+async def tunnel_refused_raises_proxy_error(client_cls, proxy):
+    async with client_cls(proxy=f"http://127.0.0.1:{proxy.port}") as client:
+        with pytest.raises(punkreq.ProxyError):
+            await client.get("https://denied.example/")

punkreq-0.2.2/tests/fakes.py

@@ -0,0 +1,151 @@
+"""Stand-ins for the httpunk objects punkreq drives: a response, a pool-facing
+connection and a connector, plus a backend wrapper with a deterministic clock."""
+
+import asyncio
+
+from httpunk import HeaderMap, Version
+
+import punkreq
+
+
+class FakeHttpunkResponse:
+    """The slice of an httpunk response punkreq reads: status, headers, version
+    and a body iterated once through `aiter_bytes`, then `aclose`d. Records how
+    it was driven (`aclose_calls`, `iter_finalized`); `aclose_error` makes the
+    close itself fail."""
+
+    def __init__(self, status=200, headers=None, body=b"", *, chunk_delay=0.0, aclose_error=None):
+        self.status = status
+        self.headers = HeaderMap(headers or {})
+        self.version = Version.HTTP_11  # stamped per protocol by FakeConnection.send_request
+        self._chunks = [body] if isinstance(body, bytes) else list(body)
+        self._chunk_delay = chunk_delay
+        self._aclose_error = aclose_error
+        self._conn = None  # set by FakeConnection.send_request
+        self._consumed = False
+        self.closed = False
+        self.aclose_calls = 0
+        self.iter_finalized = False
+
+    async def aiter_bytes(self):
+        try:
+            for chunk in self._chunks:
+                if self._chunk_delay:
+                    await asyncio.sleep(self._chunk_delay)
+                yield chunk
+            self._consumed = True
+        finally:
+            self.iter_finalized = True
+
+    async def aclose(self):
+        self.aclose_calls += 1
+        self.closed = True
+        # mirror httpunk h1: aborting a partially-read body closes the connection
+        if not self._consumed and self._conn is not None and not self._conn.multiplexed:
+            self._conn.closed = True
+        if self._aclose_error is not None:
+            raise self._aclose_error
+
+
+class FakeConnection:
+    """A pool-facing connection. `handler(request, conn)` answers each
+    `send_request` (a FakeHttpunkResponse, an awaitable of one, or by raising); with no
+    handler a streamed request body is drained and a 200 "ok" returned.
+    `fail_next` makes the next send raise that exception instead."""
+
+    def __init__(self, handler=None, *, multiplexed=False):
+        self.handler = handler
+        self.multiplexed = multiplexed
+        self.closed = False
+        self.busy = False  # httpunk: an exchange still holds the in-flight slot
+        self.entered = False
+        self.fail_next = None
+        self.requests = []
+        self.bodies_touched = 0
+
+    async def __aenter__(self):
+        self.entered = True
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, exc_tb):
+        self.closed = True
+        return False
+
+    async def ready(self):
+        if self.closed:
+            raise RuntimeError("connection is closed")
+
+    async def send_request(self, request):
+        self.requests.append(request)
+        if self.fail_next is not None:
+            exc, self.fail_next = self.fail_next, None
+            raise exc
+        if self.handler is not None:
+            result = self.handler(request, self)
+            if asyncio.iscoroutine(result):
+                result = await result
+        else:
+            if request.body is not None and not isinstance(request.body, bytes):
+                self.bodies_touched += 1
+                async for _ in request.body:
+                    pass
+            result = FakeHttpunkResponse(200, body=b"ok")
+        if isinstance(result, FakeHttpunkResponse):
+            result._conn = self
+            result.version = Version.HTTP_2 if self.multiplexed else Version.HTTP_11
+        return result
+
+
+class FakeConnector:
+    """Dials a fresh FakeConnection per call and records them. `delay` sleeps
+    before each dial; `fail` makes that many dials raise ConnectError first."""
+
+    def __init__(self, handler=None, *, multiplexed=False, delay=0.0, fail=0):
+        self.handler = handler
+        self.multiplexed = multiplexed
+        self.delay = delay
+        self.fail = fail
+        self.dials = 0
+        self.connections = []
+
+    async def __call__(self, origin):
+        self.dials += 1
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        if self.fail > 0:
+            self.fail -= 1
+            raise punkreq.ConnectError(f"boom dialing {origin}")
+        conn = FakeConnection(self.handler, multiplexed=self.multiplexed)
+        self.connections.append(conn)
+        return conn
+
+    @property
+    def requests(self):
+        """Every request sent, across all connections, in order."""
+        return [request for conn in self.connections for request in conn.requests]
+
+
+def ok_handler(body=b"hello", headers=None):
+    """A connection handler answering every request with one 200 response."""
+
+    def handler(request, conn):
+        return FakeHttpunkResponse(200, headers=headers, body=body)
+
+    return handler
+
+
+class SteppingBackend:
+    """Delegates to a real backend, but `monotonic()` strictly increases on every
+    call: on coarse OS clocks (Windows, ~16ms) consecutive releases can get equal
+    idle timestamps, making eviction order tie-dependent."""
+
+    def __init__(self, backend):
+        self._backend = backend
+        self._now = 0.0
+
+    def monotonic(self):
+        self._now += 1.0
+        return self._now
+
+    def __getattr__(self, name):
+        return getattr(self._backend, name)