trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/changes/archive/2026-07-13-federation-hardening/proposal.md
Ullrich Schäfer 42149d8e02
chore(openspec): archive federation-hardening 
All 13 tasks complete (implementation shipped in #570–573; staging
verification in #574). Archive via `openspec archive` (CLI 1.6.0):

- Creates openspec/specs/federation-operations/spec.md — the new
  capability: durable federation queue, inbound replay defense, instance
  blocklist, published protocol doc, delivery observability (Purpose
  filled in; CLI leaves a TBD placeholder).
- Applies the MODIFIED requirement to openspec/specs/social-federation:
  "Push delivery on local activity create" now guarantees persistent
  queueing + a "Fan-out survives a deploy" scenario.
- Moves the change to openspec/changes/archive/2026-07-13-federation-hardening/.

Both specs pass `openspec validate --strict`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-13 23:54:56 +02:00

3 KiB
Raw Blame History

Why

Reviewing wanderer's federation (2026-07-06, docs/inspirations.md) showed exactly which operational gaps make an ActivityPub implementation fragile in practice: fire-and-forget delivery, no replay defense, no moderation tooling. trails has one of the same gaps today — the social-federation spec promises deliveries "retrying with exponential backoff… after a documented retry budget", but the journal runs Fedify with InProcessMessageQueue (federation.server.ts:156), so every queued delivery and retry is lost on container restart (and restarts are routine: deploys, the OOM/restart-loop history). Before route-federation builds mirrors and cross-instance editing on this foundation, delivery must be durable, inbound processing replay-safe, and instances blockable.

What Changes

  • Durable delivery queue: replace InProcessMessageQueue with a PostgreSQL-backed Fedify MessageQueue (built on the existing pg-boss infrastructure), so queued activities and their retry state survive restarts — closing the gap with what the spec already promises.
  • Inbound replay/dedup defense: processed remote activity IDs are recorded (TTL-bounded) and duplicates are dropped idempotently; complements the existing remoteOriginIri unique constraint which only covers ingested Creates.
  • Instance blocklist: a federation_blocked_instances table (domain, reason) enforced at all three boundaries — inbox processing, delivery enqueue, and outbox polling. Managed via documented SQL/ops procedure for v1 (admin UI out of scope).
  • Published protocol documentation: a root FEDERATION.md (the fediverse convention) documenting objects, activities, addressing, retry semantics, NodeInfo identification, and moderation behavior — wanderer's federation.md with real JSON examples is the model.
  • Delivery observability: metrics for delivery success/failure/retry counts and queue depth, on the existing Grafana journal dashboard.
  • Not in scope: allowlist-mode federation, admin moderation UI, per-user (as opposed to per-instance) blocks, and object-model changes (that's route-federation).

Capabilities

New Capabilities

  • federation-operations: The operational layer of federation — durable delivery, replay defense, instance blocking, protocol documentation, and observability.

Modified Capabilities

  • social-federation: the "Push delivery on local activity create" requirement is strengthened to require queue persistence across process restarts.

Impact

  • apps/journal/app/lib/federation.server.ts — queue swap; new federation-queue.server.ts (Fedify MessageQueue over pg-boss) beside the existing PostgresKvStore.
  • packages/db — federation_blocked_instances + processed-activity dedup table (TTL sweep via existing jobs worker).
  • Inbox/outbound/poll paths — blocklist + dedup checks.
  • FEDERATION.md (root) + docs link; journal Grafana dashboard panels.
  • route-federation (in flight) builds on this; noted there as a dependency.