ML-146: honour API retry headers

backlog/tasks/ml-146 - Honour-Retry-After-and-rate-limit-reset-headers-for-precise-snooze.md

@@ -1,9 +1,11 @@
 ---
 id: ML-146
 title: Honour Retry-After and rate-limit reset headers for precise snooze
-status: To Do
-assignee: []
+status: Done
+assignee:
+  - Codex
 created_date: '2026-04-24 11:12'
+updated_date: '2026-04-25 06:37'
 labels: []
 dependencies:
   - ML-21
@@ -46,8 +48,58 @@ Blocked by ML-21 — requires the classification plumbing to exist first.
 
 ## Acceptance Criteria
 <!-- AC:BEGIN -->
-- [ ] #1 Each API module extracts a retry-delay value from its response (Retry-After, X-RateLimit-Reset, x-ratelimit-reset-*) when present
-- [ ] #2 Workers emit {:snooze, seconds} with the parsed value for transient errors, falling back to a fixed default when the header is absent or malformed
-- [ ] #3 Parsed durations are clamped to a safe range to prevent pathological values
-- [ ] #4 Per-API header parsing is covered by unit tests using representative fixture responses
+- [x] #1 Each API module extracts a retry-delay value from its response (Retry-After, X-RateLimit-Reset, x-ratelimit-reset-*) when present
+- [x] #2 Workers emit {:snooze, seconds} with the parsed value for transient errors, falling back to a fixed default when the header is absent or malformed
+- [x] #3 Parsed durations are clamped to a safe range to prevent pathological values
+- [x] #4 Per-API header parsing is covered by unit tests using representative fixture responses
 <!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+# Implementation Plan
+
+- Add a shared `MusicLibrary.RetryDelay` helper that parses retry/reset headers from `Req.Response` values, clamps parsed provider hints to 5..300 seconds, uses the maximum valid value for multi-window headers, and returns nil for absent or malformed hints.
+- Extend HTTP-based API `ErrorResponse` structs with an optional `retry_delay_seconds` field populated at `from_response/1` time.
+- Parse provider hints for MusicBrainz and Wikipedia `retry-after`, Brave `x-ratelimit-reset`, and OpenAI `x-ratelimit-reset-requests` / `x-ratelimit-reset-tokens`; keep Discogs and Last.fm on their existing fixed fallbacks.
+- Update each affected `retry_delay_seconds/1` implementation to prefer the parsed field when present and preserve existing defaults otherwise.
+- Add focused unit coverage for the shared parser, per-API parsed/fallback behavior, and one `ErrorHandler` integration assertion showing parsed values flow through to `{:snooze, seconds}`.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implemented precise retry-delay parsing through the existing ErrorResponse callback flow. Added MusicLibrary.RetryDelay with 5..300s clamping and max-window selection for multi-window headers. MusicBrainz/Wikipedia parse Retry-After, Brave parses X-RateLimit-Reset, OpenAI parses request/token reset durations. Discogs and Last.fm remain on fixed fallbacks because they do not expose a reliable retry-delay header in scope. Verification passed: focused API/error-handler tests, full mix test suite, mix format --check-formatted, and git diff --check.
+
+Addressed review gaps after implementation: Wikipedia Action API error promotion now passes the full Req response to `from_action_api_body/2` so `Retry-After` is preserved; OpenAI retry parsing now includes `Retry-After` and compound reset durations such as `1m30s`; `Retry-After: 0` now clamps to the 5s minimum instead of falling back. Verification passed: focused retry/API tests, full `mix test`, and `mix format --check-formatted`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+## Summary
+
+Added shared retry-delay parsing for provider retry/reset headers and wired it into the existing structured API error flow. HTTP-based ErrorResponse structs for MusicBrainz, Wikipedia, Brave Search, and OpenAI now capture an optional parsed retry delay and prefer it from `retry_delay_seconds/1`; workers automatically emit `{:snooze, parsed_seconds}` through the existing `MusicLibrary.Worker.ErrorHandler` path.
+
+## Details
+
+- New `MusicLibrary.RetryDelay` parses `Retry-After`, comma-separated reset-second headers, and OpenAI duration reset headers.
+- Parsed provider hints are clamped to 5..300 seconds and multi-window headers use the maximum valid parsed value.
+- Existing fixed fallbacks are preserved when hints are absent or malformed.
+- Discogs and Last.fm remain on current fallback behavior because they do not provide a reliable retry-delay header in this scope.
+- Updated architecture docs for the new shared helper.
+
+## Tests
+
+- `mix test test/music_library/retry_delay_test.exs test/music_brainz/api_test.exs test/wikipedia/api_test.exs test/brave_search/api_test.exs test/open_ai/api_test.exs test/music_library/worker/error_handler_test.exs`
+- `mix test`
+- `mix format --check-formatted`
+- `git diff --check`
+
+## Review follow-up
+
+- Wikipedia Action API body-error responses now preserve response headers for `Retry-After` parsing.
+- OpenAI retry parsing now considers `Retry-After` alongside request/token reset headers and supports compound durations like `1m30s`.
+- Zero-second retry hints clamp to the 5s minimum rather than falling back to fixed defaults.
+- Architecture docs now mention header-driven snooze delays in the external API integration notes.
+<!-- SECTION:FINAL_SUMMARY:END -->