httpunk 0.1.0a1__tar.gz → 0.1.1__tar.gz

{httpunk-0.1.0a1 → httpunk-0.1.1}/Cargo.lock

@@ -16,9 +16,9 @@ checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
 [[package]]
 name = "bytes"
-version = "1.11.1"
+version = "1.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "equivalent"
@@ -86,9 +86,9 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
 [[package]]
 name = "http"
-version = "1.4.0"
+version = "1.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3ba2a386d7f85a81f119ad7498ebe444d2e22c2af0b86b069416ace48b3311a"
+checksum = "6970f50e31d6fc17d3fa27329444bfa74e196cf62e95052a3f6fee181dba6425"
 dependencies = [
  "bytes",
  "itoa",
@@ -118,7 +118,7 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
 [[package]]
 name = "httpunk"
-version = "0.1.0-alpha1"
+version = "0.1.1"
 dependencies = [
  "bytes",
  "h2",
@@ -175,9 +175,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "libc"
-version = "0.2.183"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "once_cell"
@@ -271,9 +271,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.45"
+version = "1.0.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
 dependencies = [
  "proc-macro2",
 ]
@@ -292,9 +292,9 @@ checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
 
 [[package]]
 name = "syn"
-version = "2.0.117"
+version = "2.0.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
 dependencies = [
  "proc-macro2",
  "quote",

{httpunk-0.1.0a1 → httpunk-0.1.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "httpunk"
-version = "0.1.0-alpha1"
+version = "0.1.1"
 description = "The Rust HTTP library for Python"
 authors = [
     "Giovanni Barillari <g@baro.dev>",
@@ -30,8 +30,7 @@ include = [
 
 # The vendored third-party crates live in their own workspace members so each
 # owns its crate root (upstream `crate::` paths resolve with no rewrite → truly
-# byte-identical) and is excluded from the main crate's fmt/clippy. See
-# THIRD-PARTY.md and PLAN.md §4.
+# byte-identical) and is excluded from the main crate's fmt/clippy.
 [workspace]
 members = ["crates/vendor-h2", "crates/vendor-hyper", "crates/vendor-hyper-util"]
 

{httpunk-0.1.0a1 → httpunk-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpunk
-Version: 0.1.0a1
+Version: 0.1.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
@@ -19,7 +19,8 @@ Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Internet :: WWW/HTTP
-Requires-Dist: tonio>=0.7.1 ; python_full_version >= '3.14' and platform_system != 'Windows'
+Requires-Dist: tonio~=0.8.1 ; python_full_version >= '3.14' and extra == 'tonio'
+Provides-Extra: tonio
 License-File: LICENSE
 Summary: The Rust HTTP library for Python
 Keywords: http,h10,h11,h2
@@ -34,14 +35,16 @@ Project-URL: Source, https://github.com/gi0baro/httpunk
 
 # httpunk
 
-httpunk is a Rust-powered HTTP library for Python.
+httpunk is a Rust-powered async HTTP library for Python.
 It's powered by the [hyper](https://github.com/hyperium/hyper) stack and Rust crates like [http](https://github.com/hyperium/http).
 
 httpunk is deliberately *low-level*: you bring your own connected transport, and
 build requests and read responses directly. It's meant to be a solid, performant
 base for building HTTP clients and servers on top of.
 
-> **Note:** httpunk is in an early, alpha stage. The API may change between releases.
+httpunk's API mirrors hyper's wherever possible.
+
+> **Note:** httpunk is in an early, alpha stage.
 
 > **Note:** httpunk was built with substantial help from LLMs, under human supervision.
 
@@ -99,16 +102,19 @@ asyncio.run(main())
 pip install httpunk
 ```
 
-The `asyncio` backend has no extra dependencies. The `tonio` backend pulls in
-[tonio](https://github.com/gi0baro/tonio) and is only installed automatically on free-threaded
-CPython 3.14+ on Unix systems.
+httpunk supports additional backends beyond `asyncio`, but they require extra dependencies.
+Enable one via the relevant extra:
+
+```
+pip install httpunk[tonio]
+```
 
 ## Features
 
 - **HTTP/1 and HTTP/2**, client and server implementations
 - **Protocol-neutral structures** such as `Request`, `Response`, `HeaderMap`
 - **Multiple backend support**: `asyncio` and `tonio` (with `trio` targeted for future releases)
-- **AsyncIO ready-to-go protocols**: extensible `asyncio.Protocol` server classes (H1, H2, Auto)
+- **AsyncIO ready-to-go protocols**: extensible `asyncio.Protocol` classes (H1, H2, Auto)
 - **Batteries in the `util` module**: connect and ALPN negotiation, h1/h2 auto-detection, connection pooling, graceful shutdown, proxy-environment matching.
 
 ## Usage
@@ -305,7 +311,7 @@ except HTTPunkError:
 ### Utilities
 
 `httpunk.util` collects the higher-level conveniences a real client/server host needs. Unlike
-the core, these carry no wire-protocol fidelity constraint — they mirror hyper-util's shapes.
+the core, these carry no wire-protocol fidelity constraint.
 
 #### connect
 
@@ -367,10 +373,9 @@ All pools expose `retain(predicate)` (evict connections a predicate rejects), `i
 
 #### Graceful shutdown
 
-`GracefulShutdown` coordinates a graceful shutdown across many connections (hyper-util's
-`server::graceful::GracefulShutdown`). `watch(server, serve)` registers a connection and
-returns the coroutine that drives it; `shutdown()` signals every watched connection and waits
-for them to drain.
+`GracefulShutdown` coordinates a graceful shutdown across many connections.
+`watch(server, serve)` registers a connection and returns the coroutine that drives it;
+`shutdown()` signals every watched connection and waits for them to drain.
 
 ```python
 from httpunk.util import GracefulShutdown
@@ -402,8 +407,10 @@ if intercept is not None:
 
 ### AsyncIO utilities
 
-`httpunk.asyncio` provides reusable `asyncio.Protocol` server classes so you can embed httpunk
-in any asyncio-based server. Just subclass one and implement `handle(request)`:
+`httpunk.asyncio` provides reusable `asyncio.Protocol` classes so you
+can embed httpunk in any asyncio program.
+
+**Server protocols** — subclass one and implement `handle(request)`:
 
 - `H1ServerProtocol` / `H2ServerProtocol` — force the protocol.
 - `AutoServerProtocol` — detect HTTP/1 vs HTTP/2 from the client's opening bytes.
@@ -442,6 +449,38 @@ server.close()                     # stop accepting new connections
 await conns.shutdown(timeout=30)   # drain in-flight, force-close stragglers
 ```
 
+**Client protocols** — the mirror of the server ones, for `loop.create_connection`. Once the
+connection is up, `await proto.ready()` returns the httpunk client connection to send requests
+on. Configuration (`authority`/`scheme`) is passed via a factory closure, since
+`create_connection` calls the factory with no arguments.
+
+- `H1ClientProtocol` / `H2ClientProtocol` — force the protocol.
+- `AutoClientProtocol` — pick HTTP/1 vs HTTP/2 from the TLS ALPN result (plain TCP → HTTP/1).
+
+```python
+import asyncio
+import ssl
+
+import httpunk.asyncio
+
+
+async def main():
+    loop = asyncio.get_running_loop()
+    ctx = ssl.create_default_context()
+    ctx.set_alpn_protocols(["h2", "http/1.1"])
+    transport, proto = await loop.create_connection(
+        lambda: httpunk.asyncio.H2ClientProtocol(authority="example.com:443", scheme="https"),
+        "example.com", 443, ssl=ctx, server_hostname="example.com",
+    )
+    conn = await proto.ready()                 # await handshake -> H2Connection
+    resp = await conn.request("GET", "/", headers={"host": "example.com"})
+    print(resp.status, await resp.read())
+    await proto.aclose()
+
+
+asyncio.run(main())
+```
+
 ## License
 
 httpunk is released under the BSD 3-Clause License.

{httpunk-0.1.0a1 → httpunk-0.1.1}/README.md

@@ -1,13 +1,15 @@
 # httpunk
 
-httpunk is a Rust-powered HTTP library for Python.
+httpunk is a Rust-powered async HTTP library for Python.
 It's powered by the [hyper](https://github.com/hyperium/hyper) stack and Rust crates like [http](https://github.com/hyperium/http).
 
 httpunk is deliberately *low-level*: you bring your own connected transport, and
 build requests and read responses directly. It's meant to be a solid, performant
 base for building HTTP clients and servers on top of.
 
-> **Note:** httpunk is in an early, alpha stage. The API may change between releases.
+httpunk's API mirrors hyper's wherever possible.
+
+> **Note:** httpunk is in an early, alpha stage.
 
 > **Note:** httpunk was built with substantial help from LLMs, under human supervision.
 
@@ -65,16 +67,19 @@ asyncio.run(main())
 pip install httpunk
 ```
 
-The `asyncio` backend has no extra dependencies. The `tonio` backend pulls in
-[tonio](https://github.com/gi0baro/tonio) and is only installed automatically on free-threaded
-CPython 3.14+ on Unix systems.
+httpunk supports additional backends beyond `asyncio`, but they require extra dependencies.
+Enable one via the relevant extra:
+
+```
+pip install httpunk[tonio]
+```
 
 ## Features
 
 - **HTTP/1 and HTTP/2**, client and server implementations
 - **Protocol-neutral structures** such as `Request`, `Response`, `HeaderMap`
 - **Multiple backend support**: `asyncio` and `tonio` (with `trio` targeted for future releases)
-- **AsyncIO ready-to-go protocols**: extensible `asyncio.Protocol` server classes (H1, H2, Auto)
+- **AsyncIO ready-to-go protocols**: extensible `asyncio.Protocol` classes (H1, H2, Auto)
 - **Batteries in the `util` module**: connect and ALPN negotiation, h1/h2 auto-detection, connection pooling, graceful shutdown, proxy-environment matching.
 
 ## Usage
@@ -271,7 +276,7 @@ except HTTPunkError:
 ### Utilities
 
 `httpunk.util` collects the higher-level conveniences a real client/server host needs. Unlike
-the core, these carry no wire-protocol fidelity constraint — they mirror hyper-util's shapes.
+the core, these carry no wire-protocol fidelity constraint.
 
 #### connect
 
@@ -333,10 +338,9 @@ All pools expose `retain(predicate)` (evict connections a predicate rejects), `i
 
 #### Graceful shutdown
 
-`GracefulShutdown` coordinates a graceful shutdown across many connections (hyper-util's
-`server::graceful::GracefulShutdown`). `watch(server, serve)` registers a connection and
-returns the coroutine that drives it; `shutdown()` signals every watched connection and waits
-for them to drain.
+`GracefulShutdown` coordinates a graceful shutdown across many connections.
+`watch(server, serve)` registers a connection and returns the coroutine that drives it;
+`shutdown()` signals every watched connection and waits for them to drain.
 
 ```python
 from httpunk.util import GracefulShutdown
@@ -368,8 +372,10 @@ if intercept is not None:
 
 ### AsyncIO utilities
 
-`httpunk.asyncio` provides reusable `asyncio.Protocol` server classes so you can embed httpunk
-in any asyncio-based server. Just subclass one and implement `handle(request)`:
+`httpunk.asyncio` provides reusable `asyncio.Protocol` classes so you
+can embed httpunk in any asyncio program.
+
+**Server protocols** — subclass one and implement `handle(request)`:
 
 - `H1ServerProtocol` / `H2ServerProtocol` — force the protocol.
 - `AutoServerProtocol` — detect HTTP/1 vs HTTP/2 from the client's opening bytes.
@@ -408,6 +414,38 @@ server.close()                     # stop accepting new connections
 await conns.shutdown(timeout=30)   # drain in-flight, force-close stragglers
 ```
 
+**Client protocols** — the mirror of the server ones, for `loop.create_connection`. Once the
+connection is up, `await proto.ready()` returns the httpunk client connection to send requests
+on. Configuration (`authority`/`scheme`) is passed via a factory closure, since
+`create_connection` calls the factory with no arguments.
+
+- `H1ClientProtocol` / `H2ClientProtocol` — force the protocol.
+- `AutoClientProtocol` — pick HTTP/1 vs HTTP/2 from the TLS ALPN result (plain TCP → HTTP/1).
+
+```python
+import asyncio
+import ssl
+
+import httpunk.asyncio
+
+
+async def main():
+    loop = asyncio.get_running_loop()
+    ctx = ssl.create_default_context()
+    ctx.set_alpn_protocols(["h2", "http/1.1"])
+    transport, proto = await loop.create_connection(
+        lambda: httpunk.asyncio.H2ClientProtocol(authority="example.com:443", scheme="https"),
+        "example.com", 443, ssl=ctx, server_hostname="example.com",
+    )
+    conn = await proto.ready()                 # await handshake -> H2Connection
+    resp = await conn.request("GET", "/", headers={"host": "example.com"})
+    print(resp.status, await resp.read())
+    await proto.aclose()
+
+
+asyncio.run(main())
+```
+
 ## License
 
 httpunk is released under the BSD 3-Clause License.

{httpunk-0.1.0a1 → httpunk-0.1.1}/crates/vendor-h2/src/lib.rs

@@ -6,7 +6,7 @@
 //! frame parse/serialize) and `hpack` (HPACK header compression), plus the tiny
 //! `ext::Protocol` type they depend on. h2's async `codec`, `proto`, `client`
 //! and `server` are intentionally *not* vendored — that orchestration is
-//! rewritten in Python (see `PLAN.md`).
+//! rewritten in Python.
 //!
 //! The `.rs` files under here are kept **byte-identical to upstream modulo a
 //! uniform `crate::` -> `crate::` rewrite** the vendor script applies, so

{httpunk-0.1.0a1 → httpunk-0.1.1}/crates/vendor-hyper/src/lib.rs

@@ -5,7 +5,7 @@
 //! support types they depend on (`headers`, `ext`, `error`, `body::length`,
 //! `proto::MessageHead`). hyper's async `conn`, `decode`, `io`, `dispatch`,
 //! `client`, `server` and `upgrade` are intentionally *not* vendored — that
-//! orchestration is rewritten in Python (see `PLAN.md`).
+//! orchestration is rewritten in Python.
 //!
 //! The `.rs` files under here are kept **byte-identical to upstream** so a
 //! `git diff` between two vendored versions shows only genuine upstream changes.

{httpunk-0.1.0a1 → httpunk-0.1.1}/httpunk/_backend/__init__.py

@@ -25,8 +25,13 @@ class Backend(enum.Enum):
 
     def create(self) -> Any:
         if self is Backend.tonio:
-            from .tonio import TonioBackend
-
+            try:
+                from .tonio import TonioBackend
+            except ImportError as exc:
+                raise ImportError(
+                    "the tonio backend requires the 'tonio' package — install it with "
+                    "`pip install httpunk[tonio]` (needs free-threaded CPython >= 3.14 on Unix)"
+                ) from exc
             return TonioBackend()
         from .asyncio import AsyncioBackend
 

{httpunk-0.1.0a1 → httpunk-0.1.1}/httpunk/_backend/asyncio.py

@@ -1,10 +1,10 @@
 """asyncio backend: the runtime primitives the drivers need, on `asyncio`.
 
 The second backend (after tonio), validating that the drivers depend only on the
-seam (see PLAN §12). `import asyncio` below is the stdlib (absolute imports) — this
+seam. `import asyncio` below is the stdlib (absolute imports) — this
 module is `httpunk._backend.asyncio`, not the top-level package.
 
-Approach B (PLAN §12.4): asyncio's TCP is transport/protocol-based and eagerly
+asyncio's TCP is transport/protocol-based and eagerly
 drains the kernel socket into a userspace buffer, so — unlike tonio — a non-blocking
 `receive_nowait` must peek *that* buffer. Rather than lean on `StreamReader`'s
 private `_buffer`, we own a custom `asyncio.Protocol` (`_AsyncioStream`) that IS the
@@ -162,6 +162,12 @@ class _AsyncioStream(asyncio.Protocol):
         if waiter is not None and not waiter.done():
             waiter.set_result(None)
 
+    def interrupt_read(self):
+        """Wake a parked `receive_some` so it returns b"" — lets a graceful shutdown release
+        an idle keep-alive read WITHOUT racing a coroutine (asyncio can wake a parked read from
+        another task; tonio can't, which is why it uses a select-based race instead)."""
+        self._wake_reader()
+
 
 class _AsyncioScope:
     """A nursery over `asyncio` tasks, matching tonio's scope surface: `spawn`,
@@ -297,3 +303,18 @@ class AsyncioBackend:
     scope = _AsyncioScope
     monotonic = staticmethod(_time.monotonic)
     sleep = staticmethod(asyncio.sleep)  # async sleep(seconds), for deadline races (`select`)
+
+    # Every backend implements `timeout` (above), so the h1 server always uses it for the
+    # head-read deadline. This extra capability is asyncio-only: `_AsyncioStream.interrupt_read`
+    # can wake a parked idle read from another task, so the h1 server can skip the per-read
+    # shutdown `select`. tonio can't (no such method) → it keeps the select there.
+    native_read_interrupt = True
+
+    async def timeout(self, coro, seconds):
+        """Run `coro` bounded by `seconds`; return `(result, True)` on completion, or
+        `(None, False)` on timeout (the coro is cancelled). One task + one timer, far cheaper
+        than racing a `sleep()` coroutine via `select`."""
+        try:
+            return await asyncio.wait_for(coro, seconds), True
+        except (TimeoutError, asyncio.TimeoutError):
+            return None, False

{httpunk-0.1.0a1 → httpunk-0.1.1}/httpunk/_backend/tonio.py

@@ -12,7 +12,7 @@ from tonio.colored.net import open_tcp_stream as _open_tcp_stream
 from tonio.colored.net.tls import open_tls_over_tcp_stream as _open_tls_over_tcp_stream
 from tonio.colored.sync import Lock as _Lock, Semaphore as _Semaphore
 from tonio.colored.sync.channel import unbounded as _unbounded
-from tonio.colored.time import time as _now
+from tonio.colored.time import time as _now, timeout as _timeout
 
 
 class _TonioSemaphore:
@@ -107,4 +107,9 @@ class TonioBackend:
     semaphore = _TonioSemaphore
     queue = staticmethod(_unbounded)
     monotonic = staticmethod(_now)
-    sleep = staticmethod(_colored.sleep)  # async sleep(seconds), for deadline races (`select`)
+    sleep = staticmethod(_colored.sleep)  # async sleep(seconds)
+    # `timeout(coro, seconds) -> (result, completed)` — tonio's native deadline; the h1 server
+    # uses it to bound the request-head read (measured ~12-16% faster than racing sleep() via
+    # select). Same contract as AsyncioBackend.timeout. tonio still can't wake a parked recv from
+    # another task, so it does NOT advertise `native_read_interrupt` (idle shutdown stays select).
+    timeout = staticmethod(_timeout)

{httpunk-0.1.0a1 → httpunk-0.1.1}/httpunk/asyncio.py

@@ -1,11 +1,11 @@
-"""Reusable asyncio server protocols — embed httpunk in any asyncio server (uvicorn,
-hypercorn, …) by subclassing one of these and implementing `handle(request)`.
+"""Reusable asyncio protocols — embed httpunk in any asyncio program. They are
+`asyncio.Protocol` subclasses of the asyncio backend's `_AsyncioStream` (the byte
+transport the driver reads/writes); the host owns the loop and hands the protocol a
+transport. Unlike uvicorn's h11/httptools protocols (HTTP/1 only), these also bring **HTTP/2**.
 
-Unlike uvicorn's h11/httptools protocols (HTTP/1 only), these also bring **HTTP/2**.
-They are `asyncio.Protocol` subclasses of the asyncio backend's `_AsyncioStream`
-(approach B, PLAN §12.8): the host owns the loop and hands the protocol a transport
-via `loop.create_server(factory)`; the protocol drives httpunk's server over *itself*
-and calls your `handle` per request.
+**Server** — subclass one and implement `handle(request)`, then hand it to
+`loop.create_server(factory)`; the protocol drives httpunk's server over *itself* and calls
+your `handle` per request:
 
     class MyServer(httpunk.asyncio.AutoServerProtocol):
         async def handle(self, request):
@@ -16,8 +16,19 @@ and calls your `handle` per request.
     async with server:
         await server.serve_forever()
 
-`H1ServerProtocol` / `H2ServerProtocol` force the protocol; `AutoServerProtocol` sniffs h1-vs-h2 from
-the client's opening bytes.
+**Client** (the mirror) — hand one to `loop.create_connection(factory)`; once connected,
+`await proto.ready()` returns the httpunk client connection to send requests on:
+
+    transport, proto = await loop.create_connection(
+        lambda: httpunk.asyncio.H2ClientProtocol(authority="example.com:443", scheme="https"),
+        "example.com", 443, ssl=ctx,
+    )
+    conn = await proto.ready()
+    resp = await conn.request("GET", "/", headers={"host": "example.com"})
+    await proto.aclose()
+
+`H1*`/`H2*` force the protocol; `Auto*` picks h1-vs-h2 (server: from the client's opening
+bytes; client: from the TLS ALPN result).
 """
 
 from __future__ import annotations
@@ -27,12 +38,22 @@ import contextlib
 from typing import Any, TypeVar
 
 from ._backend.asyncio import AsyncioBackend, _AsyncioStream
+from .h1.client import H1Connection
 from .h1.server import H1Server
+from .h2.client import H2Connection
 from .h2.server import H2Server
 from .util import auto
 
 
-__all__ = ["AutoServerProtocol", "H1ServerProtocol", "H2ServerProtocol", "ServerConnections"]
+__all__ = [
+    "AutoClientProtocol",
+    "AutoServerProtocol",
+    "H1ClientProtocol",
+    "H1ServerProtocol",
+    "H2ClientProtocol",
+    "H2ServerProtocol",
+    "ServerConnections",
+]
 
 _ProtocolT = TypeVar("_ProtocolT", bound="_ServerProtocol")
 
@@ -229,3 +250,74 @@ class ServerConnections:
                 if c._serve_task is not None:
                     c._serve_task.cancel()  # hard-cancel a stuck handler / accept loop
             await asyncio.wait(pending)
+
+
+class _ClientProtocol(_AsyncioStream):
+    """Base for the reusable client protocols — the client-side mirror of `_ServerProtocol`.
+    `_AsyncioStream` is the transport the driver reads/writes; on `connection_made` this builds
+    an httpunk client connection over `self` and spawns its handshake. `ready()` awaits the
+    handshake and returns the connection facade to send requests on. Subclasses provide
+    `_make_client`. There is no `handle` — the client is caller-driven, not push."""
+
+    def __init__(self, *, authority: str | None = None, scheme: str | None = None) -> None:
+        super().__init__()
+        self._backend = AsyncioBackend()  # it's an asyncio protocol -> the asyncio backend
+        self._authority = authority
+        self._scheme = scheme
+        # Built in connection_made; None until then (so aclose() before a dial is a no-op).
+        self._client: H1Connection | H2Connection | None = None
+        self._connect_task: asyncio.Task[object] | None = None
+
+    def connection_made(self, transport):
+        super().connection_made(transport)
+        self._client = self._make_client()
+        # Run the HTTP handshake (the facade's __aenter__ -> conn.connect(): preface + SETTINGS
+        # for h2, a no-op for h1) concurrently; `ready()` awaits it. Retrieve the task's result
+        # so a handshake failure doesn't surface as a bare "Task exception was never retrieved".
+        task = self._loop.create_task(self._client.__aenter__())
+        self._connect_task = task
+        task.add_done_callback(lambda t: t.cancelled() or t.exception())
+
+    def _make_client(self) -> H1Connection | H2Connection:
+        raise NotImplementedError
+
+    async def ready(self) -> H1Connection | H2Connection:
+        """Await the connection handshake, then return the ready client facade
+        (`H1Connection`/`H2Connection`) to send requests on."""
+        assert self._connect_task is not None and self._client is not None  # set in connection_made
+        await self._connect_task
+        await self._client.ready()
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the connection — drops the read/write scopes and the transport. A no-op if the
+        connection was never established (`connection_made` not yet called)."""
+        if self._client is not None:
+            await self._client.__aexit__(None, None, None)
+
+
+class H1ClientProtocol(_ClientProtocol):
+    """Speak HTTP/1 on this connection."""
+
+    def _make_client(self):
+        return H1Connection(self, authority=self._authority, backend=self._backend)
+
+
+class H2ClientProtocol(_ClientProtocol):
+    """Speak HTTP/2 on this connection."""
+
+    def _make_client(self):
+        return H2Connection(self, authority=self._authority, scheme=self._scheme or "http", backend=self._backend)
+
+
+class AutoClientProtocol(_ClientProtocol):
+    """Pick HTTP/1 or HTTP/2 from the TLS ALPN result — the client-side analogue of
+    `AutoServerProtocol`'s preface sniff. `h2` -> HTTP/2; anything else (including plain TCP
+    with no ALPN) -> HTTP/1, matching `httpunk.util.connect`."""
+
+    def _make_client(self):
+        ssl_object = self._transport.get_extra_info("ssl_object")
+        selected = ssl_object.selected_alpn_protocol() if ssl_object is not None else None
+        if selected == "h2":
+            return H2Connection(self, authority=self._authority, scheme=self._scheme or "https", backend=self._backend)
+        return H1Connection(self, authority=self._authority, backend=self._backend)