Skip to content

Commit 073147d

Browse files
lesnik512claude
andcommitted
docs(release): draft 0.8.3 notes — RetryBudget cluster + retry/client robustness
Three behavioral changes (deposit per-request, ceiling math.ceil, Retry-After give-up), one mapping cleanup (RuntimeError → TransportError via is_closed), one diagnostic fix (streaming-note scoping), plus two non-user-visible test improvements. Closes 7 audit findings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 6b399eb commit 073147d

1 file changed

Lines changed: 70 additions & 0 deletions

File tree

‎planning/releases/0.8.3.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# httpware 0.8.3 — RetryBudget cluster + retry/client robustness
2+
3+
**Patch release with three behavioral changes you should know about.** All driven by the [deep audit](../audit/2026-06-07-deep-audit.md); collectively close 7 audit findings (3 RetryBudget, 2 retry-surface nits, 2 chunk-3 test rewrites).
4+
5+
## TL;DR
6+
7+
- **`RetryBudget` deposits once per request, not once per attempt.** Tighter retry pacing under load — matches the documented Finagle contract.
8+
- **`RetryBudget` ceiling uses `math.ceil`, not `int(...)` truncation.** No more silent off-by-one against the configured `percent_can_retry`.
9+
- **`Retry-After > max_delay` now raises** the underlying `StatusError` with a PEP 678 note rather than silently capping the sleep at `max_delay` (and retrying into the same error).
10+
- **`RuntimeError → TransportError` mapping** now keys on `httpx2.Client.is_closed`, not substring-matching "closed" in the exception message.
11+
- **Streaming-body refusal note** is now scoped to where streaming is actually the blocker (not attached to method-ineligible refusals).
12+
13+
## The behavioral changes
14+
15+
### `RetryBudget.deposit()` per request, not per attempt
16+
17+
The Finagle retry-budget contract is `withdrawals / deposits <= percent_can_retry` where the denominator counts original requests. `AsyncRetry` and `Retry` previously deposited a token inside the per-attempt loop, so a request that retried twice contributed three deposits and two withdrawals — inflating the ratio by `(attempts-1)/attempts` and letting through more retries than `percent_can_retry` allowed.
18+
19+
Now `deposit()` is hoisted above the attempt loop and runs exactly once per `__call__`. Users with active retry traffic will see the budget refuse retries earlier than before. This is the documented contract; the previous behavior was the bug.
20+
21+
If you were tuning `percent_can_retry` against the pre-0.8.3 behavior, re-validate your target retry rate.
22+
23+
### `RetryBudget` ceiling: `math.ceil` instead of `int(...)`
24+
25+
`try_withdraw`'s ceiling computed `int(deposits * percent) + floor`, truncating fractional values. For `deposits=4` and `percent_can_retry=0.2`, the term was `int(0.8) = 0` — with a `floor=0`, no retries were permitted even though the configured percentage says the first retry should be allowed at 5 deposits.
26+
27+
`math.ceil` makes the threshold honor the configured percentage at the first deposit-count where it is mathematically expressible. The previous behavior was strictly under-permissive; users with `min_retries_per_sec > 0` were insulated by the floor, but `min_retries_per_sec=0.0` configurations saw the off-by-one.
28+
29+
### `Retry-After > max_delay` raises instead of silently capping
30+
31+
Previously when a server sent `Retry-After: 120` and the client had `max_delay=5.0`, `AsyncRetry`/`Retry` clamped to 5s and retried — almost certainly hitting the same 503 or 429 and burning an attempt while violating the server's hint.
32+
33+
Now: when the parsed `Retry-After` exceeds `max_delay`, `AsyncRetry`/`Retry` re-raises the underlying `StatusError` (e.g. `ServiceUnavailableError`) with a PEP 678 note:
34+
35+
```text
36+
httpware: Retry-After (120s) exceeded max_delay (5.0s); giving up
37+
```
38+
39+
If you want to keep retrying despite the gap, raise `max_delay` to accommodate the server's hint, or set `respect_retry_after=False` to drop back to jittered backoff.
40+
41+
### `RuntimeError → TransportError` via `is_closed`
42+
43+
Both `AsyncClient._terminal` and `Client._terminal` mapped `RuntimeError` to `TransportError` by substring-matching `"closed" in str(exc)`. Two failure modes: any unrelated `RuntimeError` whose message happened to contain "closed" was mis-classified as `TransportError`; conversely, an httpx2 wording change (e.g. "shut down") would silently break the mapping.
44+
45+
Now the check is `self._httpx2_client.is_closed` — message-independent. Same attribute already used elsewhere in `client.py` for borrowed-client teardown guards.
46+
47+
### Streaming-body refusal note scoped correctly
48+
49+
The early-out branch for method ineligibility OR non-retryable status also attached the streaming-body refusal note whenever `retryable_status and STREAMING_BODY_MARKER` — misleadingly suggesting the stream was the blocker when the actual reason was method exclusion (e.g. `POST` not in `retry_methods`).
50+
51+
The note now fires only at the dedicated streaming-refusal site, where streaming IS the blocker. The diagnostic is precise instead of misleading.
52+
53+
## Fixes that aren't user-visible
54+
55+
- The `RetryBudget` Hypothesis property test (`tests/test_budget_props.py`) used to compute its expected ceiling with the same `int(...)` formula as production, so it couldn't detect the off-by-one. Now uses `math.ceil` and asserts equality.
56+
- A new property test on `RetryBudget` (`tests/test_retry_props.py::test_budget_exhaustion_is_reachable_and_deterministic`) exercises the budget-exhaustion path that the existing retry property tests left uncovered.
57+
58+
## Audit findings closed
59+
60+
7 of the 35 audit findings from [`planning/audit/2026-06-07-deep-audit.md`](../audit/2026-06-07-deep-audit.md) — the entire RetryBudget cross-cutting cluster plus 2 adjacent retry-surface nits.
61+
62+
## Upgrade
63+
64+
```bash
65+
uv add httpware==0.8.3
66+
# or
67+
pip install -U 'httpware==0.8.3'
68+
```
69+
70+
No import changes; no API surface changes; constructor signatures unchanged.

0 commit comments

Comments
 (0)