Files
StarPunk/docs/design/v2.13.0/2026-11-10-backfeed.md
T

2.8 KiB

v2.13.0: Backfeed (implementation report)

Implements ADR-073.

What changed

  • migrations/020_backfeed.sql: webmentions rebuilt with origin, remote_id and the quote type (rows copied, indexes recreated, plus (target_note_id, origin)); syndications gains the backfeed_* columns and Threads counts.
  • starpunk/backfeed.py (new): Response/Harvest, schedule, lease, storing and pruning, opt-outs, backfill, check_now, status.
  • starpunk/syndication.py: responses() on MastodonClient, BlueskyClient and ThreadsClient; HTTP status kept on errors (exc.status) so refused credentials can be told apart; Mastodon _call accepts absolute URLs (pagination links); the worker loop runs backfeed after crossposts; Threads host is graph.threads.com.
  • starpunk/avatars.py (new) and /avatars/<name>: local avatar copies for every response; local_avatar template filter.
  • Webmentions: Quotes group and "via" label; admin delete is a tombstone (moderation_status = 'deleted', hidden from the list unless filtered); origin filter; a webmention can't reset a backfed row, and one whose source is an already backfed response is rejected ("Already backfed").
  • Admin: Backfeed panel with Backfill responses on the Webmentions page; Check now and last-checked time per crosspost on the edit page.
  • Settings BACKFEED_ENABLED (default false), BACKFEED_MAX_AGE_DAYS (90).

Verification

  • tests/test_backfeed.py (22 tests): schedule; text/facet HTML; storing, updating and moderation kept; pruning only on complete harvests and restoring; opt-outs; tombstones; backfill and its pacing; likes/reposts and drafts skipped; refused credentials; backoff; note page (via label, quotes, Threads counts, local avatars); avatar save/serve/cleanup; webmention can't overwrite a backfed row; the three clients against fake APIs; migration 020 on a pre-020 database keeps rows and foreign keys; the admin Backfeed panel, backfill and Check now; Threads avatar URLs (signed, changing per request) aren't refetched while a copy exists.
  • Tests for the touched areas (webmentions, syndication, microformats, migrations, templates, routes): all pass. The full suite runs in CI.
  • test_microformats_v280 expects response authors' u-photo: kept via <data class="u-photo"> until the avatar is saved.

Deploying

  1. Issue a new GoToSocial token with read:statuses read:accounts added to the current scopes, and re-authorise the Threads app with threads_read_replies and threads_manage_insights. Put both in the Ansible vault.
  2. Set BACKFEED_ENABLED=true in the StarPunk environment and deploy (migration 020 runs at start: back up the database first).
  3. Run Backfill responses once from Admin → Webmentions. Turn Bridgy off for the Mastodon and Bluesky accounts.