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.8 KiB

Raw Blame History

federation-operations Specification

Purpose

Operational hardening of the Journal's ActivityPub federation: a durable (Postgres-backed) message queue so deliveries and retries survive restarts, inbound replay defense, a domain-keyed instance blocklist enforced at inbox/delivery/outbox boundaries, published protocol documentation (FEDERATION.md), and delivery observability metrics.

Requirements

Requirement: Durable federation queue

Fedify's message queue SHALL be backed by PostgreSQL so that queued activities, inbox processing tasks, and retry state survive process restarts and deploys.

Scenario: Delivery survives a restart

WHEN deliveries are queued and the journal container restarts before they complete
THEN the deliveries execute after restart without loss

Scenario: Retry state persists

WHEN a delivery has failed twice with backoff pending and the process restarts
THEN the retry continues on schedule rather than starting over or disappearing

Requirement: Inbound replay defense

The Journal SHALL record processed inbound activity IRIs (retained at least 30 days) and SHALL drop duplicate activities idempotently before any side effects.

Scenario: Replayed activity is a no-op

WHEN the same signed Like activity is delivered twice
THEN the second delivery produces no state change and is counted as a dropped duplicate

Requirement: Instance blocklist

The Journal SHALL support blocking federation instances by domain, enforced at inbox processing (activities dropped without an error oracle), delivery enqueue (recipients filtered), and outbox polling/actor fetch (refused). Blocking SHALL be manageable via a documented operator procedure.

Scenario: Blocked instance is inert in both directions

WHEN a domain is added to the blocklist
THEN its activities are silently dropped, no deliveries are sent to it, and its actors/outboxes are not fetched

Requirement: Published federation protocol documentation

The repository SHALL contain a FEDERATION.md documenting actor discovery, object and activity types with JSON examples, addressing rules, signature and deduplication expectations, delivery retry policy, and moderation semantics, kept current as federation capabilities change.

Scenario: Third-party implementer can interoperate

WHEN another project implements against FEDERATION.md
THEN the documented flows (follow, create fan-out, dedup) behave as described

Requirement: Federation delivery observability

The Journal SHALL expose metrics for delivery outcomes, queue depth, and inbox drops (duplicate/blocked), surfaced on the monitoring dashboard.

Scenario: Operator sees delivery health

WHEN deliveries to an unreachable instance keep failing
THEN failure counts and queue depth are visible on the dashboard

2.8 KiB Raw Blame History