httpunk 0.1.0__cp315-cp315-win_amd64.whl

httpunk/__init__.py

@@ -0,0 +1,19 @@
+from . import http as http
+from ._backend import Backend as Backend
+from ._httpunk import __version__ as __version__
+from .exceptions import (
+    ConnectionClosedError as ConnectionClosedError,
+    GoAwayError as GoAwayError,
+    H2Error as H2Error,
+    H2FlowControlError as H2FlowControlError,
+    H2ProtocolError as H2ProtocolError,
+    H2Reason as H2Reason,
+    H2StreamError as H2StreamError,
+    H2UserError as H2UserError,
+    HTTPunkError as HTTPunkError,
+    StreamResetError as StreamResetError,
+)
+from .h1 import H1Connection as H1Connection, H1Server as H1Server
+from .h2 import H2Connection as H2Connection, H2Server as H2Server
+from .http import HeaderMap as HeaderMap
+from .types import Request as Request, Response as Response

httpunk/_backend/__init__.py

@@ -0,0 +1,65 @@
+"""Runtime backends. Only this layer talks to a specific async runtime; the
+drivers (httpunk.h1/h2/util) are backend-agnostic — they take a `backend` and use
+only the seam it exposes.
+
+There is **no default backend**: `tonio` needs free-threaded CPython >= 3.14, while
+`asyncio` is available everywhere (incl. GIL builds), so the caller must choose.
+Selection is explicit — a `Backend` enum member (resolved to an instance lazily, so
+picking `asyncio` never imports tonio) or a backend instance. This module imports no
+backend eagerly; `Backend.<member>.create()` does the import on demand.
+"""
+
+from __future__ import annotations
+
+import enum
+from typing import TYPE_CHECKING, Any
+
+
+class Backend(enum.Enum):
+    """The available runtime backends. `create()` instantiates one, importing its
+    module lazily so an unavailable backend (e.g. tonio on a GIL build) is only
+    touched when actually selected."""
+
+    tonio = "tonio"
+    asyncio = "asyncio"
+
+    def create(self) -> Any:
+        if self is Backend.tonio:
+            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
+
+        return AsyncioBackend()
+
+
+if TYPE_CHECKING:
+    from .asyncio import AsyncioBackend
+    from .tonio import TonioBackend
+
+    # What every public `backend=` parameter accepts: a `Backend` enum member (the
+    # documented path) or an already-created backend instance (`httpunk.asyncio`
+    # passes one; `resolve()` returns whatever it's given). The backends share an
+    # implicit interface but no nominal base, so this is a union of the concretes.
+    BackendLike = Backend | AsyncioBackend | TonioBackend
+
+
+def resolve(backend) -> Any:
+    """Resolve a `backend` argument to a backend instance: a `Backend` member →
+    a fresh instance (lazy import); an instance → itself. `None` raises — there is
+    no default (see the module docstring). Call this **module-qualified**
+    (`_backend.resolve(...)`) so it stays a single monkeypatch point for tests."""
+    if backend is None:
+        raise ValueError(
+            "a backend is required: pass backend=Backend.asyncio or Backend.tonio "
+            "(or a backend instance). There is no default — tonio needs free-threaded "
+            "CPython >= 3.14, while asyncio is available everywhere."
+        )
+    if isinstance(backend, Backend):
+        return backend.create()
+    return backend

httpunk/_backend/asyncio.py

@@ -0,0 +1,320 @@
+"""asyncio backend: the runtime primitives the drivers need, on `asyncio`.
+
+The second backend (after tonio), validating that the drivers depend only on the
+seam. `import asyncio` below is the stdlib (absolute imports) — this
+module is `httpunk._backend.asyncio`, not the top-level package.
+
+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
+seam's stream: it buffers `data_received`, presents `receive_some`/`send_all`/`close`
+/`read_nowait`, and manages its own read/write backpressure. This one class serves
+both mode 1 (httpunk dials via `create_connection`) and — subclassed — Phase 6b's
+reusable server protocols (`H1/H2/Auto` `ServerProtocol`), so keep it inert + subclassable:
+a pure byte-mover + stream interface, no h1/h2 or driver logic.
+"""
+
+import asyncio
+import errno as _errno
+import ssl as _ssl
+import time as _time
+
+
+_READ_HIGH_WATER = 2**16  # 64 KiB — pause reading past this (matches StreamReader's default limit)
+
+
+class _AsyncioStream(asyncio.Protocol):
+    """The dual-fed IO layer: an `asyncio.Protocol` that owns a byte buffer and
+    presents the seam's stream interface. Fed by a socket (mode 1) or a host loop
+    (mode 2). Protocol-agnostic and driver-less."""
+
+    def __init__(self):
+        self._loop = asyncio.get_running_loop()
+        self._transport = None
+        self._buffer = bytearray()
+        self._eof = False
+        self._error = None
+        self._read_waiter = None  # Future parked in receive_some (single reader)
+        self._reading_paused = False
+        self._writing_paused = False
+        self._drain_waiter = None  # Future parked in send_all under write backpressure
+        self._conn_lost = False  # the socket died (connection_lost) — writes must now fail
+
+    # ----- asyncio.Protocol callbacks (fed from the socket / host loop) -----
+
+    def connection_made(self, transport):
+        self._transport = transport
+
+    def data_received(self, data):
+        self._buffer += data
+        self._wake_reader()
+        if not self._reading_paused and len(self._buffer) >= _READ_HIGH_WATER:
+            self._transport.pause_reading()
+            self._reading_paused = True
+
+    def eof_received(self):
+        self._eof = True
+        self._wake_reader()
+        # Keep the write half open — HTTP half-close: the peer closed its write side
+        # (our read sees EOF) but we still send the response. NOTE (F33b): asyncio
+        # honours this over plain TCP, but its SSL layer force-closes the transport on
+        # an unexpected EOF (no close_notify) regardless of this return — so a TLS
+        # half-close won't keep writing here the way tonio's does. That's an asyncio
+        # SSL-runtime limitation, not something this layer can paper over faithfully.
+        return True
+
+    def connection_lost(self, exc):
+        self._error = exc
+        self._eof = True
+        self._conn_lost = True  # writes to a dead socket must now raise (F32)
+        self._wake_reader()
+        self._writing_paused = False
+        if self._drain_waiter is not None and not self._drain_waiter.done():
+            if exc is None:
+                self._drain_waiter.set_result(None)
+            else:
+                self._drain_waiter.set_exception(exc)
+
+    def pause_writing(self):
+        self._writing_paused = True
+
+    def resume_writing(self):
+        self._writing_paused = False
+        if self._drain_waiter is not None and not self._drain_waiter.done():
+            self._drain_waiter.set_result(None)
+        self._drain_waiter = None
+
+    # ----- the seam's stream interface (called by the drivers) -----
+
+    async def receive_some(self, max_bytes=65536):
+        """Up to `max_bytes` of the next available bytes; `b""` at EOF. Blocks only
+        when the buffer is empty and no EOF/error has arrived yet."""
+        if self._buffer:
+            return self._take(max_bytes)
+        if self._eof:
+            if self._error is not None:
+                raise self._error
+            return b""
+        if self._read_waiter is not None:
+            # Single-reader contract: a second concurrent receive_some would overwrite
+            # the first's waiter, and the first caller would then park forever. The
+            # drivers read one-at-a-time, so this is a bug — fail loudly rather than
+            # hang silently (F55).
+            raise RuntimeError("concurrent receive_some on one stream (single-reader contract)")
+        self._read_waiter = self._loop.create_future()
+        try:
+            await self._read_waiter
+        finally:
+            self._read_waiter = None
+        if self._buffer:
+            return self._take(max_bytes)
+        if self._error is not None:
+            raise self._error
+        return b""
+
+    async def send_all(self, data):
+        # A write to a dead socket must fail (F32): asyncio's transport silently
+        # DISCARDS writes after connection_lost, but tonio (like a raw socket) raises
+        # EPIPE/ECONNRESET — drivers detect a dead peer via that failure. Surface the
+        # real error, or EPIPE if the close carried none (a clean peer FIN).
+        if self._conn_lost:
+            raise self._error or BrokenPipeError(_errno.EPIPE, "connection lost")
+        self._transport.write(data)
+        if self._writing_paused:  # transport buffer over high-water — wait for resume (drain)
+            if self._drain_waiter is None:
+                self._drain_waiter = self._loop.create_future()
+            await self._drain_waiter
+
+    def close(self):
+        if self._transport is None:
+            return
+        # Over TLS, abort() (no close_notify) rather than close() — an abortive close
+        # matching tonio's raw-socket close and hyper's hard close on a dropped
+        # connection (F33a); the async, caller-owned H1Upgraded.aclose path does the
+        # full close_notify dance instead. Plain TCP close() already sends a FIN.
+        if self._transport.get_extra_info("ssl_object") is not None:
+            self._transport.abort()
+        else:
+            self._transport.close()
+
+    def read_nowait(self, max_bytes=65536):
+        """Synchronous non-blocking peek: whatever is buffered right now, else `b""`
+        (the `receive_nowait` primitive — approach B peeks *our* buffer)."""
+        return self._take(max_bytes) if self._buffer else b""
+
+    # ----- helpers -----
+
+    def _take(self, max_bytes):
+        if max_bytes >= len(self._buffer):
+            data = bytes(self._buffer)
+            self._buffer.clear()
+        else:
+            data = bytes(self._buffer[:max_bytes])
+            del self._buffer[:max_bytes]
+        if self._reading_paused and len(self._buffer) < _READ_HIGH_WATER:
+            self._transport.resume_reading()
+            self._reading_paused = False
+        return data
+
+    def _wake_reader(self):
+        waiter = self._read_waiter
+        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`,
+    `cancel`, and `__aenter__`/`__aexit__` (which joins). Supports both lexical use
+    and the detached h2 pattern (`__aenter__` in `_begin`, `__aexit__` in `close`).
+    `asyncio.TaskGroup` can't do either (strictly lexical, no `cancel()`)."""
+
+    __slots__ = ["_tasks"]
+
+    def __init__(self):
+        self._tasks = set()
+
+    async def __aenter__(self):
+        return self
+
+    def spawn(self, coro):
+        task = asyncio.ensure_future(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    def cancel(self):
+        for task in list(self._tasks):
+            task.cancel()
+
+    async def __aexit__(self, exc_type, exc_value, exc_tb):
+        # Join-only teardown, matching tonio's scope exactly: `__aexit__` never
+        # cancels children on its own — a body exception still just JOINS the
+        # in-flight children (tonio's `_exit` aborts them only when the explicit
+        # `cancel()` flag is set). Callers that want children torn down on error
+        # must call `cancel()` themselves (h2 `close()`, h1 client, graceful watch,
+        # the h2 handler nursery in httpunk.asyncio all do). gather-and-swallow —
+        # a spawned task routes its own failures elsewhere, so exceptions surfacing
+        # here are teardown noise, not results.
+        if self._tasks:
+            await asyncio.gather(*list(self._tasks), return_exceptions=True)
+        return False
+
+
+class _QueueSender:
+    __slots__ = ["_q"]
+
+    def __init__(self, q):
+        self._q = q
+
+    def send(self, item):
+        self._q.put_nowait(item)
+
+
+class _QueueReceiver:
+    __slots__ = ["_q"]
+
+    def __init__(self, q):
+        self._q = q
+
+    def receive(self):
+        return self._q.get()
+
+
+class AsyncioBackend:
+    async def connect_tcp(self, host, port):
+        loop = asyncio.get_running_loop()
+        _transport, stream = await loop.create_connection(_AsyncioStream, host, port)
+        return stream
+
+    async def connect_tls(self, host, port, *, alpn=None, ssl_context=None):
+        """Dial `host:port` over TLS and return `(stream, selected_alpn)` (see the
+        tonio backend's `connect_tls`). `create_connection(ssl=...)` completes after
+        the TLS handshake, so ALPN is readable from the transport on return."""
+        if ssl_context is None:
+            ssl_context = _ssl.create_default_context()
+        if alpn:
+            ssl_context.set_alpn_protocols(list(alpn))
+        loop = asyncio.get_running_loop()
+        transport, stream = await loop.create_connection(
+            _AsyncioStream, host, port, ssl=ssl_context, server_hostname=host
+        )
+        ssl_obj = transport.get_extra_info("ssl_object")
+        selected = ssl_obj.selected_alpn_protocol() if ssl_obj is not None else None
+        return stream, selected
+
+    def receive_nowait(self, transport, max_bytes=65536):
+        """Synchronous non-blocking peek of the userspace buffer (approach B)."""
+        return transport.read_nowait(max_bytes)
+
+    def close_transport(self, transport):
+        """Close the transport (sync). `transport.close()` covers TLS too (asyncio
+        drives the `close_notify`), so no plain/TLS split like tonio."""
+        transport.close()
+
+    async def select(self, *coros):
+        """Race `coros`; return the first-ready one's result, cancelling the losers.
+        Matches tonio's `select` (`_ctl.select`: spawn all in argument order, keep the
+        first stored outcome, then `scope.cancel()` the rest):
+
+        - only the WINNER's outcome propagates — a loser's result or exception is
+          discarded (tonio never fetches a loser's stored value);
+        - the winner is the first coro in ARGUMENT ORDER among any ready in the same
+          wakeup (asyncio.wait's `done` set is unordered — pick deterministically);
+        - if `select` itself is cancelled, every racer is cancelled too (tonio's scope
+          aborts its children on teardown) — no coro is orphaned.
+        """
+        tasks = [asyncio.ensure_future(c) for c in coros]
+        try:
+            done, _pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        except asyncio.CancelledError:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            raise
+        winner = next(task for task in tasks if task in done)
+        losers = [task for task in tasks if task is not winner]
+        for task in losers:
+            task.cancel()
+        # Drain losers so their outcome is discarded (never surfaced here) and no
+        # "exception never retrieved" fires; return_exceptions swallows their
+        # error/cancellation. Losers that also finished this tick are drained too.
+        if losers:
+            await asyncio.gather(*losers, return_exceptions=True)
+        return winner.result()
+
+    def queue(self):
+        """An unbounded queue as `(sender, receiver)`: `sender.send(x)` is sync;
+        `await receiver.receive()` yields items in order."""
+        q = asyncio.Queue()
+        return _QueueSender(q), _QueueReceiver(q)
+
+    # asyncio's Lock/Event/Semaphore already match the seam's neutral contract
+    # (Event: set/wait/clear/is_set; Semaphore: async acquire / sync release — the
+    # shape step 1 normalized the h1 slot to).
+    lock = asyncio.Lock
+    event = asyncio.Event
+    semaphore = asyncio.Semaphore
+    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/_backend/tonio.py

@@ -0,0 +1,115 @@
+"""tonio backend: wraps the runtime primitives the h2 driver needs.
+
+The driver only depends on this small surface — connect, a scope to hold the
+background read-pump, a lock to order socket writes, and an event to signal
+across coroutines — so a future asyncio/trio backend is a drop-in replacement.
+"""
+
+import ssl as _ssl
+
+from tonio import colored as _colored
+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, timeout as _timeout
+
+
+class _TonioSemaphore:
+    """Adapts tonio's `Semaphore` to the backend-neutral async-`acquire`/sync-`release`
+    contract. tonio's `acquire()` is sync and returns None (a permit was free) or an
+    `Event` that fires once a permit is handed to this waiter — so awaiting that event
+    *is* the acquisition (fair handoff, no retry)."""
+
+    __slots__ = ["_sem"]
+
+    def __init__(self, value):
+        self._sem = _Semaphore(value)
+
+    async def acquire(self):
+        event = self._sem.acquire()
+        if event is not None:
+            await event.waiter(None)
+
+    def release(self):
+        self._sem.release()
+
+
+class TonioBackend:
+    connect_tcp = staticmethod(_open_tcp_stream)
+
+    async def connect_tls(self, host, port, *, alpn=None, ssl_context=None):
+        """Dial `host:port` over TLS and return `(stream, selected_alpn)` — the
+        one place TLS/ssl glue lives (behind the seam, like `receive_nowait`).
+
+        `alpn` is the ordered ALPN offer (e.g. `("h2", "http/1.1")`); it is set on
+        the context before the handshake and the peer's choice is read back from the
+        completed handshake (`None` if the peer declined / offered no ALPN). tonio's
+        `open_tls_over_tcp_stream` performs the TCP connect *and* the TLS handshake,
+        so the returned stream is ready to carry HTTP — httpunk never handshakes
+        itself. Used by `httpunk.util.connect` to pick h2 vs h1 (RFC 7301)."""
+        if ssl_context is None:
+            ssl_context = _ssl.create_default_context()
+        if alpn:
+            ssl_context.set_alpn_protocols(list(alpn))
+        stream = await _open_tls_over_tcp_stream(host, port, ssl_context=ssl_context)
+        return stream, stream._ssl.selected_alpn_protocol()
+
+    def receive_nowait(self, transport, max_bytes=65536):
+        """A synchronous, non-blocking read: whatever bytes are immediately
+        available without suspending, or `b""` if none are ready right now (also
+        `b""` at EOF). The readiness primitive hyper's server drain (`poll_read_body`
+        inside `poll_drain_or_close_read`) relies on.
+
+        - **Plain socket**: tonio's sockets are non-blocking under the hood (its own
+          `recv` does exactly this `_sock.recv` inline before ever suspending), so
+          we read the raw socket directly rather than route through the timer-backed
+          `timeout(..., 0)`, which cannot express an instantaneous peek.
+        - **TLS (`TLSStream`)**: the raw socket carries *ciphertext*, so reading it
+          would bypass decryption (and a `TLSStream` has no `.socket` anyway). The
+          non-blocking-plaintext equivalent is the SSLObject's already-decrypted
+          buffer: `pending()` bytes can be `read()` without touching the BIO/socket.
+          (Necessarily conservative — tonio exposes no non-blocking "decrypt more",
+          so unread ciphertext on the socket reads as "nothing ready"; the drain
+          then closes rather than reuses, which matches hyper's cheap-drain-or-close.)"""
+        ssl_obj = getattr(transport, "_ssl", None)
+        if ssl_obj is not None:  # a TLSStream — peek only already-decrypted plaintext
+            pending = ssl_obj.pending()
+            return ssl_obj.read(min(max_bytes, pending)) if pending else b""
+        try:
+            return transport.socket._sock.recv(max_bytes)
+        except (BlockingIOError, InterruptedError):
+            return b""
+
+    def close_transport(self, transport):
+        """Synchronously close a transport, unblocking the peer's read. The driver
+        closes from both sync (body-release, failure) and async paths, so this must
+        be sync.
+
+        - **Plain socket**: its `close()` is synchronous.
+        - **TLS (`TLSStream`)**: its own `close()` is a coroutine (it writes a TLS
+          `close_notify`), which a sync caller can't await — so close the underlying
+          socket (`.transport`) directly. The `close_notify` is skipped (a
+          best-effort/abortive close, like hyper's hard close on a dropped
+          connection), but the socket is really closed so the peer's read ends.
+          (`H1Upgraded.aclose`, which is async and caller-owned, awaits the full
+          `close_notify` dance instead.)"""
+        ssl_obj = getattr(transport, "_ssl", None)
+        if ssl_obj is not None:  # a TLSStream — close the underlying socket synchronously
+            transport.transport.close()
+        else:
+            transport.close()
+
+    select = staticmethod(_colored.select)
+    scope = staticmethod(_colored.scope)
+    lock = _Lock
+    event = _colored.Event
+    semaphore = _TonioSemaphore
+    queue = staticmethod(_unbounded)
+    monotonic = staticmethod(_now)
+    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/_common.py

@@ -0,0 +1,111 @@
+"""Cross-protocol glue shared by the h1 and h2 public API + drivers.
+
+Pure orchestration with **no protocol behavior** — the one place h1 and h2
+(separate crates upstream, sharing nothing at the protocol level) legitimately
+share code: body-chunk normalization, and the public connection/server facade
+shells that collapse the driver into an async-context-managed handle. Everything
+protocol-specific stays in the h1/h2 role files.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from .types import Body, HeadersInput, Request, Response
+
+
+if TYPE_CHECKING:
+    from typing import Self
+
+
+_RequestT = TypeVar("_RequestT")
+
+
+async def aiter_body(body):
+    """Normalize a message body — `bytes`, a sync iterable, or an async iterable
+    of `bytes` — into an async stream of chunks. Protocol-neutral: the caller
+    frames + sends each chunk (h1 via the codec, h2 via flow-controlled DATA).
+    `None` (a bodyless message) is handled by the caller, not here."""
+    if isinstance(body, (bytes, bytearray)):
+        yield bytes(body)
+    elif hasattr(body, "__aiter__"):
+        async for chunk in body:
+            yield chunk
+    elif hasattr(body, "__iter__"):
+        for chunk in body:
+            yield chunk
+    else:
+        raise TypeError("body must be None, bytes, or an (async) iterable of bytes")
+
+
+async def read_all(aiter):
+    """Drain an async byte-chunk iterator into a single `bytes`."""
+    return b"".join([chunk async for chunk in aiter])
+
+
+class BaseClientConnection:
+    """Shared public client-facade glue (h1/h2): async-context-manager entry/exit
+    + the `request` wrapper over the protocol-specific `send_request`. Subclasses
+    build `self._conn` (which exposes `connect`/`close`) and implement
+    `send_request` + `ready`.
+
+    `request(method, target, ...)` is a thin convenience over `send_request(Request)`;
+    it takes the method explicitly (no per-verb helpers like `get()` — httpunk is
+    low-level, and a single arbitrary shortcut would be inconsistent)."""
+
+    async def __aenter__(self) -> Self:
+        await self._conn.connect()
+        return self
+
+    async def __aexit__(self, exc_type: object, exc_value: object, exc_tb: object) -> bool:
+        await self._conn.close()
+        return False
+
+    def request(
+        self,
+        method: str,
+        target: str,
+        *,
+        headers: HeadersInput = None,
+        body: Body = None,
+        trailers: HeadersInput = None,
+    ) -> Awaitable[Response]:
+        return self.send_request(Request(method, target, headers=headers, body=body, trailers=trailers))
+
+
+class BaseServer(Generic[_RequestT]):
+    """Shared public server-facade glue (h1/h2): async-context-manager entry/exit
+    + the accept iterator over `self._conn.next_request()`. Subclasses build
+    `self._conn` (which exposes `start`/`close`/`next_request`)."""
+
+    async def __aenter__(self) -> Self:
+        await self._conn.start()
+        return self
+
+    async def __aexit__(self, exc_type: object, exc_value: object, exc_tb: object) -> bool:
+        await self._conn.close()
+        return False
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> _RequestT:
+        request = await self._conn.next_request()
+        if request is None:  # connection closed / can serve no more
+            raise StopAsyncIteration
+        return request
+
+    def accept(self) -> Awaitable[_RequestT | None]:
+        """Return the next incoming `ServerRequest`, or None once the connection
+        can serve no more. (`async for` over the server is the ergonomic form.)"""
+        return self._conn.next_request()
+
+    def graceful_shutdown(self) -> Awaitable[None]:
+        """Signal a graceful shutdown (non-blocking, like hyper's
+        `Connection::graceful_shutdown`): h2 sends GOAWAY and refuses new streams;
+        h1 stops reusing the connection and releases an idle read. In-flight work
+        finishes as the caller keeps driving the accept loop, which then ends and
+        closes. `httpunk.util.GracefulShutdown` coordinates this over many
+        connections (§11.3)."""
+        return self._conn.graceful_shutdown()