xtr-http-message 4.0.4__tar.gz → 5.0.0__tar.gz

{xtr_http_message-4.0.4 → xtr_http_message-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-http-message
-Version: 4.0.4
+Version: 5.0.0
 Summary: A strict, framework-free implementation of the HTTP message contract: requests, responses, streams, URIs, uploaded files and one factory for all six.
 Keywords: http,http-message,request,response,stream,uri,uploaded-file
 Author: Xterr
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Typing :: Typed
-Requires-Dist: xtr-http-message-contracts>=4.0,<5
+Requires-Dist: xtr-http-message-contracts>=5.0,<6
 Requires-Dist: typing-extensions>=4.4
 Requires-Dist: uritools>=6.1,<7
 Requires-Python: >=3.11
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 
 # xtr-http-message
 
-**The HTTP message contract, implemented — six small classes, one factory, and no web framework anywhere in sight.**
+**The HTTP message contract, implemented — six small classes, one factory, a request that can be born connected, and no web framework anywhere in sight.**
 
 <img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
 <img alt="core dependencies: 3" src="https://img.shields.io/badge/core%20deps-3-3FB950">
@@ -47,9 +47,12 @@ besides.
   header taken from the URI and sent in front of every other header.
 - 📥 **`ServerRequest`** — a request that arrived: the environment parameters, the cookies, the
   query string parsed, the files that came with it, the parsed body, and the attributes a
-  handler annotates it with.
+  handler annotates it with. Born complete — or born connected over a `RequestSource`, its body
+  side arriving as it is read.
 - 📤 **`Response`** — a status code, the reason phrase recommended for it, headers and a body.
 - 🌊 **`Stream`** — a body, as a cursor over bytes behind an open binary file object.
+- 🌊 **`LazyStream`** — a body that stands in unread: the whole of it is read once, on the first
+  read, and buffered after.
 - 🔗 **`Uri`** — a URI taken apart into components and put back together as text, read as
   RFC 3986 defines one.
 - 📎 **`UploadedFile`** — one file that came in, movable once.
@@ -108,12 +111,15 @@ application that is [xtr-http-kernel](../xtr-http-kernel)'s
 | `ServerRequest` | `ServerRequestInterface` |
 | `Response` | `ResponseInterface` |
 | `Stream` | `StreamInterface` |
+| `LazyStream` | `StreamInterface` |
 | `Uri` | `UriInterface` |
 | `UploadedFile` | `UploadedFileInterface` |
 | `HttpFactory` | all six factory interfaces |
 
 Each one names its interface as its last base class, so `isinstance` and a container
-registration both work without a plugin registry in between.
+registration both work without a plugin registry in between. `RequestSource` is the one
+protocol among them: not a message, but where a connected request reads its late answers
+from.
 
 ### The rules that hold across all of them
 
@@ -158,6 +164,63 @@ the stream itself is collected, so a file object you still hold is yours to clos
 `get_metadata()` reports three entries — `mode`, `seekable` and `uri`, the last being the path
 the file was opened on when it has one.
 
+`LazyStream` is a stream that stands in for a body nobody has read: built with an async
+callable that returns the bytes, it holds nothing until the first `read` or `get_contents`
+calls it, then buffers what came back and serves every later read out of the buffer —
+seekable, rewindable, and closing it before the first read is a no-op rather than a read.
+
+### A request born connected
+
+A request that arrived is not always known in full when it becomes a message: a connection
+hands over its head at once, but its body is still on the wire. `ServerRequest.over()` builds
+the one class both ways — born complete through the constructor, born connected through a
+`RequestSource`:
+
+```python
+from collections.abc import Mapping
+
+from xtr_http_message import RequestSource, ServerRequest
+
+
+class Connection(RequestSource):
+    """Reads the body off the wire, parses it, answers the late side."""
+
+    async def materialise(self) -> bytes: ...  # runs at most once, memoised
+
+    def parsed_body(self) -> object | None: ...  # a sync peek; None until materialised
+    def uploaded_files(self) -> Mapping[str, object]: ...  # a sync peek; {} until then
+    def attributes(self) -> Mapping[str, object]: ...  # live; routing fills it late
+
+
+served = ServerRequest.over(
+    "POST",
+    "https://example.com/orders",
+    source=Connection(),
+    headers={"host": "example.com"},
+    cookies={"session": "abc"},
+    query={"page": "2"},
+)
+```
+
+The head is passed eagerly — it costs no input and never changes mid-request — and the body
+side comes from the source:
+
+- **The body is one lazy stream** (`LazyStream` over `source.materialise`), handed out however
+  many times it is asked for; the first read materialises the whole body once, and every later
+  read is served out of the buffer.
+- **The parsed body and the uploaded files answer what materialisation has yielded so far** —
+  `None` and an empty mapping until the body has been read. `await served.ensure_parsed()`
+  materialises it at the one seam that can still await, before the message is handed on.
+- **The attributes are live**, read off the source each time: the named parameters a matched
+  route fills in are there as soon as routing has filled them.
+- **The `with_*` members detach.** The copy is a plain eager request — the attributes frozen to
+  the current snapshot, the parsed body and files to the current peek, the body the one shared
+  lazy stream — so a change a handler makes never reaches the connection, and the copy never
+  reads the source again.
+
+`body=` is refused alongside `source=` — one owner of the body. A header the message grammar
+refuses is left out rather than refusing the request: a connection let it through.
+
 ### URIs
 
 A URI is a value, read as RFC 3986 defines a URI reference — the splitting is `uritools`' work.

{xtr_http_message-4.0.4 → xtr_http_message-5.0.0}/README.md

@@ -2,7 +2,7 @@
 
 # xtr-http-message
 
-**The HTTP message contract, implemented — six small classes, one factory, and no web framework anywhere in sight.**
+**The HTTP message contract, implemented — six small classes, one factory, a request that can be born connected, and no web framework anywhere in sight.**
 
 <img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
 <img alt="core dependencies: 3" src="https://img.shields.io/badge/core%20deps-3-3FB950">
@@ -24,9 +24,12 @@ besides.
   header taken from the URI and sent in front of every other header.
 - 📥 **`ServerRequest`** — a request that arrived: the environment parameters, the cookies, the
   query string parsed, the files that came with it, the parsed body, and the attributes a
-  handler annotates it with.
+  handler annotates it with. Born complete — or born connected over a `RequestSource`, its body
+  side arriving as it is read.
 - 📤 **`Response`** — a status code, the reason phrase recommended for it, headers and a body.
 - 🌊 **`Stream`** — a body, as a cursor over bytes behind an open binary file object.
+- 🌊 **`LazyStream`** — a body that stands in unread: the whole of it is read once, on the first
+  read, and buffered after.
 - 🔗 **`Uri`** — a URI taken apart into components and put back together as text, read as
   RFC 3986 defines one.
 - 📎 **`UploadedFile`** — one file that came in, movable once.
@@ -85,12 +88,15 @@ application that is [xtr-http-kernel](../xtr-http-kernel)'s
 | `ServerRequest` | `ServerRequestInterface` |
 | `Response` | `ResponseInterface` |
 | `Stream` | `StreamInterface` |
+| `LazyStream` | `StreamInterface` |
 | `Uri` | `UriInterface` |
 | `UploadedFile` | `UploadedFileInterface` |
 | `HttpFactory` | all six factory interfaces |
 
 Each one names its interface as its last base class, so `isinstance` and a container
-registration both work without a plugin registry in between.
+registration both work without a plugin registry in between. `RequestSource` is the one
+protocol among them: not a message, but where a connected request reads its late answers
+from.
 
 ### The rules that hold across all of them
 
@@ -135,6 +141,63 @@ the stream itself is collected, so a file object you still hold is yours to clos
 `get_metadata()` reports three entries — `mode`, `seekable` and `uri`, the last being the path
 the file was opened on when it has one.
 
+`LazyStream` is a stream that stands in for a body nobody has read: built with an async
+callable that returns the bytes, it holds nothing until the first `read` or `get_contents`
+calls it, then buffers what came back and serves every later read out of the buffer —
+seekable, rewindable, and closing it before the first read is a no-op rather than a read.
+
+### A request born connected
+
+A request that arrived is not always known in full when it becomes a message: a connection
+hands over its head at once, but its body is still on the wire. `ServerRequest.over()` builds
+the one class both ways — born complete through the constructor, born connected through a
+`RequestSource`:
+
+```python
+from collections.abc import Mapping
+
+from xtr_http_message import RequestSource, ServerRequest
+
+
+class Connection(RequestSource):
+    """Reads the body off the wire, parses it, answers the late side."""
+
+    async def materialise(self) -> bytes: ...  # runs at most once, memoised
+
+    def parsed_body(self) -> object | None: ...  # a sync peek; None until materialised
+    def uploaded_files(self) -> Mapping[str, object]: ...  # a sync peek; {} until then
+    def attributes(self) -> Mapping[str, object]: ...  # live; routing fills it late
+
+
+served = ServerRequest.over(
+    "POST",
+    "https://example.com/orders",
+    source=Connection(),
+    headers={"host": "example.com"},
+    cookies={"session": "abc"},
+    query={"page": "2"},
+)
+```
+
+The head is passed eagerly — it costs no input and never changes mid-request — and the body
+side comes from the source:
+
+- **The body is one lazy stream** (`LazyStream` over `source.materialise`), handed out however
+  many times it is asked for; the first read materialises the whole body once, and every later
+  read is served out of the buffer.
+- **The parsed body and the uploaded files answer what materialisation has yielded so far** —
+  `None` and an empty mapping until the body has been read. `await served.ensure_parsed()`
+  materialises it at the one seam that can still await, before the message is handed on.
+- **The attributes are live**, read off the source each time: the named parameters a matched
+  route fills in are there as soon as routing has filled them.
+- **The `with_*` members detach.** The copy is a plain eager request — the attributes frozen to
+  the current snapshot, the parsed body and files to the current peek, the body the one shared
+  lazy stream — so a change a handler makes never reaches the connection, and the copy never
+  reads the source again.
+
+`body=` is refused alongside `source=` — one owner of the body. A header the message grammar
+refuses is left out rather than refusing the request: a connection let it through.
+
 ### URIs
 
 A URI is a value, read as RFC 3986 defines a URI reference — the splitting is `uritools`' work.

{xtr_http_message-4.0.4 → xtr_http_message-5.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-message"
-version = "4.0.4"
+version = "5.0.0"
 description = "A strict, framework-free implementation of the HTTP message contract: requests, responses, streams, URIs, uploaded files and one factory for all six."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,7 +26,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "xtr-http-message-contracts>=4.0,<5",
+    "xtr-http-message-contracts>=5.0,<6",
     "typing-extensions>=4.4",
     "uritools>=6.1,<7",
 ]

{xtr_http_message-4.0.4 → xtr_http_message-5.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-http-message"
-version = "4.0.4"
+version = "5.0.0"
 description = "A strict, framework-free implementation of the HTTP message contract: requests, responses, streams, URIs, uploaded files and one factory for all six."
 readme = "README.md"
 authors = [
@@ -26,7 +26,7 @@ classifiers = [
 # ours sees the string). Everything else the six classes need is in the
 # standard library.
 dependencies = [
-    "xtr-http-message-contracts>=4.0,<5",
+    "xtr-http-message-contracts>=5.0,<6",
     "typing-extensions>=4.4",
     "uritools>=6.1,<7",
 ]

{xtr_http_message-4.0.4 → xtr_http_message-5.0.0}/src/xtr_http_message/.agents/skills/xtr-http-message/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: xtr-http-message
-description: How to build and change requests, responses, streams, URIs and uploaded files with xtr-http-message. Use when code needs a concrete HTTP message rather than the interface - building a request or response in a test or a client, reading or writing a message body, taking a URI apart or putting one together, handling an uploaded file, or taking the factory that builds any of these. Also use when a message body reads as empty, a with_ method seems not to have changed anything, a header is refused, or a URI will not parse - a host, a port or a missing host that RFC 3986 and RFC 9110 refuse.
+description: How to build and change requests, responses, streams, URIs and uploaded files with xtr-http-message. Use when code needs a concrete HTTP message rather than the interface - building a request or response in a test or a client, reading or writing a message body, taking a URI apart or putting one together, handling an uploaded file, building a request over a connection whose body arrives late, or taking the factory that builds any of these. Also use when a message body reads as empty, a with_ method seems not to have changed anything, a header is refused, or a URI will not parse - a host, a port or a missing host that RFC 3986 and RFC 9110 refuse.
 ---
 
 # xtr-http-message
 
-The HTTP message contract, implemented. Six classes and one factory, no web framework. Code that
-only *handles* messages should depend on `xtr-http-message-contracts` instead; this is what an
-application, a test or a client installs to have something that actually is a message.
+The HTTP message contract, implemented. Six classes, one factory, a request that can be born
+connected, no web framework. Code that only *handles* messages should depend on
+`xtr-http-message-contracts` instead; this is what an application, a test or a client installs
+to have something that actually is a message.
 
 ## Quick reference
 
@@ -15,9 +16,13 @@ application, a test or a client installs to have something that actually is a me
   the URI unless you pass one.
 - `ServerRequest(method, uri, headers=None, body=None, version="1.1", server_params=None)` — the
   query parameters are read off the URI as it is built.
+- `ServerRequest.over(method, uri, *, source, ...)` — the same class, born connected over a
+  `RequestSource`: the head passed eagerly, the body side answered late.
 - `Response(status=200, headers=None, body=None, version="1.1", reason=None)` — `reason=None`
   takes the recommended phrase, `reason=""` leaves the response with none.
 - `Stream.create(bytes | BinaryIO | StreamInterface)` — no `str`: a body is bytes.
+- `LazyStream(materialise)` — a body that stands in unread: read once on the first read,
+  buffered after.
 - `Uri(text)` — read as RFC 3986 defines a URI reference;
   `UploadedFile(stream_or_file, size, error, client_filename=None, client_media_type=None)`.
 - `HttpFactory()` is all six factory interfaces at once; it holds no state.
@@ -89,6 +94,47 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Build a request born connected
+
+A request that arrived is not always known in full when it becomes a message — a connection
+hands over its head at once, but its body is still on the wire. `ServerRequest.over()` builds
+the one class both ways, over a `RequestSource`:
+
+```python
+from typing import Mapping
+
+from xtr_http_message import RequestSource, ServerRequest
+
+
+class Connection(RequestSource):
+    async def materialise(self) -> bytes:
+        """Read the whole body once, memoised; fill the parsed side as a side effect."""
+
+    def parsed_body(self) -> object | None: ...  # a sync peek; None until materialised
+    def uploaded_files(self) -> Mapping[str, object]: ...  # a sync peek; {} until then
+    def attributes(self) -> Mapping[str, object]: ...  # live; routing fills it late
+
+
+served = ServerRequest.over(
+    "POST",
+    "https://example.com/orders",
+    source=Connection(),
+    headers={"host": "example.com"},
+    cookies={"session": "abc"},
+    query={"page": "2"},
+)
+```
+
+- The head is passed eagerly; the body is one `LazyStream` over `source.materialise`, and the
+  first read materialises the whole body once.
+- `get_parsed_body()` and `get_uploaded_files()` answer what materialisation has yielded so
+  far; `await served.ensure_parsed()` materialises it at the one seam that can still await.
+- `get_attributes()` reads the source live, each time.
+- The `with_*` members detach: plain eager copies — attributes frozen to the snapshot, parsed
+  body and files to the peek, body the one shared lazy stream — that never read the source
+  again.
+- `body=` is refused alongside `source=`: one owner of the body.
+
 ## Take a URI apart and put one together
 
 ```python
@@ -276,6 +322,9 @@ implementation can catch `HttpMessageError` and get only its failures.
 - Do not expect a `with_*` method to change the message it was called on: it returns a new one,
   and returns the same one when nothing would change. `request.with_header(...)` on its own does
   nothing — keep the result.
+- Do not expect `get_parsed_body()` or `get_uploaded_files()` on a connected request to answer
+  before its body has been read: they answer what materialisation has yielded, and
+  `await served.ensure_parsed()` is the seam that materialises it.
 - Do not change a mapping or list one of the getters handed you and expect the message to follow:
   every one of them hands back a fresh copy.
 - Do not import these classes in a library that only handles messages — depend on

{xtr_http_message-4.0.4 → xtr_http_message-5.0.0}/src/xtr_http_message/__init__.py

@@ -11,11 +11,16 @@ What is here is one class per interface, and nothing besides:
 - :class:`~xtr_http_message.server_request.ServerRequest` — a request that
   arrived, with the environment parameters, the cookies, the query string
   parsed, the files that came with it, the parsed body and the attributes a
-  handler annotates it with.
+  handler annotates it with. Born complete, or born connected over a
+  :class:`~xtr_http_message.request_source.RequestSource` — a connection whose
+  body side arrives as it is read.
 - :class:`~xtr_http_message.response.Response` — a status code, the reason
   phrase recommended for it, headers and a body.
 - :class:`~xtr_http_message.stream.Stream` — a body, as a cursor over bytes
   behind an open binary file object.
+- :class:`~xtr_http_message.lazy_stream.LazyStream` — a body that stands in
+  unread: the whole of it is read once, on the first read, and buffered
+  after.
 - :class:`~xtr_http_message.uri.Uri` — a URI taken apart into components and
   put back together as text.
 - :class:`~xtr_http_message.uploaded_file.UploadedFile` — one file that came
@@ -55,7 +60,9 @@ from .exception import (
     UploadedFileError,
 )
 from .factory import HttpFactory
+from .lazy_stream import LazyStream
 from .request import Request
+from .request_source import RequestSource
 from .response import Response
 from .server_request import ServerRequest
 from .stream import Stream
@@ -73,7 +80,9 @@ __all__ = [
     "HttpFactory",
     "HttpMessageError",
     "InvalidArgumentError",
+    "LazyStream",
     "Request",
+    "RequestSource",
     "Response",
     "ServerRequest",
     "Stream",

xtr_http_message-5.0.0/src/xtr_http_message/_connected_trait.py

@@ -0,0 +1,115 @@
+"""The connected side of a server request: born over a source, read through it.
+
+A request that arrived is not always known in full when it becomes a
+message — a connection hands over its head at once, but its body is
+still on the wire. This is the plumbing that lets the one server request
+class be born that way, connected to a source that answers the body side
+late, while the eager path the class has always had stays exactly as it
+was. A mixin, for the same reason the message's own traits are: this is
+one part of what a server request answers, and the class composing it
+carries the rest.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Self
+
+from typing_extensions import override
+
+from ._request_trait import RequestTrait
+from .lazy_stream import LazyStream
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts import StreamInterface, UriInterface
+
+    from .request_source import RequestSource
+
+__all__ = ["ConnectedTrait"]
+
+
+class ConnectedTrait(RequestTrait):
+    """The body side of a server request that arrives late, over a source.
+
+    The ``with_*`` members a connected request answers detach: the copy
+    is a plain eager request — the live parts frozen to what they answer
+    at that moment — so a change a listener makes never reaches the
+    connection. Because the copy is the same class, the ``Self`` the
+    ``with_*`` members promise is finally the whole truth.
+    """
+
+    __slots__: ClassVar[tuple[str, ...]] = ("_source",)
+
+    def __init__(self) -> None:
+        """Start connected to nothing; :meth:`ServerRequest.over` connects."""
+        super().__init__()
+        self._source: RequestSource | None = None
+
+    @override
+    def get_body(self) -> StreamInterface:
+        """Return the body of the message.
+
+        A connected request's body is one lazy stream over its source,
+        handed out however many times the body is asked for: the first
+        read materialises the whole body once, and every later read is
+        served out of the buffer.
+
+        Returns:
+            The body, as a stream.
+        """
+        if self._source is not None and self._stream is None:
+            self._stream: StreamInterface | None = LazyStream(self._source.materialise)
+
+        return super().get_body()
+
+    async def ensure_parsed(self) -> None:
+        """Materialise the body side, when connected and nothing has read it yet.
+
+        The seam that can still await calls this before the message is
+        handed on: a consumer written against the contract reads
+        :meth:`~xtr_http_message.server_request.ServerRequest.get_parsed_body`
+        without reading the stream first, and only a body that has been
+        read can answer it. A no-op for an eager request, and for one
+        whose body has already been read.
+        """
+        if self._source is None:
+            return
+
+        body = self.get_body()
+        if isinstance(body, LazyStream) and not body.materialised:
+            _ = await body.get_contents()
+
+    @override
+    def with_protocol_version(self, version: str) -> Self:
+        """Return an instance carrying ``version``; a connected one detaches first."""
+        if self._source is not None:
+            return self._copy().with_protocol_version(version)
+
+        return super().with_protocol_version(version)
+
+    @override
+    def without_header(self, name: str) -> Self:
+        """Return an instance with the ``name`` header gone; a connected one detaches first."""
+        if self._source is not None:
+            return self._copy().without_header(name)
+
+        return super().without_header(name)
+
+    @override
+    def with_body(self, body: StreamInterface) -> Self:
+        """Return an instance reading its body from ``body``; a connected one detaches first."""
+        if self._source is not None:
+            return self._copy().with_body(body)
+
+        return super().with_body(body)
+
+    @override
+    def with_uri(self, uri: UriInterface, preserve_host: bool = False) -> Self:
+        """Return an instance for ``uri``; a connected one detaches first.
+
+        The copy is a plain eager request, so the URI it carries is a
+        value, not a view — and a ``Host`` header is kept where asked.
+        """
+        if self._source is not None:
+            return self._copy().with_uri(uri, preserve_host)
+
+        return super().with_uri(uri, preserve_host)

xtr_http_message-5.0.0/src/xtr_http_message/lazy_stream.py

@@ -0,0 +1,157 @@
+"""A body stream that reads its bytes once, on its first read.
+
+A request built over a connection must hand out a stream, but nobody
+has read that connection's body until something asks to — reading it
+eagerly is exactly what a lazy request may not do. This stream stands
+in for the body until the first read, then materialises the whole of it
+once and serves every later read out of the buffer: seekable and
+rewindable, so a reader that inspects can rewind for whoever reads
+after it.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_http_message_contracts import StreamInterface
+
+from .stream import Stream
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from typing import BinaryIO
+
+__all__ = ["LazyStream"]
+
+
+@final
+class LazyStream(StreamInterface):
+    """A body stream that reads its bytes once, on its first read.
+
+    Built with a coroutine that returns the buffered body — one that
+    reads the connection and parses it per its content type — and holds
+    nothing until the first :meth:`read` or :meth:`get_contents` calls
+    it. From then on it is a plain view over the buffer, and every
+    question the contract asks of an unread stream is answered for the
+    buffer it will be.
+    """
+
+    __slots__ = ("_buffered", "_materialise")
+
+    def __init__(self, materialise: Callable[[], Awaitable[bytes]]) -> None:
+        """Read the body through ``materialise``, when anything first asks to.
+
+        Args:
+            materialise: Reads the whole body and returns its bytes.
+        """
+        self._materialise = materialise
+        self._buffered: StreamInterface | None = None
+
+    @property
+    def materialised(self) -> bool:
+        """Tell whether the body has been read into memory."""
+        return self._buffered is not None
+
+    async def _held(self) -> StreamInterface:
+        """Return the buffered body, reading it off the connection if nothing has yet."""
+        if self._buffered is None:
+            self._buffered = Stream.create(await self._materialise())
+        return self._buffered
+
+    @override
+    async def close(self) -> None:
+        """Close the buffer, if there is one to close.
+
+        An unread body holds nothing open, so closing one before the
+        first read is not a read: it is a no-op, and the next reader
+        still gets the bytes off the connection.
+        """
+        if self._buffered is not None:
+            await self._buffered.close()
+
+    @override
+    def detach(self) -> BinaryIO | None:
+        """Hand out the buffer's file object, or ``None`` while there is none."""
+        return self._buffered.detach() if self._buffered is not None else None
+
+    @override
+    def get_size(self) -> int | None:
+        """Return the size of the buffered body, or ``None`` before there is one."""
+        return self._buffered.get_size() if self._buffered is not None else None
+
+    @override
+    def tell(self) -> int:
+        """Return where the cursor sits: the first byte, until there is a buffer."""
+        return self._buffered.tell() if self._buffered is not None else 0
+
+    @override
+    def eof(self) -> bool:
+        """Tell whether a read reached the end: no read has, until there is a buffer."""
+        return self._buffered.eof() if self._buffered is not None else False
+
+    @override
+    def is_seekable(self) -> bool:
+        """Tell whether the cursor moves: the buffer it will be is over bytes in memory."""
+        return True
+
+    @override
+    async def seek(self, offset: int, whence: int = os.SEEK_SET) -> None:
+        """Move the cursor, materialising the body if nothing has read it yet.
+
+        Raises:
+            StreamError: When the buffer cannot be moved, once there is one.
+        """
+        await (await self._held()).seek(offset, whence)
+
+    @override
+    async def rewind(self) -> None:
+        """Move the cursor back to the first byte, materialising if nothing has read."""
+        await (await self._held()).rewind()
+
+    @override
+    def is_writable(self) -> bool:
+        """Tell whether bytes can be written to the buffer: it is a buffer, so yes."""
+        return True
+
+    @override
+    async def write(self, data: bytes) -> int:
+        """Write at the cursor, materialising the body if nothing has read it yet.
+
+        Raises:
+            StreamError: When the buffer cannot be written to.
+        """
+        return await (await self._held()).write(data)
+
+    @override
+    def is_readable(self) -> bool:
+        """Tell whether bytes can be read: they can, once anything has been read."""
+        return True
+
+    @override
+    async def read(self, length: int) -> bytes:
+        """Read up to ``length`` bytes, materialising the body if nothing has read it yet.
+
+        Raises:
+            StreamError: When the buffer cannot be read.
+        """
+        return await (await self._held()).read(length)
+
+    @override
+    async def get_contents(self) -> bytes:
+        """Return every byte of the body, materialising it if nothing has read it yet.
+
+        Raises:
+            StreamError: When the buffer cannot be read.
+        """
+        return await (await self._held()).get_contents()
+
+    @override
+    def get_metadata(self, key: str | None = None) -> object:
+        """Return what the buffer knows about itself, or nothing while there is none."""
+        return (
+            self._buffered.get_metadata(key)
+            if self._buffered is not None
+            else ({} if key is None else None)
+        )

xtr_http_message-5.0.0/src/xtr_http_message/request_source.py

@@ -0,0 +1,71 @@
+"""Where a connected request reads its late answers from.
+
+A request built over a connection is born before anything has read its
+body: the head is already on the connection, but the body, the parsed
+form and the uploaded files arrive only as the body is read. This is
+the seam between the two moments — framework-free, so the message
+package stays tied to no web framework, and small enough that a
+connection adapter is all an integration needs to write.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["RequestSource"]
+
+
+@runtime_checkable
+class RequestSource(Protocol):
+    """Where a connected request reads its late answers from.
+
+    A request built over a connection materialises its body side
+    lazily: the sync getters answer what materialisation has yielded so
+    far, and the body stream reads the rest through here on its first
+    read. The head — method, URI, headers, cookies, query, environment —
+    never comes from here: it is passed eagerly when the request is
+    built, because it costs no input and never changes mid-request.
+    """
+
+    async def materialise(self) -> bytes:
+        """Read the whole body once, and answer its bytes.
+
+        Runs at most once — the implementation memoises — filling the
+        parsed side and the uploaded files as a side effect, so the sync
+        peeks answer from then on. The bytes answered are the raw body
+        bytes: for a submitted form, the raw form bytes, with the form
+        itself landing in the parsed side.
+
+        Returns:
+            The raw bytes of the body.
+        """
+        ...
+
+    def parsed_body(self) -> object | None:
+        """Return what parsing the body yielded, or ``None`` until it has.
+
+        A sync peek at what :meth:`materialise` has yielded so far: the
+        form for form content types, a JSON object for JSON, ``None``
+        before any body read.
+        """
+        ...
+
+    def uploaded_files(self) -> Mapping[str, object]:
+        """Return the files that came with the body, empty until it is read.
+
+        A sync peek, as :meth:`parsed_body` is one: the files are
+        gathered when the body is materialised, so before any body read
+        this answers an empty mapping.
+        """
+        ...
+
+    def attributes(self) -> Mapping[str, object]:
+        """Return what has been derived from the request while handling it.
+
+        A live view: routing fills the named path parameters after the
+        request exists, and each read answers them as they are now.
+        """
+        ...

{xtr_http_message-4.0.4 → xtr_http_message-5.0.0}/src/xtr_http_message/server_request.py

@@ -9,7 +9,7 @@ from urllib.parse import parse_qsl
 from typing_extensions import override
 from xtr_http_message_contracts import ServerRequestInterface
 
-from ._request_trait import RequestTrait
+from ._connected_trait import ConnectedTrait
 from .exception import InvalidArgumentError
 from .uri import Uri
 
@@ -19,6 +19,8 @@ if TYPE_CHECKING:
 
     from xtr_http_message_contracts import StreamInterface, UriInterface
 
+    from .request_source import RequestSource
+
 __all__ = ["ServerRequest"]
 
 _HOST = "Host"
@@ -61,7 +63,7 @@ def _parse_query(query: str) -> dict[str, object]:
 
 
 @final
-class ServerRequest(RequestTrait, ServerRequestInterface):
+class ServerRequest(ConnectedTrait, ServerRequestInterface):
     """An incoming, server-side request.
 
     On top of what every request carries, this one gathers what reached the
@@ -88,6 +90,14 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
     mapping of a kind that answers more than a single value per name reaches
     whoever reads it back as that kind, rather than flattened into a plain
     one.
+
+    A request is also born connected, over a
+    :class:`~xtr_http_message.request_source.RequestSource` — see
+    :meth:`over`. Its head is passed eagerly; its body is one lazy stream
+    that materialises on first read; its parsed body, uploaded files and
+    attributes answer what the source has yielded so far, the attributes
+    live. The ``with_*`` members of such a request detach: plain eager
+    copies, so a change a handler makes never reaches the connection.
     """
 
     __slots__ = (
@@ -146,6 +156,77 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
 
         self._set_body(body)
 
+    @classmethod
+    def over(
+        cls,
+        method: str,
+        uri: UriInterface | str,
+        *,
+        source: RequestSource,
+        body: bytes | BinaryIO | StreamInterface | None = None,
+        headers: Mapping[str, str | Sequence[str]] | None = None,
+        server_params: Mapping[str, object] | None = None,
+        cookies: Mapping[str, str] | None = None,
+        query: Mapping[str, object] | None = None,
+        protocol_version: str = "1.1",
+    ) -> Self:
+        """Build a server request over ``source``, born connected to it.
+
+        The head is passed eagerly — it costs no input and never changes
+        mid-request — and the body side comes from the source: the body
+        is one lazy stream that materialises on its first read, and the
+        parsed body and the uploaded files answer what materialisation
+        has yielded so far.
+
+        Args:
+            method: The HTTP method, kept exactly as given.
+            uri: The URI of the request. Given as text, it is read into a
+                :class:`~xtr_http_message.uri.Uri`.
+            source: Where the connected request reads its late answers
+                from.
+            body: Refused — the body of a request built over a source is
+                the source's to materialise, and there is one owner of
+                the body. The parameter exists so a caller used to the
+                constructor's shape is told the rule rather than left
+                with an unexpected keyword.
+            headers: Each header name mapped to one value or to several.
+                A header the message grammar refuses is left out rather
+                than refusing the request: a connection let it through,
+                and a message is no place to re-litigate that.
+            server_params: The parameters of the environment the request
+                arrived in, taken exactly as given.
+            cookies: The cookies the client sent; left out, none.
+            query: The query string, parsed into parameters; left out,
+                the URI's own query stands.
+            protocol_version: The HTTP version number alone.
+
+        Returns:
+            The request, connected to ``source``.
+
+        Raises:
+            InvalidArgumentError: When ``body`` is given alongside
+                ``source``.
+        """
+        if body is not None:
+            raise InvalidArgumentError(
+                "One owner of the body: body= and source= cannot both be given"
+            )
+
+        request = cls(method, uri, None, None, protocol_version, server_params)
+        for name, values in (headers or {}).items():
+            try:
+                request = request.with_header(name, values)
+            except ValueError:
+                continue
+
+        if cookies is not None:
+            request = request.with_cookie_params(cookies)
+        if query is not None:
+            request = request.with_query_params(query)
+
+        request._source = source  # noqa: SLF001 — a fresh instance of this very class.
+        return request
+
     @override
     def get_server_params(self) -> Mapping[str, object]:
         """Return the parameters of the environment the request arrived in.
@@ -225,8 +306,13 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
             A mapping shaped like the names the files were submitted under,
             every leaf of it an uploaded file — the mapping as it was given
             where nothing can change it, otherwise a fresh one. Empty when no
-            file came with the request.
+            file came with the request. A request built over a connection
+            answers what its body's materialisation has gathered so far:
+            empty until the body has been read.
         """
+        if self._source is not None:
+            return self._source.uploaded_files()
+
         return _held(self._uploaded_files)
 
     @override
@@ -251,8 +337,13 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
 
         Returns:
             Whatever parsing the body yielded, or ``None`` when nothing has
-            been parsed into the request.
+            been parsed into the request. A request built over a connection
+            answers what its body's materialisation has yielded so far:
+            ``None`` until the body has been read.
         """
+        if self._source is not None:
+            return self._source.parsed_body()
+
         return self._parsed_body
 
     @override
@@ -287,8 +378,14 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
         """Return what was derived from the request while handling it.
 
         Returns:
-            A fresh mapping of each attribute name to its value.
+            A fresh mapping of each attribute name to its value. A request
+            built over a connection reads them live, off its source: the
+            named parameters the matched route fills in are there as soon
+            as routing has filled them — which is after the request exists.
         """
+        if self._source is not None:
+            return self._source.attributes()
+
         return dict(self._attributes)
 
     @override
@@ -307,6 +404,9 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
         Returns:
             The value under ``name``, or ``default``.
         """
+        if self._source is not None:
+            return self._source.attributes().get(name, default)
+
         if name not in self._attributes:
             return default
 
@@ -324,7 +424,9 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
             A new instance; this one is left as it was.
         """
         new = self._copy()
-        new._attributes = {**self._attributes, name: value}  # noqa: SLF001 — a copy of this class.
+        # Read the copy's bag, not this instance's: a connected request's own
+        # is empty, its attributes living on the source the copy detached from.
+        new._attributes = {**new._attributes, name: value}  # noqa: SLF001 — a copy of this class.
 
         return new
 
@@ -337,8 +439,19 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
 
         Returns:
             A new instance, or this one when the request carries no such
-            attribute.
+            attribute. A connected request always answers a copy: its
+            attributes are live, so the name is looked for in what they
+            answer now, and the copy detaches either way.
         """
+        source = self._source
+        if source is not None:
+            new = self._copy()
+            new._attributes = {  # noqa: SLF001 — a copy of this very class.
+                held: value for held, value in source.attributes().items() if held != name
+            }
+
+            return new
+
         if name not in self._attributes:
             return self
 
@@ -348,3 +461,28 @@ class ServerRequest(RequestTrait, ServerRequestInterface):
         }
 
         return new
+
+    @override
+    def _copy(self) -> Self:
+        """Return a copy to change, leaving this instance as it is.
+
+        A connected request's copy detaches: it is a plain eager request,
+        carrying the head as it was passed and the live parts frozen to
+        what they answer at this moment — the attributes as a snapshot,
+        the parsed body and the uploaded files as the source's peeks. The
+        body is the one lazy stream, shared: one materialisation serves
+        the request and every copy of it, and the copy never reads the
+        source again.
+        """
+        source = self._source
+        if source is None:
+            return super()._copy()
+
+        new = super()._copy()
+        new._stream = self.get_body()  # noqa: SLF001 — a copy of this very class.
+        new._attributes = dict(source.attributes())  # noqa: SLF001 — a copy of this class.
+        new._parsed_body = source.parsed_body()  # noqa: SLF001 — a copy of this class.
+        new._uploaded_files = source.uploaded_files()  # noqa: SLF001 — a copy of this class.
+        new._source = None  # noqa: SLF001 — a copy of this very class.
+
+        return new