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>
This commit is contained in:
parent
55da03132a
commit
42149d8e02
8 changed files with 51 additions and 2 deletions
|
|
@ -1,28 +0,0 @@
|
|||
## 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue