trails/openspec/changes/federation-hardening/specs/federation-operations/spec.md at 5dd4968626e98466a447cdcdcb7945aecea646c0

Ullrich Schäfer 5dd4968626 docs+openspec: prior-art research (Organic Maps, Endurain, wanderer) and 15 proposals

Add docs/inspirations.md as the durable record of the 2026-07-05/06
prior-art research — per-project learnings with source paths, canonical
credit lines, and the changes each spawned — and extend the
acknowledgment lists in philosophy.md/architecture.md (Organic Maps,
Endurain, wanderer).

New OpenSpec changes (proposal/design/specs/tasks each):
- Organic Maps: elevation-profile-hardening, gpx-parser-robustness,
  hiking-time-estimate, poi-index, hiking-foot-profile
- Endurain: account-export, activity-duplicate-review,
  fit-parsing-hardening, activity-locations, self-hosting-guide,
  activity-privacy-controls
- wanderer: federation-hardening, link-share-tokens
- credits-page (user-visible acknowledgments)

Updated in-flight changes with wanderer prior-art sections:
route-federation, route-discovery.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-06 07:23:00 +02:00

2.4 KiB

Raw Blame History

ADDED 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.4 KiB Raw Blame History