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/tasks.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

2.5 KiB
Raw Blame History

1. Durable queue

  • 1.1 Implement federation-queue.server.ts: Fedify MessageQueue over pg-boss (enqueue with delay, listen loop), mirroring the PostgresKvStore adapter pattern
  • 1.2 Swap InProcessMessageQueue for it in federation.server.ts; document the two-layer queueing (fan-out jobs + Fedify queue) in a code comment
  • 1.3 Tests: enqueue/delay/consume roundtrip; simulated restart (new listener picks up previously enqueued messages)

2. Replay defense

  • 2.1 Add federation_processed_activities table (activity IRI PK, received_at) + migration; insert-or-drop check in inbox handlers before side effects
  • 2.2 30-day TTL sweep in the jobs worker
  • 2.3 Tests: duplicate Like/Delete/Update dropped as no-ops; Create double-delivery still covered by remoteOriginIri constraint

3. Blocklist

  • 3.1 Add federation_blocked_instances table + migration; exact-host check helper
  • 3.2 Enforce at inbox (silent 202 drop + counter), delivery enqueue (filter recipients), and outbox poll/actor fetch (refuse)
  • 3.3 Document the operator procedure (SQL insert/delete) in the ops docs; tests for all three boundaries

4. Protocol doc & observability

  • 4.1 Write FEDERATION.md (repo root): NodeInfo, actors/WebFinger, object + activity types with JSON examples, addressing, signatures + dedup expectations, retry policy, moderation semantics; link from README and docs
  • 4.2 Add federation_delivery_total{outcome}, federation_queue_depth, federation_inbox_dropped_total{reason} metrics + journal dashboard row

5. Verification

  • 5.1 Staging check (verified on staging.trails.cool 2026-07-13): queued a real delivery, restarted the journal container mid-flight — the job survived the restart in Postgres (the old in-process queue would have lost it) and completed after, "Successfully sent activity … to social.ullrich.is/users/ullrich/inbox" (federation_delivery_total{outcome="delivered"} 1, queue drained to 0). Blocklist outbound verified: a poll-remote-actor for a blocked domain logged result: {skipped: "blocked instance"} (no fetch). Operator block/unblock procedure works against the live DB. The blocklist inbound drop is covered by the group-2/3 real-Postgres integration tests + the two-instance e2e/federation/ harness (firing it live needs a peer-initiated signed request).
  • 5.2 Run pnpm typecheck && pnpm lint && pnpm test && pnpm test:e2e — typecheck/lint/test green locally; test:e2e enforced by the required "E2E Tests" CI check on every PR