total deadline stops at the response headers on httpx, a dripping body escapes it

[AlexeyShalaev]

Same measuring session as #24, clientwright 0.2.0, httpx 0.28.1, Python 3.13.

A server that sends the status line and headers at once and then one body byte every 0.5 s, eight times:

async def drip(reader, writer):
    await reader.readuntil(b"\r\n\r\n")
    writer.write(b"HTTP/1.1 200 OK\r\nContent-Length: 8\r\n\r\n")
    for _ in range(8):
        await asyncio.sleep(0.5)
        writer.write(b"x")
        await writer.drain()
    writer.close()

config = ClientConfig(service_name="lab", timeout=TimeoutConfig(total=1.0), retry=None, on_unsupported="strict")
client = build("httpx", config)
response = await client.get(url)   # 200, 8 bytes, 4.01 s

The total is 1.0 s and the call returns after 4.01 s with a full body. Bare httpx with timeout=1.0 does the same (its read timeout resets on every chunk), so the total buys nothing here. Against a server that stalls for 4 s before the headers the same config raises HttpxDeadlineExceededError at 1.00 s, as expected.

I know this is by design today: the engine sits in the transport, handle_async_request returns at the headers, and the httpx capability record says boundary=headers. But TimeoutConfig.total is documented as "wall clock for the whole logical call", and a wall clock that stops at the headers is the one thing a caller cannot tell from the outside. asyncio.timeout() around the call is the only way to actually bound the call, which defeats the point of having total.

The place to fix it already exists. run() installs AsyncTimedStreamMixin over the response stream for the body-duration metric, so the body read is already wrapped by clientwright code with a clock in hand. If that wrapper also knew the call's deadline it could bound each chunk to the remaining total and raise the adapter's DeadlineExceededError (kind total_timeout, so the metrics say what happened) instead of only timing it. Then the async httpx family could declare DurationBoundary.FULL, and the read phase clamp would stop being the only thing standing between a slow body and an unbounded call. The sync side cannot cancel a blocked read, so I'd leave it at headers, declared, the way deadline_hard already is.

Repro: 01_read_timeout.py in https://github.com/bedrock-python/bedrock-python.github.io/tree/docs/production-python-series/docs/blog/lab/2026-09-06-timeouts-are-not-deadlines (the clientwright total=1.0, body drips line).

[AlexeyShalaev]

Reproduced: clientwright total=1.0, body drips -> 200, 8 bytes, 4.02s on master, the stall line correctly at 1.00 s.

Plan for the mechanism is what you sketched. run() builds the Deadline (today _admitted does, a few microseconds later) and hands it to wrap_stream(response, on_done, deadline). The httpx family's AsyncTimedStreamMixin then bounds every chunk with asyncio.timeout(deadline.remaining()) and, when the scope fires or the budget is already gone before the next read, raises the adapter's DeadlineExceededError through the adapter's own translator (bound into the normalizer, so _httpx_shared stays SDK-free) and hands on_done an Outcome(kind=total_timeout). httpcore closes the connection on the cancellation, httpx's send() closes the response on the way out, and the caller sees HttpxDeadlineExceededError at 1.00 s, still an httpx.TimeoutException. I would not leave the sync client at headers entirely: SyncTimedStreamMixin cannot cancel a blocked read, but it can re-check the deadline between chunks, exactly how the sync engine treats the total at attempt boundaries. A chunk that arrives after the deadline is not delivered and the call raises the same error, late by at most one chunk or one read timeout. That is the soft/hard split the family already declares for deadline_hard.

Where I diverge from the issue is boundary=FULL. DurationBoundary is documented, on the agents page and in the Prometheus help text, as where the call duration closes, and call_end still fires at the headers after this change; the only honest FULL would move requests_total, request_duration and the in-flight gauge to the end of the body for every httpx user, and an abandoned stream would then leak in flight. That is a different, much bigger change, and I do not think you want it in this one. So the declaration becomes a capability instead: Capability.DEADLINE_COVERS_BODY, emulated on the httpx family with a note (hard on async, soft on sync), absent on aiohttp, requests and urllib3 with notes, and listed in the httpx build report's emulated. boundary stays headers everywhere, which is still true. The consequence worth stating plainly: the body-phase deadline shows up in the exception, in body_duration and in the outcome the stream wrapper reports, not in requests_total{outcome}, because that metric closed at the headers.

aiohttp stays at headers, declared. The middleware hands back a ClientResponse whose body the caller reads through aiohttp's StreamReader, which aiohttp itself relies on for release, EOF and connection reuse; replacing or wrapping it is private surgery, and aiohttp's own total timer would cover the body but wraps the whole middleware chain including our retries, which is why the adapter zeroes it. sock_read is the only bound there, and the capability says so.

Two smaller things. wrap_stream on the normalizer protocol gains the deadline argument; the protocols sit below clientwright.core, which the reference page marks as internal, so it is not a semver break, but a third-party adapter would need the extra parameter and the PR will say so. And OriginServer gets a /drip/{count}/{interval} route so the scenario is a real integration test rather than a raw asyncio server.

Rejected: asyncio.timeout() around the call (defeats total); boundary=FULL for the reason above; wrapping aiohttp's StreamReader; leaving the sync client's body unbounded when a check between chunks costs nothing.

[AlexeyShalaev]

#28 is up. Your 01_read_timeout.py now ends with clientwright total=1.0, body drips -> HttpxDeadlineExceededError, 1.00s; the other four lines are unchanged. The mechanism is the one you pointed at: the deadline rides into the timed-stream wrapper and each chunk is bounded by what is left of the total, on the sync client as a check before the next read.

The one place I went a different way is the declaration: boundary stays headers, because that field says where the call duration metric closes, and it still closes at the headers. The coverage is Capability.DEADLINE_COVERS_BODY instead, emulated on the httpx family and absent on aiohttp, requests and urllib3, so capabilities_matrix() answers the question directly. If you would rather see the call metric itself move to the end of the body for httpx, that is a separate change with a real blast radius (request_duration, the in-flight gauge, abandoned streams), and I would want it as its own issue.

Nothing to change on your side unless you were relying on a body arriving after the total; the only cost lands on a third-party normalizer, whose wrap_stream now takes the deadline. Not merging; yours to look over.