punkreq 0.2.1__tar.gz → 0.2.3__tar.gz

{punkreq-0.2.1 → punkreq-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: punkreq
-Version: 0.2.1
+Version: 0.2.3
 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.3.0
+Requires-Dist: httpunk~=0.4.4
 Provides-Extra: brotli
 Requires-Dist: brotli~=1.2.0; extra == 'brotli'
 Provides-Extra: tonio
-Requires-Dist: tonio~=0.9.15; (python_version >= '3.14') and extra == 'tonio'
+Requires-Dist: tonio~=0.10.0; (python_version >= '3.14') and extra == 'tonio'
 Description-Content-Type: text/markdown
 
 # punkreq

{punkreq-0.2.1 → punkreq-0.2.3}/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."""
@@ -108,7 +117,7 @@ class Connector:
             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_bio` takes ALPN from the context alone), so the
+        # 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:
@@ -119,7 +128,7 @@ class Connector:
             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:

punkreq-0.2.3/punkreq/_proxies.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import ssl
+import typing
+from urllib.parse import urlsplit
+
+import httpunk
+from httpunk.h1.client import H1Connection
+from httpunk.h2.client import H2Connection
+from httpunk.util.proxy import Matcher
+
+from ._config import Proxy
+from ._connect import Connector, Origin, connect_errors
+from ._exceptions import ConnectError, ProxyError
+from ._headers import Headers
+from ._urls import URL
+
+
+__all__ = ["ProxyConfig", "ProxyConnector", "ProxyInfo"]
+
+ProxyTypes = typing.Union[Proxy, URL, str, None]
+
+# attribute name tagging plain-http proxied connections for the transport
+PROXY_ATTR = "punkreq_proxy"
+
+
+class ProxyInfo(typing.NamedTuple):
+    """Per-request proxy metadata for absolute-form (plain http) proxying."""
+
+    auth: str | None  # ready `Proxy-Authorization` value
+    headers: Headers
+
+
+class ProxyConfig:
+    """Resolved proxy configuration: a matcher plus proxy-level extras."""
+
+    def __init__(
+        self, matcher: Matcher, *, headers: Headers | None = None, ssl_context: ssl.SSLContext | None = None
+    ) -> None:
+        self.matcher = matcher
+        self.headers = headers if headers is not None else Headers()
+        self.ssl_context = ssl_context  # for TLS to the proxy itself (https:// proxies)
+
+    @classmethod
+    def resolve(cls, proxy: ProxyTypes, trust_env: bool) -> ProxyConfig | None:
+        if proxy is not None:
+            proxy = proxy if isinstance(proxy, Proxy) else Proxy(proxy)
+            url = proxy.url
+            if proxy.auth is not None:
+                url = url.copy_with(username=proxy.auth[0], password=proxy.auth[1])
+            matcher = Matcher.from_parts(all=str(url))
+            return cls(matcher, headers=proxy.headers, ssl_context=proxy.ssl_context)
+        if trust_env:
+            return cls(Matcher.from_env())
+        return None
+
+
+class ProxyConnector:
+    """Connector that routes each origin through its matched proxy, delegating
+    unmatched origins to the direct `Connector`."""
+
+    def __init__(
+        self,
+        *,
+        backend: typing.Any,
+        ssl_context: ssl.SSLContext,
+        http1: bool = True,
+        http2: bool = True,
+        config: ProxyConfig,
+    ) -> None:
+        self._backend = backend
+        self._ssl_context = ssl_context
+        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)
+
+    async def __call__(self, origin: Origin) -> typing.Any:
+        intercept = self._config.matcher.intercept(f"{origin.scheme}://{origin.authority}/")
+        if intercept is None:
+            return await self._direct(origin)
+        try:
+            if origin.scheme == "http":
+                return await self._absolute_form(origin, intercept)
+            return await self._tunnel(origin, intercept)
+        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:
+        parts = urlsplit(intercept.uri)
+        scheme, host = parts.scheme, parts.hostname
+        port = parts.port or (443 if scheme == "https" else 80)
+        if scheme == "https":
+            stream, _ = await self._backend.connect_tls(
+                host, port, alpn=("http/1.1",), ssl_context=self._config.ssl_context
+            )
+            return stream
+        return await self._backend.connect_tcp(host, port)
+
+    def _proxy_headers(self, intercept: typing.Any, authority: str) -> httpunk.HeaderMap:
+        headers = httpunk.HeaderMap({"host": authority})
+        auth = intercept.basic_auth()
+        if auth is not None:
+            headers["proxy-authorization"] = auth
+        for key, value in self._config.headers.raw:
+            headers.add(key, value)
+        return headers
+
+    async def _absolute_form(self, origin: Origin, intercept: typing.Any) -> typing.Any:
+        transport = await self._dial_proxy(intercept)
+        conn = H1Connection(transport, authority=origin.authority, backend=self._backend)
+        setattr(conn, PROXY_ATTR, ProxyInfo(auth=intercept.basic_auth(), headers=self._config.headers))
+        return conn
+
+    async def _tunnel(self, origin: Origin, intercept: typing.Any) -> typing.Any:
+        transport = await self._dial_proxy(intercept)
+        host = f"[{origin.host}]" if ":" in origin.host else origin.host
+        target = f"{host}:{origin.port}"  # CONNECT wants authority form with an explicit port
+        try:
+            proxy_conn = H1Connection(transport, backend=self._backend)
+            await proxy_conn.__aenter__()
+            response = await proxy_conn.send_request(
+                httpunk.Request("CONNECT", target, headers=self._proxy_headers(intercept, target))
+            )
+            if not (200 <= response.status < 300):
+                raise ProxyError(f"The proxy refused CONNECT to {target}: {response.status}")
+            tunnel = response.upgraded
+            if tunnel is None:
+                raise ProxyError(f"The proxy did not open a CONNECT tunnel to {target}")
+        except BaseException:
+            self._backend.close_transport(transport)
+            raise
+
+        # 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:
+            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 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.3/punkreq/_version.py

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

{punkreq-0.2.1 → punkreq-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "punkreq"
-version = "0.2.1"
+version = "0.2.3"
 description = "An async HTTP client built on httpunk"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -32,12 +32,12 @@ classifiers = [
 ]
 
 dependencies = [
-    "httpunk~=0.3.0",
+    "httpunk~=0.4.4",
 ]
 
 [project.optional-dependencies]
 brotli = ["brotli~=1.2.0"]
-tonio = ["tonio~=0.9.15; python_version >= '3.14'"]
+tonio = ["tonio~=0.10.0; 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.3/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.3/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.3/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)

punkreq-0.2.3/tests/servers.py

@@ -0,0 +1,101 @@
+"""Real peers for the end-to-end tests: an httpunk echo server on asyncio, its
+TLS context, and a minimal CONNECT proxy."""
+
+import asyncio
+import contextlib
+import json
+import ssl
+
+import httpunk.asyncio
+
+
+class EchoJsonProtocol(httpunk.asyncio.AutoServerProtocol):
+    """Answers every request with a JSON echo of its method, path, headers and body."""
+
+    async def handle(self, request):
+        body = await request.read()
+        payload = {
+            "method": request.method,
+            "path": request.path,
+            "headers": {key: value.decode("latin-1") for key, value in request.headers.items()},
+            "body": body.decode("utf-8", errors="replace"),
+        }
+        await request.respond(200, headers={"content-type": "application/json"}, body=json.dumps(payload).encode())
+
+
+async def start_server(protocol=EchoJsonProtocol, ssl_context=None):
+    """`(server, port)` for `protocol` listening on a free loopback port."""
+    loop = asyncio.get_running_loop()
+    server = await loop.create_server(protocol, "127.0.0.1", 0, ssl=ssl_context)
+    return server, server.sockets[0].getsockname()[1]
+
+
+def server_tls_context(ca, alpn):
+    """A server-side TLS context with a `ca`-issued loopback certificate offering `alpn`."""
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ca.issue_cert("localhost", "127.0.0.1").configure_cert(context)
+    context.set_alpn_protocols(alpn)
+    return context
+
+
+class RawProxy:
+    """A minimal HTTP proxy on asyncio streams that relays CONNECT tunnels to the
+    requested destination (or refuses them with `connect_status`)."""
+
+    def __init__(self, connect_status=200):
+        self.connect_status = connect_status
+        self.connect_targets: list[str] = []
+        self.server = None
+        self.port = None
+
+    async def start(self):
+        self.server = await asyncio.start_server(self._handle, "127.0.0.1", 0)
+        self.port = self.server.sockets[0].getsockname()[1]
+        return self
+
+    async def stop(self):
+        self.server.close()
+        await self.server.wait_closed()
+
+    async def _handle(self, reader, writer):
+        head = b""
+        while b"\r\n\r\n" not in head:
+            chunk = await reader.read(65536)
+            if not chunk:
+                writer.close()
+                return
+            head += chunk
+        head, _, leftover = head.partition(b"\r\n\r\n")
+        method, target, _ = head.split(b"\r\n")[0].decode().split(" ")
+        if method != "CONNECT":
+            writer.write(b"HTTP/1.1 405 Method Not Allowed\r\ncontent-length: 0\r\n\r\n")
+            await writer.drain()
+            writer.close()
+            return
+
+        self.connect_targets.append(target)
+        if self.connect_status != 200:
+            writer.write(f"HTTP/1.1 {self.connect_status} Denied\r\ncontent-length: 0\r\n\r\n".encode())
+            await writer.drain()
+            writer.close()
+            return
+        host, _, port = target.rpartition(":")
+        upstream_reader, upstream_writer = await asyncio.open_connection(host.strip("[]"), int(port))
+        writer.write(b"HTTP/1.1 200 Connection established\r\n\r\n")
+        await writer.drain()
+        if leftover:
+            upstream_writer.write(leftover)
+            await upstream_writer.drain()
+
+        async def pipe(src, dst):
+            try:
+                while data := await src.read(65536):
+                    dst.write(data)
+                    await dst.drain()
+            except Exception:
+                pass
+            finally:
+                with contextlib.suppress(Exception):
+                    dst.close()
+
+        await asyncio.gather(pipe(reader, upstream_writer), pipe(upstream_reader, writer))