Phase 5: federation

Implements PLAN.md Phase 5: the Server-Server API. Warp joins rooms on
other servers and lets their users join its rooms, invites across servers
with the invitee's server countersigning, rejects remote invites (locally
if the inviter is unreachable), and exchanges events, typing, receipts and
to-device messages with other homeservers — all behind the runtime switch,
which now starts and stops real outbound traffic.

The protocol lives in internal/federation with no knowledge of rooms:
X-Matrix signing (fuzzed parser), the spec's discovery algorithm keeping
the dial address and the TLS name apart, a signed client that refuses
every request while the switch is off or the policy denies the
destination, and a key ring that caches other servers' keys for at most a
week, with optional notaries.

The roomserver takes events from elsewhere through the spec's intake:
signatures and hashes (a hash mismatch keeps the redacted form), the rules
against the event's own auth events, against the state before it — with
/get_missing_events for small gaps and /state_ids for wide ones — and
against the current state, where a failure is a soft failure. Events held
without their state are outliers: a column on roomserver_events, because
the current state of a room joined over federation is almost all
outliers, and excluded from every timeline query. Forks are resolved at
the room's head. Membership across servers is make_join/send_join,
make_leave/send_leave and countersigned invites, in both directions;
m.room.server_acl is enforced on everything another server sends.
History before a remote join is backfilled when /messages pages past it,
stored at negative stream positions.

internal/federationapi is the running component: the inbound endpoints,
and an outbound queue that persists what it owes each destination, sends
it in transactions of 50 PDUs and 100 EDUs, backs off from ten seconds to
six hours, survives restarts, and drops events persisted while federation
is off rather than delivering a backlog in one burst. Its Module is what
the switch starts and stops.

Also: a TLS listener for port 8448, trusted key servers, key validity and
an outbound CA bundle in the config; per-destination health and backoff
reset in the admin API; remote profiles, aliases and directories in the
Client-Server API; a Complement federation profile. See
docs/federation.md, including its known gaps (no partial-state joins, no
key rotation).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

server/internal/federationapi/module.go

@@ -0,0 +1,96 @@
+// Package federationapi is the Server-Server API as a running component:
+// the inbound endpoints other servers call, the outbound queue that sends
+// them this server's events, and the Module that starts and stops it all
+// with the federation switch.
+//
+// The protocol itself — X-Matrix signing, server discovery, the HTTP
+// client, keys — is in package federation. This package is where that
+// protocol meets the roomserver and the sync API, which is why it is
+// separate: the roomserver uses the protocol, and this package uses the
+// roomserver.
+package federationapi
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+)
+
+// Module is the switchable part of federation: everything that runs in the
+// background and talks to other servers on its own initiative.
+//
+// The inbound endpoints are not in it. They are behind the gate, which
+// reads the switch on every request, so they need nothing started or
+// stopped. What does is the outbound queue — the only thing in Warp that
+// opens connections to other servers unprompted — and turning federation
+// off stops it mid-flight, leaving what it had not sent in the database for
+// when federation comes back on.
+//
+// Requests a component makes on a client's behalf — a join, a key fetch,
+// a profile lookup — need nothing stopping either: the client refuses
+// every request while the switch is off.
+type Module struct {
+	queue *Queue
+	log   *slog.Logger
+
+	mu      sync.Mutex
+	running bool
+}
+
+// NewModule builds a stopped module.
+func NewModule(queue *Queue, log *slog.Logger) *Module {
+	if log == nil {
+		log = slog.Default()
+	}
+	return &Module{queue: queue, log: log}
+}
+
+// Start brings federation up. Starting a running module does nothing.
+func (m *Module) Start(ctx context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.running {
+		return nil
+	}
+	if err := m.queue.Start(ctx); err != nil {
+		m.queue.Stop()
+		return err
+	}
+	m.running = true
+	m.log.Info("federation started")
+	return nil
+}
+
+// Stop takes federation down and waits for in-flight sends to finish or
+// be cancelled. Stopping a stopped module does nothing.
+func (m *Module) Stop() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if !m.running {
+		return
+	}
+	m.queue.Stop()
+	m.running = false
+	m.log.Info("federation stopped")
+}
+
+// Apply starts or stops the module to match the switch.
+func (m *Module) Apply(ctx context.Context, enabled bool) {
+	if enabled {
+		if err := m.Start(ctx); err != nil {
+			m.log.Error("could not start federation", "error", err)
+		}
+		return
+	}
+	m.Stop()
+}
+
+// Running reports whether the module is up.
+func (m *Module) Running() bool {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.running
+}
+
+// Queue exposes the outbound queue, for the admin API.
+func (m *Module) Queue() *Queue { return m.queue }