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/syncapi/context.go

@@ -106,7 +106,7 @@ func (s *API) Context(ctx context.Context, req ContextRequest) (ContextResponse,
 			User:   req.User,
 			// Strictly before the target: High is inclusive, and the
 			// target itself is reported separately.
-			High:      position - 1,
+			High:      storage.PositionBefore(position),
 			Direction: storage.DirectionBackward,
 			Limit:     before,
 			Filter:    filter.TimelineFilter(),
@@ -120,7 +120,7 @@ func (s *API) Context(ctx context.Context, req ContextRequest) (ContextResponse,
 		out.Start = pduToken(earlier.Start).String()
 	}
 	if out.Start == "" {
-		out.Start = pduToken(position - 1).String()
+		out.Start = pduToken(storage.PositionBefore(position)).String()
 	}
 
 	if after > 0 {

server/internal/syncapi/messages.go

@@ -112,6 +112,9 @@ func (s *API) Messages(ctx context.Context, req MessagesRequest) (MessagesRespon
 		Direction: direction,
 		Limit:     limit,
 		Filter:    filter.TimelineFilter(),
+		// Scrolling up past the oldest event this server holds of a room
+		// joined over federation asks the room's other servers for more.
+		Backfill: true,
 	})
 	if err != nil {
 		return MessagesResponse{}, err

server/internal/syncapi/outbound.go

@@ -0,0 +1,31 @@
+package syncapi
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+)
+
+// Outbound passes this server's ephemeral events on to other servers.
+//
+// Typing notifications, read receipts and to-device messages are not room
+// events and never go through the roomserver, so the federation queue
+// cannot pick them up from there; the sync API, which is where they are
+// written, hands them over instead. Only what a local user did is handed
+// over — the same calls are how an EDU from another server is taken in,
+// and passing those on again would echo them back to where they came
+// from.
+//
+// Every method must return quickly: they are called on the request path
+// of the client that typed, read or sent.
+type Outbound interface {
+	Typing(ctx context.Context, roomID, userID string, typing bool, timeout time.Duration)
+	Receipt(ctx context.Context, roomID, userID, receiptType, eventID, threadID string, ts int64)
+	ToDevice(ctx context.Context, sender, eventType string, messages map[string]map[string]json.RawMessage)
+}
+
+// SetOutbound connects the federation queue. It is a setter rather than an
+// option because the queue is built after the sync API's dependencies and
+// before the sync API is serving, and nil — no federation — is a valid
+// value throughout.
+func (s *API) SetOutbound(o Outbound) { s.outbound = o }

server/internal/syncapi/presence.go

@@ -104,7 +104,7 @@ func (s *API) Presence(ctx context.Context, userID string) (storage.PresenceStat
 		return storage.PresenceState{}, ErrPresenceDisabled
 	}
 	if !s.isLocal(userID) {
-		// Remote presence needs federation (Phase 5). Reporting offline
+		// Remote presence is not fetched over federation. Reporting offline
 		// would be a guess; saying so is not.
 		return storage.PresenceState{}, errForbiddenf(
 			"%s belongs to another server and federation is required to ask it", userID)

server/internal/syncapi/receipts.go

@@ -104,6 +104,10 @@ func (s *API) SetReceipt(ctx context.Context, req ReceiptRequest) error {
 		return nil
 	}
 	s.notifier.NotifyRoom(req.RoomID)
+	// A private receipt never leaves the server, which is the point of it.
+	if s.outbound != nil && s.isLocal(req.User) {
+		s.outbound.Receipt(ctx, req.RoomID, req.User, req.ReceiptType, req.EventID, req.ThreadID, s.nowMS())
+	}
 	return nil
 }
 

server/internal/syncapi/syncapi.go

@@ -90,6 +90,10 @@ type API struct {
 	// asking, where a clear refusal tells it this one has it turned off.
 	presenceEnabled bool
 
+	// outbound passes local typing, receipts and remote to-device
+	// messages to the federation queue; nil without federation.
+	outbound Outbound
+
 	// longPollTimeout caps how long a /sync may block, whatever ?timeout=
 	// the client asked for. A client asking for ten minutes would hold a
 	// connection and a database handle for ten minutes.

server/internal/syncapi/todevice.go

@@ -33,13 +33,13 @@ type SendToDeviceRequest struct {
 
 // SendToDevice queues messages for delivery.
 //
-// A message to a user of another server is dropped rather than refused.
-// That is deliberate: a client encrypting for a room with remote members
-// sends one message per device in one request, and failing the request
-// because federation is off would stop it from delivering to the local
-// devices as well. The dropped recipients simply never see the key and
-// their client reports an undecryptable message, which is what they would
-// see anyway. Phase 5 routes them.
+// A message to a user of another server goes to the federation queue. With
+// federation off it is dropped rather than refused. That is deliberate: a
+// client encrypting for a room with remote members sends one message per
+// device in one request, and failing the request because federation is
+// off would stop it from delivering to the local devices as well. The
+// dropped recipients simply never see the key and their client reports an
+// undecryptable message, which is what they would see anyway.
 func (s *API) SendToDevice(ctx context.Context, req SendToDeviceRequest) error {
 	if req.EventType == "" {
 		return errInvalidParamf("an event type is required")
@@ -48,11 +48,19 @@ func (s *API) SendToDevice(ctx context.Context, req SendToDeviceRequest) error {
 	var (
 		queued []storage.NewToDeviceMessage
 		woken  []string
+		remote = map[string]map[string]json.RawMessage{}
 		sentAt = s.nowMS()
 	)
 	for userID, byDevice := range req.Messages {
 		localpart, ok := s.localpartOf(userID)
 		if !ok {
+			// A remote recipient goes to the federation queue when there
+			// is one and the sender is ours; a remote sender's message to
+			// a remote user is not this server's to forward.
+			if s.outbound != nil && s.isLocal(req.Sender) {
+				remote[userID] = byDevice
+				continue
+			}
 			s.log.Debug("dropping a to-device message for a remote user",
 				"sender", req.Sender, "recipient", userID)
 			continue
@@ -95,6 +103,9 @@ func (s *API) SendToDevice(ctx context.Context, req SendToDeviceRequest) error {
 		woken = append(woken, userID)
 	}
 
+	if len(remote) > 0 {
+		s.outbound.ToDevice(ctx, req.Sender, req.EventType, remote)
+	}
 	if len(queued) == 0 {
 		return nil
 	}

server/internal/syncapi/token.go

@@ -96,7 +96,10 @@ func ParseToken(raw string) (Token, error) {
 	var positions [5]int64
 	for i, field := range fields {
 		value, err := strconv.ParseInt(field, 10, 64)
-		if err != nil || value < 0 {
+		// The PDU position alone may be negative: /messages hands out
+		// positions inside history backfilled from other servers, which
+		// is numbered downwards from -1. Every other stream starts at 0.
+		if err != nil || (value < 0 && i > 0) {
 			return Token{}, fmt.Errorf("%q is not a sync token: position %d is %q", raw, i+1, field)
 		}
 		positions[i] = value

server/internal/syncapi/token_test.go

@@ -20,6 +20,13 @@ func TestTokenRoundTrips(t *testing.T) {
 			syncapi.Token{PDU: 1, Receipt: 2, ToDevice: 3, AccountData: 4, Presence: 5},
 			"s1_2_3_4_5",
 		},
+		{
+			// /messages pages back into history backfilled from other
+			// servers, which is numbered downwards from -1.
+			"a position inside backfilled history",
+			syncapi.Token{PDU: -7},
+			"s-7",
+		},
 		{
 			// A zero in the middle has to be written, because the
 			// positions are read by place.
@@ -77,7 +84,7 @@ func TestParseTokenRejectsNonsense(t *testing.T) {
 		"nonsense",     // no prefix
 		"t1_2",         // a prefix this build does not write
 		"s",            // a prefix and nothing else
-		"s-1",          // a negative position
+		"s1_-1",        // a negative position outside the event stream
 		"sx",           // not a number
 		"s1_",          // a trailing separator
 		"s1_2_3_4_5_6", // more positions than there are streams

server/internal/syncapi/typing.go

@@ -196,6 +196,9 @@ func (s *API) SetTyping(ctx context.Context, req TypingRequest) error {
 	}
 
 	s.typing.set(req.RoomID, req.User, req.Typing, req.Timeout)
+	if s.outbound != nil && s.isLocal(req.User) {
+		s.outbound.Typing(ctx, req.RoomID, req.User, req.Typing, req.Timeout)
+	}
 	return nil
 }