Skip to content

Commit 25db15b

Browse files
lesnik512claude
andcommitted
test(resilience): address review feedback — leak-proof + composition tests + docstring
- Bulkhead class docstring: replace one-liner with Parameters section so IDE hovers carry the required-vs-default + range info. - test_cancellation_before_acquire_does_not_hold_slot: issue a third request WHILE first still holds the slot. Pins that the cancelled second did not leave a phantom free slot behind. - Add Bulkhead+Retry composition tests (test_bulkhead.py): - test_bulkhead_outside_retry_holds_one_slot_across_attempts — pins the documented [Bulkhead, Retry] ordering: one slot covers the whole retry sequence (max_in_flight stays at 1 even though handler is called twice). - test_bulkhead_full_error_is_not_retried_by_retry — pins that BulkheadFullError (ClientError) is NOT in Retry's catch set; injected _sleep with # pragma: no cover documents the "must never run" assertion. Skipped one review item (#3): the BulkheadFullError summary string includes "acquire_timeout=None" when constructed manually with None. This branch is unreachable by design — the exception is never raised when acquire_timeout=None. Cosmetic at best; not worth special-casing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent b93b0e6 commit 25db15b

2 files changed

Lines changed: 112 additions & 6 deletions

File tree

‎src/httpware/middleware/resilience/bulkhead.py‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,22 @@
2424

2525

2626
class Bulkhead:
27-
"""Concurrency limiter middleware. See module docstring for behavior."""
27+
"""Concurrency limiter middleware backed by ``asyncio.Semaphore``.
28+
29+
Parameters
30+
----------
31+
max_concurrent
32+
Required. Maximum number of in-flight requests this Bulkhead permits.
33+
Must be ``>= 1``. There is no default because no value is universally
34+
correct — the right cap depends on downstream capacity and SLA.
35+
acquire_timeout
36+
Seconds to wait for a slot before raising ``BulkheadFullError``.
37+
Defaults to ``1.0``. ``None`` waits forever; ``0`` fails fast. Must be
38+
``>= 0`` (or ``None``).
39+
40+
See the module docstring for the algorithm and middleware-ordering guidance.
41+
42+
"""
2843

2944
def __init__(
3045
self,

‎tests/test_bulkhead.py‎

Lines changed: 96 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
from httpware import AsyncClient
1717
from httpware.errors import BulkheadFullError
1818
from httpware.middleware.resilience.bulkhead import Bulkhead
19+
from httpware.middleware.resilience.retry import Retry
1920

2021

2122
_MAX_CONCURRENT_1 = 1
@@ -241,7 +242,13 @@ async def test_slot_released_on_cancellation() -> None:
241242

242243

243244
async def test_cancellation_before_acquire_does_not_hold_slot() -> None:
244-
"""Cancellation while waiting for a slot must not leak the slot to the cancelled task."""
245+
"""Cancellation while waiting for a slot must not leak the slot to the cancelled task.
246+
247+
Stronger check than just "first completes": after the cancelled task is buried,
248+
a fresh request issued WHILE first still holds the slot must wait for first to
249+
release (it must NOT take the slot the cancelled task was waiting for). And once
250+
first releases, the fresh request must complete normally.
251+
"""
245252
handler = _SlowHandler(delay=0.05)
246253
bulkhead = Bulkhead(max_concurrent=_MAX_CONCURRENT_1, acquire_timeout=None)
247254
client = _client(handler, bulkhead=bulkhead)
@@ -254,10 +261,13 @@ async def test_cancellation_before_acquire_does_not_hold_slot() -> None:
254261
with pytest.raises(asyncio.CancelledError):
255262
await second
256263

257-
# First should still complete normally.
258-
response = await first
259-
assert response.status_code == HTTPStatus.OK
260-
assert handler.calls == 1 # second never reached the handler
264+
# Third request issued while first still holds the slot — must not see a phantom
265+
# free slot left by the cancelled second.
266+
third = asyncio.create_task(client.get("https://example.test/c"))
267+
first_response, third_response = await asyncio.gather(first, third)
268+
assert first_response.status_code == HTTPStatus.OK
269+
assert third_response.status_code == HTTPStatus.OK
270+
assert handler.calls == 2 # noqa: PLR2004 — first and third reached handler; second never did
261271

262272

263273
# Constructed at module scope on purpose — pins the construct-outside-loop behavior.
@@ -306,3 +316,84 @@ async def shared_handler(request: httpx2.Request) -> httpx2.Response:
306316

307317
# The shared bulkhead enforces max=1 across BOTH clients combined.
308318
assert state["max_in_flight"] <= _MAX_CONCURRENT_1
319+
320+
321+
# ----------------------------------------------------------------------------
322+
# Bulkhead + Retry composition tests
323+
#
324+
# The recommended ordering is [Bulkhead, Retry] in middleware= — Bulkhead OUTSIDE
325+
# Retry so a retrying request holds one slot across all attempts (rather than
326+
# re-acquiring per retry). These tests pin the documented composition.
327+
# ----------------------------------------------------------------------------
328+
329+
330+
async def test_bulkhead_outside_retry_holds_one_slot_across_attempts() -> None:
331+
"""[Bulkhead, Retry]: one slot covers the whole retry sequence, not per-attempt."""
332+
state = {"in_flight": 0, "max_in_flight": 0}
333+
call_count = {"n": 0}
334+
335+
async def handler(request: httpx2.Request) -> httpx2.Response:
336+
call_count["n"] += 1
337+
state["in_flight"] += 1
338+
state["max_in_flight"] = max(state["max_in_flight"], state["in_flight"])
339+
try:
340+
# First call returns 503 (retryable); second call returns OK.
341+
if call_count["n"] == 1:
342+
return httpx2.Response(HTTPStatus.SERVICE_UNAVAILABLE, request=request)
343+
return httpx2.Response(HTTPStatus.OK, request=request)
344+
finally:
345+
state["in_flight"] -= 1
346+
347+
transport = httpx2.MockTransport(handler)
348+
349+
async def _sleep(_: float) -> None: # don't actually wait between retries
350+
return
351+
352+
client = AsyncClient(
353+
httpx2_client=httpx2.AsyncClient(transport=transport),
354+
middleware=[
355+
Bulkhead(max_concurrent=_MAX_CONCURRENT_1, acquire_timeout=None),
356+
Retry(_sleep=_sleep, base_delay=0.001, max_delay=0.002),
357+
],
358+
)
359+
response = await client.get("https://example.test/x")
360+
assert response.status_code == HTTPStatus.OK
361+
assert call_count["n"] == 2 # noqa: PLR2004 — first 503 + retry success
362+
# max_in_flight stays at 1: the same Bulkhead slot covers both attempts.
363+
assert state["max_in_flight"] == 1
364+
365+
366+
async def test_bulkhead_full_error_is_not_retried_by_retry() -> None:
367+
"""Retry does NOT retry BulkheadFullError — it's neither a StatusError nor a NetworkError/TimeoutError."""
368+
handler = _SlowHandler(delay=0.5) # holds the slot indefinitely
369+
bulkhead = Bulkhead(max_concurrent=_MAX_CONCURRENT_1, acquire_timeout=0)
370+
transport = httpx2.MockTransport(handler)
371+
372+
sleep_calls: list[float] = []
373+
374+
async def _sleep(
375+
delay: float,
376+
) -> None: # pragma: no cover — assert is `sleep_calls == []`, so this body must never run
377+
sleep_calls.append(delay)
378+
379+
client = AsyncClient(
380+
httpx2_client=httpx2.AsyncClient(transport=transport),
381+
middleware=[
382+
bulkhead,
383+
Retry(_sleep=_sleep, max_attempts=3, base_delay=0.001, max_delay=0.002),
384+
],
385+
)
386+
387+
# Fill the slot with a long-lived task.
388+
first = asyncio.create_task(client.get("https://example.test/holder"))
389+
await asyncio.sleep(0.01)
390+
391+
# Second call hits a full Bulkhead. Retry must NOT swallow + retry it.
392+
with pytest.raises(BulkheadFullError):
393+
await client.get("https://example.test/rejected")
394+
assert sleep_calls == [] # Retry never slept — it didn't try to retry
395+
396+
# Cleanup.
397+
first.cancel()
398+
with contextlib.suppress(asyncio.CancelledError):
399+
await first

0 commit comments

Comments
 (0)