Skip to content

Commit 3c63a09

Browse files
lesnik512claude
andcommitted
feat(resilience): add AsyncTimeout overall-deadline middleware
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent e2a38bb commit 3c63a09

5 files changed

Lines changed: 160 additions & 3 deletions

File tree

‎src/httpware/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
before_request,
3939
on_error,
4040
)
41-
from httpware.middleware.resilience import AsyncBulkhead, AsyncRetry, Bulkhead, Retry, RetryBudget
41+
from httpware.middleware.resilience import AsyncBulkhead, AsyncRetry, AsyncTimeout, Bulkhead, Retry, RetryBudget
4242

4343

4444
__all__ = [
@@ -48,6 +48,7 @@
4848
"AsyncMiddleware",
4949
"AsyncNext",
5050
"AsyncRetry",
51+
"AsyncTimeout",
5152
"BadRequestError",
5253
"Bulkhead",
5354
"BulkheadFullError",
Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
"""Resilience primitives: Bulkhead/AsyncBulkhead, Retry/AsyncRetry, RetryBudget."""
1+
"""Resilience primitives: Bulkhead, Retry, RetryBudget, AsyncTimeout."""
22

33
from httpware.middleware.resilience.budget import RetryBudget
44
from httpware.middleware.resilience.bulkhead import AsyncBulkhead, Bulkhead
55
from httpware.middleware.resilience.retry import AsyncRetry, Retry
6+
from httpware.middleware.resilience.timeout import AsyncTimeout
67

78

8-
__all__ = ["AsyncBulkhead", "AsyncRetry", "Bulkhead", "Retry", "RetryBudget"]
9+
__all__ = ["AsyncBulkhead", "AsyncRetry", "AsyncTimeout", "Bulkhead", "Retry", "RetryBudget"]
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
"""AsyncTimeout middleware — overall wall-clock deadline across the inner pipeline.
2+
3+
This is NOT a per-call timeout — httpx2's connect/read/write/pool timeouts are the
4+
right tool for bounding a single outbound call, and AsyncTimeout does not duplicate
5+
them. What httpx2 cannot bound is the total wall-clock across the whole middleware
6+
pipeline (most importantly across an AsyncRetry loop, whose attempts and backoff
7+
sleeps it knows nothing about). Place AsyncTimeout outermost to enforce
8+
"this whole operation must finish within `timeout` seconds, even across retries."
9+
10+
Async-only by design: a sync total-deadline cannot interrupt a blocking httpx2 call
11+
mid-flight (sync Python has no cancellation), and httpx2 already covers sync per-call
12+
timeouts. Sync callers configure httpx2's timeouts directly; there is no sync Timeout.
13+
"""
14+
15+
import asyncio
16+
import logging
17+
18+
import httpx2
19+
20+
from httpware._internal.observability import _emit_event
21+
from httpware.errors import TimeoutError as HttpwareTimeoutError
22+
from httpware.middleware import AsyncNext
23+
24+
25+
_TIMEOUT_INVALID = "timeout must be > 0"
26+
27+
_LOGGER = logging.getLogger("httpware.timeout")
28+
29+
30+
class AsyncTimeout:
31+
"""Bounds total wall-clock time spent in the inner pipeline.
32+
33+
Parameters
34+
----------
35+
timeout
36+
Required. Overall deadline in seconds for ``next(request)`` to complete,
37+
including everything it wraps (retries, backoff sleeps, the call itself).
38+
Must be ``> 0``. On expiry the middleware raises ``httpware.TimeoutError``.
39+
40+
Place outermost in the chain for an overall-operation deadline. For bounding a
41+
single outbound call (connect/read/write/pool), configure ``httpx2`` instead.
42+
43+
"""
44+
45+
def __init__(self, *, timeout: float) -> None:
46+
if timeout <= 0:
47+
raise ValueError(_TIMEOUT_INVALID)
48+
self._timeout = timeout
49+
50+
async def __call__(self, request: httpx2.Request, next: AsyncNext) -> httpx2.Response: # noqa: A002
51+
"""Invoke next under an asyncio.timeout; raise httpware.TimeoutError on expiry.
52+
53+
Only a deadline THIS middleware imposed is re-wrapped: ``cm.expired()``
54+
distinguishes our own expiry from an inner ``TimeoutError`` (e.g. an httpx2
55+
per-call timeout surfacing through a retry), which propagates unchanged.
56+
"""
57+
try:
58+
async with asyncio.timeout(self._timeout) as cm:
59+
return await next(request)
60+
except TimeoutError as exc:
61+
if not cm.expired():
62+
raise # inner TimeoutError, not our deadline — leave it untouched
63+
_emit_event(
64+
_LOGGER,
65+
"timeout.exceeded",
66+
level=logging.WARNING,
67+
message="overall timeout exceeded",
68+
attributes={
69+
"timeout": self._timeout,
70+
"method": request.method,
71+
"url": str(request.url),
72+
},
73+
)
74+
msg = f"overall timeout of {self._timeout}s exceeded"
75+
raise HttpwareTimeoutError(msg) from exc

‎tests/test_public_api.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ def test_expected_exports() -> None:
3333
"AsyncMiddleware",
3434
"AsyncNext",
3535
"AsyncRetry",
36+
"AsyncTimeout",
3637
"BadRequestError",
3738
"Bulkhead",
3839
"BulkheadFullError",

‎tests/test_timeout.py‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
"""Tests for the AsyncTimeout middleware.
2+
3+
Calls the middleware directly with an injected `next` callable. Expiry tests use a
4+
tiny timeout against a long sleep (large margin -> not wall-clock flaky); the
5+
inner-timeout test raises immediately so no real time passes.
6+
"""
7+
8+
import asyncio
9+
import builtins
10+
import logging
11+
12+
import httpx2
13+
import pytest
14+
15+
from httpware.errors import TimeoutError as HttpwareTimeoutError
16+
from httpware.middleware.resilience.timeout import AsyncTimeout
17+
18+
19+
def _request() -> httpx2.Request:
20+
return httpx2.Request("GET", "https://example.test/x")
21+
22+
23+
async def test_passes_through_response_when_under_budget() -> None:
24+
async def _next(request: httpx2.Request) -> httpx2.Response:
25+
return httpx2.Response(200, request=request)
26+
27+
middleware = AsyncTimeout(timeout=10.0)
28+
response = await middleware(_request(), _next)
29+
assert response.status_code == 200 # noqa: PLR2004
30+
31+
32+
async def test_expiry_raises_httpware_timeout_chained_from_builtin(
33+
caplog: pytest.LogCaptureFixture,
34+
) -> None:
35+
async def _next(request: httpx2.Request) -> httpx2.Response:
36+
await asyncio.sleep(5.0)
37+
return httpx2.Response(200, request=request) # pragma: no cover — deadline fires first
38+
39+
middleware = AsyncTimeout(timeout=0.01)
40+
with (
41+
caplog.at_level(logging.WARNING, logger="httpware.timeout"),
42+
pytest.raises(HttpwareTimeoutError) as info,
43+
):
44+
await middleware(_request(), _next)
45+
46+
assert "overall timeout of 0.01s exceeded" in str(info.value)
47+
assert isinstance(info.value.__cause__, builtins.TimeoutError)
48+
49+
records = [r for r in caplog.records if r.name == "httpware.timeout"]
50+
assert len(records) == 1
51+
assert records[0].levelno == logging.WARNING
52+
assert records[0].timeout == 0.01 # noqa: PLR2004 # ty: ignore[unresolved-attribute]
53+
assert records[0].method == "GET" # ty: ignore[unresolved-attribute]
54+
assert "example.test/x" in records[0].url # ty: ignore[unresolved-attribute]
55+
56+
57+
async def test_inner_timeout_propagates_unchanged() -> None:
58+
"""A TimeoutError from next (not our deadline) is re-raised untouched."""
59+
60+
async def _next(_request: httpx2.Request) -> httpx2.Response:
61+
msg = "inner read timeout"
62+
raise HttpwareTimeoutError(msg)
63+
64+
middleware = AsyncTimeout(timeout=10.0)
65+
with pytest.raises(HttpwareTimeoutError) as info:
66+
await middleware(_request(), _next)
67+
68+
assert "inner read timeout" in str(info.value)
69+
assert "overall timeout" not in str(info.value)
70+
71+
72+
def test_zero_timeout_rejected() -> None:
73+
with pytest.raises(ValueError, match="timeout must be > 0"):
74+
AsyncTimeout(timeout=0)
75+
76+
77+
def test_negative_timeout_rejected() -> None:
78+
with pytest.raises(ValueError, match="timeout must be > 0"):
79+
AsyncTimeout(timeout=-1.0)

0 commit comments

Comments
 (0)