trails/openspec/changes/federation-hardening/proposal.md at 7dd9ccd2b0273c44aa0222498cec8efbde87ae9d

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

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.

3 KiB Raw Blame History

Why