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/edus.go

@@ -0,0 +1,98 @@
+package federationapi
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/json"
+	"time"
+
+	"github.com/dariuszjaniak/warp/server/internal/federation"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/id"
+)
+
+// EDUs turns the sync API's local typing, receipts and to-device messages
+// into queued EDUs. It implements syncapi.Outbound.
+type EDUs struct {
+	queue *Queue
+	rooms RoomServers
+}
+
+// NewEDUs builds the adapter.
+func NewEDUs(queue *Queue, rooms RoomServers) *EDUs {
+	return &EDUs{queue: queue, rooms: rooms}
+}
+
+// roomServers is everybody in a room but this server; the queue drops
+// this server anyway, and an error is logged rather than returned, because
+// a typing notification that does not go out is not worth failing the
+// client's request over.
+func (e *EDUs) roomServers(ctx context.Context, roomID string) []string {
+	servers, err := e.rooms.JoinedServers(ctx, roomID)
+	if err != nil {
+		e.queue.log.Warn("could not read a room's servers for an EDU", "room_id", roomID, "error", err)
+		return nil
+	}
+	return servers
+}
+
+// Typing implements syncapi.Outbound.
+func (e *EDUs) Typing(ctx context.Context, roomID, userID string, typing bool, _ time.Duration) {
+	if !e.queue.Running() {
+		return
+	}
+	content, _ := json.Marshal(federation.TypingContent{RoomID: roomID, UserID: userID, Typing: typing})
+	e.queue.QueueEDU(ctx, e.roomServers(ctx, roomID), federation.EDU{Type: federation.EDUTyping, Content: content})
+}
+
+// Receipt implements syncapi.Outbound.
+func (e *EDUs) Receipt(ctx context.Context, roomID, userID, receiptType, eventID, threadID string, ts int64) {
+	if !e.queue.Running() || receiptType != "m.read" {
+		return
+	}
+	var data federation.ReceiptData
+	data.EventIDs = []string{eventID}
+	data.Data.TS = ts
+	data.Data.ThreadID = threadID
+	content, _ := json.Marshal(federation.ReceiptContent{roomID: {receiptType: {userID: data}}})
+	e.queue.QueueEDU(ctx, e.roomServers(ctx, roomID), federation.EDU{Type: federation.EDUReceipt, Content: content})
+}
+
+// ToDevice implements syncapi.Outbound: one m.direct_to_device per
+// destination, carrying that server's recipients only.
+func (e *EDUs) ToDevice(ctx context.Context, sender, eventType string, messages map[string]map[string]json.RawMessage) {
+	if !e.queue.Running() {
+		return
+	}
+	byServer := map[string]map[string]map[string]json.RawMessage{}
+	for userID, devices := range messages {
+		server, err := id.ServerNameOf(userID)
+		if err != nil {
+			continue
+		}
+		if byServer[server] == nil {
+			byServer[server] = map[string]map[string]json.RawMessage{}
+		}
+		byServer[server][userID] = devices
+	}
+	for server, recipients := range byServer {
+		content, err := json.Marshal(federation.DirectToDeviceContent{
+			Sender:    sender,
+			Type:      eventType,
+			MessageID: messageID(),
+			Messages:  recipients,
+		})
+		if err != nil {
+			continue
+		}
+		e.queue.QueueEDU(ctx, []string{server}, federation.EDU{Type: federation.EDUDirectToDev, Content: content})
+	}
+}
+
+// messageID is the per-message identifier a receiving server deduplicates
+// a to-device message by.
+func messageID() string {
+	buf := make([]byte, 12)
+	_, _ = rand.Read(buf)
+	return base64.RawURLEncoding.EncodeToString(buf)
+}

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 }

server/internal/federationapi/queue.go

@@ -0,0 +1,563 @@
+package federationapi
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"math/rand/v2"
+	"slices"
+	"strconv"
+	"sync"
+	"time"
+
+	"github.com/dariuszjaniak/warp/server/internal/federation"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/event"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/id"
+	"github.com/dariuszjaniak/warp/server/internal/roomserver"
+	"github.com/dariuszjaniak/warp/server/internal/storage"
+)
+
+// The outbound queue: every event and EDU this server owes another one.
+//
+// It has three moving parts. The roomserver hands it every persisted event
+// through EventPersisted, which only appends to an in-memory list — it is
+// called with the room's write lock held and must not touch the database.
+// A dispatcher drains that list, works out each event's destinations and
+// writes one queue row per destination. And one worker per destination
+// with something queued sends it, in transactions of up to 50 PDUs and
+// 100 EDUs, backing off exponentially when the destination fails.
+//
+// The rows are deleted only once the destination has answered, so a crash
+// or a restart loses nothing that had reached the database, and a
+// destination that is down gets everything it missed when it comes back.
+// What it does lose is the dispatcher's in-memory list: the events
+// persisted in the instant before a crash. A remote server notices those
+// as gaps the next time it hears from this one, and fetches them.
+
+// Transaction limits, from the spec.
+const (
+	maxPDUsPerTxn = 50
+	maxEDUsPerTxn = 100
+)
+
+// Backoff bounds. The first retry comes quickly, because most failures are
+// a restart on the other side; the cap is long, because a server that has
+// been gone for a day is not coming back in the next minute, and every
+// retry costs a connection attempt.
+const (
+	defaultMinBackoff = 10 * time.Second
+	defaultMaxBackoff = 6 * time.Hour
+)
+
+// sendTimeout bounds one transaction.
+const sendTimeout = 2 * time.Minute
+
+// Sender is the part of the federation client the queue uses.
+type Sender interface {
+	SendTransaction(ctx context.Context, destination, txnID string, txn federation.Transaction) (federation.SendTransactionResponse, error)
+}
+
+// RoomServers says which servers are in a room.
+type RoomServers interface {
+	JoinedServers(ctx context.Context, roomID string) ([]string, error)
+}
+
+// QueueOptions configure a Queue.
+type QueueOptions struct {
+	ServerName string
+	Store      storage.FederationStore
+	Sender     Sender
+	Rooms      RoomServers
+	Policy     *federation.Policy
+
+	MinBackoff time.Duration
+	MaxBackoff time.Duration
+
+	Logger *slog.Logger
+	Now    func() time.Time
+}
+
+// Queue is the outbound queue.
+type Queue struct {
+	serverName string
+	store      storage.FederationStore
+	sender     Sender
+	rooms      RoomServers
+	policy     *federation.Policy
+	minBackoff time.Duration
+	maxBackoff time.Duration
+	log        *slog.Logger
+	now        func() time.Time
+
+	// txnPrefix makes transaction IDs unique across restarts: a remote
+	// server deduplicates by (origin, txn ID), and an ID reused with
+	// different contents would be answered from its cache and the events
+	// in it never seen.
+	txnPrefix string
+
+	mu       sync.Mutex
+	running  bool
+	ctx      context.Context
+	cancel   context.CancelFunc
+	wg       sync.WaitGroup
+	incoming []roomserver.Notification
+	wake     chan struct{}
+	workers  map[string]*worker
+	txnSeq   uint64
+}
+
+// worker sends one destination's queue.
+type worker struct {
+	destination string
+	wake        chan struct{}
+}
+
+// NewQueue builds a stopped queue.
+func NewQueue(opts QueueOptions) *Queue {
+	if opts.Logger == nil {
+		opts.Logger = slog.Default()
+	}
+	if opts.Now == nil {
+		opts.Now = time.Now
+	}
+	if opts.MinBackoff <= 0 {
+		opts.MinBackoff = defaultMinBackoff
+	}
+	if opts.MaxBackoff < opts.MinBackoff {
+		opts.MaxBackoff = max(defaultMaxBackoff, opts.MinBackoff)
+	}
+	if opts.Policy == nil {
+		opts.Policy = federation.NewPolicy(nil, nil)
+	}
+	return &Queue{
+		serverName: opts.ServerName,
+		store:      opts.Store,
+		sender:     opts.Sender,
+		rooms:      opts.Rooms,
+		policy:     opts.Policy,
+		minBackoff: opts.MinBackoff,
+		maxBackoff: opts.MaxBackoff,
+		log:        opts.Logger,
+		now:        opts.Now,
+		wake:       make(chan struct{}, 1),
+		workers:    map[string]*worker{},
+	}
+}
+
+// Start begins sending: the dispatcher, and a worker for every destination
+// with something left in the queue from before.
+func (q *Queue) Start(ctx context.Context) error {
+	q.mu.Lock()
+	if q.running {
+		q.mu.Unlock()
+		return nil
+	}
+	q.ctx, q.cancel = context.WithCancel(context.WithoutCancel(ctx))
+	q.running = true
+	q.txnPrefix = strconv.FormatInt(q.now().UnixNano(), 36)
+	q.mu.Unlock()
+
+	q.wg.Add(1)
+	go q.dispatch()
+
+	destinations, err := q.store.QueuedDestinations(ctx)
+	if err != nil {
+		return fmt.Errorf("read the outbound queue: %w", err)
+	}
+	for _, d := range destinations {
+		q.kick(d)
+	}
+	q.log.Info("federation queue started", "destinations_with_backlog", len(destinations))
+	return nil
+}
+
+// Stop halts every send and waits for the workers to finish. What is
+// queued stays queued.
+func (q *Queue) Stop() {
+	q.mu.Lock()
+	if !q.running {
+		q.mu.Unlock()
+		return
+	}
+	q.running = false
+	q.cancel()
+	q.incoming = nil
+	q.mu.Unlock()
+
+	q.wg.Wait()
+
+	q.mu.Lock()
+	q.workers = map[string]*worker{}
+	q.mu.Unlock()
+	q.log.Info("federation queue stopped")
+}
+
+// Running reports whether the queue is sending.
+func (q *Queue) Running() bool {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	return q.running
+}
+
+// EventPersisted implements roomserver.Notifier. It must not block, and
+// does not: it appends and signals.
+//
+// While the queue is stopped events are dropped rather than held. That is
+// what the federation switch promises — no remote traffic while it is off
+// — and holding them would turn switching federation back on after a month
+// into a month of events delivered in one burst. A remote server that
+// cares about the room fetches what it missed when it next hears from it.
+func (q *Queue) EventPersisted(_ context.Context, n roomserver.Notification) {
+	if n.Origin != "" && !n.Relay {
+		return
+	}
+	q.mu.Lock()
+	if !q.running {
+		q.mu.Unlock()
+		return
+	}
+	q.incoming = append(q.incoming, n)
+	q.mu.Unlock()
+	select {
+	case q.wake <- struct{}{}:
+	default:
+	}
+}
+
+// dispatch turns persisted events into queue rows.
+func (q *Queue) dispatch() {
+	defer q.wg.Done()
+	for {
+		select {
+		case <-q.ctx.Done():
+			return
+		case <-q.wake:
+		}
+		q.mu.Lock()
+		batch := q.incoming
+		q.incoming = nil
+		q.mu.Unlock()
+
+		for _, n := range batch {
+			if err := q.queueEvent(q.ctx, n); err != nil && q.ctx.Err() == nil {
+				q.log.Error("could not queue an event for federation",
+					"room_id", n.RoomID, "event_id", n.Event.EventID(), "error", err)
+			}
+		}
+	}
+}
+
+// queueEvent writes one event's queue rows.
+func (q *Queue) queueEvent(ctx context.Context, n roomserver.Notification) error {
+	servers, err := q.rooms.JoinedServers(ctx, n.RoomID)
+	if err != nil {
+		return err
+	}
+	// A membership event also goes to the server of the user it is about:
+	// a server whose last user was just kicked is no longer joined, and is
+	// exactly the one that needs to hear it.
+	if key, ok := n.Event.StateKey(); ok && n.Event.Type() == event.TypeMember {
+		if server, err := id.ServerNameOf(key); err == nil && !slices.Contains(servers, server) {
+			servers = append(servers, server)
+		}
+	}
+
+	var items []storage.QueuedItem
+	for _, server := range servers {
+		if server == q.serverName || server == n.Origin || !q.policy.Allowed(server) {
+			continue
+		}
+		items = append(items, storage.QueuedItem{
+			Destination: server,
+			Kind:        storage.QueueKindPDU,
+			RoomID:      n.RoomID,
+			EventID:     n.Event.EventID(),
+			Payload:     n.Event.JSON(),
+			QueuedAtMS:  q.now().UnixMilli(),
+		})
+	}
+	return q.enqueue(ctx, items)
+}
+
+// QueueEDU queues an EDU for a set of destinations.
+func (q *Queue) QueueEDU(ctx context.Context, destinations []string, edu federation.EDU) {
+	if !q.Running() {
+		return
+	}
+	payload, err := json.Marshal(edu)
+	if err != nil {
+		q.log.Error("could not encode an EDU", "type", edu.Type, "error", err)
+		return
+	}
+	var items []storage.QueuedItem
+	for _, server := range destinations {
+		if server == q.serverName || !q.policy.Allowed(server) {
+			continue
+		}
+		items = append(items, storage.QueuedItem{
+			Destination: server,
+			Kind:        storage.QueueKindEDU,
+			Payload:     payload,
+			QueuedAtMS:  q.now().UnixMilli(),
+		})
+	}
+	if err := q.enqueue(ctx, items); err != nil {
+		q.log.Error("could not queue an EDU", "type", edu.Type, "error", err)
+	}
+}
+
+// enqueue writes rows and wakes their workers.
+func (q *Queue) enqueue(ctx context.Context, items []storage.QueuedItem) error {
+	if len(items) == 0 {
+		return nil
+	}
+	if _, err := q.store.Enqueue(ctx, items); err != nil {
+		return err
+	}
+	seen := map[string]bool{}
+	for _, item := range items {
+		if !seen[item.Destination] {
+			seen[item.Destination] = true
+			q.kick(item.Destination)
+		}
+	}
+	return nil
+}
+
+// kick wakes a destination's worker, starting one if there is none.
+func (q *Queue) kick(destination string) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	if !q.running {
+		return
+	}
+	w, ok := q.workers[destination]
+	if !ok {
+		w = &worker{destination: destination, wake: make(chan struct{}, 1)}
+		q.workers[destination] = w
+		q.wg.Add(1)
+		go q.run(w)
+	}
+	select {
+	case w.wake <- struct{}{}:
+	default:
+	}
+}
+
+// run is one destination's worker. It sends until the queue for the
+// destination is empty, then exits; the next enqueue starts a new one.
+func (q *Queue) run(w *worker) {
+	defer q.wg.Done()
+	for {
+		dest, err := q.store.Destination(q.ctx, w.destination)
+		if err != nil {
+			if q.ctx.Err() != nil {
+				return
+			}
+			q.log.Error("could not read a destination's backoff", "destination", w.destination, "error", err)
+			dest = storage.Destination{ServerName: w.destination}
+		}
+		if wait := time.Duration(dest.RetryAtMS-q.now().UnixMilli()) * time.Millisecond; wait > 0 {
+			// A wake-up during the wait re-reads the backoff, which is how
+			// an administrator's reset takes effect at once; an ordinary
+			// enqueue finds the backoff unchanged and waits again.
+			timer := time.NewTimer(wait)
+			select {
+			case <-q.ctx.Done():
+				timer.Stop()
+				return
+			case <-w.wake:
+				timer.Stop()
+				continue
+			case <-timer.C:
+			}
+		}
+
+		sent, err := q.sendOnce(w.destination, dest)
+		if q.ctx.Err() != nil {
+			return
+		}
+		if err != nil {
+			// A failed send has recorded its backoff, which the next pass
+			// waits out. The pause here is for the other kind of failure —
+			// the queue's own database — which records nothing and would
+			// otherwise be retried in a tight loop.
+			select {
+			case <-q.ctx.Done():
+				return
+			case <-time.After(time.Second):
+			}
+			continue
+		}
+		if !sent && q.retire(w) {
+			return
+		}
+	}
+}
+
+// retire removes an idle worker, unless something was queued for it in
+// the meantime.
+func (q *Queue) retire(w *worker) bool {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	select {
+	case <-w.wake:
+		return false
+	default:
+	}
+	if q.workers[w.destination] == w {
+		delete(q.workers, w.destination)
+	}
+	return true
+}
+
+// sendOnce sends one transaction. It reports whether there was anything to
+// send.
+func (q *Queue) sendOnce(destination string, health storage.Destination) (bool, error) {
+	pdus, err := q.store.Queued(q.ctx, destination, storage.QueueKindPDU, maxPDUsPerTxn)
+	if err != nil {
+		return false, err
+	}
+	edus, err := q.store.Queued(q.ctx, destination, storage.QueueKindEDU, maxEDUsPerTxn)
+	if err != nil {
+		return false, err
+	}
+	if len(pdus) == 0 && len(edus) == 0 {
+		return false, nil
+	}
+
+	// A destination the policy no longer allows gets nothing, and what
+	// was queued for it is dropped: the allow and deny lists can change at
+	// runtime, and a backlog for a server that was just denied is exactly
+	// what must not go out.
+	if !q.policy.Allowed(destination) {
+		return true, q.store.Dequeue(q.ctx, append(itemIDs(pdus), itemIDs(edus)...))
+	}
+
+	txn := federation.Transaction{
+		Origin:         q.serverName,
+		OriginServerTS: q.now().UnixMilli(),
+		PDUs:           make([]json.RawMessage, 0, len(pdus)),
+	}
+	for _, item := range pdus {
+		txn.PDUs = append(txn.PDUs, item.Payload)
+	}
+	for _, item := range edus {
+		var edu federation.EDU
+		if err := json.Unmarshal(item.Payload, &edu); err == nil {
+			txn.EDUs = append(txn.EDUs, edu)
+		}
+	}
+
+	ctx, cancel := context.WithTimeout(q.ctx, sendTimeout)
+	defer cancel()
+	resp, err := q.sender.SendTransaction(ctx, destination, q.nextTxnID(), txn)
+	if err != nil {
+		if q.ctx.Err() != nil {
+			return true, err
+		}
+		q.recordFailure(destination, health, err)
+		return true, err
+	}
+
+	for eventID, result := range resp.PDUs {
+		if result.Error != "" {
+			q.log.Info("a destination refused an event",
+				"destination", destination, "event_id", eventID, "error", result.Error)
+		}
+	}
+	if err := q.store.Dequeue(q.ctx, append(itemIDs(pdus), itemIDs(edus)...)); err != nil {
+		return true, err
+	}
+	if health.Failures > 0 || health.LastSuccessMS == 0 {
+		q.log.Info("destination is reachable", "destination", destination, "after_failures", health.Failures)
+		if err := q.store.SetDestination(q.ctx, storage.Destination{
+			ServerName:    destination,
+			LastSuccessMS: q.now().UnixMilli(),
+			LastFailureMS: health.LastFailureMS,
+			LastError:     health.LastError,
+		}); err != nil {
+			q.log.Warn("could not record a destination's recovery", "destination", destination, "error", err)
+		}
+	}
+	return true, nil
+}
+
+// recordFailure backs a destination off.
+func (q *Queue) recordFailure(destination string, health storage.Destination, err error) {
+	failures := health.Failures + 1
+	backoff := q.backoff(failures)
+	now := q.now()
+	q.log.Info("sending to a destination failed",
+		"destination", destination, "failures", failures, "retry_in", backoff, "error", err)
+	if serr := q.store.SetDestination(q.ctx, storage.Destination{
+		ServerName:    destination,
+		Failures:      failures,
+		RetryAtMS:     now.Add(backoff).UnixMilli(),
+		LastSuccessMS: health.LastSuccessMS,
+		LastFailureMS: now.UnixMilli(),
+		LastError:     truncate(err.Error(), 500),
+	}); serr != nil {
+		q.log.Warn("could not record a destination's backoff", "destination", destination, "error", serr)
+	}
+}
+
+// backoff is the wait after a number of consecutive failures: doubling
+// from the minimum up to the cap, with a fifth of jitter so that a server
+// coming back is not hit by every other server's retry at once.
+func (q *Queue) backoff(failures int) time.Duration {
+	d := q.minBackoff
+	for i := 1; i < failures && d < q.maxBackoff; i++ {
+		d *= 2
+	}
+	if d > q.maxBackoff {
+		d = q.maxBackoff
+	}
+	jitter := time.Duration(rand.Int64N(int64(d)/5 + 1))
+	return d + jitter
+}
+
+// nextTxnID mints a transaction ID.
+func (q *Queue) nextTxnID() string {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	q.txnSeq++
+	return q.txnPrefix + "_" + strconv.FormatUint(q.txnSeq, 10)
+}
+
+// Destinations lists every destination the queue knows, for the admin API.
+func (q *Queue) Destinations(ctx context.Context) ([]storage.DestinationSummary, error) {
+	return q.store.Destinations(ctx)
+}
+
+// ResetBackoff clears a destination's backoff so that it is tried now,
+// for an administrator who knows it is back.
+func (q *Queue) ResetBackoff(ctx context.Context, destination string) error {
+	health, err := q.store.Destination(ctx, destination)
+	if err != nil {
+		return err
+	}
+	health.Failures = 0
+	health.RetryAtMS = 0
+	if err := q.store.SetDestination(ctx, health); err != nil {
+		return err
+	}
+	q.kick(destination)
+	return nil
+}
+
+func itemIDs(items []storage.QueuedItem) []int64 {
+	out := make([]int64, 0, len(items))
+	for _, item := range items {
+		out = append(out, item.ID)
+	}
+	return out
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n]
+}

server/internal/federationapi/queue_test.go

@@ -0,0 +1,316 @@
+package federationapi
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"path/filepath"
+	"slices"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/dariuszjaniak/warp/server/internal/federation"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/event"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/roomversion"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/signing"
+	"github.com/dariuszjaniak/warp/server/internal/roomserver"
+	"github.com/dariuszjaniak/warp/server/internal/storage"
+	_ "github.com/dariuszjaniak/warp/server/internal/storage/drivers"
+)
+
+const ourName = "warp.example"
+
+// fakeSender records transactions and fails on demand.
+type fakeSender struct {
+	mu   sync.Mutex
+	txns map[string][]federation.Transaction
+	ids  map[string]bool
+	down map[string]bool
+}
+
+func newFakeSender() *fakeSender {
+	return &fakeSender{txns: map[string][]federation.Transaction{}, ids: map[string]bool{}, down: map[string]bool{}}
+}
+
+func (f *fakeSender) SendTransaction(_ context.Context, destination, txnID string, txn federation.Transaction) (federation.SendTransactionResponse, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.down[destination] {
+		return federation.SendTransactionResponse{}, errors.New("connection refused")
+	}
+	if f.ids[txnID] {
+		return federation.SendTransactionResponse{}, fmt.Errorf("transaction ID %s reused", txnID)
+	}
+	f.ids[txnID] = true
+	f.txns[destination] = append(f.txns[destination], txn)
+	return federation.SendTransactionResponse{PDUs: map[string]federation.PDUResult{}}, nil
+}
+
+func (f *fakeSender) setDown(destination string, down bool) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.down[destination] = down
+}
+
+// pdus returns how many PDUs a destination has received.
+func (f *fakeSender) pdus(destination string) int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	n := 0
+	for _, txn := range f.txns[destination] {
+		n += len(txn.PDUs)
+	}
+	return n
+}
+
+func (f *fakeSender) largestTxn(destination string) int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	largest := 0
+	for _, txn := range f.txns[destination] {
+		largest = max(largest, len(txn.PDUs))
+	}
+	return largest
+}
+
+func (f *fakeSender) edus(destination string) []federation.EDU {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var out []federation.EDU
+	for _, txn := range f.txns[destination] {
+		out = append(out, txn.EDUs...)
+	}
+	return out
+}
+
+// fakeRooms answers JoinedServers from a table.
+type fakeRooms map[string][]string
+
+func (f fakeRooms) JoinedServers(_ context.Context, roomID string) ([]string, error) {
+	return f[roomID], nil
+}
+
+func openStore(t *testing.T) storage.FederationStore {
+	t.Helper()
+	db, err := storage.Open(t.Context(), storage.Config{
+		Driver:           storage.DriverSQLite,
+		ConnectionString: "file:" + filepath.ToSlash(filepath.Join(t.TempDir(), "q.db")) + "?_pragma=busy_timeout(5000)",
+	}, slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	if err := db.Migrate(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+	return db.Federation()
+}
+
+func newTestQueue(t *testing.T, store storage.FederationStore, sender Sender, rooms RoomServers, policy *federation.Policy) *Queue {
+	t.Helper()
+	q := NewQueue(QueueOptions{
+		ServerName: ourName,
+		Store:      store,
+		Sender:     sender,
+		Rooms:      rooms,
+		Policy:     policy,
+		MinBackoff: 20 * time.Millisecond,
+		MaxBackoff: 100 * time.Millisecond,
+		Logger:     slog.New(slog.DiscardHandler),
+	})
+	t.Cleanup(q.Stop)
+	return q
+}
+
+var testKey = func() *signing.KeyPair {
+	k, err := signing.Generate("q")
+	if err != nil {
+		panic(err)
+	}
+	return k
+}()
+
+// notification builds a persisted-event notification for a message, or a
+// membership event about target when target is set.
+func notification(t *testing.T, roomID, sender, target string, n int) roomserver.Notification {
+	t.Helper()
+	b := event.Builder{
+		RoomID: roomID, Type: "m.room.message", Sender: sender,
+		Content:    json.RawMessage(fmt.Sprintf(`{"body":"%d"}`, n)),
+		PrevEvents: []string{"$prev"}, AuthEvents: []string{"$auth"}, Depth: int64(n + 2),
+	}
+	if target != "" {
+		b.Type = event.TypeMember
+		b.StateKey = &target
+		b.Content = json.RawMessage(`{"membership":"leave"}`)
+	}
+	e, err := b.Build(time.Unix(1_700_000_000+int64(n), 0), testKey, roomversion.MustGet("11"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return roomserver.Notification{RoomID: roomID, Event: e, StreamOrdering: int64(n)}
+}
+
+func waitFor(t *testing.T, what string, check func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) {
+		if check() {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatalf("timed out waiting for %s", what)
+}
+
+func TestQueueSendsToTheRoomsServers(t *testing.T) {
+	sender := newFakeSender()
+	rooms := fakeRooms{"!r:warp.example": {ourName, "a.example", "b.example"}}
+	q := newTestQueue(t, openStore(t), sender, rooms, nil)
+	if err := q.Start(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+
+	q.EventPersisted(t.Context(), notification(t, "!r:warp.example", "@me:"+ourName, "", 1))
+	// Received from b and not to be relayed: b sends its own events.
+	received := notification(t, "!r:warp.example", "@x:b.example", "", 2)
+	received.Origin = "b.example"
+	q.EventPersisted(t.Context(), received)
+	// A join handed over by send_join from c: relayed to everybody but c.
+	relayed := notification(t, "!r:warp.example", "@y:c.example", "", 3)
+	relayed.Origin, relayed.Relay = "c.example", true
+	q.EventPersisted(t.Context(), relayed)
+	// A kick of a user on d, whose server is no longer joined but must
+	// hear of it.
+	q.EventPersisted(t.Context(), notification(t, "!r:warp.example", "@me:"+ourName, "@z:d.example", 4))
+
+	waitFor(t, "deliveries", func() bool {
+		return sender.pdus("a.example") == 3 && sender.pdus("b.example") == 3 && sender.pdus("d.example") == 1
+	})
+	if n := sender.pdus("c.example"); n != 0 {
+		t.Errorf("c received %d PDUs; it is not in the room and its own join was not to be echoed", n)
+	}
+	if n := sender.pdus(ourName); n != 0 {
+		t.Errorf("the queue sent %d PDUs to this server", n)
+	}
+}
+
+func TestQueueBacksOffAndRetries(t *testing.T) {
+	sender := newFakeSender()
+	sender.setDown("a.example", true)
+	store := openStore(t)
+	q := newTestQueue(t, store, sender, fakeRooms{"!r:warp.example": {"a.example"}}, nil)
+	if err := q.Start(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+
+	for i := range 120 {
+		q.EventPersisted(t.Context(), notification(t, "!r:warp.example", "@me:"+ourName, "", i))
+	}
+	waitFor(t, "a recorded failure", func() bool {
+		d, err := store.Destination(t.Context(), "a.example")
+		return err == nil && d.Failures >= 2
+	})
+
+	sender.setDown("a.example", false)
+	waitFor(t, "every PDU delivered", func() bool { return sender.pdus("a.example") == 120 })
+	if largest := sender.largestTxn("a.example"); largest > maxPDUsPerTxn {
+		t.Errorf("a transaction carried %d PDUs, the limit is %d", largest, maxPDUsPerTxn)
+	}
+	waitFor(t, "the failure count to clear", func() bool {
+		d, err := store.Destination(t.Context(), "a.example")
+		return err == nil && d.Failures == 0 && d.LastSuccessMS > 0
+	})
+	left, err := store.Queued(t.Context(), "a.example", storage.QueueKindPDU, 10)
+	if err != nil || len(left) != 0 {
+		t.Errorf("queue after delivery = %d items, %v", len(left), err)
+	}
+}
+
+func TestQueueSurvivesARestart(t *testing.T) {
+	sender := newFakeSender()
+	sender.setDown("a.example", true)
+	store := openStore(t)
+	rooms := fakeRooms{"!r:warp.example": {"a.example"}}
+
+	first := newTestQueue(t, store, sender, rooms, nil)
+	if err := first.Start(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+	for i := range 5 {
+		first.EventPersisted(t.Context(), notification(t, "!r:warp.example", "@me:"+ourName, "", i))
+	}
+	waitFor(t, "the events to be queued", func() bool {
+		items, _ := store.Queued(t.Context(), "a.example", storage.QueueKindPDU, 10)
+		return len(items) == 5
+	})
+	first.Stop()
+
+	// While stopped, events are dropped rather than held.
+	first.EventPersisted(t.Context(), notification(t, "!r:warp.example", "@me:"+ourName, "", 99))
+
+	sender.setDown("a.example", false)
+	if err := store.SetDestination(t.Context(), storage.Destination{ServerName: "a.example"}); err != nil {
+		t.Fatal(err)
+	}
+	second := newTestQueue(t, store, sender, rooms, nil)
+	if err := second.Start(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, "the backlog after a restart", func() bool { return sender.pdus("a.example") == 5 })
+	time.Sleep(50 * time.Millisecond)
+	if n := sender.pdus("a.example"); n != 5 {
+		t.Errorf("a received %d PDUs; the one persisted while stopped should not have been queued", n)
+	}
+}
+
+func TestQueueHonoursThePolicy(t *testing.T) {
+	sender := newFakeSender()
+	policy := federation.NewPolicy(nil, []string{"denied.example"})
+	q := newTestQueue(t, openStore(t), sender, fakeRooms{"!r:warp.example": {"ok.example", "denied.example"}}, policy)
+	if err := q.Start(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+	q.EventPersisted(t.Context(), notification(t, "!r:warp.example", "@me:"+ourName, "", 1))
+	waitFor(t, "delivery to the allowed server", func() bool { return sender.pdus("ok.example") == 1 })
+	if n := sender.pdus("denied.example"); n != 0 {
+		t.Errorf("a denied server received %d PDUs", n)
+	}
+}
+
+func TestEDUsGoToTheRoomsServers(t *testing.T) {
+	sender := newFakeSender()
+	rooms := fakeRooms{"!r:warp.example": {ourName, "a.example"}}
+	q := newTestQueue(t, openStore(t), sender, rooms, nil)
+	if err := q.Start(t.Context()); err != nil {
+		t.Fatal(err)
+	}
+	edus := NewEDUs(q, rooms)
+	edus.Typing(t.Context(), "!r:warp.example", "@me:"+ourName, true, 0)
+	edus.Receipt(t.Context(), "!r:warp.example", "@me:"+ourName, "m.read", "$e", "", 5)
+	edus.Receipt(t.Context(), "!r:warp.example", "@me:"+ourName, "m.read.private", "$e", "", 5)
+	edus.ToDevice(t.Context(), "@me:"+ourName, "m.room_key", map[string]map[string]json.RawMessage{
+		"@u:a.example": {"DEV": json.RawMessage(`{"k":1}`)},
+		"@v:b.example": {"*": json.RawMessage(`{"k":2}`)},
+	})
+
+	waitFor(t, "EDUs", func() bool { return len(sender.edus("a.example")) == 3 && len(sender.edus("b.example")) == 1 })
+	var types []string
+	for _, e := range sender.edus("a.example") {
+		types = append(types, e.Type)
+	}
+	slices.Sort(types)
+	if !slices.Equal(types, []string{federation.EDUDirectToDev, federation.EDUReceipt, federation.EDUTyping}) {
+		t.Errorf("EDUs to a = %v; a private receipt must not leave the server", types)
+	}
+	var toDevice federation.DirectToDeviceContent
+	if err := json.Unmarshal(sender.edus("b.example")[0].Content, &toDevice); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := toDevice.Messages["@u:a.example"]; ok {
+		t.Error("b was sent a's recipients")
+	}
+}

server/internal/federationapi/server.go

@@ -0,0 +1,661 @@
+package federationapi
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/dariuszjaniak/warp/server/internal/buildinfo"
+	"github.com/dariuszjaniak/warp/server/internal/federation"
+	"github.com/dariuszjaniak/warp/server/internal/httputil"
+	"github.com/dariuszjaniak/warp/server/internal/matrix/id"
+	"github.com/dariuszjaniak/warp/server/internal/roomserver"
+	"github.com/dariuszjaniak/warp/server/internal/storage"
+	"github.com/dariuszjaniak/warp/server/internal/syncapi"
+)
+
+// maxBody caps a federation request body. A transaction is up to 50 PDUs
+// of up to 64 KiB each, plus EDUs; anything past this is not a
+// transaction.
+const maxBody = 8 << 20
+
+// Error codes the federation API uses beyond the Client-Server set.
+const (
+	errCodeIncompatibleRoomVersion = "M_INCOMPATIBLE_ROOM_VERSION"
+	errCodeUnableToAuthoriseJoin   = "M_UNABLE_TO_AUTHORISE_JOIN"
+)
+
+// EphemeralSink takes in EDUs from other servers. *syncapi.API satisfies
+// it.
+type EphemeralSink interface {
+	SetTyping(ctx context.Context, req syncapi.TypingRequest) error
+	SetReceipt(ctx context.Context, req syncapi.ReceiptRequest) error
+	SendToDevice(ctx context.Context, req syncapi.SendToDeviceRequest) error
+}
+
+// Profiles answers profile queries for local users. *userapi.API
+// satisfies it.
+type Profiles interface {
+	Account(ctx context.Context, localpart string) (storage.Account, error)
+}
+
+// ServerOptions configure the inbound API.
+type ServerOptions struct {
+	ServerName string
+	Gate       *federation.Gate
+	Keys       *federation.KeyRing
+	Rooms      *roomserver.API
+	Ephemeral  EphemeralSink
+	Profiles   Profiles
+	Store      storage.FederationStore
+	Logger     *slog.Logger
+	Now        func() time.Time
+}
+
+// Server is the inbound Server-Server API.
+type Server struct {
+	serverName string
+	gate       *federation.Gate
+	keys       *federation.KeyRing
+	rooms      *roomserver.API
+	ephemeral  EphemeralSink
+	profiles   Profiles
+	store      storage.FederationStore
+	log        *slog.Logger
+	now        func() time.Time
+}
+
+// NewServer builds the inbound API.
+func NewServer(opts ServerOptions) (*Server, error) {
+	switch {
+	case opts.ServerName == "":
+		return nil, errors.New("federationapi: ServerName must not be empty")
+	case opts.Gate == nil, opts.Keys == nil, opts.Rooms == nil, opts.Store == nil:
+		return nil, errors.New("federationapi: Gate, Keys, Rooms and Store are required")
+	}
+	if opts.Logger == nil {
+		opts.Logger = slog.Default()
+	}
+	if opts.Now == nil {
+		opts.Now = time.Now
+	}
+	return &Server{
+		serverName: opts.ServerName,
+		gate:       opts.Gate,
+		keys:       opts.Keys,
+		rooms:      opts.Rooms,
+		ephemeral:  opts.Ephemeral,
+		profiles:   opts.Profiles,
+		store:      opts.Store,
+		log:        opts.Logger,
+		now:        opts.Now,
+	}, nil
+}
+
+// authedHandler is a federation handler that runs after the request has
+// been authenticated, with the origin and the body it was signed over.
+type authedHandler func(w http.ResponseWriter, r *http.Request, origin string, body []byte) error
+
+// RegisterRoutes adds every federation endpoint, each behind the gate: with
+// the switch off the whole surface answers M_UNRECOGNIZED, as a server
+// with no federation API would.
+func (s *Server) RegisterRoutes(r *httputil.Router) {
+	public := func(pattern string, h httputil.Handler) {
+		r.Handle(pattern, s.gate.ProtectFunc(h))
+	}
+	authed := func(pattern string, h authedHandler) {
+		r.Handle(pattern, s.gate.ProtectFunc(s.authenticated(h)))
+	}
+
+	// Keys and version need no authentication: a server has to be able to
+	// fetch our key before it can check anything we sign.
+	public("GET /_matrix/key/v2/server", s.handleServerKey)
+	public("GET /_matrix/key/v2/server/{keyID}", s.handleServerKey)
+	public("POST /_matrix/key/v2/query", s.handleKeyQuery)
+	public("GET /_matrix/key/v2/query/{serverName}", s.handleKeyQueryOne)
+	public("GET /_matrix/key/v2/query/{serverName}/{keyID}", s.handleKeyQueryOne)
+	public("GET /_matrix/federation/v1/version", s.handleVersion)
+
+	const v1, v2 = "/_matrix/federation/v1", "/_matrix/federation/v2"
+	authed("PUT "+v1+"/send/{txnID}", s.handleSend)
+	authed("GET "+v1+"/make_join/{roomID}/{userID}", s.handleMakeJoin)
+	authed("PUT "+v1+"/send_join/{roomID}/{eventID}", s.handleSendJoinV1)
+	authed("PUT "+v2+"/send_join/{roomID}/{eventID}", s.handleSendJoinV2)
+	authed("GET "+v1+"/make_leave/{roomID}/{userID}", s.handleMakeLeave)
+	authed("PUT "+v1+"/send_leave/{roomID}/{eventID}", s.handleSendLeaveV1)
+	authed("PUT "+v2+"/send_leave/{roomID}/{eventID}", s.handleSendLeaveV2)
+	authed("PUT "+v2+"/invite/{roomID}/{eventID}", s.handleInvite)
+	authed("GET "+v1+"/event/{eventID}", s.handleEvent)
+	authed("GET "+v1+"/state/{roomID}", s.handleState)
+	authed("GET "+v1+"/state_ids/{roomID}", s.handleStateIDs)
+	authed("GET "+v1+"/event_auth/{roomID}/{eventID}", s.handleEventAuth)
+	authed("GET "+v1+"/backfill/{roomID}", s.handleBackfill)
+	authed("POST "+v1+"/get_missing_events/{roomID}", s.handleMissingEvents)
+	authed("GET "+v1+"/query/directory", s.handleQueryDirectory)
+	authed("GET "+v1+"/query/profile", s.handleQueryProfile)
+	authed("GET "+v1+"/publicRooms", s.handlePublicRoomsGet)
+	authed("POST "+v1+"/publicRooms", s.handlePublicRoomsPost)
+}
+
+// authenticated checks X-Matrix and the allow/deny lists before the
+// handler runs.
+func (s *Server) authenticated(h authedHandler) httputil.Handler {
+	return func(w http.ResponseWriter, r *http.Request) error {
+		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, maxBody))
+		if err != nil {
+			return httputil.NewError(http.StatusRequestEntityTooLarge, httputil.ErrCodeTooLarge, "Request body too large")
+		}
+		origin, err := s.keys.AuthenticateRequest(r.Context(), r, body)
+		if err != nil {
+			httputil.LoggerFrom(r.Context()).Info("federation request failed authentication", "error", err)
+			return httputil.NewError(http.StatusUnauthorized, httputil.ErrCodeUnauthorized, "%s", err.Error())
+		}
+		if !s.gate.Policy().Allowed(origin) {
+			return httputil.Forbidden("Federation with %s is not allowed by this server", origin)
+		}
+		return h(w, r, origin, body)
+	}
+}
+
+// fedError maps a roomserver error onto the Matrix error a remote server
+// is sent.
+func fedError(err error) error {
+	var matrixErr *httputil.MatrixError
+	switch {
+	case err == nil:
+		return nil
+	case errors.As(err, &matrixErr):
+		return err
+	case errors.Is(err, roomserver.ErrIncompatibleRoomVersion):
+		return httputil.NewError(http.StatusBadRequest, errCodeIncompatibleRoomVersion, "%s", err.Error())
+	case errors.Is(err, roomserver.ErrNoSuchRoom), errors.Is(err, roomserver.ErrNoSuchEvent),
+		errors.Is(err, roomserver.ErrNoSuchAlias):
+		return httputil.NotFound("%s", err.Error())
+	case errors.Is(err, roomserver.ErrForbidden), errors.Is(err, roomserver.ErrRejected),
+		errors.Is(err, roomserver.ErrNotInRoom):
+		return httputil.Forbidden("%s", err.Error())
+	case errors.Is(err, roomserver.ErrBadEvent), errors.Is(err, roomserver.ErrInvalidContent):
+		return httputil.BadJSON("%s", err.Error())
+	case errors.Is(err, roomserver.ErrFederationDisabled):
+		return httputil.Unrecognized()
+	case errors.Is(err, roomserver.ErrRemote):
+		return httputil.NewError(http.StatusBadGateway, httputil.ErrCodeUnknown, "%s", err.Error())
+	}
+	return err
+}
+
+// decode reads an already-read body.
+func decode(body []byte, v any) error {
+	if len(body) == 0 {
+		return httputil.NotJSON()
+	}
+	if err := json.Unmarshal(body, v); err != nil {
+		return httputil.BadJSON("Invalid request body: %v", err)
+	}
+	return nil
+}
+
+// --- keys and version -------------------------------------------------------
+
+func (s *Server) handleServerKey(w http.ResponseWriter, _ *http.Request) error {
+	doc, err := s.keys.OwnKeyResponse()
+	if err != nil {
+		return err
+	}
+	httputil.WriteRawJSON(w, http.StatusOK, doc)
+	return nil
+}
+
+// keyQueryResponse is the notary answer.
+type keyQueryResponse struct {
+	ServerKeys []json.RawMessage `json:"server_keys"`
+}
+
+func (s *Server) handleKeyQuery(w http.ResponseWriter, r *http.Request) error {
+	var req struct {
+		ServerKeys map[string]json.RawMessage `json:"server_keys"`
+	}
+	if err := httputil.DecodeJSON(w, r, &req); err != nil {
+		return err
+	}
+	resp := keyQueryResponse{ServerKeys: []json.RawMessage{}}
+	for serverName := range req.ServerKeys {
+		docs, err := s.keys.NotaryResponse(serverName)
+		if err != nil {
+			return err
+		}
+		resp.ServerKeys = append(resp.ServerKeys, docs...)
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+func (s *Server) handleKeyQueryOne(w http.ResponseWriter, r *http.Request) error {
+	docs, err := s.keys.NotaryResponse(r.PathValue("serverName"))
+	if err != nil {
+		return err
+	}
+	if docs == nil {
+		docs = []json.RawMessage{}
+	}
+	httputil.WriteJSON(w, http.StatusOK, keyQueryResponse{ServerKeys: docs})
+	return nil
+}
+
+func (s *Server) handleVersion(w http.ResponseWriter, _ *http.Request) error {
+	var resp federation.VersionResponse
+	resp.Server.Name = "Warp"
+	resp.Server.Version = buildinfo.Version
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// --- transactions -------------------------------------------------------------
+
+func (s *Server) handleSend(w http.ResponseWriter, r *http.Request, origin string, body []byte) error {
+	txnID := r.PathValue("txnID")
+	if cached, ok, err := s.store.InboundTransaction(r.Context(), origin, txnID); err != nil {
+		return err
+	} else if ok {
+		httputil.WriteRawJSON(w, http.StatusOK, cached)
+		return nil
+	}
+
+	var txn federation.Transaction
+	if err := decode(body, &txn); err != nil {
+		return err
+	}
+	if txn.Origin != "" && txn.Origin != origin {
+		return httputil.Forbidden("The transaction's origin is %s, but it was signed by %s", txn.Origin, origin)
+	}
+	if len(txn.PDUs) > maxPDUsPerTxn || len(txn.EDUs) > maxEDUsPerTxn {
+		return httputil.BadJSON("A transaction carries at most %d PDUs and %d EDUs", maxPDUsPerTxn, maxEDUsPerTxn)
+	}
+
+	resp := federation.SendTransactionResponse{PDUs: map[string]federation.PDUResult{}}
+	for _, raw := range txn.PDUs {
+		eventID, err := s.rooms.ReceivePDU(r.Context(), origin, raw)
+		if eventID == "" {
+			// Unparseable: there is no ID to report a result under.
+			s.log.Info("dropping an unreadable PDU", "origin", origin, "error", err)
+			continue
+		}
+		result := federation.PDUResult{}
+		if err != nil {
+			result.Error = err.Error()
+			s.log.Info("refused a PDU", "origin", origin, "event_id", eventID, "error", err)
+		}
+		resp.PDUs[eventID] = result
+	}
+	for _, edu := range txn.EDUs {
+		s.receiveEDU(r.Context(), origin, edu)
+	}
+
+	encoded, err := json.Marshal(resp)
+	if err != nil {
+		return err
+	}
+	if err := s.store.RecordInboundTransaction(r.Context(), origin, txnID, encoded, s.now().UnixMilli()); err != nil {
+		s.log.Warn("could not record an inbound transaction", "origin", origin, "txn_id", txnID, "error", err)
+	}
+	httputil.WriteRawJSON(w, http.StatusOK, encoded)
+	return nil
+}
+
+// sameServer reports whether a user belongs to the server that sent the
+// EDU about them. Nothing in an EDU is signed, so this is the only check
+// there is, and without it any server could make anybody appear to type.
+func sameServer(userID, origin string) bool {
+	server, err := id.ServerNameOf(userID)
+	return err == nil && server == origin
+}
+
+// receiveEDU takes one EDU in. Failures are logged and otherwise ignored:
+// an EDU is ephemeral, and the transaction it came in succeeds whatever
+// becomes of it.
+func (s *Server) receiveEDU(ctx context.Context, origin string, edu federation.EDU) {
+	if s.ephemeral == nil {
+		return
+	}
+	switch edu.Type {
+	case federation.EDUTyping:
+		var c federation.TypingContent
+		if json.Unmarshal(edu.Content, &c) != nil || !sameServer(c.UserID, origin) || !s.allowed(ctx, c.RoomID, origin) {
+			return
+		}
+		if err := s.ephemeral.SetTyping(ctx, syncapi.TypingRequest{RoomID: c.RoomID, User: c.UserID, Typing: c.Typing}); err != nil {
+			s.log.Debug("ignored a typing EDU", "origin", origin, "room_id", c.RoomID, "error", err)
+		}
+
+	case federation.EDUReceipt:
+		var c federation.ReceiptContent
+		if json.Unmarshal(edu.Content, &c) != nil {
+			return
+		}
+		for roomID, byType := range c {
+			if !s.allowed(ctx, roomID, origin) {
+				continue
+			}
+			for receiptType, byUser := range byType {
+				if receiptType != syncapi.ReceiptRead {
+					continue
+				}
+				for userID, data := range byUser {
+					if !sameServer(userID, origin) || len(data.EventIDs) == 0 {
+						continue
+					}
+					if err := s.ephemeral.SetReceipt(ctx, syncapi.ReceiptRequest{
+						RoomID: roomID, User: userID, ReceiptType: receiptType,
+						EventID: data.EventIDs[len(data.EventIDs)-1], ThreadID: data.Data.ThreadID,
+					}); err != nil {
+						s.log.Debug("ignored a receipt EDU", "origin", origin, "room_id", roomID, "error", err)
+					}
+				}
+			}
+		}
+
+	case federation.EDUDirectToDev:
+		var c federation.DirectToDeviceContent
+		if json.Unmarshal(edu.Content, &c) != nil || !sameServer(c.Sender, origin) {
+			return
+		}
+		if err := s.ephemeral.SendToDevice(ctx, syncapi.SendToDeviceRequest{
+			Sender: c.Sender, EventType: c.Type, Messages: c.Messages,
+		}); err != nil {
+			s.log.Debug("ignored a to-device EDU", "origin", origin, "error", err)
+		}
+
+	default:
+		// Presence and device list updates belong to phases that have not
+		// landed (presence is off by default; device lists are Phase 7).
+		s.log.Debug("ignored an EDU", "origin", origin, "type", edu.Type)
+	}
+}
+
+// --- membership ---------------------------------------------------------------
+
+func (s *Server) handleMakeJoin(w http.ResponseWriter, r *http.Request, origin string, _ []byte) error {
+	version, tmpl, err := s.rooms.MakeJoin(r.Context(), origin, r.PathValue("roomID"), r.PathValue("userID"),
+		r.URL.Query()["ver"])
+	if err != nil {
+		if errors.Is(err, roomserver.ErrForbidden) && strings.Contains(err.Error(), "authorise a restricted join") {
+			return httputil.NewError(http.StatusBadRequest, errCodeUnableToAuthoriseJoin, "%s", err.Error())
+		}
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.MakeJoinResponse{RoomVersion: version, Event: tmpl})
+	return nil
+}
+
+func (s *Server) sendJoin(r *http.Request, origin string, body []byte) (federation.SendJoinResponse, error) {
+	res, err := s.rooms.SendJoin(r.Context(), origin, r.PathValue("roomID"), r.PathValue("eventID"), body)
+	if err != nil {
+		return federation.SendJoinResponse{}, fedError(err)
+	}
+	return federation.SendJoinResponse{
+		Origin:        s.serverName,
+		State:         res.State,
+		AuthChain:     res.AuthChain,
+		Event:         res.Event,
+		ServersInRoom: res.ServersInRoom,
+	}, nil
+}
+
+func (s *Server) handleSendJoinV2(w http.ResponseWriter, r *http.Request, origin string, body []byte) error {
+	resp, err := s.sendJoin(r, origin, body)
+	if err != nil {
+		return err
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// handleSendJoinV1 is the deprecated form, which wraps the same answer in
+// a [200, body] pair.
+func (s *Server) handleSendJoinV1(w http.ResponseWriter, r *http.Request, origin string, body []byte) error {
+	resp, err := s.sendJoin(r, origin, body)
+	if err != nil {
+		return err
+	}
+	httputil.WriteJSON(w, http.StatusOK, []any{http.StatusOK, resp})
+	return nil
+}
+
+func (s *Server) handleMakeLeave(w http.ResponseWriter, r *http.Request, origin string, _ []byte) error {
+	version, tmpl, err := s.rooms.MakeLeave(r.Context(), origin, r.PathValue("roomID"), r.PathValue("userID"))
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.MakeJoinResponse{RoomVersion: version, Event: tmpl})
+	return nil
+}
+
+func (s *Server) handleSendLeaveV2(w http.ResponseWriter, r *http.Request, origin string, body []byte) error {
+	if err := s.rooms.SendLeave(r.Context(), origin, r.PathValue("roomID"), r.PathValue("eventID"), body); err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, struct{}{})
+	return nil
+}
+
+func (s *Server) handleSendLeaveV1(w http.ResponseWriter, r *http.Request, origin string, body []byte) error {
+	if err := s.rooms.SendLeave(r.Context(), origin, r.PathValue("roomID"), r.PathValue("eventID"), body); err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, []any{http.StatusOK, struct{}{}})
+	return nil
+}
+
+func (s *Server) handleInvite(w http.ResponseWriter, r *http.Request, origin string, body []byte) error {
+	var req federation.InviteRequest
+	if err := decode(body, &req); err != nil {
+		return err
+	}
+	signed, err := s.rooms.ReceiveInvite(r.Context(), origin, req.RoomVersion, req.Event, req.InviteRoomState)
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.InviteResponse{Event: signed})
+	return nil
+}
+
+// --- reads --------------------------------------------------------------------
+
+func (s *Server) transaction(pdus []json.RawMessage) federation.Transaction {
+	if pdus == nil {
+		pdus = []json.RawMessage{}
+	}
+	return federation.Transaction{Origin: s.serverName, OriginServerTS: s.now().UnixMilli(), PDUs: pdus}
+}
+
+func (s *Server) handleEvent(w http.ResponseWriter, r *http.Request, origin string, _ []byte) error {
+	raw, err := s.rooms.EventForServer(r.Context(), origin, r.PathValue("eventID"))
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, s.transaction([]json.RawMessage{raw}))
+	return nil
+}
+
+func (s *Server) handleState(w http.ResponseWriter, r *http.Request, origin string, _ []byte) error {
+	eventID := r.URL.Query().Get("event_id")
+	if eventID == "" {
+		return httputil.MissingParam("event_id is required")
+	}
+	state, chain, err := s.rooms.StateForServer(r.Context(), origin, r.PathValue("roomID"), eventID)
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.StateResponse{PDUs: state, AuthChain: chain})
+	return nil
+}
+
+func (s *Server) handleStateIDs(w http.ResponseWriter, r *http.Request, origin string, _ []byte) error {
+	eventID := r.URL.Query().Get("event_id")
+	if eventID == "" {
+		return httputil.MissingParam("event_id is required")
+	}
+	state, chain, err := s.rooms.StateIDsForServer(r.Context(), origin, r.PathValue("roomID"), eventID)
+	if err != nil {
+		return fedError(err)
+	}
+	if state == nil {
+		state = []string{}
+	}
+	if chain == nil {
+		chain = []string{}
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.StateIDsResponse{PDUIDs: state, AuthChainIDs: chain})
+	return nil
+}
+
+func (s *Server) handleEventAuth(w http.ResponseWriter, r *http.Request, origin string, _ []byte) error {
+	chain, err := s.rooms.EventAuthForServer(r.Context(), origin, r.PathValue("roomID"), r.PathValue("eventID"))
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.EventAuthResponse{AuthChain: chain})
+	return nil
+}
+
+func (s *Server) handleBackfill(w http.ResponseWriter, r *http.Request, origin string, _ []byte) error {
+	query := r.URL.Query()
+	from := query["v"]
+	if len(from) == 0 {
+		return httputil.MissingParam("v is required")
+	}
+	limit, err := strconv.Atoi(query.Get("limit"))
+	if err != nil || limit <= 0 {
+		return httputil.InvalidParam("limit must be a positive integer")
+	}
+	events, err := s.rooms.BackfillForServer(r.Context(), origin, r.PathValue("roomID"), from, limit)
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, s.transaction(events))
+	return nil
+}
+
+func (s *Server) handleMissingEvents(w http.ResponseWriter, r *http.Request, origin string, body []byte) error {
+	var req federation.MissingEventsRequest
+	if err := decode(body, &req); err != nil {
+		return err
+	}
+	events, err := s.rooms.MissingEventsForServer(r.Context(), origin, r.PathValue("roomID"),
+		req.EarliestEvents, req.LatestEvents, req.Limit, req.MinDepth)
+	if err != nil {
+		return fedError(err)
+	}
+	if events == nil {
+		events = []json.RawMessage{}
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.MissingEventsResponse{Events: events})
+	return nil
+}
+
+// --- queries ------------------------------------------------------------------
+
+func (s *Server) handleQueryDirectory(w http.ResponseWriter, r *http.Request, _ string, _ []byte) error {
+	alias := r.URL.Query().Get("room_alias")
+	if alias == "" {
+		return httputil.MissingParam("room_alias is required")
+	}
+	resolved, err := s.rooms.QueryAliasForServer(r.Context(), alias)
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, federation.DirectoryResponse{RoomID: resolved.RoomID, Servers: resolved.Servers})
+	return nil
+}
+
+func (s *Server) handleQueryProfile(w http.ResponseWriter, r *http.Request, _ string, _ []byte) error {
+	query := r.URL.Query()
+	userID := query.Get("user_id")
+	localpart, server, err := id.SplitUserID(userID)
+	if err != nil {
+		return httputil.InvalidParam("user_id is not a user ID")
+	}
+	if server != s.serverName || s.profiles == nil {
+		return httputil.NotFound("%s is not a user of this server", userID)
+	}
+	account, err := s.profiles.Account(r.Context(), localpart)
+	if errors.Is(err, storage.ErrNoSuchUser) {
+		return httputil.NotFound("Profile not found")
+	} else if err != nil {
+		return err
+	}
+	resp := map[string]string{}
+	switch field := query.Get("field"); field {
+	case "":
+		if account.DisplayName != "" {
+			resp["displayname"] = account.DisplayName
+		}
+		if account.AvatarURL != "" {
+			resp["avatar_url"] = account.AvatarURL
+		}
+	case "displayname":
+		if account.DisplayName != "" {
+			resp["displayname"] = account.DisplayName
+		}
+	case "avatar_url":
+		if account.AvatarURL != "" {
+			resp["avatar_url"] = account.AvatarURL
+		}
+	default:
+		return httputil.InvalidParam("field must be displayname or avatar_url")
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+func (s *Server) handlePublicRoomsGet(w http.ResponseWriter, r *http.Request, _ string, _ []byte) error {
+	query := r.URL.Query()
+	limit, _ := strconv.Atoi(query.Get("limit"))
+	return s.publicRooms(w, r, roomserver.PublicRoomsRequest{Limit: limit, Since: query.Get("since")})
+}
+
+func (s *Server) handlePublicRoomsPost(w http.ResponseWriter, r *http.Request, _ string, body []byte) error {
+	var req struct {
+		Limit  int    `json:"limit"`
+		Since  string `json:"since"`
+		Filter struct {
+			GenericSearchTerm string `json:"generic_search_term"`
+		} `json:"filter"`
+	}
+	if len(body) > 0 {
+		if err := decode(body, &req); err != nil {
+			return err
+		}
+	}
+	return s.publicRooms(w, r, roomserver.PublicRoomsRequest{
+		Limit: req.Limit, Since: req.Since, Search: req.Filter.GenericSearchTerm,
+	})
+}
+
+func (s *Server) publicRooms(w http.ResponseWriter, r *http.Request, req roomserver.PublicRoomsRequest) error {
+	resp, err := s.rooms.PublicRooms(r.Context(), req)
+	if err != nil {
+		return fedError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// String is for logs.
+func (s *Server) String() string { return fmt.Sprintf("federation API for %s", s.serverName) }
+
+// allowed applies a room's server ACL to an EDU about it. An EDU is not
+// a room event, but it is still a server speaking in the room, and a
+// server the room has banned does not get to make its users appear to
+// type.
+func (s *Server) allowed(ctx context.Context, roomID, origin string) bool {
+	ok, err := s.rooms.ServerAllowed(ctx, roomID, origin)
+	return err == nil && ok
+}