httpunk 0.1.4__tar.gz → 0.2.0__tar.gz

{httpunk-0.1.4 → httpunk-0.2.0}/Cargo.lock

@@ -55,9 +55,9 @@ checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
 
 [[package]]
 name = "h2"
-version = "0.4.16"
+version = "0.4.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9f37a958b41b3b19ee2707c06439c0e9e547e847223eb791ecb0cb821c65e27"
+checksum = "ef8e5e5a340588f4452631496976cf8636d4a7ecf600239fdc27615d2530bc16"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -118,7 +118,7 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
 [[package]]
 name = "httpunk"
-version = "0.1.4"
+version = "0.2.0"
 dependencies = [
  "bytes",
  "h2",

{httpunk-0.1.4 → httpunk-0.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "httpunk"
-version = "0.1.4"
+version = "0.2.0"
 description = "The Rust HTTP library for Python"
 authors = [
     "Giovanni Barillari <g@baro.dev>",
@@ -60,7 +60,7 @@ vendor-hyper-util = { path = "crates/vendor-hyper-util" }
 # THIRD-PARTY.md). Optional + gated behind the never-enabled `_audit` feature so
 # the pinned versions land in Cargo.lock for `cargo audit` / Dependabot advisory
 # coverage without pulling them (and tokio) into the build.
-h2 = { version = "=0.4.16", optional = true }
+h2 = { version = "=0.4.19", optional = true }
 hyper = { version = "=1.11.0", optional = true, default-features = false, features = ["http1", "client", "server"] }
 
 [profile.release]

{httpunk-0.1.4 → httpunk-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: httpunk
-Version: 0.1.4
-Classifier: Development Status :: 3 - Alpha
+Version: 0.2.0
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: MacOS
@@ -13,13 +13,14 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Internet :: WWW/HTTP
-Requires-Dist: tonio~=0.9.7 ; python_full_version >= '3.14' and extra == 'tonio'
+Requires-Dist: tonio~=0.9.12 ; python_full_version >= '3.14' and extra == 'tonio'
 Provides-Extra: tonio
 License-File: LICENSE
 Summary: The Rust HTTP library for Python
@@ -44,7 +45,7 @@ base for building HTTP clients and servers on top of.
 
 httpunk's API mirrors hyper's wherever possible.
 
-> **Note:** httpunk is in an early, alpha stage.
+> **Warning:** httpunk is in an early stage and still work in progress.
 
 > **Note:** httpunk was built with substantial help from LLMs, under human supervision.
 

{httpunk-0.1.4 → httpunk-0.2.0}/README.md

@@ -9,7 +9,7 @@ base for building HTTP clients and servers on top of.
 
 httpunk's API mirrors hyper's wherever possible.
 
-> **Note:** httpunk is in an early, alpha stage.
+> **Warning:** httpunk is in an early stage and still work in progress.
 
 > **Note:** httpunk was built with substantial help from LLMs, under human supervision.
 

httpunk-0.2.0/crates/vendor-h2/UPSTREAM_VERSION

@@ -0,0 +1 @@
+0.4.19

{httpunk-0.1.4 → httpunk-0.2.0}/crates/vendor-h2/src/hpack/encoder.rs

@@ -4,9 +4,12 @@ use super::{huffman, Header};
 use bytes::{BufMut, BytesMut};
 use http::header::{HeaderName, HeaderValue};
 
+const DEFAULT_MAX_ALLOWED_SIZE: usize = 4 * 1024;
+
 #[derive(Debug)]
 pub struct Encoder {
     table: Table,
+    max_allowed_size: usize,
     size_update: Option<SizeUpdate>,
     /// Reusable buffer for the encoded header block of a single frame.
     ///
@@ -25,13 +28,25 @@ enum SizeUpdate {
 
 impl Encoder {
     pub fn new(max_size: usize, capacity: usize) -> Encoder {
+        let max_size = max_size.min(DEFAULT_MAX_ALLOWED_SIZE);
+
         Encoder {
             table: Table::new(max_size, capacity),
+            max_allowed_size: DEFAULT_MAX_ALLOWED_SIZE,
             size_update: None,
             scratch: BytesMut::new(),
         }
     }
 
+    #[cfg(test)]
+    fn set_max_allowed_size(&mut self, max: usize) {
+        self.max_allowed_size = max;
+
+        if self.table.max_size() > max {
+            self.update_max_size(max);
+        }
+    }
+
     /// Takes the reusable buffer for one header-block encode.
     ///
     /// The buffer is returned by `return_scratch` once the encoded block has
@@ -51,6 +66,8 @@ impl Encoder {
     ///
     /// The next call to `encode` will include a dynamic size update frame.
     pub fn update_max_size(&mut self, val: usize) {
+        let val = val.min(self.max_allowed_size);
+
         match self.size_update {
             Some(SizeUpdate::One(old)) => {
                 if val > old {
@@ -614,6 +631,7 @@ mod test {
         assert_eq!(Some(SizeUpdate::Two(0, 100)), encoder.size_update);
 
         let mut encoder = Encoder::default();
+        encoder.set_max_allowed_size(8000);
         encoder.update_max_size(8000);
         assert_eq!(Some(SizeUpdate::One(8000)), encoder.size_update);
 
@@ -701,6 +719,7 @@ mod test {
     #[test]
     fn test_large_size_update() {
         let mut encoder = Encoder::default();
+        encoder.set_max_allowed_size(usize::MAX);
 
         encoder.update_max_size(1912930560);
         assert_eq!(Some(SizeUpdate::One(1912930560)), encoder.size_update);
@@ -710,6 +729,22 @@ mod test {
         assert_eq!([63, 225, 129, 148, 144, 7], &dst[..]);
     }
 
+    #[test]
+    fn test_large_size_update_is_capped() {
+        let mut encoder = Encoder::new(0, 0);
+
+        encoder.update_max_size(1912930560);
+        assert_eq!(
+            Some(SizeUpdate::One(DEFAULT_MAX_ALLOWED_SIZE)),
+            encoder.size_update
+        );
+
+        let mut dst = BytesMut::with_capacity(3);
+        encoder.encode_size_updates(&mut dst);
+        assert_eq!([63, 225, 31], &dst[..]);
+        assert_eq!(DEFAULT_MAX_ALLOWED_SIZE, encoder.table.max_size());
+    }
+
     #[test]
     #[ignore]
     fn test_evicted_overflow() {

{httpunk-0.1.4 → httpunk-0.2.0}/httpunk/_backend/asyncio.py

@@ -257,6 +257,17 @@ class AsyncioBackend:
         drives the `close_notify`), so no plain/TLS split like tonio."""
         transport.close()
 
+    def spawn_without_results(self, *coros):
+        """Spawn task(s) NOW, discarding their results; returns the join handle
+        (see the tonio backend's twin for the full contract: await-once by a
+        single owner, no cancellation surface, coroutines route their own
+        errors). One coro -> its Task; several -> a gather with
+        `return_exceptions=True`, so the join waits for ALL of them exactly
+        like tonio's barrier does."""
+        if len(coros) == 1:
+            return asyncio.ensure_future(coros[0])
+        return asyncio.gather(*coros, return_exceptions=True)
+
     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
@@ -294,6 +305,13 @@ class AsyncioBackend:
         q = asyncio.Queue()
         return _QueueSender(q), _QueueReceiver(q)
 
+    # Abrupt-peer-teardown exceptions (see the tonio backend's twin attribute):
+    # an RST surfaces as `ConnectionError` from `connection_lost`; a TLS close
+    # without close_notify as `ssl.SSLEOFError` (asyncio's SSL layer raises it
+    # on an unexpected EOF). The h1 server maps these at the request-head
+    # boundary to a clean end-of-iteration (F47).
+    broken_transport_errors = (ConnectionError, _ssl.SSLEOFError)
+
     # 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).

{httpunk-0.1.4 → httpunk-0.2.0}/httpunk/_backend/tonio.py

@@ -13,7 +13,7 @@ from tonio.colored.net.tls import open_tls_over_tcp_stream as _open_tls_over_tcp
 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
-from tonio.exceptions import CancelledError
+from tonio.exceptions import CancelledError, ResourceBroken
 
 
 class _TonioSemaphore:
@@ -106,6 +106,27 @@ class TonioBackend:
         else:
             transport.close()
 
+    # Exceptions `receive_some`/`send_all` raise when the peer tears the
+    # transport down ABRUPTLY instead of a clean EOF: an RST on plain TCP
+    # (`ConnectionError`: ConnectionResetError/BrokenPipeError), or a TLS close
+    # without close_notify (tonio wraps the SSLEOFError in `ResourceBroken`) —
+    # which httpunk's own sync `close_transport` produces by design (abortive
+    # close, F33a), so any httpunk client hanging up makes the peer see one.
+    # The h1 server maps these at the request-head boundary to a clean
+    # end-of-iteration (F47).
+    broken_transport_errors = (ConnectionError, ResourceBroken)
+
+    # Spawn task(s) NOW, discarding their results; returns the join handle.
+    # `await handle` resolves once ALL of them finished — exactly one owner
+    # awaits it, exactly once (tonio's handle is Barrier-based one-shot). NO
+    # cancellation surface, by design: this is the primitive for tasks that
+    # must never be cancelled (flush/handoff obligations — the h2 write pump,
+    # the h1 idle watcher); a group that needs teardown-with-cancel uses
+    # `scope`. Spawned coroutines must not let exceptions escape (drivers
+    # route errors into connection state); an escaped one surfaces at the
+    # join in a backend-specific shape and is a driver bug, not API.
+    spawn_without_results = staticmethod(_colored.spawn.without_results)
+
     select = staticmethod(_colored.select)
     scope = staticmethod(_colored.scope)
     lock = _Lock

{httpunk-0.1.4 → httpunk-0.2.0}/httpunk/exceptions.py

@@ -17,6 +17,15 @@ state-machine / flow-control / API-misuse errors raised by the extension share i
 
 `error_code` attributes are `H2Reason` members for known codes (an `IntEnum`, so
 they compare equal to ints), or a plain int for codes outside the RFC set.
+
+An HTTP/1 `send_request` failure raised before the request was handed to the
+writer carries `request_unsent = True` on the exception instance (whatever its
+type — `ConnectionClosedError`, or the unexpected-bytes poison error): nothing
+reached the wire, so the request is safe to retry with any body, streamed
+included. The mirror of hyper's `TrySendError { message: Some(request) }`
+give-back (client/conn/http1.rs L247-263; proto/h1/dispatch.rs L711-733). Read
+it with `getattr(exc, "request_unsent", False)` — it is absent once the write
+may have begun.
 """
 
 from __future__ import annotations

{httpunk-0.1.4 → httpunk-0.2.0}/httpunk/h1/client.py

@@ -12,6 +12,7 @@ Cross-reference: hyper `client::conn::http1` (`SendRequest`/`Connection`) +
 
 from __future__ import annotations
 
+import threading
 from collections.abc import Awaitable
 from typing import TYPE_CHECKING, Any
 
@@ -61,6 +62,12 @@ class Connection(H1ConnectionBase):
     - `Expect: 100-continue` and the request's `Connection: close` are non-gaps for
       the client: hyper hard-codes `expect_continue: false` (role.rs L1161) and
       derives reuse solely from the response's keep-alive (conn.rs L294).
+    - While reusable-idle, a watcher task holds read interest — the re-expression
+      of hyper's always-polled `Connection` future (see `_watch_idle`) — so an
+      idle peer close or stray byte flips `closed`/`error` when it happens, and
+      a `send_request` failure raised before the request was handed to the
+      writer carries `request_unsent = True` (hyper's `TrySendError` message
+      give-back, client/conn/http1.rs L247-263).
     """
 
     def __init__(self, transport, *, authority=None, backend=None):
@@ -87,22 +94,151 @@ class Connection(H1ConnectionBase):
         # (a scope can't be re-armed after `cancel()`), so reuse isn't blocked.
         self._writer_scope = None
         self._writer_done = None
+        # The idle watcher: a background task parked in ONE read while the
+        # connection is reusable-idle — the Python re-expression of hyper's
+        # always-polled `Connection` future, which keeps read interest registered
+        # for the whole idle period (dispatch.rs L287 falls through to
+        # `poll_read_keep_alive`, conn.rs L435-443; `force_io_read` returns
+        # Pending, conn.rs L510-520), so a peer FIN or stray byte is observed
+        # when it ARRIVES, not at the next send. Python coroutines can't hold
+        # read interest without a parked task — the watcher is that task
+        # (divergence in mechanism only; behavior matches hyper, see
+        # `_watch_idle`). The watcher is NEVER cancelled or signalled: a parked
+        # `receive_some` legitimately ends only via data, EOF, or transport
+        # close (cancelling one leaves the socket's read registration armed —
+        # tonio contract), so its read completes naturally and is dispatched by
+        # `_exchange_active`: while idle it enforces the idle rules; once an
+        # exchange has started, the bytes that complete it ARE the response's
+        # first bytes, handed to `_read_head` via `_watcher_data`/`_watcher_error`
+        # — exactly hyper's structure, where one poll loop owns the read across
+        # the idle->busy transition. A bare task via `spawn_without_results`
+        # (the cancel-free seam primitive — a scope is for groups that DO get
+        # cancelled, like the body writer's): the handle IS the per-idle-period
+        # join, awaited by `_read_head` (handoff) or a teardown path.
+        self._watcher_handle = None
+        self._watcher_data = None
+        self._watcher_error = None
+        self._exchange_active = False
+        # Guards the take-ownership pop of the background-task handles
+        # (`_writer_scope`, `_watcher_handle`): a `close()` from another thread
+        # (tonio is work-stealing) can race the exchange's own join/teardown
+        # for the SAME handle — a second `Scope.__aexit__` raises RuntimeError
+        # (tonio `_exit`), spawn handles are await-once, and the handoff-field
+        # consumption must have one owner — the pop under the lock makes the
+        # loser see None. Held only for the sync swap, never across an await.
+        # Everything else the watcher shares is lock-free by construction: the
+        # handoff fields are published by the join, the handles/flag resets by
+        # the slot semaphore, and the `_exchange_active` read by the runtime's
+        # causal chain (flag-set -> head write -> peer response -> poller wake).
+        self._scopes_lock = threading.Lock()
 
     async def connect(self):
-        pass  # HTTP/1 has no connection preface / handshake (unlike h2)
+        # HTTP/1 has no connection preface / handshake (unlike h2), but hyper's
+        # `Connection` future is polled from the moment it is spawned — the
+        # dial-to-first-send window has read interest upstream, so it is watched
+        # here too.
+        self._start_watcher()
 
     async def _teardown_writer(self, *, cancel):
         """Finish with the in-flight body writer: `cancel=True` aborts it (still
         running — an early response we didn't wait out), then joins; `cancel=False`
-        just joins an already-finished writer (instant). Idempotent."""
-        scope = self._writer_scope
+        just joins an already-finished writer (instant). Idempotent, and
+        single-owner via the pop under `_scopes_lock`: a `close()` from another
+        thread can race the exchange's own teardown for the SAME scope, and a
+        second `Scope.__aexit__` raises RuntimeError (tonio `_exit`) — the
+        losing popper sees None and returns instead."""
+        with self._scopes_lock:
+            scope, self._writer_scope, self._writer_done = self._writer_scope, None, None
         if scope is None:
             return
-        self._writer_scope = self._writer_done = None
         if cancel:
             scope.cancel()
         await scope.__aexit__(None, None, None)
 
+    def _start_watcher(self):
+        """Arm the idle watcher (see `_watch_idle`) for one idle period — SYNC:
+        the bare-task spawn suspends nothing, so callers have no interruption
+        window. They guarantee no exchange can be reading: `connect()` runs
+        before any request, and `release_slot` starts it BEFORE releasing the
+        slot — tonio is work-stealing, so a waiter resumed by the release can
+        run in parallel immediately, and the semaphore release/acquire is the
+        happens-before edge that guarantees it observes the watcher and takes
+        its read as the response's first read (F55 single-reader). No-op if the
+        connection can serve no more requests."""
+        if self._closed or self.error is not None or self.transport is None:
+            return
+        self._exchange_active = False
+        self._watcher_data = self._watcher_error = None
+        self._watcher_handle = self.backend.spawn_without_results(self._watch_idle())
+
+    async def _join_watcher(self):
+        """JOIN the idle watcher (never cancel/signal it — see `_watch_idle`):
+        await its handle, which resolves when its single read has completed
+        and publishes the handoff fields. Idempotent; instant when none is
+        armed or it already finished. On teardown paths the transport is
+        closed first, which is what ends the parked read. The handle is taken
+        via a pop under `_scopes_lock` so a racing `close()` and exchange join
+        have one owner (handles are await-once); the loser sees None and
+        returns — the connection state it then observes is force-closed either
+        way."""
+        with self._scopes_lock:
+            handle, self._watcher_handle = self._watcher_handle, None
+        if handle is None:
+            return
+        await handle
+
+    async def _watch_idle(self):
+        """ONE read, dispatched by connection state when it completes; the
+        spawn handle `_join_watcher` awaits resolves on exit. The
+        watcher is never cancelled or woken by a signal — a parked
+        `receive_some` legitimately ends only via data, EOF, or transport close
+        (cancellation would leave the socket's read registration armed for a
+        dead task, corrupting the next read). This is also hyper's structure:
+        the same poll loop owns the read across the idle->busy transition
+        (dispatch.rs L287 `poll_read` -> `poll_read_keep_alive` while idle, the
+        response read once busy), so there is no reader handoff to cancel.
+
+        Dispatch of the completed read (`_exchange_active` is set by
+        `send_request` before it writes):
+
+        - exchange active -> these are the response's first bytes (or `b""` =
+          EOF before the head, or a transport error): store them in
+          `_watcher_data`/`_watcher_error` for `_read_head`, touch nothing else
+          — the exchange's own paths handle errors exactly as if it had done
+          this read itself.
+        - idle EOF -> hyper's CLEAN idle close: "found EOF on idle connection,
+          closing" (conn.rs L471-481; `should_error_on_eof` is false when idle —
+          conn.rs L201-204). `_closed` only, NO error recorded: a pool discards
+          silently. The transport is closed NOW — hyper's connection task winds
+          down and drops its io (dispatch.rs L152-160) — so the socket never
+          parks in CLOSE_WAIT.
+        - idle bytes -> `new_unexpected_message` (conn.rs L484-489): poison +
+          close. Bytes racing `send_request`'s flag-set land in the same window
+          hyper has between `require_empty_read` and the head write — either
+          side of it, behavior matches upstream.
+        - idle transport error -> fail (hyper `force_io_read` io error ->
+          `state.close()`, conn.rs L510-520) — unless a concurrent `close()`
+          already committed the flags (its transport close is what woke us)."""
+        transport = self.transport
+        if transport is None:  # a racing close() nulled it before we ran (F59)
+            return
+        try:
+            data = await transport.receive_some(65536)
+        except Exception as exc:
+            if self._exchange_active:
+                self._watcher_error = exc  # surfaced by _read_head's first read
+            elif not self._closed:
+                self._fail(exc)
+            return
+        if self._exchange_active:
+            self._watcher_data = data  # the response's first bytes (b"" = EOF)
+            return
+        if data:
+            self.poison_unexpected(len(data))
+            return
+        self._closed = True
+        self._close_transport()
+
     def _acquire(self):
         return self._slot.acquire()  # blocks until the single in-flight slot is free
 
@@ -123,27 +259,47 @@ class Connection(H1ConnectionBase):
         # modeled by the 1-permit slot.
         await self._acquire()
         self._busy = True
+        # The watcher may have observed EOF/bytes and closed/poisoned the
+        # connection while `_acquire` waited — the mirror of
+        # `SendRequest::poll_ready` failing once the connection task died
+        # (client/conn/http1.rs L156-180). `request_unsent` mirrors hyper
+        # handing the request back when the dispatch channel refuses it —
+        # `TrySendError { message: Some(req) }`, client/conn/http1.rs L247-263
+        # — and a queued-never-taken request canceled on a connection error
+        # (the idle-bytes poison, proto/h1/dispatch.rs L711-733): nothing was
+        # written, so the caller may safely retry ANY body, streamed included.
         if self._closed or self.error is not None:
             self._busy = False
             self._slot.release()
-            raise self.error or ConnectionClosedError("connection closed")
-        # hyper's always-polled Connection validates the read buffer is empty before it
-        # will send (require_empty_read -> new_unexpected_message, conn.rs L463-465; its
-        # regression test client_read_bytes_before_writing_request): a server may not
-        # send anything before the client's next request. Lacking a background read task
-        # to notice bytes arriving while idle, poll once here, just before writing — any
-        # bytes waiting are a protocol violation, so poison + fail rather than write a
-        # request that would misparse them as its response (F31, problem b). (An idle
-        # peer *close* still can't be told apart from "no data ready" by a non-blocking
-        # read, so it surfaces only as the write below failing — a known limitation
-        # short of hyper's always-polled connection task.)
+            exc = self.error or ConnectionClosedError("connection closed")
+            exc.request_unsent = True
+            raise exc
+        # `require_empty_read`'s buffered-bytes fast path at send time (conn.rs
+        # L463-465; regression test client_read_bytes_before_writing_request):
+        # a server may not send anything before the client's next request, and
+        # hyper's single poll loop serializes this check ahead of the write even
+        # under scheduler starvation — bytes ALREADY DELIVERED when a request is
+        # submitted are always a violation, never that request's "response". A
+        # parked watcher can't reproduce that ordering (its wake races this
+        # task), so the check runs here too, BEFORE `_exchange_active` is set —
+        # the ordering that makes it safe beside a parked watcher: if it steals
+        # the violation bytes, the watcher's spurious wake (empty read / closed
+        # transport) still dispatches through the idle rules against an
+        # already-poisoned connection and touches nothing (F31, problem b).
         pending = self.backend.receive_nowait(self.transport, 65536)
         if pending:
-            self.poison_unexpected(len(pending))
-            self._fail(self.error)  # the stream is corrupt — close, don't reuse
+            self.poison_unexpected(len(pending))  # records the error AND closes
             self._busy = False
             self._slot.release()
+            self.error.request_unsent = True
             raise self.error
+        # The exchange starts NOW: the watcher is not stopped (its parked read
+        # is never cancelled — see `_watch_idle`); this sync flag redirects its
+        # completing read from the idle rules to the exchange, whose `_read_head`
+        # joins it and takes the bytes as the response's first read. Bytes
+        # arriving from here to the head write are hyper's own race window
+        # (require_empty_read ran; the write turn follows).
+        self._exchange_active = True
         try:
             codec = H1Codec()
             content_length, chunked = self._body_framing(body)
@@ -199,6 +355,12 @@ class Connection(H1ConnectionBase):
             write_error = []
             scope = self.backend.scope()
             await scope.__aenter__()
+            # The `request_unsent` boundary: this spawn is httpunk's analogue of
+            # hyper's dispatcher taking the request off the channel (dispatch.rs
+            # `poll_msg`). From here on a failure NEVER carries the marker — in
+            # hyper, once taken, errors return `message: None` even if no byte
+            # reached the wire (an encoded-but-unflushed head is not handed
+            # back), and this boundary mirrors that exactly.
             scope.spawn(self._write_request(codec, head, body, body_done, write_error, body_failed, trailers))
             self._writer_scope, self._writer_done = scope, body_done
             try:
@@ -223,6 +385,11 @@ class Connection(H1ConnectionBase):
                 # the caller owns; this driver won't touch the transport again
                 # (hyper `on_upgrade` / `Connection::into_parts`).
                 await self._teardown_writer(cancel=True)  # the request-body write is moot
+                # No idle watcher can be running here: `_read_head` consumed it
+                # (its read delivered this 101 head's first bytes) and one is
+                # only re-armed by `release_slot` on a reuse verdict, which the
+                # upgrade path never reaches — a detached transport is never
+                # watched.
                 upgraded = H1Upgraded(self.transport, codec.take_body())
                 self._detach()
                 self._busy = False
@@ -247,6 +414,10 @@ class Connection(H1ConnectionBase):
             self._fail(exc)  # sync poison BEFORE the teardown suspension (see release_slot)
             try:
                 await self._teardown_writer(cancel=True)
+                # A watcher not yet consumed by `_read_head` (failure before it
+                # ran): `_fail` closed the transport, which is what ends its
+                # parked read — join it (never cancel).
+                await self._join_watcher()
             finally:
                 self._busy = False
                 self._slot.release()
@@ -283,8 +454,33 @@ class Connection(H1ConnectionBase):
         # hyper: conn.rs `can_read_head` (L175) + `read_head` -> role.rs
         # `Client::parse` (L1013), which loops past 1xx informational responses.
         buffered = 0
+        data = None
+        if self._watcher_handle is not None:
+            # An idle watcher is armed: its parked `receive_some` is the
+            # connection's single reader (F55), so the response's FIRST read is
+            # its completing read — join it and take the handoff (bytes, `b""`
+            # EOF, or a transport error re-raised here, exactly as if this task
+            # had done the read). Only after the join does this task own the
+            # transport. Hyper needs no join: one poll loop does both reads.
+            await self._join_watcher()
+            exc, self._watcher_error = self._watcher_error, None
+            if exc is not None:
+                raise exc
+            data, self._watcher_data = self._watcher_data, None
+            if data is None:
+                # The watcher exited without a handoff: it dispatched through
+                # the IDLE rules against this exchange — either a racing
+                # close() tore the connection down under us, or bytes/EOF
+                # landed concurrently with the exchange start and the watcher
+                # saw the flag before this task's write of it was visible
+                # (free-threaded: the junk race has no causal ordering, both
+                # dispatches are legitimate). Surface the recorded verdict —
+                # the unexpected-bytes poison (hyper `new_unexpected_message`)
+                # or the clean close — not a generic error that would mask it.
+                raise self.error or ConnectionClosedError("connection closed")
         while True:
-            data = await self.transport.receive_some(65536)
+            if data is None:
+                data = await self.transport.receive_some(65536)
             if not data:
                 # EOF before a full head. If the body write also failed (server
                 # closed both directions), surface that as the cause.
@@ -303,6 +499,7 @@ class Connection(H1ConnectionBase):
             # just fails the connection (hyper `Parse::TooLarge`).
             if buffered >= _MAX_HEAD_SIZE:
                 raise ValueError("response head too large (Parse::TooLarge)")
+            data = None
 
     async def _await_body_failure(self, body_failed, write_error):
         # Raced against `_read_head` (once per request, in send_request): if the request
@@ -315,13 +512,19 @@ class Connection(H1ConnectionBase):
         raise write_error[0]
 
     def poison_unexpected(self, nbytes):
-        """The server sent `nbytes` unsolicited bytes past the response body — an
+        """The server sent `nbytes` unsolicited bytes outside a response — an
         HTTP/1 protocol violation (a server may not send anything before the next
-        request). hyper's client fails the connection here via `require_empty_read`
-        -> `new_unexpected_message` (conn.rs L463-465); we record the error so the
-        next `send_request`/`wait_idle` raises it (the slot release closes it)."""
+        request). hyper's client fails the connection via `require_empty_read` ->
+        `new_unexpected_message` (conn.rs L463-465 buffered, L484-489 read) and
+        the errored connection task then winds down, dropping its io
+        (dispatch.rs `poll_catch` L123-141) — so record the error AND close, for
+        every caller (the idle watcher, the send-time guard, the past-body
+        leftover check in share.py). The next `send_request`/`wait_idle` raises
+        the recorded error."""
         if self.error is None:
             self.error = ValueError(f"received {nbytes} unexpected bytes on an idle HTTP/1 connection")
+        self._closed = True
+        self._close_transport()
 
     async def release_slot(self, resp_keep_alive):
         """Free the in-flight slot once the caller has finished the response. Reuse
@@ -341,24 +544,38 @@ class Connection(H1ConnectionBase):
         poisoned, and on reuse the exchange genuinely completed, so freeing the
         slot is correct even if the writer join was cut short."""
         fully_sent = self._writer_done is None or self._writer_done.is_set()
-        if not (resp_keep_alive and fully_sent):
+        reuse = resp_keep_alive and fully_sent
+        if not reuse:
             self._closed = True
             self._close_transport()  # sync by design (backend.close_transport)
         try:
             await self._teardown_writer(cancel=not fully_sent)
+            if reuse:
+                # The connection is reusable-idle again: restore hyper's idle
+                # read interest. Started BEFORE the slot release below (see
+                # `_start_watcher` — the semaphore is the visibility edge for a
+                # parallel waiter); `_start_watcher` no-ops if a racing
+                # close()/failure landed during the writer join.
+                self._start_watcher()
         finally:
             self._busy = False
             self._slot.release()
 
     async def close(self):
         # Commit `_closed` + close the transport FIRST (the base close is sync —
-        # no suspension), then abort + join a still-running background writer.
-        # The join can be interrupted (it suspends); a force-close must never
-        # come away with `closed` still False.
+        # no suspension): the transport close is what ends the idle watcher's
+        # parked read (it sees `_closed` and exits quietly) — then join it and
+        # abort + join a still-running background writer. The joins can be
+        # interrupted (they suspend); a force-close must never come away with
+        # `closed` still False.
         await super().close()
+        await self._join_watcher()
         await self._teardown_writer(cancel=True)
 
     def _fail(self, exc):
+        # Sync poison + close. No live watcher to stop here: `_fail` runs only
+        # inside an exchange (slot held, watcher joined at send_request entry)
+        # or from the watcher itself.
         if self.error is None and not isinstance(exc, ConnectionClosedError):
             self.error = exc
         self._closed = True
@@ -412,5 +629,12 @@ class H1Connection(BaseClientConnection):
         absolute-form for a proxy, and an authority (``"host:port"``) is
         authority-form for CONNECT. The caller supplies the ``Host`` header (we
         never auto-add it), exactly like hyper's `client::conn::http1`.
+
+        A failure raised before the request was handed to the writer carries
+        ``request_unsent = True`` on the exception: nothing reached the wire, so
+        the request — any body, streamed included — is safe to retry. The mirror
+        of hyper handing the request back in `TrySendError { message: Some }`
+        (client/conn/http1.rs L247-263; proto/h1/dispatch.rs L711-733). Absent
+        (falsy) once the write may have begun.
         """
         return self._conn.send_request(request.method, request.target, request.headers, request.body, request.trailers)