fix: dead external links are retried sparingly, not three times a day

The daily recovery reset every dead link to a fresh three-attempt budget,
so a link that can never succeed (an archive too big to import inside the
fetch's hard limit, a file made private) was downloaded up to three times a
day, every day.

Recovery now gives a dead link one more attempt once it has been dead for
2**recoveries days (1, 2, 4, 8, 16), and stops after five. A recovered link
that fails again goes straight back to dead. Retention prunes only links
recovery has given up on, 30 days after their last attempt. A manual refetch
of a post restores the full budgets.

Migration 0118 adds external_link.recoveries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

backend/app/models/external_link.py

@@ -80,6 +80,12 @@ class ExternalLink(Base):
         Integer, nullable=False, server_default=text("0")
     )
     last_error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # Times the daily recovery has given this link another attempt after it
+    # went dead. Recovery stops at a limit, so a link that can never succeed
+    # isn't downloaded forever.
+    recoveries: Mapped[int] = mapped_column(
+        Integer, nullable=False, server_default=text("0")
+    )
     attachment_id: Mapped[int | None] = mapped_column(
         ForeignKey("post_attachment.id", ondelete="SET NULL"), nullable=True
     )

backend/app/services/external_links.py

@@ -21,9 +21,9 @@ log = logging.getLogger(__name__)
 
 
 def refetch_links_for_post(session: Session, post_id: int) -> dict:
-    """Reset every settled ExternalLink on a post to pending (fresh attempt
-    budget) and dispatch its fetch. In-flight ('downloading') links are left
-    alone. Commits. Returns {links_total, links_reset}."""
+    """Reset every settled ExternalLink on a post to pending (fresh attempt and
+    recovery budgets) and dispatch its fetch. In-flight ('downloading') links
+    are left alone. Commits. Returns {links_total, links_reset}."""
     links = session.execute(
         select(ExternalLink).where(ExternalLink.post_id == post_id)
     ).scalars().all()
@@ -33,6 +33,7 @@ def refetch_links_for_post(session: Session, post_id: int) -> dict:
             continue
         link.status = "pending"
         link.attempts = 0
+        link.recoveries = 0
         link.last_error = None
         link.completed_at = None
         reset_ids.append(link.id)

backend/app/tasks/external.py

@@ -39,14 +39,20 @@ log = logging.getLogger(__name__)
 IMAGES_ROOT = Path("/images")
 
 # After this many failed attempts a link is dead-lettered (skipped by routine
-# sweeps; an operator recovery still re-attempts). Mirrors the ingester ledger.
+# sweeps; the daily recovery retries it, sparingly). Mirrors the ingester ledger.
 DEAD_LETTER_THRESHOLD = 3
 # Per-fetch read + total budgets now live in external_fetch (a short read
 # timeout fails a stalled host fast; a generous total caps a big-but-flowing
 # download). The celery soft/hard time_limit is the outer backstop above those.
 # Links enqueued per sweep — bounds the burst when a big backfill records many.
 _SWEEP_BATCH = 50
-# Dead rows older than this are pruned (retention).
+# Recovery gives a dead link one more attempt once it has been dead for
+# 2**recoveries days (1, 2, 4, 8, 16), and stops after _MAX_RECOVERIES. A host
+# outage gets several later chances; a link that can never succeed (too big to
+# import in time, a file made private) costs a handful of downloads, not three
+# a day.
+_MAX_RECOVERIES = 5
+# A link recovery has given up on is pruned this long after its last attempt.
 _RETENTION_DAYS = 30
 # Per-host serialize lock. TTL is a safety net for a worker that dies holding it
 # (normal completion/error releases it in `finally`); sized just past the fetch
@@ -404,29 +410,48 @@ def sweep_external_links() -> dict:
 
 @celery.task(name="backend.app.tasks.external.recover_external_links")
 def recover_external_links() -> dict:
-    """Recovery sweep (rule #89): reset dead links back to retryable so a stuck
-    host outage or a since-fixed bug gets another pass, then enqueue. Bounded."""
+    """Recovery sweep: give each dead link one more attempt once it
+    has been dead for 2**recoveries days, then enqueue. A recovered link that
+    fails again goes straight back to dead, and after _MAX_RECOVERIES it stays
+    dead until retention prunes it."""
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
-        session.execute(
-            update(ExternalLink).where(ExternalLink.status == "dead")
-            .values(status="failed", attempts=0, last_error=None)
-        )
+        now = datetime.now(UTC)
+        candidates = session.execute(
+            select(ExternalLink).where(
+                ExternalLink.status == "dead",
+                ExternalLink.recoveries < _MAX_RECOVERIES,
+            )
+        ).scalars().all()
+        recovered = 0
+        for link in candidates:
+            wait = timedelta(days=2 ** link.recoveries)
+            if link.completed_at is not None and link.completed_at > now - wait:
+                continue
+            link.status = "failed"
+            link.attempts = DEAD_LETTER_THRESHOLD - 1
+            link.recoveries += 1
+            recovered += 1
         session.commit()
-    return sweep_external_links()
+    return {**sweep_external_links(), "revived": recovered}
 
 
 @celery.task(name="backend.app.tasks.external.prune_external_links")
 def prune_external_links() -> dict:
-    """Retention (rule #89): delete long-dead links so the ledger doesn't grow
-    unbounded. Downloaded links are kept (they're the record of what we have)."""
+    """Retention: delete links recovery has given up on, once their
+    last attempt is _RETENTION_DAYS old, so the ledger doesn't grow unbounded.
+    Downloaded links are kept (they're the record of what we have)."""
     cutoff = datetime.now(UTC) - timedelta(days=_RETENTION_DAYS)
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
         res = session.execute(
             delete(ExternalLink).where(
                 ExternalLink.status == "dead",
-                ExternalLink.created_at < cutoff,
+                ExternalLink.recoveries >= _MAX_RECOVERIES,
+                or_(
+                    ExternalLink.completed_at.is_(None),
+                    ExternalLink.completed_at < cutoff,
+                ),
             )
         )
         session.commit()