fix: emit retry.giving_up when Retry-After exceeds max_delay

Author: lesnik512

docs/observability.md

@@ -13,6 +13,8 @@ The logger and event names below are a stable public contract:
 
 Each log record has an `event` field holding the event name, such as `event="circuit.opened"`, which you can filter on in your log aggregator. `circuit.rejected` is emitted at most once per second per circuit, so an open circuit under heavy traffic does not flood your logs. The first rejection of each outage is always emitted, `suppressed` counts the rejections left out since the previous one, and `circuit.closed` reports the outage's total in `rejected`. Events from `AsyncKeyedCircuitBreaker` and `KeyedCircuitBreaker` also carry `circuit_key`, the circuit they belong to. [Resilience](resilience.md) describes when each event fires.
 
+`retry.giving_up` fires when a retryable failure is re-raised without another attempt, and its `reason` attribute says why. `max_attempts` means every attempt failed. `retry_after_exceeds_max_delay` means the server's `Retry-After` asked for a longer wait than `max_delay` allows; these events also carry `retry_after` and `max_delay` in seconds. Both kinds carry `attempts`, `method`, `url`, `last_status` and `last_exception_type`.
+
 Events that carry a `url` attribute get it redacted first: httpware strips `user:pass@` userinfo and replaces every query-parameter value with `REDACTED`, keeping the keys. A URL logged as `https://api.test/items?page=REDACTED&sort=REDACTED` came from `https://api.test/items?page=2&sort=name`.
 
 ```python

docs/resilience.md

@@ -28,7 +28,7 @@ from httpware.middleware.resilience import AsyncRetry
 | `max_delay` | `5.0` (s) | Ceiling for backoff and the longest `Retry-After` honored. Must be finite and `>= 0`; a negative, NaN or infinite value raises `ValueError`. |
 | `retry_status_codes` | `frozenset({408, 429, 502, 503, 504})` | Status codes considered retryable. |
 | `retry_methods` | `frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})` | Idempotent methods only. To retry POST, pass a frozenset that includes `"POST"`. Matching ignores case, so `"post"` works too. |
-| `respect_retry_after` | `True` | When a retryable response has a `Retry-After` header, wait that long instead of the jittered backoff. If the value is over `max_delay`, `AsyncRetry` gives up and re-raises the `StatusError` with a PEP 678 note: `httpware: Retry-After (Ns) exceeded max_delay (Ms); giving up`. To avoid this, set `respect_retry_after=False` or raise `max_delay`. |
+| `respect_retry_after` | `True` | When a retryable response has a `Retry-After` header, wait that long instead of the jittered backoff. If the value is over `max_delay`, `AsyncRetry` gives up, emits `retry.giving_up` with `reason="retry_after_exceeds_max_delay"`, and re-raises the `StatusError` with a PEP 678 note: `httpware: Retry-After (Ns) exceeded max_delay (Ms); giving up`. To avoid this, set `respect_retry_after=False` or raise `max_delay`. |
 | `budget` | `RetryBudget()` | The token bucket. Pass one shared `RetryBudget` to several clients to give them a joint budget. |
 
 To bound the total time across all attempts, put [`AsyncTimeout`](#asynctimeout) first in the chain. To bound a single request, set `httpx2.Timeout` on the client or pass `timeout=` per request.

src/httpware/middleware/resilience/retry.py

@@ -179,6 +179,7 @@ def decide(  # noqa: C901 — complexity budget: classification + streaming-body
                     "url": str(request.url),
                     "last_status": last_response.status_code if last_response is not None else None,
                     "last_exception_type": type(exc).__qualname__,
+                    "reason": "max_attempts",
                 },
             )
             raise exc
@@ -196,6 +197,22 @@ def decide(  # noqa: C901 — complexity budget: classification + streaming-body
                     max_delay=self.max_delay,
                 ),
             )
+            _emit_event(
+                _LOGGER,
+                "retry.giving_up",
+                level=logging.WARNING,
+                message=f"retry gave up after {attempt + 1} attempts: Retry-After exceeded max_delay",
+                attributes={
+                    "attempts": attempt + 1,
+                    "method": request.method,
+                    "url": str(request.url),
+                    "last_status": last_response.status_code if last_response is not None else None,
+                    "last_exception_type": type(exc).__qualname__,
+                    "reason": "retry_after_exceeds_max_delay",
+                    "retry_after": retry_after,
+                    "max_delay": self.max_delay,
+                },
+            )
             raise exc
 
         if not self.budget.try_withdraw():

tests/test_retry.py

@@ -647,6 +647,28 @@ async def test_retry_giving_up_emits_observability_event(caplog: pytest.LogCaptu
     assert record.method == "GET"  # ty: ignore[unresolved-attribute]
     assert record.last_status == HTTPStatus.SERVICE_UNAVAILABLE  # ty: ignore[unresolved-attribute]
     assert record.last_exception_type == "ServiceUnavailableError"  # ty: ignore[unresolved-attribute]
+    assert record.reason == "max_attempts"  # ty: ignore[unresolved-attribute]
+
+
+async def test_retry_after_exceeding_max_delay_emits_giving_up_event(caplog: pytest.LogCaptureFixture) -> None:
+    sleeper = _SleepRecorder()
+    handler = _ResponseSequenceWithHeaders([(HTTPStatus.SERVICE_UNAVAILABLE, {"Retry-After": "9999"})])
+    client = _client(handler, retry=AsyncRetry(_sleep=sleeper, base_delay=0.01, max_delay=2.5))
+
+    with caplog.at_level(logging.WARNING, logger="httpware.retry"), pytest.raises(ServiceUnavailableError):
+        await client.get("https://example.test/x")
+
+    records = [r for r in caplog.records if r.name == "httpware.retry" and r.event == "retry.giving_up"]  # ty: ignore[unresolved-attribute]
+    assert len(records) == 1
+    record = records[0]
+    assert record.levelno == logging.WARNING
+    assert record.reason == "retry_after_exceeds_max_delay"  # ty: ignore[unresolved-attribute]
+    assert record.attempts == 1  # ty: ignore[unresolved-attribute]
+    assert record.method == "GET"  # ty: ignore[unresolved-attribute]
+    assert record.last_status == HTTPStatus.SERVICE_UNAVAILABLE  # ty: ignore[unresolved-attribute]
+    assert record.last_exception_type == "ServiceUnavailableError"  # ty: ignore[unresolved-attribute]
+    assert record.retry_after == 9999.0  # noqa: PLR2004 — matches the header above  # ty: ignore[unresolved-attribute]
+    assert record.max_delay == 2.5  # noqa: PLR2004 — matches max_delay above  # ty: ignore[unresolved-attribute]
 
 
 async def test_retry_budget_refused_emits_observability_event(caplog: pytest.LogCaptureFixture) -> None:

tests/test_retry_sync.py

@@ -488,7 +488,30 @@ def test_emits_giving_up_log_event(caplog: pytest.LogCaptureFixture) -> None:
     client = _client(handler, retry=Retry(_sleep=sleeper, base_delay=0.01, max_attempts=2))
     with caplog.at_level(logging.WARNING, logger="httpware.retry"), pytest.raises(ServiceUnavailableError):
         client.get("https://example.test/x")
-    assert any("retry gave up" in r.getMessage() for r in caplog.records)
+    giving_up = [r for r in caplog.records if r.name == "httpware.retry" and r.event == "retry.giving_up"]  # ty: ignore[unresolved-attribute]
+    assert len(giving_up) == 1
+    assert giving_up[0].reason == "max_attempts"  # ty: ignore[unresolved-attribute]
+
+
+def test_retry_after_exceeding_max_delay_emits_giving_up_event(caplog: pytest.LogCaptureFixture) -> None:
+    sleeper = _SleepRecorder()
+    handler = _ResponseSequenceWithHeaders([(HTTPStatus.SERVICE_UNAVAILABLE, {"Retry-After": "9999"})])
+    client = _client(handler, retry=Retry(_sleep=sleeper, base_delay=0.01, max_delay=2.5))
+
+    with caplog.at_level(logging.WARNING, logger="httpware.retry"), pytest.raises(ServiceUnavailableError):
+        client.get("https://example.test/x")
+
+    records = [r for r in caplog.records if r.name == "httpware.retry" and r.event == "retry.giving_up"]  # ty: ignore[unresolved-attribute]
+    assert len(records) == 1
+    record = records[0]
+    assert record.levelno == logging.WARNING
+    assert record.reason == "retry_after_exceeds_max_delay"  # ty: ignore[unresolved-attribute]
+    assert record.attempts == 1  # ty: ignore[unresolved-attribute]
+    assert record.method == "GET"  # ty: ignore[unresolved-attribute]
+    assert record.last_status == HTTPStatus.SERVICE_UNAVAILABLE  # ty: ignore[unresolved-attribute]
+    assert record.last_exception_type == "ServiceUnavailableError"  # ty: ignore[unresolved-attribute]
+    assert record.retry_after == 9999.0  # noqa: PLR2004 — matches the header above  # ty: ignore[unresolved-attribute]
+    assert record.max_delay == 2.5  # noqa: PLR2004 — matches max_delay above  # ty: ignore[unresolved-attribute]
 
 
 def test_emits_budget_refused_log_event(caplog: pytest.LogCaptureFixture) -> None: