feat(patreon): ingester rate-limit resilience — #703 step 1

A single 429 mid-walk used to fail the run → RATE_LIMITED → platform-wide
cooldown → every Patreon source dark ("testing dead"). The native path also
ignored the operator's existing politeness setting. Fixed both:

- Pacing (avoid 429s): honor download_rate_limit_seconds (gallery-dl's
  `rate_limit`, read off self.gdl) as a pre-download sleep on real media
  downloads only (skips don't pace); pace /api/posts page fetches with the
  per-source sleep_request override, defaulting to max(0.5, rate_limit/4) —
  the same API-pacing default gallery-dl used for `sleep-request`.
- 429 backoff (ride out transient limits): PatreonClient._fetch retries a
  429 with backoff (honor Retry-After, else exponential 2·2^(n-1), capped
  30s, ≤3 tries); only a PERSISTENT 429 propagates as terminal
  RATE_LIMITED. Light 2-retry on a media-GET 429 too.

Threaded via PatreonIngester(rate_limit=, request_sleep=) →
PatreonClient/PatreonDownloader; download_service sources them. Injected
test client/downloader are unaffected (carry their own pacing).

Tests mock time.sleep (no real sleeping): retry-then-success, persistent
429 raises after N, Retry-After honored, request_sleep paces, media pacing
per real download, skips don't pace, media 429 retried.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

backend/app/services/patreon_client.py

@@ -30,6 +30,7 @@ import http.cookiejar
 import logging
 import os
 import re
+import time
 from collections.abc import Iterator
 from dataclasses import dataclass
 from html import unescape
@@ -47,6 +48,34 @@ _USER_AGENT = (
 )
 _TIMEOUT_SECONDS = 30.0
 
+# 429 backoff (plan #703): ride out a transient API rate-limit instead of
+# failing the whole walk (which would stamp RATE_LIMITED → platform-wide
+# cooldown → every Patreon source dark). Honor the server's `Retry-After`;
+# otherwise exponential base·2^(n-1), capped. Only after the retries are
+# exhausted does the 429 propagate as terminal RATE_LIMITED.
+_MAX_429_RETRIES = 3
+_BACKOFF_BASE_SECONDS = 2.0
+_BACKOFF_CAP_SECONDS = 30.0
+
+
+def _retry_after_seconds(
+    resp: requests.Response,
+    attempt: int,
+    *,
+    base: float = _BACKOFF_BASE_SECONDS,
+    cap: float = _BACKOFF_CAP_SECONDS,
+) -> float:
+    """Backoff delay for a 429: the `Retry-After` seconds header if present and
+    numeric, else exponential `base·2^(attempt-1)`, both capped. (HTTP-date form
+    of Retry-After is rare here and falls through to exponential.)"""
+    header = resp.headers.get("Retry-After")
+    if header:
+        try:
+            return min(float(header), cap)
+        except (TypeError, ValueError):
+            pass
+    return min(base * (2 ** max(0, attempt - 1)), cap)
+
 # JSON:API request contract (observed from real traffic — see module plan).
 _INCLUDE = (
     "campaign,access_rules,attachments,attachments_media,audio,images,media,"
@@ -205,9 +234,19 @@ class PatreonClient:
     requests.Session; no secure-context APIs are used.
     """
 
-    def __init__(self, cookies_path: str | Path | None):
+    def __init__(
+        self,
+        cookies_path: str | Path | None,
+        *,
+        request_sleep: float = 0.0,
+        max_retries: int = _MAX_429_RETRIES,
+    ):
         self.cookies_path = str(cookies_path) if cookies_path else None
         self._session = _load_session(cookies_path)
+        # Politeness: seconds to sleep before each /api/posts page fetch (paces
+        # the rate-limited API endpoint). 0 = no pacing. plan #703.
+        self._request_sleep = request_sleep or 0.0
+        self._max_retries = max_retries
 
     # -- request -----------------------------------------------------------
 
@@ -228,16 +267,34 @@ class PatreonClient:
         return params
 
     def _fetch(self, campaign_id: str, cursor: str | None) -> dict:
-        try:
-            resp = self._session.get(
-                _POSTS_URL,
-                params=self._params(campaign_id, cursor),
-                timeout=_TIMEOUT_SECONDS,
-            )
-        except requests.RequestException as exc:
-            raise PatreonAPIError(
-                f"Patreon posts request failed (campaign_id={campaign_id}): {exc}"
-            ) from exc
+        if self._request_sleep > 0:
+            time.sleep(self._request_sleep)  # pace the API endpoint
+        attempt = 0
+        while True:
+            try:
+                resp = self._session.get(
+                    _POSTS_URL,
+                    params=self._params(campaign_id, cursor),
+                    timeout=_TIMEOUT_SECONDS,
+                )
+            except requests.RequestException as exc:
+                raise PatreonAPIError(
+                    f"Patreon posts request failed (campaign_id={campaign_id}): {exc}"
+                ) from exc
+
+            # Transient rate-limit: back off and retry rather than failing the
+            # whole walk. Only a PERSISTENT 429 (retries exhausted) falls
+            # through to the terminal RATE_LIMITED raise below.
+            if resp.status_code == 429 and attempt < self._max_retries:
+                attempt += 1
+                delay = _retry_after_seconds(resp, attempt)
+                log.warning(
+                    "Patreon 429 (campaign_id=%s) — backing off %.1fs (retry %d/%d)",
+                    campaign_id, delay, attempt, self._max_retries,
+                )
+                time.sleep(delay)
+                continue
+            break
 
         if resp.status_code in (401, 403):
             # Auth rejected — expired/missing cookies or an insufficient tier.