feat(downloads): serialize same-platform downloads (Patreon concurrency cap)

Two concurrent Patreon walks could trip the server rate limit even with each
source pacing its own requests. The platform-cooldown handled the aftermath of
a 429; this adds the preventive half — a per-platform Redis lock so only one
Patreon walk runs at a time. Different platforms still run concurrently up to
the worker concurrency; only a second walk on the SAME serialized platform
waits.

download_source acquires fc:download_lock:<platform> (non-blocking) before the
run. On contention it re-enqueues itself with a short countdown (the pending
event stays — no new event, no log spam), bounded to ~15 min then runs uncapped
as a safety valve. The lock TTL sits just past the hard kill so a SIGKILL'd
worker auto-releases; a backfill chunk only holds it ~10 min, well under the
30-min DownloadEvent recovery sweep. A broker hiccup degrades to uncapped
(prior behaviour) rather than stalling downloads. SERIALIZED_PLATFORMS={patreon};
gallery-dl platforms are left uncapped (self-pacing subprocesses).

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

backend/app/tasks/download.py

@@ -44,6 +44,25 @@ _KEY_PATH = IMAGES_ROOT / "secrets" / "credential_key.b64"
 DOWNLOAD_SOFT_TIME_LIMIT = 1350
 DOWNLOAD_HARD_TIME_LIMIT = 1500
 
+# Per-platform serialization (plan: concurrency cap). When a serialized
+# platform (Patreon) is already walking, defer this run by re-enqueuing it a
+# little later rather than holding a worker slot or bowling into the same rate
+# limit. Bounded so a wedged platform eventually runs anyway. The lock TTL sits
+# just past the hard kill so a SIGKILL'd worker's lock auto-expires; a backfill
+# chunk only holds it ~10 min, so the bounded wait stays well under the 30-min
+# DownloadEvent recovery sweep.
+_PLATFORM_LOCK_TTL = DOWNLOAD_HARD_TIME_LIMIT + 120
+_SERIALIZE_COUNTDOWN = 20
+_MAX_SERIALIZE_WAITS = 45  # ~15 min ceiling, then run uncapped as a safety valve
+
+
+def _peek_platform(source_id: int) -> str | None:
+    SyncFactory = _sync_session_factory()
+    with SyncFactory() as session:
+        return session.execute(
+            select(Source.platform).where(Source.id == source_id)
+        ).scalar_one_or_none()
+
 
 def _finalize_soft_limited(session: SyncSession, source_id: int) -> None:
     """Defense in depth for the soft-time-limit kill path.
@@ -107,9 +126,48 @@ def _finalize_soft_limited(session: SyncSession, source_id: int) -> None:
     soft_time_limit=DOWNLOAD_SOFT_TIME_LIMIT,
     time_limit=DOWNLOAD_HARD_TIME_LIMIT,
 )
-def download_source(self, source_id: int) -> int:
+def download_source(self, source_id: int, _serialize_waits: int = 0) -> int:
     """Returns the DownloadEvent.id."""
 
+    # Per-platform concurrency cap: only one Patreon walk runs at a time.
+    from ..services.platform_lock import platform_lock
+
+    platform = _peek_platform(source_id)
+    lock = (
+        platform_lock(platform, ttl_seconds=_PLATFORM_LOCK_TTL)
+        if platform is not None
+        else None
+    )
+    if lock is not None:
+        try:
+            got_lock = bool(lock.acquire(blocking=False))
+        except Exception:  # noqa: BLE001 — broker hiccup → degrade to uncapped
+            log.warning("platform lock acquire failed for %s; running uncapped", platform)
+            lock = None
+            got_lock = True
+        if lock is not None and not got_lock:
+            if _serialize_waits < _MAX_SERIALIZE_WAITS:
+                # Another walk on this platform holds the lock — re-enqueue
+                # ourselves shortly (the pending DownloadEvent stays; no new
+                # event, no log spam) rather than running concurrently into
+                # the rate limit.
+                download_source.apply_async(
+                    (source_id,),
+                    {"_serialize_waits": _serialize_waits + 1},
+                    countdown=_SERIALIZE_COUNTDOWN,
+                )
+                log.info(
+                    "download_source(%s) deferred — %s already walking (wait %d/%d)",
+                    source_id, platform, _serialize_waits + 1, _MAX_SERIALIZE_WAITS,
+                )
+                return -1
+            log.warning(
+                "download_source(%s) running WITHOUT the %s lock — max serialize "
+                "waits hit, proceeding uncapped",
+                source_id, platform,
+            )
+            lock = None
+
     async def _run():
         async_factory, async_engine = async_session_factory()
         SyncFactory = _sync_session_factory()
@@ -169,3 +227,12 @@ def download_source(self, source_id: int) -> int:
         except Exception:  # noqa: BLE001 — cleanup must not swallow the kill
             log.exception("soft-limit finalize failed for source %s", source_id)
         raise
+    finally:
+        # Release the per-platform lock so the next walk can proceed. The TTL is
+        # a backstop for a SIGKILL; here we free it the instant the run ends. A
+        # late release after TTL expiry raises (lock already gone) — ignore it.
+        if lock is not None:
+            try:
+                lock.release()
+            except Exception:  # noqa: BLE001 — TTL may have already freed it
+                pass