alkhttp/tasks/client/review-002-cli01-retry-after-budget.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-002-cli01-retry-after-budget	Budget-aware Retry-After sleep — stop re-arming a full ceiling per attempt (CLI-01)	completed		narrow	medium	component	implementation	client review-002

Description

Review 002 CLI-01 [major]. The Retry-After middleware sleeps outside the retry budget and re-arms a full ceiling on every throttled retry — middleware order is RetryGateMiddleware outside RetryAfterMiddleware (http_client.rs:511-520), so every retry attempt re-enters RetryAfterMiddleware::handle:

1. attempt 1 → 429 + Retry-After: 300 → deadline recorded t₀+300
2. reqwest-retry sleeps ≤ 2 s, retries
3. attempt 2 re-sleeps until t₀+300 (inside maybe_sleep_for), gets a fresh 429 → deadline re-armed to t₀+302 (a full new 300 s)
4. … for up to max_retries more → ~15 min wall time inside one forward() call

TotalRetryBudget gates only its own backoff sleeps; the 30 s request timeout never covers this window (the sleep happens before the reqwest request is constructed, so the timer never starts).

Acceptance Criteria

• maybe_sleep_for is budget-aware: caps the sleep by the remaining max_total_retry_duration (check inside the sleep — the pending sleeps, clamped, or checks-and-skips when the budget is spent; implementer's choice, but a deadline that would extend past the budget must be truncated to it)
• Re-arm clamp: record_if_throttled keeps the earliest deadline (or otherwise does not extend past the first-seen deadline for the same URL within one logical request) — a retry storm cannot push the wall clock out ceiling-per-attempt
• Wire test: counting responder that always answers 429/Retry-After: N with the test's ceiling set small → the caller's total wall time is bounded by max_total_retry_duration + one attempt's request time (assert the bound, not the exact count)
• The per-URL deadline map semantics for separate logical requests are unchanged (a fresh request still honors the recorded throttle window — that feature stays)
• Fix the misspelled test name malware_records_under_the_effective_url while touching the file
• cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check pass

References

• docs/reviews/002-post-remediation-review.md (Part D', CLI-01)
• src/client/http_client.rs:511-520 (stack order), 370-395 (TotalRetryBudget), src/client/retry_after.rs:44-62 (ceiling), :127-211 (record/maybe_sleep)
• tasks/client/review-001-client-timeout-retry.md (the Retry-After machinery)
• tasks/client/review-002-client-policy-wire-tests.md (the counting-responder seam this test family shares)

Notes

Keep the semantics decision narrow: the goal is "one logical request's Retry-After waits are bounded by the retry budget," NOT changing the cross-request throttle map (FWD-11's eviction/jitter behavior is already fixed and correct). The natural seam is threading the budget handle into the middleware order so RetryAfter sees it — small, testable, no public API change (the budget is already a HttpClientConfig field).

Summary

BudgetClock extension anchored per logical request; sleeps truncated to min(deadline, budget); record() keeps earliest deadline, refreshes clamped to hard stop (drop-on-exhaustion). No public API change; tests/retry_after_budget.rs wire tests added.