attempt timeout escapes as a bare TimeoutError and is never retried

[AlexeyShalaev]

Ran into this while measuring timeouts for a blog post, clientwright 0.2.0, httpx 0.28.1, Python 3.13.

config = ClientConfig(
    service_name="lab",
    timeout=TimeoutConfig(total=1.0, attempt=0.4),
    retry=RetryConfig(max_attempts=3, initial_backoff=0.01),
)
client = build("httpx", config)
await client.get(url)   # server accepts and never answers

I expected the first attempt to be cut at 0.4 s, retried, and the whole thing to end at 1.0 s with an HttpxDeadlineExceededError (or a retry-worthy timeout kind after the third attempt). What happens: after 0.4 s a bare asyncio.TimeoutError escapes client.get, one request reached the server, nothing was retried, and the except httpx.TimeoutException I had around the call did not catch it.

The cause is in core/engine/aio.py, _attempts: the except TimeoutError after asyncio.timeout(timeouts.attempt) classifies the outcome as FailureKind.TOTAL_TIMEOUT. That kind is not in DEFAULT_RETRYABLE_KINDS, so the retry policy declines, and DeadlineExceededError is only raised when deadline.expired is true, which it is not yet. So run() re-raises outcome.exception as is, and that is the raw stdlib TimeoutError, not translated through the adapter's error family. Same code on master.

I think an attempt ceiling that fires before the total should be its own kind (attempt_timeout, retryable by default like read_timeout), and when it is the final outcome it should leave through the adapter translator the way every other CallError does. The total_timeout classification would then be reserved for the case where deadline.expired is true.

Full repro:

import asyncio, time
import httpx
from clientwright import ClientConfig, RetryConfig, TimeoutConfig, build

async def hang(reader, writer):
    await reader.readuntil(b"\r\n\r\n")
    await asyncio.sleep(30)

async def main():
    server = await asyncio.start_server(hang, "127.0.0.1", 0)
    url = f"http://127.0.0.1:{server.sockets[0].getsockname()[1]}/"
    config = ClientConfig(
        service_name="lab",
        timeout=TimeoutConfig(total=1.0, attempt=0.4),
        retry=RetryConfig(max_attempts=3, initial_backoff=0.01),
    )
    client = build("httpx", config)
    started = time.perf_counter()
    try:
        await client.get(url)
    except httpx.TimeoutException as e:
        print("httpx family:", type(e).__name__, f"{time.perf_counter() - started:.2f}s")
    except Exception as e:
        print("escaped:", type(e).__module__, type(e).__name__, f"{time.perf_counter() - started:.2f}s")
    await client.aclose()

asyncio.run(main())

prints escaped: builtins TimeoutError 0.40s.

The same run is the attempt=0.4 case behind 02_retry_multiplies.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. Related: #25.

[AlexeyShalaev]

Reproduced on master (escaped: builtins TimeoutError 0.40s), and while reading that branch I found it is greedy in a second way. aiohttp's whole timeout family subclasses asyncio.TimeoutError, which is the builtin TimeoutError on 3.11+, so a SocketTimeoutError from a sock_read stall never reaches the adapter's classifier either: it lands in the same except TimeoutError, gets labelled total_timeout and is not retried. read=0.2 against an origin that answers in 1 s gives one attempt, outcome=total_timeout, raw SocketTimeoutError. Same root cause: the engine reads "the exception is a TimeoutError" as "my cancel scope fired".

Plan: stop matching on the exception type and ask the scope. asyncio.timeout() hands back a Timeout whose expired() says whether the ceiling is what cancelled the attempt. If it did not fire, the exception is the SDK's and goes through classify_error like every other one. If it did, the kind is total_timeout when the deadline is gone and a new FailureKind.ATTEMPT_TIMEOUT otherwise. attempt_timeout joins DEFAULT_RETRYABLE_KINDS and DEFAULT_TRIP_KINDS next to read_timeout. When the retry gate declines and the last outcome is an attempt timeout, _attempts raises a new AttemptTimeoutError(CallError) carrying the ceiling, from the TimeoutError, the way it already raises DeadlineExceededError, so it leaves run() through the adapter translator: HttpxAttemptTimeoutError is also an httpx.TimeoutException, AiohttpAttemptTimeoutError also an aiohttp.ServerTimeoutError. Your config then does what you expected: cut at 0.4 s, retry, cut at 0.4 s, retry, the third ceiling clamps to the 0.17 s left and the call ends at 1.0 s with HttpxDeadlineExceededError, three requests at the server. With more total than attempts it ends with HttpxAttemptTimeoutError and outcome="attempt_timeout".

To have one place where an outcome becomes final, the retry gate (decide, skip counter, budget) moves into a _retry_delay helper in both engines; the sync engine gets the same move with no behaviour change so the two loops keep reading the same. It has no ceiling to fire, so nothing else changes there and requests/urllib3 get no new error class.

One knock-on I want to be explicit about: dead_retryable_kinds would flag the new default on every sync adapter, since none of them can emit it, and under strict that would fail every default requests build. The honest declaration for them is a collapse, attempt_timeout -> read_timeout: on a sync runtime the stall a ceiling would have caught arrives as the clamped read phase, which is the reasoning the existing write_timeout -> total_timeout collapse already uses. The httpx family record is shared by both flavors, so it lists attempt_timeout in emits with a note that only the async client produces it, as deadline_hard does today.

Rejected: raising DeadlineExceededError for the ceiling too (it is not the deadline, and the label that tells you which knob fired is the whole point); leaving attempt_timeout out of the retry defaults (a ceiling that is never retried is not worth setting next to retry); keeping the except TimeoutError and only relabelling it (that leaves the aiohttp misclassification in place). attempt_timeout is the one new concept; the rest reuses the CallError -> translator path.

[AlexeyShalaev]

#26 is up. Your repro now prints httpx family: HttpxDeadlineExceededError 1.00s: the first two ceilings cut at 0.4 s and are retried as attempt_timeout, the third is clamped to the 0.17 s the total has left and ends the call as total_timeout, three requests at the server. Give it more total than attempts and the last ceiling leaves as HttpxAttemptTimeoutError instead, still an httpx.TimeoutException, with outcome="attempt_timeout".

Nothing to change on your side: except httpx.TimeoutException catches both, and attempt_timeout is in DEFAULT_RETRYABLE_KINDS and DEFAULT_TRIP_KINDS, so a config that only sets attempt and retry behaves the way the blog expected. If someone wants a ceiling that is not retried they drop the kind from retryable_kinds, same as for read_timeout.

The aiohttp side is in the same PR: read=0.2 against an origin answering in 1 s now gives three read_timeout attempts and the SDK's own SocketTimeoutError, where master gave one attempt labelled total_timeout. Not merging; it is yours to look over.