without-http 0.0.2__tar.gz → 0.0.3__tar.gz

{without_http-0.0.2 → without_http-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: without-http
-Version: 0.0.2
+Version: 0.0.3
 Summary: A sans-IO-backed ASGI server and HTTP client for without: h11/h2/wsproto over asyncio sockets.
 Author: Josh Karpel
 Author-email: Josh Karpel <josh.karpel@gmail.com>
@@ -16,8 +16,8 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
-Requires-Dist: without-core==0.0.2
-Requires-Dist: without-asgi==0.0.2
+Requires-Dist: without-core==0.0.3
+Requires-Dist: without-asgi==0.0.3
 Requires-Dist: h11>=0.16
 Requires-Dist: h2>=4.1
 Requires-Dist: wsproto>=1.2
@@ -43,15 +43,15 @@ translate between typed events and the ASGI dicts an app expects.
 ```python
 from without import sleep_forever
 from without_asgi import make_asgi_app
-from without_http import ConnectionPool, serving
+from without_http import ConnectionPool, request, serving
 
 app = make_asgi_app(lifespan, http=router.dispatch, websocket=sockets.dispatch)
 
 async with serving(app, host="127.0.0.1", port=8000):
-    await sleep_forever()   # run until cancelled
+    await sleep_forever()  # run until cancelled
 
 async with ConnectionPool() as pool:
-    async with pool.request("GET", "http://127.0.0.1:8000/items") as (head, body):
+    async with request(pool, "GET", "http://127.0.0.1:8000/items") as (head, body):
         assert head.status == 200
         data = await body.read()
 ```
@@ -59,11 +59,16 @@ async with ConnectionPool() as pool:
 Because `without-http` speaks plain ASGI to the app, *any* ASGI app runs over it,
 interchangeably with uvicorn. The server handles TLS, HTTP/2 (by ALPN or prior
 knowledge), keep-alive, WebSockets over the HTTP/1.1 upgrade, per-handler
-isolation, and flow control. The client is a `ConnectionPool` with a `(head,
-body)` response split, buffered and streaming bodies in both directions,
-opt-in trailers, HTTP/2 multiplexing, per-host connection bounds, per-phase
-request timeouts, consumer-driven duplex (with bidirectional streaming over
-HTTP/2), and `stack`-composed middleware.
+isolation, and flow control. A client is a function from a request to a response, and
+a `ConnectionPool` is the one that answers over the network: a `(head, body)` response
+split, buffered and streaming bodies in both directions, opt-in trailers, HTTP/2
+multiplexing, per-host connection bounds, per-phase request timeouts, consumer-driven
+duplex (with bidirectional streaming over HTTP/2), and `stack`-composed middleware.
+
+`without_http.testing` carries the same interface into a test: a mock client that answers
+from a function, an ASGI client that drives an app in memory, and a loopback client that
+runs the real wire protocols over no socket at all, plus the raw in-memory endpoints
+those are built from, for a test that writes frames rather than requests.
 
 See the
 [`without-http` guide](https://without.help/without-http/)

{without_http-0.0.2 → without_http-0.0.3}/README.md

@@ -17,15 +17,15 @@ translate between typed events and the ASGI dicts an app expects.
 ```python
 from without import sleep_forever
 from without_asgi import make_asgi_app
-from without_http import ConnectionPool, serving
+from without_http import ConnectionPool, request, serving
 
 app = make_asgi_app(lifespan, http=router.dispatch, websocket=sockets.dispatch)
 
 async with serving(app, host="127.0.0.1", port=8000):
-    await sleep_forever()   # run until cancelled
+    await sleep_forever()  # run until cancelled
 
 async with ConnectionPool() as pool:
-    async with pool.request("GET", "http://127.0.0.1:8000/items") as (head, body):
+    async with request(pool, "GET", "http://127.0.0.1:8000/items") as (head, body):
         assert head.status == 200
         data = await body.read()
 ```
@@ -33,11 +33,16 @@ async with ConnectionPool() as pool:
 Because `without-http` speaks plain ASGI to the app, *any* ASGI app runs over it,
 interchangeably with uvicorn. The server handles TLS, HTTP/2 (by ALPN or prior
 knowledge), keep-alive, WebSockets over the HTTP/1.1 upgrade, per-handler
-isolation, and flow control. The client is a `ConnectionPool` with a `(head,
-body)` response split, buffered and streaming bodies in both directions,
-opt-in trailers, HTTP/2 multiplexing, per-host connection bounds, per-phase
-request timeouts, consumer-driven duplex (with bidirectional streaming over
-HTTP/2), and `stack`-composed middleware.
+isolation, and flow control. A client is a function from a request to a response, and
+a `ConnectionPool` is the one that answers over the network: a `(head, body)` response
+split, buffered and streaming bodies in both directions, opt-in trailers, HTTP/2
+multiplexing, per-host connection bounds, per-phase request timeouts, consumer-driven
+duplex (with bidirectional streaming over HTTP/2), and `stack`-composed middleware.
+
+`without_http.testing` carries the same interface into a test: a mock client that answers
+from a function, an ASGI client that drives an app in memory, and a loopback client that
+runs the real wire protocols over no socket at all, plus the raw in-memory endpoints
+those are built from, for a test that writes frames rather than requests.
 
 See the
 [`without-http` guide](https://without.help/without-http/)

{without_http-0.0.2 → without_http-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "without-http"
-version = "0.0.2"
+version = "0.0.3"
 description = "A sans-IO-backed ASGI server and HTTP client for without: h11/h2/wsproto over asyncio sockets."
 readme = "README.md"
 license = "MIT"
@@ -23,8 +23,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "without-core==0.0.2",
-    "without-asgi==0.0.2",
+    "without-core==0.0.3",
+    "without-asgi==0.0.3",
     "h11>=0.16",
     "h2>=4.1",
     "wsproto>=1.2",

{without_http-0.0.2 → without_http-0.0.3}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "without-http"
-version = "0.0.2"
+version = "0.0.3"
 description = "A sans-IO-backed ASGI server and HTTP client for without: h11/h2/wsproto over asyncio sockets."
 readme = "README.md"
 license = "MIT"
@@ -26,8 +26,8 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "without-core==0.0.2",
-    "without-asgi==0.0.2",
+    "without-core==0.0.3",
+    "without-asgi==0.0.3",
     "h11>=0.16",
     "h2>=4.1",
     "wsproto>=1.2",

{without_http-0.0.2 → without_http-0.0.3}/src/without_http/__init__.py

@@ -1,7 +1,8 @@
-from without_http.client import ClientExchange
+from without_http.client import Client
 from without_http.client import ClientMiddleware
 from without_http.client import ClientRequest
 from without_http.client import ClientResponse
+from without_http.client import Connect
 from without_http.client import ConnectionPool
 from without_http.client import CookieJar
 from without_http.client import ResponseBody
@@ -9,7 +10,9 @@ from without_http.client import ResponseHead
 from without_http.client import ResponseTrailers
 from without_http.client import add_headers
 from without_http.client import cookies
+from without_http.client import deadline
 from without_http.client import follow_redirects
+from without_http.client import request
 from without_http.client import stack
 from without_http.client import wrap
 from without_http.h2_wire import early_hint_headers
@@ -42,10 +45,11 @@ from without_http.ws_wire import ws_events_from_outbound
 
 __all__ = [
     "ALPN_PROTOCOLS",
-    "ClientExchange",
+    "Client",
     "ClientMiddleware",
     "ClientRequest",
     "ClientResponse",
+    "Connect",
     "ConnectTimeout",
     "ConnectionPool",
     "CookieJar",
@@ -62,12 +66,14 @@ __all__ = [
     "WriteTimeout",
     "add_headers",
     "cookies",
+    "deadline",
     "early_hint_headers",
     "follow_redirects",
     "h11_events_from_outbound",
     "inbound_from_event",
     "is_websocket_upgrade",
     "receive_buffer_size",
+    "request",
     "request_headers",
     "response_headers",
     "response_status_and_headers",

{without_http-0.0.2 → without_http-0.0.3}/src/without_http/client.py

@@ -16,6 +16,7 @@ from datetime import UTC
 from datetime import datetime
 from email.utils import parsedate_to_datetime
 from typing import NamedTuple
+from typing import Protocol
 from typing import Self
 from urllib.parse import SplitResult
 from urllib.parse import urljoin
@@ -30,7 +31,9 @@ from without import Endo
 from without import Stream
 from without import cancel_futures
 from without import stack
+from without_asgi import Content
 from without_asgi import RawHeaders
+from without_asgi.headers import merge
 
 from without_http.h2_wire import request_headers
 from without_http.h2_wire import response_status_and_headers
@@ -86,18 +89,26 @@ class Origin:
 @dataclass(frozen=True, slots=True)
 class ClientRequest:
     """
-    A client request as a value: the head plus a streaming body.
+    A client request as a value: the head, a streaming body, and its deadline.
 
     The body is a `Stream[bytes]` (an async iterable of chunks), so a request can be
     buffered (one chunk) or streamed (many), the upload half of the buffered/streaming
-    matrix. Because the whole request is the value a `ClientExchange` transforms,
-    middleware can rewrite it: add headers, change the URL, wrap the body.
+    matrix. Because the whole request is the value a `Client` transforms, middleware can
+    rewrite it: add headers, change the URL, wrap the body, extend the deadline.
+
+    `timeout` bounds each phase of *this* request (see `Timeout`), and defaults to no
+    bounds at all. It rides on the request rather than on the transport because a
+    deadline is the caller's policy, not the connection's: it is the caller's time
+    budget that decides when slow progress is worse than failure. Carrying it here is
+    what lets a `Client` be a plain one-argument function, and what lets middleware
+    (`deadline`, or a retry that shortens each attempt) set it like any other field.
     """
 
     method: str
     url: str
     headers: RawHeaders = ()
     body: Stream[bytes] = field(default_factory=_empty_body)
+    timeout: Timeout = _NO_TIMEOUT
 
 
 @dataclass(frozen=True, slots=True)
@@ -185,16 +196,16 @@ class ClientResponse(NamedTuple):
     A client response as a value: the head paired with the body.
 
     `head` is the parsed `ResponseHead` (status + headers), available the instant
-    `await exchange(request)` returns. `body` is a `ResponseBody`, a once-consumable
+    `await client(request)` returns. `body` is a `ResponseBody`, a once-consumable
     stream that releases its connection when it ends or is closed.
 
     A `NamedTuple` so a caller can take it whole (`response.head`, `response.body`) or
     unpack it (`head, body = response`) with each field keeping its precise type, which a
     `__iter__` on a dataclass could not give. The two halves are independent, the
     consumer split that mirrors how a server consumes a request (a `scope` value plus a
-    body stream): branch on `head` without touching `body`. `ConnectionPool.request`
-    yields this value and closes `body` on exit; it is also what a `ClientExchange`
-    rewrites (by constructing a new one, since a `NamedTuple` has no `dataclasses.replace`).
+    body stream): branch on `head` without touching `body`. `request` yields this value
+    and closes `body` on exit; it is also what a `ClientMiddleware` rewrites (by
+    constructing a new one, since a `NamedTuple` has no `dataclasses.replace`).
     """
 
     head: ResponseHead
@@ -242,17 +253,21 @@ async def _releasing(
     return armed
 
 
-# A client exchange is the dual of a server handler: where a handler maps a request to
-# a response over streams, an exchange maps a whole `ClientRequest` to a
-# `ClientResponse`. A `ClientMiddleware` wraps an exchange into an exchange (`Endo`):
-# it can rewrite the request before, or the response after, the inner exchange runs.
-# This is the zero-context case of the shared `stack` vocabulary: a server middleware
-# is `(handler, state, scope)`, a client one needs no context (the request is the value
-# it transforms, not a fixed scope), so it is simply `(exchange) -> exchange`, and the
-# same `stack` composes them. State a middleware must keep lives in a closure (see
-# `cookies`), as it does server-side.
-type ClientExchange = Callable[[ClientRequest], Awaitable[ClientResponse]]
-type ClientMiddleware = Endo[ClientExchange]
+# A client *is* a function from a request to a response, the dual of a server handler:
+# where a handler maps a request to a response over streams, a client maps a whole
+# `ClientRequest` to a `ClientResponse`. Everything that answers a request is one, and
+# they are interchangeable by construction: a `ConnectionPool` over the network, a
+# canned response table in a test, an ASGI app driven in memory.
+#
+# A `ClientMiddleware` wraps a client into a client (`Endo`): it can rewrite the request
+# before, or the response after, the inner client runs. This is the zero-context case of
+# the shared `stack` vocabulary: a server middleware is `(handler, state, scope)`, a
+# client one needs no context (the request is the value it transforms, not a fixed
+# scope), so it is simply `(client) -> client`, and the same `stack` composes them.
+# State a middleware must keep lives in a closure (see `cookies`), as it does
+# server-side.
+type Client = Callable[[ClientRequest], Awaitable[ClientResponse]]
+type ClientMiddleware = Endo[Client]
 
 _PASSTHROUGH: ClientMiddleware = stack()
 
@@ -275,23 +290,34 @@ def _target(parts: SplitResult) -> str:
     return target
 
 
-def _build_request(method: str, url: str, headers: RawHeaders, content: bytes | Stream[bytes]) -> ClientRequest:
+def _build_request(
+    method: str, url: str, headers: RawHeaders, content: bytes | Stream[bytes] | Content, timeout: Timeout
+) -> ClientRequest:
     """
     Assemble a `ClientRequest`, picking the body framing from `content`.
 
     Buffered `bytes` get a `content-length`; a streaming body whose length is unknown
     gets `transfer-encoding: chunked` (HTTP/1.1 frames it as chunks; over HTTP/2 the
     framing headers are dropped and the body rides DATA frames either way).
+
+    A `Content` is bytes that already know what they are, so its headers go *under* the
+    caller's: an explicit `content-type` on the request wins over the one the encoding
+    supplied, and everything after this point sees plain bytes.
     """
+    if isinstance(content, Content):
+        headers = merge(content.headers, headers)
+        content = content.body
     if isinstance(content, bytes):
         if not content:
-            return ClientRequest(method, url, headers, _empty_body())  # pragma: no mutate - equals _empty_body()
+            return ClientRequest(
+                method, url, headers, _empty_body(), timeout
+            )  # pragma: no mutate - equals _empty_body()
         if not _has(headers, b"content-length"):
             headers = (*headers, (b"content-length", str(len(content)).encode(_ASCII)))
-        return ClientRequest(method, url, headers, _single(content))
+        return ClientRequest(method, url, headers, _single(content), timeout)
     if not _has(headers, b"content-length") and not _has(headers, b"transfer-encoding"):
         headers = (*headers, (b"transfer-encoding", b"chunked"))
-    return ClientRequest(method, url, headers, content)
+    return ClientRequest(method, url, headers, content, timeout)
 
 
 _ALPN_H2 = ("h2", "http/1.1")
@@ -329,6 +355,28 @@ async def _open(
     return reader, writer, "h2" if negotiated == "h2" else "http/1.1"
 
 
+class Connect(Protocol):
+    """
+    How a pool reaches an origin: the one step that touches the network.
+
+    Injected into `ConnectionPool` so the rest of it (reuse, bounds, protocol selection)
+    stays independent of how a connection is made. `_open` is the default and speaks
+    TCP; a test dials an in-memory pipe, and a unix-socket or proxy connector would slot
+    in the same way. The negotiated wire protocol comes back alongside the streams
+    because only the connector can know it: ALPN is read off the finished handshake.
+    """
+
+    async def __call__(
+        self,
+        host: str,
+        port: int,
+        *,
+        ssl_context: ssl.SSLContext | None,
+        timeout: Timeout = ...,
+        socket_options: SocketOptions = (),
+    ) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, str]: ...
+
+
 @dataclass(slots=True, eq=False)
 class _Http11Connection:
     """
@@ -933,12 +981,16 @@ class _HostPool:
 @dataclass(slots=True)
 class ConnectionPool:
     """
-    Connections keyed by origin, and the entrypoint for making requests.
+    Connections keyed by origin: the `Client` that answers a request over the network.
+
+    Calling it *is* the request (`await pool(request)`), so a pool is interchangeable
+    with any other `Client` and composes with `ClientMiddleware` through `stack`. Most
+    callers go through the `request` context manager rather than calling it directly,
+    since that builds the `ClientRequest` and closes the response body for them.
 
     Open it as an async context manager (`async with ConnectionPool(...) as pool`) so
     its connections are closed on exit; a directly-constructed pool works for
     short-lived use but does not manage the long-lived connections keep-alive retains.
-    Make requests through `async with pool.request(...) as response`.
 
     HTTP/2 connections are kept and reused: many concurrent requests to one origin
     multiplex over a single connection, which is the point of h2. HTTP/1.1
@@ -957,13 +1009,14 @@ class ConnectionPool:
     live context, precisely because ALPN can only be set context-wide: a shared context
     would be mutated out from under other pools or libraries using it.
 
-    `middleware` decorates every request through the pool; per-request `middleware` on
-    `request` composes inside it. Keep pool-level middleware to *pure* decoration
-    (default headers, redirect following, retry): things that are values, not state.
-    Anything carrying mutable, request-spanning identity (a `CookieJar`, an auth
-    session) belongs in a value you own and pass per request, so that connection reuse
-    (a transport concern) and application identity stay independent rather than both
-    hiding in the pool.
+    `connect` is how the pool reaches an origin, defaulting to a TCP connect (see
+    `Connect`). It is the only part of the pool that touches the network, so replacing
+    it points the same pooling, protocol selection, and keep-alive at somewhere else.
+
+    Decoration (default headers, redirect following, cookies, a deadline) is *not* a
+    pool concern: compose it around the pool with `stack`, which yields another `Client`.
+    That keeps connection reuse (a transport concern) and application identity
+    independent, rather than both hiding in the pool.
 
     `max_connections_per_host` bounds the number of concurrent HTTP/1.1 connections to
     one origin: at the bound, a checkout *waits* for one to be returned (the wait a
@@ -980,9 +1033,9 @@ class ConnectionPool:
     connections cannot outnumber concurrent checkouts. Both knobs, when set, MUST be `>=
     1`.
 
-    `timeout` bounds each phase of a request (see `Timeout`); it defaults to no timeouts,
-    since a deadline is the caller's policy, not the transport's. A per-request `timeout`
-    on `request` replaces it wholesale for that call.
+    Deadlines ride on the request (`ClientRequest.timeout`), not on the pool: the same
+    pool serves callers with different time budgets, and a bound stored here would be a
+    property of the connection rather than of the caller that wanted it.
 
     `socket_options` is applied to every socket the pool opens, as `(level, option, value)`
     triples. Build it by concatenating the pure producers in `without_http.socket_options`
@@ -996,10 +1049,9 @@ class ConnectionPool:
     allow_http2: bool = True
     force_http2_cleartext: bool = False
     ssl_context_factory: Callable[[], ssl.SSLContext] = ssl.create_default_context
-    middleware: ClientMiddleware = _PASSTHROUGH
+    connect: Connect = _open
     max_connections_per_host: int | None = None
     max_keepalive_per_host: int | None = None
-    timeout: Timeout = _NO_TIMEOUT
     socket_options: SocketOptions = _DEFAULT_SOCKET_OPTIONS
     _h2: dict[Origin, _Http2Connection] = field(default_factory=dict)
     _h11: dict[Origin, _HostPool] = field(default_factory=dict)
@@ -1021,61 +1073,16 @@ class ConnectionPool:
     async def __aexit__(self, *exc: object) -> None:
         await self.aclose()
 
-    @asynccontextmanager
-    async def request(
-        self,
-        method: str,
-        url: str,
-        *,
-        headers: RawHeaders = (),
-        body: bytes | Stream[bytes] = b"",
-        middleware: ClientMiddleware = _PASSTHROUGH,
-        timeout: Timeout | None = None,
-    ) -> AsyncIterator[ClientResponse]:
-        """
-        Send a request and yield its `ClientResponse` for the block, then release the connection.
-
-        `body` is the request body: `bytes` to buffer it, or a `Stream[bytes]` to stream
-        it. The yielded `ClientResponse` can be taken whole (`response.head`,
-        `response.body`) or unpacked (`head, body = ...`); read the response body with
-        `async for chunk in body` / `await body.read()`, or `body.read_with_trailers()`
-        when the endpoint carries trailers. On exit any unread body is drained or aborted
-        so the connection is never stranded.
-
-        `middleware` is composed inside the pool's own `middleware`, so a single request
-        can add decoration (a `CookieJar` via `cookies`, an extra header) on top of the
-        pool-wide stack for this call alone.
-
-        `timeout` replaces the pool's own `timeout` for this call (`None` inherits it).
-        It is captured as a value in the transport exchange, so it does not compose through
-        `middleware` the way decoration does; a deadline overrides, it does not layer.
+    async def __call__(self, request: ClientRequest) -> ClientResponse:
         """
-        outgoing = _build_request(method, url, headers, body)
-        effective = self.timeout if timeout is None else timeout
-
-        async def bound(outgoing: ClientRequest) -> ClientResponse:
-            return await self._exchange(outgoing, effective)
+        Answer one request over the network, which is what makes a pool a `Client`.
 
-        exchange = stack(self.middleware, middleware)(bound)
-        response = await exchange(outgoing)
-        try:
-            yield response
-        except BaseException:
-            # An error is already in flight; still close the body to release the connection,
-            # but suppress any close error (e.g. a surfaced request-body send failure) so it
-            # cannot mask the original exception the caller is trying to debug.
-            with suppress(Exception):
-                await response.body.aclose()
-            raise
-        else:
-            await response.body.aclose()
-
-    async def _exchange(self, request: ClientRequest, timeout: Timeout) -> ClientResponse:
-        # The bare transport exchange: the inner `ClientExchange` that `request` wraps
-        # with `stack(self.middleware, ...)`. Private so callers go through `request`
-        # and never accidentally bypass the pool's configured middleware. The effective
-        # `timeout` is threaded in as a value (captured by `bound` above), never stored on
-        # the shared connection objects, so concurrent requests keep their own deadlines.
+        Picks the origin's wire protocol, checks out (or opens) a connection, and returns
+        the response as soon as its head arrives, with the body still streaming. The
+        request's own `timeout` is threaded through as a value, never stored on the
+        shared connection objects, so concurrent requests keep their own deadlines.
+        """
+        timeout = request.timeout
         parts = urlsplit(request.url)
         origin = _origin(parts)
         if origin.secure and self.allow_http2:
@@ -1110,7 +1117,7 @@ class ConnectionPool:
             async with self._lock_for(origin):
                 connection = self._reusable_h2(origin)
                 if connection is None and origin not in self._h11_only:
-                    reader, writer, protocol = await _open(
+                    reader, writer, protocol = await self.connect(
                         origin.host,
                         origin.port,
                         ssl_context=self._context_for_connection(http2=True),
@@ -1140,7 +1147,7 @@ class ConnectionPool:
             async with self._lock_for(origin):
                 connection = self._reusable_h2(origin)
                 if connection is None:
-                    reader, writer, _ = await _open(
+                    reader, writer, _ = await self.connect(
                         origin.host,
                         origin.port,
                         ssl_context=None,
@@ -1233,7 +1240,7 @@ class ConnectionPool:
 
     async def _open_h11(self, origin: Origin, timeout: Timeout) -> _Http11Connection:
         ssl_context = self._context_for_connection(http2=False) if origin.secure else None
-        reader, writer, _ = await _open(
+        reader, writer, _ = await self.connect(
             origin.host, origin.port, ssl_context=ssl_context, timeout=timeout, socket_options=self.socket_options
         )
         return _Http11Connection.new(reader, writer)
@@ -1263,6 +1270,53 @@ class ConnectionPool:
             await host_pool.aclose()
 
 
+@asynccontextmanager
+async def request(
+    client: Client,
+    method: str,
+    url: str,
+    *,
+    headers: RawHeaders = (),
+    body: bytes | Stream[bytes] | Content = b"",
+    timeout: Timeout = _NO_TIMEOUT,
+) -> AsyncIterator[ClientResponse]:
+    """
+    Send a request through `client` and yield its `ClientResponse` for the block.
+
+    The one request surface, over *any* `Client`: a `ConnectionPool`, a pool wrapped in
+    middleware (`stack(add_headers(...), cookies(jar))(pool)`), or an in-memory one from
+    `without_http.testing`. It owns the two things a caller would otherwise repeat: the
+    body framing (`bytes` gets a `content-length`, a `Stream[bytes]` gets
+    `transfer-encoding: chunked`) and closing the response body on the way out, so a
+    connection is never stranded by a body nobody read.
+
+    `body` takes bytes, a `Stream[bytes]` to stream them, or a `Content` when the caller
+    holds a *value* rather than bytes: `body=json_content(order)` sends the encoding and
+    the `content-type` describing it together, since neither is any use without the other.
+
+    The yielded `ClientResponse` can be taken whole (`response.head`, `response.body`) or
+    unpacked (`head, body = ...`); read the response body with `async for chunk in body`
+    / `await body.read()`, or `body.read_with_trailers()` when the endpoint carries
+    trailers. On exit any unread body is drained or aborted.
+
+    `timeout` bounds this request's phases (see `Timeout`), defaulting to no bounds. It
+    lands on the `ClientRequest`, so middleware sees and can rewrite it like any other
+    field; `deadline` sets the same field for every request through a client.
+    """
+    response = await client(_build_request(method, url, headers, body, timeout))
+    try:
+        yield response
+    except BaseException:
+        # An error is already in flight; still close the body to release the connection,
+        # but suppress any close error (e.g. a surfaced request-body send failure) so it
+        # cannot mask the original exception the caller is trying to debug.
+        with suppress(Exception):
+            await response.body.aclose()
+        raise
+    else:
+        await response.body.aclose()
+
+
 def wrap(
     *,
     request: Endo[ClientRequest] | None = None,
@@ -1280,10 +1334,10 @@ def wrap(
     This is the easy path for the *independent* before/after case (the dual of why
     `add_headers`, below, is a one-liner over it). A middleware whose two sides share
     state, like `cookies` needing the request URL when it stores the response, or that
-    loops, like `follow_redirects`, is written directly as a `ClientExchange` wrapper.
+    loops, like `follow_redirects`, is written directly as a `Client` wrapper.
     """
 
-    def middleware(inner: ClientExchange) -> ClientExchange:
+    def middleware(inner: Client) -> Client:
         async def exchange(outgoing: ClientRequest) -> ClientResponse:
             if request is not None:
                 outgoing = request(outgoing)
@@ -1302,14 +1356,35 @@ def add_headers(*headers: tuple[bytes, bytes]) -> ClientMiddleware:
     Client middleware that adds headers to every request.
 
     The mirror of a server's request-decorating middleware: it sits in the same
-    `stack` and rewrites the request before the inner exchange runs. This is how a
-    pool sends default headers (auth tokens, a user agent) on every request, or a
+    `stack` and rewrites the request before the inner client runs. This is how a
+    caller sends default headers (auth tokens, a user agent) on every request, or a
     single request adds its own.
     """
     extra: RawHeaders = tuple(headers)
     return wrap(request=lambda request: replace(request, headers=extra + request.headers))
 
 
+def deadline(timeout: Timeout) -> ClientMiddleware:
+    """
+    Client middleware that applies `timeout` to every request that bounds nothing itself.
+
+    A default time budget for everything sent through the composed client, in the same
+    `stack` as any other decoration. A request that bounds any phase of its own keeps its
+    own `timeout` whole, so a caller with a tighter budget for one call is not overridden
+    by the default; that is the difference between a default and a policy imposed from
+    above. A request bounding *nothing* (the default `Timeout()`) reads as "no budget
+    stated" rather than "no budget wanted", so it takes the default: a caller who wants
+    one request exempt composes it against a client without this middleware.
+    """
+
+    def apply(request: ClientRequest) -> ClientRequest:
+        if request.timeout != _NO_TIMEOUT:
+            return request
+        return replace(request, timeout=timeout)
+
+    return wrap(request=apply)
+
+
 _SENSITIVE_REDIRECT_HEADERS = frozenset({b"authorization", b"cookie", b"proxy-authorization"})
 _BODY_FRAMING_HEADERS = frozenset({b"content-length", b"content-type", b"transfer-encoding"})
 
@@ -1334,7 +1409,7 @@ def follow_redirects(max_hops: int = 5) -> ClientMiddleware:
     unfollowed) so nothing is replayed over cleartext.
     """
 
-    def middleware(inner: ClientExchange) -> ClientExchange:
+    def middleware(inner: Client) -> Client:
         async def exchange(request: ClientRequest) -> ClientResponse:
             response = await inner(request)
             for _ in range(max_hops):
@@ -1622,7 +1697,7 @@ def cookies(jar: CookieJar) -> ClientMiddleware:
     the hop sets.
     """
 
-    def middleware(inner: ClientExchange) -> ClientExchange:
+    def middleware(inner: Client) -> Client:
         async def exchange(request: ClientRequest) -> ClientResponse:
             header = jar.header_for(request.url)
             if header is not None:

{without_http-0.0.2 → without_http-0.0.3}/src/without_http/server.py

@@ -86,13 +86,18 @@ class _Limits:
     Bundled into one value so `serving` threads a single argument down through the
     protocol handlers, and a new bound snaps in as a field rather than another
     parameter on every signature. `serving` exposes each field as an explicit keyword
-    argument, keeping the public surface flat while the plumbing stays terse.
+    argument, keeping the public surface flat while the plumbing stays terse. The
+    defaults live here, and the exposing signatures (`serving`, `loopback_client`,
+    `served_pipe`) read them off `_DEFAULT_LIMITS`, so the three cannot disagree.
     """
 
-    max_concurrent_streams: int
-    max_stream_resets: int
-    idle_timeout: timedelta | None
-    max_websocket_message_bytes: int | None
+    max_concurrent_streams: int = 100
+    max_stream_resets: int = 200
+    idle_timeout: timedelta | None = None
+    max_websocket_message_bytes: int | None = None
+
+
+_DEFAULT_LIMITS = _Limits()
 
 
 def _address(info: object) -> tuple[str, int] | None:
@@ -845,10 +850,10 @@ async def serving(
     host: str = "127.0.0.1",
     port: int = 0,
     max_pending_connections: int = 100,
-    max_concurrent_streams: int = 100,
-    max_stream_resets: int = 200,
-    idle_timeout: timedelta | None = None,
-    max_websocket_message_bytes: int | None = None,
+    max_concurrent_streams: int = _DEFAULT_LIMITS.max_concurrent_streams,
+    max_stream_resets: int = _DEFAULT_LIMITS.max_stream_resets,
+    idle_timeout: timedelta | None = _DEFAULT_LIMITS.idle_timeout,
+    max_websocket_message_bytes: int | None = _DEFAULT_LIMITS.max_websocket_message_bytes,
     ssl_context: ssl.SSLContext | None = None,
     ssl_handshake_timeout: float | None = None,
     ssl_shutdown_timeout: float | None = None,

without_http-0.0.3/src/without_http/testing.py

@@ -0,0 +1,587 @@
+from __future__ import annotations
+
+import asyncio
+import ssl
+from collections.abc import AsyncGenerator
+from collections.abc import AsyncIterator
+from collections.abc import Awaitable
+from collections.abc import Buffer
+from collections.abc import Callable
+from collections.abc import Mapping
+from contextlib import asynccontextmanager
+from dataclasses import replace
+from datetime import timedelta
+from types import MappingProxyType
+from typing import assert_never
+from urllib.parse import unquote
+from urllib.parse import urlsplit
+
+from without import cancel_futures
+from without_asgi import Asgi
+from without_asgi import ASGIApp
+from without_asgi import Disconnect
+from without_asgi import EarlyHint
+from without_asgi import HttpScope
+from without_asgi import PathSend
+from without_asgi import RawHeaders
+from without_asgi import RawMessage
+from without_asgi import RequestBody
+from without_asgi import ResponseDebug
+from without_asgi import ResponseStart
+from without_asgi import ServerPush
+from without_asgi import ZeroCopySend
+from without_asgi import encode_http_scope
+from without_asgi import encode_inbound
+from without_asgi import parse_outbound
+from without_asgi.outbound import ResponseBody as OutboundBody
+from without_asgi.outbound import ResponseTrailers as OutboundTrailers
+
+from without_http.client import _NO_TIMEOUT
+from without_http.client import Client
+from without_http.client import ClientMiddleware
+from without_http.client import ClientRequest
+from without_http.client import ClientResponse
+from without_http.client import ConnectionPool
+from without_http.client import ResponseBody
+from without_http.client import ResponseHead
+from without_http.client import ResponseTrailers
+from without_http.client import _releasing
+from without_http.client import wrap
+from without_http.lifespan import _wait_for
+from without_http.lifespan import run_lifespan
+from without_http.server import _DEFAULT_LIMITS
+from without_http.server import _Limits
+from without_http.server import _serve_connection
+from without_http.socket_options import SocketOptions
+from without_http.timeouts import Timeout
+
+# What an in-memory client tells an app about itself. It presents as HTTP/1.1, so an app
+# that runs against it faces the same surface it would over a socket.
+_ASGI = Asgi(version="3.0", spec_version="2.4")
+
+# The one extension this transport can honestly offer: a `ClientResponse` carries trailer
+# blocks through to `read_with_trailers`, so an app's trailers reach the caller here
+# rather than being dropped. The server-offload extensions (server push, zero-copy and
+# path send) have a kernel or a proxy to offload to and nothing in memory does, so they
+# stay unadvertised, as they are over HTTP/1.1.
+_EXTENSIONS: Mapping[str, Mapping[str, object]] = MappingProxyType({"http.response.trailers": {}})
+_ASCII = "ascii"
+_CLIENT_ADDRESS = ("127.0.0.1", 51234)
+_BUFFER = 65536
+
+# The address an in-memory server presents as, which nothing resolves: a `pipe` has no
+# port to report, so the server reads this back from `sockname` and a client names it in
+# the URL (or, over HTTP/2, in `:authority`). Public because a test that writes frames by
+# hand has to spell the authority itself, which is what `AUTHORITY` spells for it.
+SERVER_ADDRESS = ("testserver", 80)
+AUTHORITY = f"{SERVER_ADDRESS[0]}:{SERVER_ADDRESS[1]}".encode()
+
+
+def mock_client(handler: Callable[[ClientRequest], ClientResponse | Awaitable[ClientResponse]]) -> Client:
+    """
+    A `Client` that answers every request from `handler`, reaching nothing at all.
+
+    The whole of mocking, because a client is already a function: `handler` takes the
+    `ClientRequest` a caller built and returns the `ClientResponse` it should see, so no
+    pool, socket, or app exists underneath. Use it to test code that *sends* requests.
+
+    ```python
+    def answer(request: ClientRequest) -> ClientResponse:
+        if request.url == "https://api.test/items":
+            return respond(200, body=b'[]')
+        raise AssertionError(f"unexpected request to {request.url}")
+
+    stats = await summarize(mock_client(answer))
+    ```
+
+    `handler` may be sync or async, and is called once per request, which is what keeps
+    a canned body usable more than once: a `ClientResponse` body is a *stream*, consumed
+    exactly once, so build it inside `handler` (as above) rather than holding one
+    response value and returning it twice.
+    """
+
+    async def client(request: ClientRequest) -> ClientResponse:
+        answered = handler(request)
+        if isinstance(answered, ClientResponse):
+            return answered
+        return await answered
+
+    return client
+
+
+def respond(
+    status: int = 200,
+    *,
+    headers: RawHeaders = (),
+    body: bytes = b"",
+    trailers: RawHeaders | None = None,
+) -> ClientResponse:
+    """
+    Build a canned `ClientResponse` for a `mock_client` handler to return.
+
+    The body is a one-shot stream over `body`, so call this per request rather than
+    reusing one value (see `mock_client`). `trailers`, when given, is a single trailing
+    header block a `read_with_trailers` caller will see after the body.
+    """
+
+    async def events() -> AsyncGenerator[bytes | ResponseTrailers]:
+        if body:
+            yield body
+        if trailers is not None:
+            yield ResponseTrailers(trailers)
+
+    return ClientResponse(ResponseHead(status, headers), ResponseBody(events()))
+
+
+def base_url(base: str) -> ClientMiddleware:
+    """
+    Client middleware that resolves each request's URL against `base`.
+
+    A test client needs absolute URLs for the same reason the network one does (the URL
+    names the origin), so this is how `"/items"` becomes `"http://testserver/items"`
+    without every call site repeating the host. An already-absolute URL is left alone.
+    """
+    prefix = base.rstrip("/")
+
+    def resolve(request: ClientRequest) -> ClientRequest:
+        if urlsplit(request.url).scheme:
+            return request
+        return replace(request, url=prefix + request.url)
+
+    return wrap(request=resolve)
+
+
+def scope_from_client_request(request: ClientRequest, *, root_path: str = "") -> HttpScope:
+    """
+    Build the `HttpScope` an ASGI app expects directly from a `ClientRequest`.
+
+    The in-memory counterpart of `scope_from_request`, which does the same job from an
+    `h11.Request`: pure, and reading only the request itself. The URL supplies what the
+    wire would have (`scheme`, `server`, the raw path and query string), and a `host`
+    header is synthesized when the caller did not set one, matching what the HTTP/1.1
+    transport puts on the wire.
+
+    The scope advertises `http.response.trailers`, since trailers do reach the caller in
+    memory, and nothing else: an app that negotiates the extension takes its trailer path
+    here.
+    """
+    parts = urlsplit(request.url)
+    if parts.hostname is None:
+        raise ValueError(f"client request URL must be absolute, got {request.url!r}")
+    raw_path = (parts.path or "/").encode(_ASCII)
+    headers = request.headers
+    if not any(name.lower() == b"host" for name, _ in headers):
+        headers = ((b"host", parts.netloc.encode(_ASCII)), *headers)
+    return HttpScope(
+        asgi=_ASGI,
+        http_version="1.1",
+        method=request.method,
+        scheme=parts.scheme,
+        path=unquote(raw_path.decode(_ASCII)),
+        raw_path=raw_path,
+        query_string=parts.query.encode(_ASCII),
+        root_path=root_path,
+        headers=headers,
+        client=_CLIENT_ADDRESS,
+        server=(parts.hostname, parts.port or (443 if parts.scheme == "https" else 80)),
+        extensions=_EXTENSIONS,
+    )
+
+
+@asynccontextmanager
+async def asgi_client(app: ASGIApp, *, root_path: str = "") -> AsyncIterator[Client]:
+    """
+    A `Client` that drives `app` in memory, with no wire and no server underneath.
+
+    The app's lifespan runs for the block (through the same `run_lifespan` a real server
+    uses), so startup state is in place before the first request and torn down after the
+    last, and each request calls `app(scope, receive, send)` directly on a task of its
+    own. Nothing is encoded, no socket is opened, and the whole exchange is one process.
+
+    ```python
+    async with asgi_client(app) as client:
+        async with request(client, "GET", "http://testserver/items") as (head, body):
+            assert head.status == 200
+    ```
+
+    It speaks only ASGI, so it drives *any* ASGI app, not just a `without` one. The
+    response streams: the head is returned the instant the app sends
+    `http.response.start`, and each body chunk crosses a one-slot queue, so an app that
+    reads the request body while writing its response behaves as it would on the wire. An
+    exception from the app surfaces to the caller rather than becoming a `500`, since
+    there is no server here to convert it; reach for `loopback_client` to exercise the
+    server's own error path.
+
+    URLs are absolute, as they are for a `ConnectionPool`, so the same test body runs
+    against a real server by swapping the client. Compose `base_url` for relative ones.
+    """
+    async with run_lifespan(app):
+
+        async def client(request: ClientRequest) -> ClientResponse:
+            return await _drive(app, request, root_path=root_path)
+
+        yield client
+
+
+async def _drive(app: ASGIApp, request: ClientRequest, *, root_path: str) -> ClientResponse:
+    """
+    Run one request through `app`, returning as soon as its head is sent.
+
+    The in-memory sibling of the server's `_run_request`: it closes a `receive` and a
+    `send` over local state and hands them to the app. Where that one encodes through
+    `h11`, this one resolves a future for the head and pushes body chunks onto a
+    one-slot queue, which is the in-memory stand-in for a socket buffer: an app that
+    runs ahead of a slow reader blocks in `send`, exactly as it would on the wire.
+    """
+    scope = encode_http_scope(scope_from_client_request(request, root_path=root_path))
+    started = asyncio.Event()
+    head: list[ResponseHead] = []
+    chunks: asyncio.Queue[bytes | ResponseTrailers] = asyncio.Queue(maxsize=1)
+    body = aiter(request.body)
+    request_done = False  # pragma: no mutate - initial sentinel, read only as a bool
+    response_done = False  # pragma: no mutate - initial sentinel, read only as a bool
+    sends_trailers = False  # pragma: no mutate - `http.response.start` always assigns it before a body event
+
+    async def receive() -> RawMessage:
+        nonlocal request_done
+        if request_done:
+            return encode_inbound(Disconnect())
+        try:
+            chunk = await anext(body)
+        except StopAsyncIteration:
+            request_done = True
+            return encode_inbound(RequestBody(body=b"", more_body=False))
+        return encode_inbound(RequestBody(body=chunk, more_body=True))
+
+    def end_response() -> None:
+        nonlocal response_done
+        response_done = True
+        chunks.shutdown()  # drains what is queued, then ends the body stream
+
+    async def send(message: RawMessage) -> None:
+        nonlocal sends_trailers
+        match parse_outbound(message):
+            case ResponseStart(status, headers, trailers):
+                sends_trailers = trailers
+                head.append(ResponseHead(status, headers))
+                started.set()
+            case OutboundBody(chunk, more_body):
+                if chunk and request.method != "HEAD":
+                    await chunks.put(chunk)
+                if not more_body and not sends_trailers:
+                    end_response()
+            case OutboundTrailers(headers, more_trailers):
+                # The extension puts the trailing blocks *after* the final body message,
+                # so for an app that declared them at `http.response.start` it is the
+                # last block, not the last body chunk, that ends the response.
+                await chunks.put(ResponseTrailers(headers))
+                if not more_trailers:
+                    end_response()
+            case EarlyHint():
+                pass  # a client discards informational responses, as the h11 one does
+            case ServerPush() | ZeroCopySend() | PathSend() | ResponseDebug() as unsupported:
+                # Trailers are the only extension this transport advertises, so an app
+                # sending one of these events is misusing the scope it was handed.
+                raise NotImplementedError(f"{type(unsupported).__name__} is not supported in memory")
+            case _ as unreachable:
+                assert_never(unreachable)
+
+    async def drive() -> None:
+        try:
+            await app(scope, receive, send)
+        finally:
+            # However the app ends, the body stream ends with it: shutting the queue down
+            # is synchronous and non-blocking, so this is safe even under cancellation,
+            # and it drains what is already queued before ending the stream.
+            chunks.shutdown()
+
+    task = asyncio.create_task(drive())
+    if not await _wait_for(started, task):
+        await task  # re-raises whatever the app failed with, if anything
+        raise RuntimeError("the application returned without starting a response")
+
+    async def events() -> AsyncGenerator[bytes | ResponseTrailers]:
+        while True:
+            try:
+                item = await chunks.get()
+            except asyncio.QueueShutDown:
+                break
+            yield item
+        if response_done:
+            return
+        # The app ended mid-response: short of the final body chunk, or short of the
+        # trailing block it declared. Surface why, rather than handing back a truncated
+        # response as though it were the whole thing.
+        await task  # re-raises the app's failure, when it had one
+        raise RuntimeError("the application ended before finishing its response")
+
+    async def release(fully_read: bool) -> None:
+        # Shutting the queue down is what unblocks a `send` parked on it, immediate or not;
+        # `immediate` additionally drops what is still queued, which nothing will read now
+        # that the body generator is closed.
+        chunks.shutdown(immediate=True)  # pragma: no mutate - nothing reads the queue after this
+        await cancel_futures([task])
+
+    return ClientResponse(head[0], ResponseBody(await _releasing(events(), release)))
+
+
+class _PipeTransport(asyncio.Transport):
+    """
+    One direction of an in-memory connection: writes land in the peer's `StreamReader`.
+
+    The stand-in for the socket transport `asyncio.open_connection` would hand back, so
+    the reader/writer pair above it is the ordinary `asyncio` one and every consumer
+    (`h11`, `h2`, the server's connection loop) is unchanged. Three behaviours make it a
+    connection rather than a buffer:
+
+    - **EOF and close.** `write_eof` and `close` feed the peer EOF, which is the half-
+      close the wire protocols read as "the peer is done sending"; `close` also completes
+      this side's `wait_closed` by delivering `connection_lost` to its own protocol. Once
+      either end has closed, a `write` is dropped rather than delivered, since a socket
+      also accepts it and reports the failure on a later read.
+    - **Backpressure.** When a reader's buffer fills, `asyncio` pauses *its* transport;
+      here that is translated into pausing the peer's writing, so the peer's `drain()`
+      blocks until the reader catches up. Without that wiring an in-memory writer would
+      run arbitrarily far ahead of its reader, which no socket does.
+    - **Connection facts.** `get_extra_info` answers `sockname`/`peername` from the
+      addresses it was built with and `None` for `socket`/`ssl_object`, so the server
+      reads a cleartext connection with a peer address, as it would off a real socket.
+    """
+
+    def __init__(self, extra: dict[str, object]) -> None:
+        super().__init__(extra)
+        # Three placeholders until `link` runs, which it always does before any use.
+        self._peer_reader: asyncio.StreamReader | None = None  # pragma: no mutate
+        self._peer: _PipeTransport | None = None  # pragma: no mutate
+        self._protocol: asyncio.StreamReaderProtocol | None = None  # pragma: no mutate
+        self._closing = False
+        self._paused = False
+        self._eof_sent = False
+
+    def link(
+        self, peer_reader: asyncio.StreamReader, peer: _PipeTransport, protocol: asyncio.StreamReaderProtocol
+    ) -> None:
+        self._peer_reader = peer_reader
+        self._peer = peer
+        self._protocol = protocol
+
+    def write(self, data: Buffer) -> None:
+        # A write lands in the peer's `StreamReader`, which refuses data once it has been
+        # fed EOF: by this side's own `write_eof`, or by the peer's `connection_lost` when
+        # the peer closed. A socket takes such a write and surfaces the failure on a later
+        # read, so the bytes are dropped here rather than raising out of the reader.
+        if self._eof_sent or (self._peer is not None and self._peer.is_closing()):
+            return
+        if self._peer_reader is not None:  # pragma: no branch - always linked before use
+            self._peer_reader.feed_data(bytes(data))
+
+    def can_write_eof(self) -> bool:
+        return True
+
+    def write_eof(self) -> None:
+        self._eof_sent = True
+        if self._peer_reader is not None:  # pragma: no branch - always linked before use
+            self._peer_reader.feed_eof()
+
+    def is_closing(self) -> bool:
+        return self._closing
+
+    def close(self) -> None:
+        if self._closing:
+            return
+        self._closing = True
+        self.write_eof()
+        if self._protocol is not None:  # pragma: no branch - always linked before use
+            asyncio.get_running_loop().call_soon(self._protocol.connection_lost, None)
+
+    def abort(self) -> None:
+        self.close()
+
+    def pause_reading(self) -> None:
+        # asyncio pauses the transport a full reader belongs to; here that means telling
+        # the *peer* to stop writing, which is what a socket's receive window would do.
+        if self._peer is not None:  # pragma: no branch - always linked before use
+            self._peer.stall_writes()
+
+    def resume_reading(self) -> None:
+        if self._peer is not None:  # pragma: no branch - always linked before use
+            self._peer.resume_writes()
+
+    def stall_writes(self) -> None:
+        """Park this side's `drain()` until the peer's reader has caught up."""
+        if not self._paused and self._protocol is not None:  # pragma: no branch
+            self._paused = True
+            self._protocol.pause_writing()
+
+    def resume_writes(self) -> None:
+        """Let this side's `drain()` proceed again."""
+        if self._paused and self._protocol is not None:  # pragma: no branch
+            self._paused = False
+            self._protocol.resume_writing()
+
+
+type Endpoint = tuple[asyncio.StreamReader, asyncio.StreamWriter]
+
+
+def pipe(
+    *,
+    server: tuple[str, int] = SERVER_ADDRESS,
+    client: tuple[str, int] = _CLIENT_ADDRESS,
+    limit: int = _BUFFER,
+) -> tuple[Endpoint, Endpoint]:
+    """
+    Two connected `(reader, writer)` endpoints, wired to each other and to nothing else.
+
+    The in-memory equivalent of a connected socket pair, `(client_side, server_side)`,
+    with no file descriptor, no port, and no kernel involved. `limit` is the reader
+    buffer at which backpressure kicks in, the analogue of a socket receive buffer.
+
+    What it cannot reproduce is what only a kernel provides: TLS, and the difference
+    between an orderly `FIN` and an abortive `RST`. Tests that turn on those stay on a
+    real socket.
+    """
+    loop = asyncio.get_running_loop()
+
+    def endpoint(
+        sockname: tuple[str, int], peername: tuple[str, int]
+    ) -> tuple[Endpoint, _PipeTransport, asyncio.StreamReaderProtocol]:
+        reader = asyncio.StreamReader(limit=limit, loop=loop)
+        protocol = asyncio.StreamReaderProtocol(reader, loop=loop)
+        transport = _PipeTransport({"sockname": sockname, "peername": peername})
+        writer = asyncio.StreamWriter(transport, protocol, reader, loop)
+        protocol.connection_made(transport)  # sets the reader's transport, for flow control
+        return (reader, writer), transport, protocol
+
+    near, near_transport, near_protocol = endpoint(client, server)
+    far, far_transport, far_protocol = endpoint(server, client)
+    near_transport.link(far[0], far_transport, near_protocol)
+    far_transport.link(near[0], near_transport, far_protocol)
+    return near, far
+
+
+@asynccontextmanager
+async def served_pipe(
+    app: ASGIApp,
+    *,
+    max_concurrent_streams: int = _DEFAULT_LIMITS.max_concurrent_streams,
+    max_stream_resets: int = _DEFAULT_LIMITS.max_stream_resets,
+    idle_timeout: timedelta | None = _DEFAULT_LIMITS.idle_timeout,
+    max_websocket_message_bytes: int | None = _DEFAULT_LIMITS.max_websocket_message_bytes,
+) -> AsyncIterator[Endpoint]:
+    """
+    The client end of a `pipe` with `app` served on the other, for a test that writes bytes.
+
+    `serving` minus `asyncio.start_server`, and minus a client: where `loopback_client`
+    puts a `ConnectionPool` on this end, this hands the raw `(reader, writer)` over, so a
+    test can drive the exact frames and (half-)close timing a protocol conformance test
+    needs. The server reads `SERVER_ADDRESS` back as its `sockname`, which is the
+    authority such a test names.
+
+    ```python
+    async with served_pipe(app, max_stream_resets=2) as (reader, writer):
+        writer.write(connection.data_to_send())
+        await writer.drain()
+    ```
+
+    The app's lifespan runs for the block and the connection is cancelled on exit, both
+    as `serving` does, so a test can assert what leaving the block does to work still in
+    flight. Both ends are closed on the way out, and a test may `write_eof()` its own
+    end early to send the half-close a protocol reads as "done sending" while still
+    reading the response. `close()` is full teardown, not a half-close: it also ends
+    this end's own reader and drops the server's subsequent writes, though closing
+    early is safe since closing twice is a no-op. The keyword arguments are `serving`'s
+    per-connection bounds, with the same defaults.
+    """
+    limits = _Limits(
+        max_concurrent_streams=max_concurrent_streams,
+        max_stream_resets=max_stream_resets,
+        idle_timeout=idle_timeout,
+        max_websocket_message_bytes=max_websocket_message_bytes,
+    )
+    async with run_lifespan(app):
+        near, far = pipe()
+        connection = asyncio.create_task(_serve_connection(app, *far, limits))
+        try:
+            yield near
+        finally:
+            # Cancelling first is what makes the shutdown, rather than the client's EOF,
+            # the thing that ends work still in flight. The server's end is closed here
+            # rather than left to `_serve_connection`, since a block that exits without
+            # ever awaiting never lets the connection task run at all. `close()` alone,
+            # not `wait_closed()`: a pipe has nothing to flush, and the close waiter is
+            # shared with whoever closed the endpoint first, so it may already have been
+            # cancelled with them. The closes run even when the connection task crashed
+            # (`cancel_futures` re-raises such a failure), so the endpoints never leak.
+            try:
+                await cancel_futures([connection])
+            finally:
+                for _reader, writer in (near, far):
+                    writer.close()
+
+
+@asynccontextmanager
+async def loopback_client(
+    app: ASGIApp,
+    *,
+    http2: bool = False,
+    max_concurrent_streams: int = _DEFAULT_LIMITS.max_concurrent_streams,
+    max_stream_resets: int = _DEFAULT_LIMITS.max_stream_resets,
+    idle_timeout: timedelta | None = _DEFAULT_LIMITS.idle_timeout,
+    max_websocket_message_bytes: int | None = _DEFAULT_LIMITS.max_websocket_message_bytes,
+) -> AsyncIterator[Client]:
+    """
+    A `Client` that reaches `app` through the real wire protocols, over no socket at all.
+
+    This is `serving` minus `asyncio.start_server`: the same `ConnectionPool` encodes the
+    request, the same server code decodes and drives the app, and the bytes cross a
+    `pipe` instead of the kernel. So it exercises what `asgi_client` skips (framing,
+    chunking, keep-alive and connection reuse, the server turning a crashing handler into
+    a `500`) while still opening no port and holding no file descriptor.
+
+    ```python
+    async with loopback_client(app) as client:
+        async with request(client, "GET", "http://testserver/items") as (head, body):
+            assert head.status == 200
+    ```
+
+    `http2` sends the h2 connection preface instead, which the server recognizes by prior
+    knowledge, so one flag runs the same test over HTTP/2. The remaining arguments are
+    `serving`'s per-connection bounds, with the same defaults.
+
+    URLs must be `http`, since a pipe has no TLS to negotiate: an `https` URL is a loud
+    failure rather than a silent downgrade. Nor can it reproduce an abortive close, so
+    tests that turn on `RST` versus `FIN` semantics belong on `serving` and a real socket.
+    """
+    limits = _Limits(
+        max_concurrent_streams=max_concurrent_streams,
+        max_stream_resets=max_stream_resets,
+        idle_timeout=idle_timeout,
+        max_websocket_message_bytes=max_websocket_message_bytes,
+    )
+    connections: set[asyncio.Task[None]] = set()
+
+    async def connect(
+        host: str,
+        port: int,
+        *,
+        ssl_context: ssl.SSLContext | None,
+        timeout: Timeout = _NO_TIMEOUT,
+        socket_options: SocketOptions = (),
+    ) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, str]:
+        if ssl_context is not None:
+            raise ValueError("loopback_client has no TLS; request an http:// URL")
+        near, far = pipe(server=(host, port))
+        task = asyncio.create_task(_serve_connection(app, *far, limits))
+        connections.add(task)
+        task.add_done_callback(connections.discard)
+        return (*near, "http/1.1")
+
+    async with run_lifespan(app), ConnectionPool(connect=connect, force_http2_cleartext=http2) as pool:
+        try:
+            yield pool
+        finally:
+            # Close the pooled connections first, so each server task sees the EOF and
+            # ends on its own; whatever is still in flight after that is cancelled, which
+            # is what `serving` does at shutdown too.
+            await pool.aclose()
+            await cancel_futures(connections)

{without_http-0.0.2 → without_http-0.0.3}/src/without_http/timeouts.py

@@ -12,7 +12,7 @@ from without import timeout
 @dataclass(frozen=True, slots=True)
 class Timeout:
     """
-    Per-phase inactivity bounds for a client request, each disabled (`None`) by default.
+    Per-phase inactivity bounds for one client request, each disabled (`None`) by default.
 
     Four axes, following httpx, each bounding one phase of a request that fails for its
     own reason (see the `without-http` guide's request-lifecycle table):
@@ -31,8 +31,10 @@ class Timeout:
     budget ("fail rather than make slow progress so my upstream can react"), which the
     transport cannot know, so a caller opts in per axis (`Timeout(connect=timedelta(
     seconds=10), read=timedelta(seconds=30))`). There is deliberately no shared-default
-    scalar: one duration across four unrelated phases carries no meaning. For an overall
-    wall-clock cap, compose `async with asyncio.timeout(t): pool.request(...)`.
+    scalar: one duration across four unrelated phases carries no meaning. It rides on the
+    `ClientRequest` it bounds (`deadline` fills it in for a whole client), so it is the
+    caller's value rather than the connection's. For an overall wall-clock cap, compose
+    `async with asyncio.timeout(t): request(...)`.
 
     Each axis is applied through its own bound: `connecting()`, `reading()`, `writing()`,
     and `pooling()` each return a context manager that bounds the wrapped await(s) by that