Phase 10: hardening and ops

Implements PLAN.md Phase 10.

Simplified Sliding Sync (MSC4186) is served at the unstable
org.matrix.simplified_msc3575 endpoint and advertised in /versions. Lists
are sorted by activity and filtered by DM, invite, encryption, room type,
space and tag; room subscriptions, required_state with wildcards, $ME and
$LAZY, and the to_device, e2ee, account_data, receipts and typing
extensions are supported. Per-connection state is kept in memory and an
unknown pos answers M_UNKNOWN_POS.

Threads and relations: m.relates_to is indexed on roomserver_events
(migration 0012), /relations (with recursion) and /threads are served, and
every event a timeline read returns carries its m.thread, m.replace and
m.reference summaries in unsigned.m.relations. Notifications carry a
thread ID (migration 0013): threaded receipts clear only their thread, and
sync reports unread_thread_notifications when the filter asks.

Spaces: /hierarchy walks a space breadth first, asking other servers about
rooms this one is not in through the new federation hierarchy endpoint;
room_summary describes one room. /search runs on FTS5 (sqlite, pocketbase)
or tsvector (postgres), bounded to what each user may see, with context,
profiles, state, grouping and paging.

The PocketBase driver is real: the sqlite schema and store on an embedded
PocketBase app's database, with media in its filesystem, local or S3
(database.pocketbase.s3). It runs the full storage test suite.

Ops: OpenTelemetry tracing over OTLP/HTTP (tracing.*), with server spans
per route, component spans, and trace propagation on federation, push and
application service calls. New metrics for persisted events, waiting
syncs, sliding sync connections and the database pool, with a Grafana
dashboard. deploy/ adds a Compose setup (PostgreSQL, Prometheus, Grafana,
Jaeger) and a Helm chart; cmd/warp-loadtest loads a server and reports
request and delivery latencies.

The load tester found a long-standing bug, fixed here: on a server where
no account data had been written, every incremental /sync re-sent the push
rules and returned at once, and an all-zero token was taken for an initial
sync, so long polls became busy loops.

The PostgreSQL migrations and search dialect compile but were not run
against a live PostgreSQL in this change.

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

server/internal/clientapi/clientapi.go

@@ -313,9 +313,19 @@ func (c *ClientAPI) registerSyncRoutes(r *httputil.Router) {
 	}
 
 	c.authed(r, "GET "+v3+"/sync", c.limitSync, c.handleSync)
+	c.authed(r, "POST "+slidingSyncPath, c.limitSync, c.handleSlidingSync)
 	c.authed(r, "GET "+v3+"/rooms/{roomID}/messages", c.limitDefault, c.handleMessages)
 	c.authed(r, "GET "+v3+"/rooms/{roomID}/context/{eventID}", c.limitDefault, c.handleContext)
 
+	// Relations and threads, which the spec introduced at v1.
+	c.authed(r, "GET "+v1+"/rooms/{roomID}/relations/{eventID}", c.limitDefault, c.handleRelations)
+	c.authed(r, "GET "+v1+"/rooms/{roomID}/relations/{eventID}/{relType}", c.limitDefault, c.handleRelations)
+	c.authed(r, "GET "+v1+"/rooms/{roomID}/relations/{eventID}/{relType}/{eventType}",
+		c.limitDefault, c.handleRelations)
+	c.authed(r, "GET "+v1+"/rooms/{roomID}/threads", c.limitDefault, c.handleThreads)
+
+	c.authed(r, "POST "+v3+"/search", c.limitDefault, c.handleSearch)
+
 	// Filters.
 	c.authed(r, "POST "+v3+"/user/{userID}/filter", c.limitDefault, c.handlePostFilter)
 	c.authed(r, "GET "+v3+"/user/{userID}/filter/{filterID}", c.limitDefault, c.handleGetFilter)
@@ -387,6 +397,10 @@ func (c *ClientAPI) registerRoomRoutes(r *httputil.Router) {
 		c.limitDefault, c.handleGetJoinedMembers)
 	c.authed(r, "GET "+v3+"/joined_rooms", c.limitDefault, c.handleGetJoinedRooms)
 
+	// Spaces, and the summary of a room the user may not be in.
+	c.authed(r, "GET "+v1+"/rooms/{roomID}/hierarchy", c.limitDefault, c.handleHierarchy)
+	c.authed(r, "GET "+v1+"/room_summary/{roomIDOrAlias}", c.limitDefault, c.handleRoomSummary)
+
 	// The directory. Resolving an alias and reading the public room list
 	// need no token: a client handed a link has to be able to follow it
 	// before it decides whether to log in.

server/internal/clientapi/relations.go

@@ -0,0 +1,88 @@
+package clientapi
+
+import (
+	"net/http"
+
+	"github.com/dariuszjaniak/warp/server/internal/httputil"
+	"github.com/dariuszjaniak/warp/server/internal/storage"
+	"github.com/dariuszjaniak/warp/server/internal/syncapi"
+	"github.com/dariuszjaniak/warp/server/internal/userapi"
+)
+
+// handleRelations implements
+// GET /_matrix/client/v1/rooms/{roomID}/relations/{eventID}[/{relType}[/{eventType}]].
+//
+// The three routes share the handler; the narrower ones only fill in more
+// of the path.
+func (c *ClientAPI) handleRelations(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	roomID, err := pathRoomID(r)
+	if err != nil {
+		return err
+	}
+	eventID := r.PathValue("eventID")
+	if eventID == "" {
+		return httputil.MissingParam("An event ID is required")
+	}
+	query := r.URL.Query()
+
+	direction := storage.DirectionBackward
+	switch query.Get("dir") {
+	case "f":
+		direction = storage.DirectionForward
+	case "b", "":
+	default:
+		return httputil.InvalidParam("dir must be \"b\" or \"f\"")
+	}
+	limit, err := intParam(query.Get("limit"))
+	if err != nil {
+		return err
+	}
+	recurse, err := boolParam(query.Get("recurse"))
+	if err != nil {
+		return err
+	}
+
+	resp, err := c.sync.Relations(r.Context(), syncapi.RelationsRequest{
+		RoomID:    roomID,
+		EventID:   eventID,
+		User:      auth.UserID,
+		RelType:   r.PathValue("relType"),
+		EventType: r.PathValue("eventType"),
+		From:      query.Get("from"),
+		To:        query.Get("to"),
+		Direction: direction,
+		Limit:     limit,
+		Recurse:   recurse,
+	})
+	if err != nil {
+		return syncError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// handleThreads implements GET /_matrix/client/v1/rooms/{roomID}/threads.
+func (c *ClientAPI) handleThreads(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	roomID, err := pathRoomID(r)
+	if err != nil {
+		return err
+	}
+	query := r.URL.Query()
+	limit, err := intParam(query.Get("limit"))
+	if err != nil {
+		return err
+	}
+
+	resp, err := c.sync.Threads(r.Context(), syncapi.ThreadsRequest{
+		RoomID:  roomID,
+		User:    auth.UserID,
+		Include: query.Get("include"),
+		From:    query.Get("from"),
+		Limit:   limit,
+	})
+	if err != nil {
+		return syncError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}

server/internal/clientapi/relations_test.go

@@ -0,0 +1,306 @@
+package clientapi_test
+
+import (
+	"fmt"
+	"net/http"
+	"net/url"
+	"testing"
+	"time"
+)
+
+// Relations and threads: what /relations lists, what /threads lists, and
+// the summaries a parent carries in unsigned.m.relations wherever it is
+// served.
+
+// sendEvent sends an event of any type and returns its ID.
+func (ts *testServer) sendEvent(acc account, roomID, eventType string, content map[string]any) string {
+	ts.t.Helper()
+	path := fmt.Sprintf("/_matrix/client/v3/rooms/%s/send/%s/%s",
+		url.PathEscape(roomID), url.PathEscape(eventType), fmt.Sprintf("txn-%d", time.Now().UnixNano()))
+	rec := ts.put(path, acc.AccessToken, content)
+	expectStatus(ts.t, rec, http.StatusOK)
+	eventID, _ := jsonBody(ts.t, rec)["event_id"].(string)
+	if eventID == "" {
+		ts.t.Fatalf("send returned no event ID: %s", rec.Body.String())
+	}
+	return eventID
+}
+
+// threadReply sends a message in a thread.
+func (ts *testServer) threadReply(acc account, roomID, rootID, body string) string {
+	ts.t.Helper()
+	return ts.sendEvent(acc, roomID, "m.room.message", map[string]any{
+		"msgtype": "m.text", "body": body,
+		"m.relates_to": map[string]any{"rel_type": "m.thread", "event_id": rootID},
+	})
+}
+
+type relationsResult struct {
+	Chunk          []syncEvent `json:"chunk"`
+	NextBatch      string      `json:"next_batch"`
+	RecursionDepth int         `json:"recursion_depth"`
+}
+
+func (ts *testServer) relations(acc account, roomID, path string, query url.Values) relationsResult {
+	ts.t.Helper()
+	full := "/_matrix/client/v1/rooms/" + url.PathEscape(roomID) + "/relations/" + path
+	if encoded := query.Encode(); encoded != "" {
+		full += "?" + encoded
+	}
+	rec := ts.get(full, acc.AccessToken)
+	expectStatus(ts.t, rec, http.StatusOK)
+	return decode[relationsResult](ts.t, rec)
+}
+
+// threadSummaryOf digs unsigned.m.relations.m.thread out of an event.
+func threadSummaryOf(t *testing.T, event map[string]any) map[string]any {
+	t.Helper()
+	unsigned, _ := event["unsigned"].(map[string]any)
+	relations, _ := unsigned["m.relations"].(map[string]any)
+	summary, _ := relations["m.thread"].(map[string]any)
+	return summary
+}
+
+func TestRelationsListsChildrenNewestFirst(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, nil)
+
+	root := ts.sendMessage(alice, roomID, "root")
+	r1 := ts.threadReply(alice, roomID, root, "one")
+	r2 := ts.threadReply(alice, roomID, root, "two")
+	reaction := ts.sendEvent(alice, roomID, "m.reaction", map[string]any{
+		"m.relates_to": map[string]any{"rel_type": "m.annotation", "event_id": root, "key": "👍"},
+	})
+	ts.sendMessage(alice, roomID, "unrelated")
+
+	all := ts.relations(alice, roomID, url.PathEscape(root), nil)
+	if got := idsOf(all.Chunk); !equalStrings(got, []string{reaction, r2, r1}) {
+		t.Fatalf("relations = %v, want the reaction and the two replies newest first", got)
+	}
+
+	threads := ts.relations(alice, roomID, url.PathEscape(root)+"/m.thread", nil)
+	if got := idsOf(threads.Chunk); !equalStrings(got, []string{r2, r1}) {
+		t.Errorf("m.thread relations = %v, want the two replies", got)
+	}
+	reactions := ts.relations(alice, roomID, url.PathEscape(root)+"/m.annotation/m.reaction", nil)
+	if got := idsOf(reactions.Chunk); !equalStrings(got, []string{reaction}) {
+		t.Errorf("m.annotation m.reaction relations = %v, want the reaction", got)
+	}
+
+	// Paging one at a time walks every child and stops.
+	var paged []string
+	from := ""
+	for range 10 {
+		query := url.Values{"limit": {"1"}}
+		if from != "" {
+			query.Set("from", from)
+		}
+		page := ts.relations(alice, roomID, url.PathEscape(root), query)
+		paged = append(paged, idsOf(page.Chunk)...)
+		if page.NextBatch == "" {
+			break
+		}
+		from = page.NextBatch
+	}
+	if !equalStrings(paged, []string{reaction, r2, r1}) {
+		t.Errorf("paged relations = %v", paged)
+	}
+}
+
+func TestRelationsRecurse(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, nil)
+
+	root := ts.sendMessage(alice, roomID, "root")
+	reply := ts.threadReply(alice, roomID, root, "reply")
+	edit := ts.sendEvent(alice, roomID, "m.room.message", map[string]any{
+		"msgtype": "m.text", "body": "* reply!",
+		"m.new_content": map[string]any{"msgtype": "m.text", "body": "reply!"},
+		"m.relates_to":  map[string]any{"rel_type": "m.replace", "event_id": reply},
+	})
+
+	flat := ts.relations(alice, roomID, url.PathEscape(root), nil)
+	if got := idsOf(flat.Chunk); !equalStrings(got, []string{reply}) {
+		t.Errorf("non-recursive relations = %v, want only the reply", got)
+	}
+	deep := ts.relations(alice, roomID, url.PathEscape(root), url.Values{"recurse": {"true"}})
+	if got := idsOf(deep.Chunk); !equalStrings(got, []string{edit, reply}) {
+		t.Errorf("recursive relations = %v, want the edit of the reply too", got)
+	}
+	if deep.RecursionDepth != 2 {
+		t.Errorf("recursion_depth = %d, want 2", deep.RecursionDepth)
+	}
+}
+
+func TestBundledAggregations(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, map[string]any{"preset": "public_chat"})
+	escaped := url.PathEscape(roomID)
+	expectStatus(t, ts.post("/_matrix/client/v3/join/"+escaped, bob.AccessToken, map[string]any{}), http.StatusOK)
+
+	root := ts.sendMessage(alice, roomID, "root")
+	ts.threadReply(bob, roomID, root, "first")
+	latest := ts.threadReply(bob, roomID, root, "second")
+	edit := ts.sendEvent(alice, roomID, "m.room.message", map[string]any{
+		"msgtype": "m.text", "body": "* root, edited",
+		"m.new_content": map[string]any{"msgtype": "m.text", "body": "root, edited"},
+		"m.relates_to":  map[string]any{"rel_type": "m.replace", "event_id": root},
+	})
+	// An edit by somebody else is not an edit.
+	ts.sendEvent(bob, roomID, "m.room.message", map[string]any{
+		"msgtype": "m.text", "body": "* hijacked",
+		"m.new_content": map[string]any{"msgtype": "m.text", "body": "hijacked"},
+		"m.relates_to":  map[string]any{"rel_type": "m.replace", "event_id": root},
+	})
+
+	check := func(who string, acc account, participated bool) {
+		t.Helper()
+		rec := ts.get("/_matrix/client/v3/rooms/"+escaped+"/event/"+url.PathEscape(root), acc.AccessToken)
+		expectStatus(t, rec, http.StatusOK)
+		event := jsonBody(t, rec)
+		summary := threadSummaryOf(t, event)
+		if summary == nil {
+			t.Fatalf("%s: the root has no m.thread summary: %v", who, event["unsigned"])
+		}
+		if summary["count"] != float64(2) {
+			t.Errorf("%s: thread count = %v, want 2", who, summary["count"])
+		}
+		latestEvent, _ := summary["latest_event"].(map[string]any)
+		if latestEvent["event_id"] != latest {
+			t.Errorf("%s: latest_event = %v, want %s", who, latestEvent["event_id"], latest)
+		}
+		if summary["current_user_participated"] != participated {
+			t.Errorf("%s: current_user_participated = %v, want %v", who, summary["current_user_participated"], participated)
+		}
+		unsigned, _ := event["unsigned"].(map[string]any)
+		relations, _ := unsigned["m.relations"].(map[string]any)
+		replace, _ := relations["m.replace"].(map[string]any)
+		if replace["event_id"] != edit {
+			t.Errorf("%s: m.replace = %v, want alice's own edit %s", who, replace["event_id"], edit)
+		}
+	}
+	// Alice started the thread and Bob replied in it: both took part.
+	check("alice", alice, true)
+	check("bob", bob, true)
+
+	carol := ts.register("carol", "correct-horse-battery-staple")
+	expectStatus(t, ts.post("/_matrix/client/v3/join/"+escaped, carol.AccessToken, map[string]any{}), http.StatusOK)
+	check("carol", carol, false)
+
+	// The same summary rides along on /messages.
+	page := ts.get("/_matrix/client/v3/rooms/"+escaped+"/messages?dir=b&limit=50", alice.AccessToken)
+	expectStatus(t, page, http.StatusOK)
+	chunk, _ := jsonBody(t, page)["chunk"].([]any)
+	found := false
+	for _, raw := range chunk {
+		e, _ := raw.(map[string]any)
+		if e["event_id"] == root {
+			found = threadSummaryOf(t, e) != nil
+		}
+	}
+	if !found {
+		t.Error("the root in /messages carries no m.thread summary")
+	}
+}
+
+func TestThreadsEndpoint(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, map[string]any{"preset": "public_chat"})
+	escaped := url.PathEscape(roomID)
+	expectStatus(t, ts.post("/_matrix/client/v3/join/"+escaped, bob.AccessToken, map[string]any{}), http.StatusOK)
+
+	first := ts.sendMessage(alice, roomID, "first root")
+	second := ts.sendMessage(bob, roomID, "second root")
+	ts.sendMessage(alice, roomID, "not a thread")
+	ts.threadReply(alice, roomID, first, "in the first")
+	ts.threadReply(alice, roomID, second, "in the second")
+	ts.threadReply(alice, roomID, first, "the first again")
+
+	threads := func(acc account, query string) relationsResult {
+		t.Helper()
+		rec := ts.get("/_matrix/client/v1/rooms/"+escaped+"/threads"+query, acc.AccessToken)
+		expectStatus(t, rec, http.StatusOK)
+		return decode[relationsResult](t, rec)
+	}
+
+	all := threads(bob, "")
+	if got := idsOf(all.Chunk); !equalStrings(got, []string{first, second}) {
+		t.Fatalf("threads = %v, want the first (latest activity) then the second", got)
+	}
+
+	// Bob started the second thread and never replied in the first.
+	mine := threads(bob, "?include=participated")
+	if got := idsOf(mine.Chunk); !equalStrings(got, []string{second}) {
+		t.Errorf("participated threads = %v, want only bob's own", got)
+	}
+
+	page1 := threads(bob, "?limit=1")
+	if got := idsOf(page1.Chunk); !equalStrings(got, []string{first}) || page1.NextBatch == "" {
+		t.Fatalf("first page = %v, next_batch %q", got, page1.NextBatch)
+	}
+	page2 := threads(bob, "?limit=1&from="+url.QueryEscape(page1.NextBatch))
+	if got := idsOf(page2.Chunk); !equalStrings(got, []string{second}) || page2.NextBatch != "" {
+		t.Errorf("second page = %v, next_batch %q", got, page2.NextBatch)
+	}
+
+	rec := ts.get("/_matrix/client/v1/rooms/"+escaped+"/threads?include=everything", bob.AccessToken)
+	expectStatus(t, rec, http.StatusBadRequest)
+}
+
+func TestRedactedRelationDisappears(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, nil)
+	escaped := url.PathEscape(roomID)
+
+	root := ts.sendMessage(alice, roomID, "root")
+	reply := ts.threadReply(alice, roomID, root, "reply")
+	expectStatus(t, ts.put("/_matrix/client/v3/rooms/"+escaped+"/redact/"+url.PathEscape(reply)+"/r1",
+		alice.AccessToken, map[string]any{}), http.StatusOK)
+
+	if got := ts.relations(alice, roomID, url.PathEscape(root), nil); len(got.Chunk) != 0 {
+		t.Errorf("relations after the reply was redacted = %v", idsOf(got.Chunk))
+	}
+	rec := ts.get("/_matrix/client/v3/rooms/"+escaped+"/event/"+url.PathEscape(root), alice.AccessToken)
+	if summary := threadSummaryOf(t, jsonBody(t, rec)); summary != nil {
+		t.Errorf("the root still has a thread summary: %v", summary)
+	}
+}
+
+func TestRelationsOfAnInvisibleEvent(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, nil)
+	root := ts.sendMessage(alice, roomID, "secret")
+
+	rec := ts.get("/_matrix/client/v1/rooms/"+url.PathEscape(roomID)+"/relations/"+url.PathEscape(root),
+		bob.AccessToken)
+	expectStatus(t, rec, http.StatusForbidden)
+}
+
+func idsOf(events []syncEvent) []string {
+	out := make([]string, 0, len(events))
+	for _, e := range events {
+		out = append(out, e.EventID)
+	}
+	return out
+}
+
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}

server/internal/clientapi/search.go

@@ -0,0 +1,27 @@
+package clientapi
+
+import (
+	"net/http"
+
+	"github.com/dariuszjaniak/warp/server/internal/httputil"
+	"github.com/dariuszjaniak/warp/server/internal/syncapi"
+	"github.com/dariuszjaniak/warp/server/internal/userapi"
+)
+
+// handleSearch implements POST /_matrix/client/v3/search.
+func (c *ClientAPI) handleSearch(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	var body syncapi.SearchBody
+	if err := httputil.DecodeJSON(w, r, &body); err != nil {
+		return err
+	}
+	resp, err := c.sync.Search(r.Context(), syncapi.SearchRequest{
+		User:      auth.UserID,
+		NextBatch: r.URL.Query().Get("next_batch"),
+		Body:      body,
+	})
+	if err != nil {
+		return syncError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}

server/internal/clientapi/search_test.go

@@ -0,0 +1,147 @@
+package clientapi_test
+
+import (
+	"net/http"
+	"net/url"
+	"testing"
+)
+
+type searchResult struct {
+	SearchCategories struct {
+		RoomEvents struct {
+			Count      int      `json:"count"`
+			Highlights []string `json:"highlights"`
+			NextBatch  string   `json:"next_batch"`
+			Results    []struct {
+				Rank    float64   `json:"rank"`
+				Result  syncEvent `json:"result"`
+				Context *struct {
+					EventsBefore []syncEvent               `json:"events_before"`
+					EventsAfter  []syncEvent               `json:"events_after"`
+					ProfileInfo  map[string]map[string]any `json:"profile_info"`
+				} `json:"context"`
+			} `json:"results"`
+			State  map[string][]syncEvent               `json:"state"`
+			Groups map[string]map[string]map[string]any `json:"groups"`
+		} `json:"room_events"`
+	} `json:"search_categories"`
+}
+
+func (ts *testServer) search(acc account, criteria map[string]any, nextBatch string) searchResult {
+	ts.t.Helper()
+	path := "/_matrix/client/v3/search"
+	if nextBatch != "" {
+		path += "?next_batch=" + url.QueryEscape(nextBatch)
+	}
+	rec := ts.post(path, acc.AccessToken, map[string]any{
+		"search_categories": map[string]any{"room_events": criteria},
+	})
+	expectStatus(ts.t, rec, http.StatusOK)
+	return decode[searchResult](ts.t, rec)
+}
+
+func TestSearchFindsOnlyWhatTheUserMaySee(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+
+	shared := ts.createRoom(alice, map[string]any{"preset": "public_chat"})
+	private := ts.createRoom(alice, nil)
+	expectStatus(t, ts.post("/_matrix/client/v3/join/"+url.PathEscape(shared), bob.AccessToken, map[string]any{}), http.StatusOK)
+
+	ts.sendMessage(alice, shared, "the quick brown fox")
+	ts.sendMessage(alice, private, "a secret fox")
+	ts.sendMessage(bob, shared, "lazy dog")
+
+	got := ts.search(bob, map[string]any{"search_term": "fox"}, "").SearchCategories.RoomEvents
+	if got.Count != 1 || len(got.Results) != 1 || got.Results[0].Result.Content["body"] != "the quick brown fox" {
+		t.Fatalf("bob's search for fox = %+v, want the one message in the room he is in", got)
+	}
+	if len(got.Highlights) != 1 || got.Highlights[0] != "fox" {
+		t.Errorf("highlights = %v", got.Highlights)
+	}
+
+	all := ts.search(alice, map[string]any{"search_term": "fox"}, "").SearchCategories.RoomEvents
+	if all.Count != 2 {
+		t.Errorf("alice's search for fox found %d, want both rooms' messages", all.Count)
+	}
+	only := ts.search(alice, map[string]any{
+		"search_term": "fox",
+		"filter":      map[string]any{"rooms": []string{private}},
+	}, "").SearchCategories.RoomEvents
+	if only.Count != 1 || only.Results[0].Result.RoomID != private {
+		t.Errorf("search filtered to one room = %+v", only)
+	}
+
+	// After Bob leaves, what was said while he was there stays findable
+	// and what comes later does not.
+	expectStatus(t, ts.post("/_matrix/client/v3/rooms/"+url.PathEscape(shared)+"/leave", bob.AccessToken, map[string]any{}), http.StatusOK)
+	ts.sendMessage(alice, shared, "another fox, later")
+	after := ts.search(bob, map[string]any{"search_term": "fox"}, "").SearchCategories.RoomEvents
+	if after.Count != 1 {
+		t.Errorf("after leaving, bob's search found %d, want only the message from before", after.Count)
+	}
+}
+
+func TestSearchContextStateGroupsAndPaging(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, nil)
+
+	ts.sendMessage(alice, roomID, "before")
+	ts.sendMessage(alice, roomID, "needle one")
+	ts.sendMessage(alice, roomID, "after")
+	ts.sendMessage(alice, roomID, "needle two")
+	ts.sendMessage(alice, roomID, "needle three")
+
+	got := ts.search(alice, map[string]any{
+		"search_term":   "needle",
+		"order_by":      "recent",
+		"event_context": map[string]any{"before_limit": 1, "after_limit": 1, "include_profile": true},
+		"include_state": true,
+		"groupings":     map[string]any{"group_by": []map[string]any{{"key": "room_id"}}},
+		"filter":        map[string]any{"limit": 2},
+	}, "").SearchCategories.RoomEvents
+
+	if got.Count != 3 || len(got.Results) != 2 {
+		t.Fatalf("first page: count %d, %d results", got.Count, len(got.Results))
+	}
+	if body := got.Results[0].Result.Content["body"]; body != "needle three" {
+		t.Errorf("newest first: got %v", body)
+	}
+	ctx := got.Results[1].Context
+	if ctx == nil || len(ctx.EventsBefore) != 1 || len(ctx.EventsAfter) != 1 ||
+		ctx.EventsBefore[0].Content["body"] != "after" || ctx.EventsAfter[0].Content["body"] != "needle three" {
+		t.Errorf("context of needle two = %+v", ctx)
+	}
+	if _, ok := ctx.ProfileInfo[alice.UserID]; !ok {
+		t.Errorf("profile_info has no entry for alice: %v", ctx.ProfileInfo)
+	}
+	if len(got.State[roomID]) == 0 {
+		t.Error("include_state returned no state for the room")
+	}
+	if group := got.Groups["room_id"][roomID]; group == nil {
+		t.Errorf("groups = %v", got.Groups)
+	}
+	if got.NextBatch == "" {
+		t.Fatal("a full first page carried no next_batch")
+	}
+
+	next := ts.search(alice, map[string]any{
+		"search_term": "needle", "order_by": "recent", "filter": map[string]any{"limit": 2},
+	}, got.NextBatch).SearchCategories.RoomEvents
+	if len(next.Results) != 1 || next.Results[0].Result.Content["body"] != "needle one" {
+		t.Errorf("second page = %+v", next.Results)
+	}
+
+	ranked := ts.search(alice, map[string]any{"search_term": "needle", "filter": map[string]any{"limit": 2}}, "").SearchCategories.RoomEvents
+	rest := ts.search(alice, map[string]any{"search_term": "needle", "filter": map[string]any{"limit": 2}}, ranked.NextBatch).SearchCategories.RoomEvents
+	if len(ranked.Results)+len(rest.Results) != 3 || rest.NextBatch != "" {
+		t.Errorf("ranked pages: %d then %d results, next %q", len(ranked.Results), len(rest.Results), rest.NextBatch)
+	}
+
+	rec := ts.post("/_matrix/client/v3/search", alice.AccessToken, map[string]any{
+		"search_categories": map[string]any{"room_events": map[string]any{"search_term": "x", "order_by": "loudest"}},
+	})
+	expectStatus(t, rec, http.StatusBadRequest)
+}

server/internal/clientapi/sliding.go

@@ -0,0 +1,47 @@
+package clientapi
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/dariuszjaniak/warp/server/internal/httputil"
+	"github.com/dariuszjaniak/warp/server/internal/syncapi"
+	"github.com/dariuszjaniak/warp/server/internal/userapi"
+)
+
+// slidingSyncPath is MSC4186's endpoint. It is still unstable: the MSC has
+// not been merged, and the prefix is what every client implementing it
+// sends.
+const slidingSyncPath = "/_matrix/client/unstable/org.matrix.simplified_msc3575/sync"
+
+// handleSlidingSync implements POST slidingSyncPath.
+func (c *ClientAPI) handleSlidingSync(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	query := r.URL.Query()
+	timeout, err := durationParam(query.Get("timeout"))
+	if err != nil {
+		return err
+	}
+	var body syncapi.SlidingBody
+	if _, err := httputil.DecodeOptionalJSON(w, r, &body); err != nil {
+		return err
+	}
+
+	resp, err := c.sync.SlidingSync(r.Context(), syncapi.SlidingRequest{
+		User:        auth.UserID,
+		Localpart:   auth.Localpart,
+		Device:      auth.DeviceID,
+		Pos:         query.Get("pos"),
+		Timeout:     timeout,
+		SetPresence: query.Get("set_presence"),
+		Body:        body,
+	})
+	if err != nil {
+		if ctxErr := r.Context().Err(); ctxErr != nil && errors.Is(err, ctxErr) {
+			return nil //nolint:nilerr // the client is gone; there is nobody to answer
+		}
+		return syncError(err)
+	}
+	httputil.NoCache(w)
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}

server/internal/clientapi/sliding_test.go

@@ -0,0 +1,332 @@
+package clientapi_test
+
+import (
+	"fmt"
+	"net/http"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/dariuszjaniak/warp/server/internal/httputil"
+)
+
+// Simplified Sliding Sync (MSC4186).
+
+const slidingPath = "/_matrix/client/unstable/org.matrix.simplified_msc3575/sync"
+
+type slidingResult struct {
+	Pos   string `json:"pos"`
+	Lists map[string]struct {
+		Count int `json:"count"`
+	} `json:"lists"`
+	Rooms map[string]struct {
+		Name          string           `json:"name"`
+		Initial       bool             `json:"initial"`
+		RequiredState []syncEvent      `json:"required_state"`
+		Timeline      []syncEvent      `json:"timeline"`
+		PrevBatch     string           `json:"prev_batch"`
+		Limited       bool             `json:"limited"`
+		NumLive       *int             `json:"num_live"`
+		BumpStamp     int64            `json:"bump_stamp"`
+		JoinedCount   *int             `json:"joined_count"`
+		InviteState   []map[string]any `json:"invite_state"`
+		Heroes        []map[string]any `json:"heroes"`
+	} `json:"rooms"`
+	Extensions struct {
+		ToDevice *struct {
+			NextBatch string           `json:"next_batch"`
+			Events    []map[string]any `json:"events"`
+		} `json:"to_device"`
+		E2EE *struct {
+			DeviceLists struct {
+				Changed []string `json:"changed"`
+			} `json:"device_lists"`
+			DeviceOneTimeKeysCount map[string]int `json:"device_one_time_keys_count"`
+		} `json:"e2ee"`
+		AccountData *struct {
+			Global []map[string]any            `json:"global"`
+			Rooms  map[string][]map[string]any `json:"rooms"`
+		} `json:"account_data"`
+		Receipts *struct {
+			Rooms map[string]map[string]any `json:"rooms"`
+		} `json:"receipts"`
+		Typing *struct {
+			Rooms map[string]map[string]any `json:"rooms"`
+		} `json:"typing"`
+	} `json:"extensions"`
+}
+
+func (ts *testServer) slidingRaw(acc account, pos string, timeout time.Duration, body map[string]any) (int, slidingResult, map[string]any) {
+	ts.t.Helper()
+	query := url.Values{}
+	if pos != "" {
+		query.Set("pos", pos)
+	}
+	query.Set("timeout", fmt.Sprint(timeout.Milliseconds()))
+	rec := ts.post(slidingPath+"?"+query.Encode(), acc.AccessToken, body)
+	if rec.Code != http.StatusOK {
+		return rec.Code, slidingResult{}, jsonBody(ts.t, rec)
+	}
+	return rec.Code, decode[slidingResult](ts.t, rec), nil
+}
+
+func (ts *testServer) sliding(acc account, pos string, body map[string]any) slidingResult {
+	ts.t.Helper()
+	code, result, errBody := ts.slidingRaw(acc, pos, 0, body)
+	if code != http.StatusOK {
+		ts.t.Fatalf("sliding sync answered %d: %v", code, errBody)
+	}
+	if result.Pos == "" {
+		ts.t.Fatal("sliding sync returned no pos")
+	}
+	return result
+}
+
+func roomList(ranges [][2]int, timelineLimit int, requiredState [][]string) map[string]any {
+	return map[string]any{
+		"lists": map[string]any{
+			"all": map[string]any{
+				"ranges":         ranges,
+				"timeline_limit": timelineLimit,
+				"required_state": requiredState,
+			},
+		},
+	}
+}
+
+func TestSlidingSyncListWindowAndIncrementals(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+
+	oldest := ts.createRoom(alice, map[string]any{"name": "Oldest"})
+	middle := ts.createRoom(alice, map[string]any{"name": "Middle"})
+	newest := ts.createRoom(alice, map[string]any{"name": "Newest"})
+	ts.sendMessage(alice, oldest, "o1")
+	ts.sendMessage(alice, middle, "m1")
+	ts.sendMessage(alice, newest, "n1")
+	ts.sendMessage(alice, newest, "n2")
+
+	body := roomList([][2]int{{0, 1}}, 2, [][]string{{"m.room.name", ""}})
+	first := ts.sliding(alice, "", body)
+	if first.Lists["all"].Count != 3 {
+		t.Fatalf("list count = %d, want 3", first.Lists["all"].Count)
+	}
+	if len(first.Rooms) != 2 {
+		t.Fatalf("rooms = %v, want the two most recently active", keysOf(first.Rooms))
+	}
+	room, ok := first.Rooms[newest]
+	if !ok || !room.Initial || room.Name != "Newest" {
+		t.Fatalf("newest room = %+v", room)
+	}
+	if got := bodiesOf(room.Timeline); len(got) != 2 || got[1] != "n2" || !room.Limited || room.PrevBatch == "" {
+		t.Errorf("newest timeline = %v (limited %v, prev_batch %q)", got, room.Limited, room.PrevBatch)
+	}
+	if len(room.RequiredState) != 1 || room.RequiredState[0].Type != "m.room.name" {
+		t.Errorf("required_state = %+v", room.RequiredState)
+	}
+	if room.JoinedCount == nil || *room.JoinedCount != 1 || room.BumpStamp == 0 {
+		t.Errorf("counts and bump stamp = %v %d", room.JoinedCount, room.BumpStamp)
+	}
+	if _, ok := first.Rooms[middle]; !ok {
+		t.Errorf("middle room missing from the window: %v", keysOf(first.Rooms))
+	}
+
+	// Nothing has happened: nothing is sent.
+	idle := ts.sliding(alice, first.Pos, body)
+	if len(idle.Rooms) != 0 {
+		t.Errorf("an idle incremental sent %v", keysOf(idle.Rooms))
+	}
+
+	// A message in a room already sent comes as an increment.
+	ts.sendMessage(alice, middle, "m2")
+	inc := ts.sliding(alice, idle.Pos, body)
+	got, ok := inc.Rooms[middle]
+	if !ok || got.Initial || len(got.Timeline) != 1 || got.Timeline[0].Content["body"] != "m2" {
+		t.Fatalf("increment for middle = %+v (rooms %v)", got, keysOf(inc.Rooms))
+	}
+	if got.NumLive == nil || *got.NumLive != 1 {
+		t.Errorf("num_live = %v, want 1", got.NumLive)
+	}
+
+	// The oldest room becomes active, moves into the window, and is sent
+	// in full because this connection has never seen it.
+	ts.sendMessage(alice, oldest, "o2")
+	bumped := ts.sliding(alice, inc.Pos, body)
+	if o, ok := bumped.Rooms[oldest]; !ok || !o.Initial {
+		t.Errorf("the bumped room = %+v (rooms %v)", o, keysOf(bumped.Rooms))
+	}
+
+	// A retry of an earlier pos still works; a made-up one does not.
+	if retry := ts.sliding(alice, inc.Pos, body); retry.Pos == "" {
+		t.Error("retrying the previous pos failed")
+	}
+	code, _, errBody := ts.slidingRaw(alice, "nonsense.5", 0, body)
+	if code != http.StatusBadRequest || errBody["errcode"] != httputil.ErrCodeUnknownPos {
+		t.Errorf("an unknown pos answered %d %v, want M_UNKNOWN_POS", code, errBody)
+	}
+}
+
+func TestSlidingSyncInvitesSubscriptionsAndLeaves(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+
+	joined := ts.createRoom(bob, nil)
+	ts.sendMessage(bob, joined, "hello")
+	invited := ts.createRoom(alice, map[string]any{"name": "Party", "invite": []string{bob.UserID}})
+
+	body := map[string]any{
+		"lists": map[string]any{
+			"invites": map[string]any{"ranges": [][2]int{{0, 10}}, "filters": map[string]any{"is_invite": true}},
+			"rooms": map[string]any{
+				"ranges": [][2]int{{0, 10}}, "filters": map[string]any{"is_invite": false},
+				"timeline_limit": 5, "required_state": [][]string{{"m.room.member", "$LAZY"}},
+			},
+		},
+	}
+	first := ts.sliding(bob, "", body)
+	if first.Lists["invites"].Count != 1 || first.Lists["rooms"].Count != 1 {
+		t.Fatalf("list counts = %+v", first.Lists)
+	}
+	if inv := first.Rooms[invited]; len(inv.InviteState) == 0 || inv.Timeline != nil {
+		t.Errorf("the invite = %+v, want stripped state and no timeline", inv)
+	}
+	lazy := first.Rooms[joined].RequiredState
+	if len(lazy) != 1 || lazy[0].Type != "m.room.member" || *lazy[0].StateKey != bob.UserID {
+		t.Errorf("lazy-loaded members = %+v, want only bob, who sent the timeline", lazy)
+	}
+
+	// A subscription to a room outside every list.
+	public := ts.createRoom(alice, map[string]any{"name": "Public", "preset": "public_chat"})
+	expectStatus(t, ts.post("/_matrix/client/v3/join/"+url.PathEscape(public), bob.AccessToken, map[string]any{}), http.StatusOK)
+	sub := ts.sliding(bob, first.Pos, map[string]any{
+		"room_subscriptions": map[string]any{public: map[string]any{"timeline_limit": 1, "required_state": [][]string{{"*", "*"}}}},
+	})
+	if r, ok := sub.Rooms[public]; !ok || !r.Initial || len(r.RequiredState) < 5 {
+		t.Fatalf("subscribed room = %+v", r)
+	}
+
+	// Joining the invited room turns it into a room sent in full.
+	expectStatus(t, ts.post("/_matrix/client/v3/join/"+url.PathEscape(invited), bob.AccessToken, map[string]any{}), http.StatusOK)
+	afterJoin := ts.sliding(bob, sub.Pos, body)
+	if r, ok := afterJoin.Rooms[invited]; !ok || !r.Initial || len(r.Timeline) == 0 {
+		t.Errorf("the room just joined = %+v", r)
+	}
+
+	// Leaving is reported, with the leave in the timeline.
+	expectStatus(t, ts.post("/_matrix/client/v3/rooms/"+url.PathEscape(invited)+"/leave", bob.AccessToken, map[string]any{}), http.StatusOK)
+	afterLeave := ts.sliding(bob, afterJoin.Pos, body)
+	r, ok := afterLeave.Rooms[invited]
+	if !ok || len(r.Timeline) == 0 || r.Timeline[len(r.Timeline)-1].Type != "m.room.member" {
+		t.Errorf("the room just left = %+v (rooms %v)", r, keysOf(afterLeave.Rooms))
+	}
+}
+
+func TestSlidingSyncExtensions(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, nil)
+	eventID := ts.sendMessage(alice, roomID, "read me")
+
+	body := roomList([][2]int{{0, 0}}, 1, nil)
+	body["extensions"] = map[string]any{
+		"to_device":    map[string]any{"enabled": true},
+		"e2ee":         map[string]any{"enabled": true},
+		"account_data": map[string]any{"enabled": true},
+		"receipts":     map[string]any{"enabled": true},
+		"typing":       map[string]any{"enabled": true},
+	}
+
+	expectStatus(t, ts.put("/_matrix/client/v3/user/"+url.PathEscape(alice.UserID)+"/account_data/com.example.setting",
+		alice.AccessToken, map[string]any{"on": true}), http.StatusOK)
+	expectStatus(t, ts.post(fmt.Sprintf("/_matrix/client/v3/rooms/%s/receipt/m.read/%s",
+		url.PathEscape(roomID), url.PathEscape(eventID)), alice.AccessToken, map[string]any{}), http.StatusOK)
+	expectStatus(t, ts.put("/_matrix/client/v3/sendToDevice/m.test/t1", alice.AccessToken, map[string]any{
+		"messages": map[string]any{alice.UserID: map[string]any{alice.DeviceID: map[string]any{"hello": "device"}}},
+	}), http.StatusOK)
+
+	first := ts.sliding(alice, "", body)
+	ext := first.Extensions
+	if ext.ToDevice == nil || len(ext.ToDevice.Events) != 1 || ext.ToDevice.NextBatch == "" {
+		t.Fatalf("to_device = %+v", ext.ToDevice)
+	}
+	if ext.E2EE == nil || ext.E2EE.DeviceOneTimeKeysCount == nil {
+		t.Errorf("e2ee = %+v", ext.E2EE)
+	}
+	foundSetting := false
+	if ext.AccountData != nil {
+		for _, e := range ext.AccountData.Global {
+			if e["type"] == "com.example.setting" {
+				foundSetting = true
+			}
+		}
+	}
+	if !foundSetting {
+		t.Errorf("account_data = %+v", ext.AccountData)
+	}
+	if ext.Receipts == nil || ext.Receipts.Rooms[roomID] == nil {
+		t.Errorf("receipts = %+v", ext.Receipts)
+	}
+
+	// Coming back with the to-device token acknowledges the batch.
+	body["extensions"].(map[string]any)["to_device"] = map[string]any{"enabled": true, "since": ext.ToDevice.NextBatch}
+	second := ts.sliding(alice, first.Pos, body)
+	if second.Extensions.ToDevice == nil || len(second.Extensions.ToDevice.Events) != 0 {
+		t.Errorf("an acknowledged batch came again: %+v", second.Extensions.ToDevice)
+	}
+
+	// Typing is sent when it starts and again when it stops.
+	expectStatus(t, ts.put(fmt.Sprintf("/_matrix/client/v3/rooms/%s/typing/%s", url.PathEscape(roomID), url.PathEscape(alice.UserID)),
+		alice.AccessToken, map[string]any{"typing": true, "timeout": 30000}), http.StatusOK)
+	typing := ts.sliding(alice, second.Pos, body)
+	if typing.Extensions.Typing == nil || typing.Extensions.Typing.Rooms[roomID] == nil {
+		t.Fatalf("typing = %+v", typing.Extensions.Typing)
+	}
+	again := ts.sliding(alice, typing.Pos, body)
+	if len(again.Extensions.Typing.Rooms) != 0 {
+		t.Errorf("unchanged typing was sent again: %+v", again.Extensions.Typing.Rooms)
+	}
+	expectStatus(t, ts.put(fmt.Sprintf("/_matrix/client/v3/rooms/%s/typing/%s", url.PathEscape(roomID), url.PathEscape(alice.UserID)),
+		alice.AccessToken, map[string]any{"typing": false}), http.StatusOK)
+	stopped := ts.sliding(alice, again.Pos, body)
+	if stopped.Extensions.Typing.Rooms[roomID] == nil {
+		t.Errorf("stopping typing was not sent: %+v", stopped.Extensions.Typing.Rooms)
+	}
+}
+
+func TestSlidingSyncLongPoll(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	roomID := ts.createRoom(alice, nil)
+	body := roomList([][2]int{{0, 0}}, 5, nil)
+	first := ts.sliding(alice, "", body)
+
+	done := make(chan slidingResult, 1)
+	start := time.Now()
+	go func() {
+		_, result, _ := ts.slidingRaw(alice, first.Pos, 10*time.Second, body)
+		done <- result
+	}()
+	time.Sleep(200 * time.Millisecond)
+	ts.sendMessage(alice, roomID, "wake up")
+
+	select {
+	case result := <-done:
+		if r, ok := result.Rooms[roomID]; !ok || len(r.Timeline) != 1 {
+			t.Errorf("the woken response = %+v", result.Rooms)
+		}
+		if time.Since(start) > 5*time.Second {
+			t.Errorf("the long poll took %s to wake", time.Since(start))
+		}
+	case <-time.After(15 * time.Second):
+		t.Fatal("the long poll never returned")
+	}
+}
+
+func keysOf[V any](m map[string]V) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}

server/internal/clientapi/spaces.go

@@ -0,0 +1,105 @@
+package clientapi
+
+import (
+	"net/http"
+	"strconv"
+	"strings"
+
+	"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/userapi"
+)
+
+// hierarchyResponse is what GET /hierarchy returns.
+type hierarchyResponse struct {
+	Rooms     []roomserver.SpaceRoom `json:"rooms"`
+	NextBatch string                 `json:"next_batch,omitempty"`
+}
+
+// hierarchyTokenPrefix marks a /hierarchy token: how far into the walk
+// the next page starts.
+const hierarchyTokenPrefix = "h"
+
+// handleHierarchy implements GET /_matrix/client/v1/rooms/{roomID}/hierarchy.
+func (c *ClientAPI) handleHierarchy(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	roomID, err := pathRoomID(r)
+	if err != nil {
+		return err
+	}
+	query := r.URL.Query()
+
+	limit, err := intParam(query.Get("limit"))
+	if err != nil {
+		return err
+	}
+	suggestedOnly, err := boolParam(query.Get("suggested_only"))
+	if err != nil {
+		return err
+	}
+	maxDepth := -1
+	if raw := query.Get("max_depth"); raw != "" {
+		if maxDepth, err = strconv.Atoi(raw); err != nil || maxDepth < 0 {
+			return httputil.InvalidParam("max_depth must be a non-negative integer")
+		}
+	}
+	from := 0
+	if raw := query.Get("from"); raw != "" {
+		body, ok := strings.CutPrefix(raw, hierarchyTokenPrefix)
+		if from, err = strconv.Atoi(body); !ok || err != nil || from < 0 {
+			return httputil.InvalidParam("%q is not a hierarchy token", raw)
+		}
+	}
+
+	page, err := c.rooms.Hierarchy(r.Context(), roomserver.HierarchyRequest{
+		RoomID:        roomID,
+		User:          auth.UserID,
+		SuggestedOnly: suggestedOnly,
+		MaxDepth:      maxDepth,
+		From:          from,
+		Limit:         limit,
+	})
+	if err != nil {
+		return roomError(err)
+	}
+	resp := hierarchyResponse{Rooms: page.Rooms}
+	if resp.Rooms == nil {
+		resp.Rooms = []roomserver.SpaceRoom{}
+	}
+	if page.Next != 0 {
+		resp.NextBatch = hierarchyTokenPrefix + strconv.Itoa(page.Next)
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}
+
+// handleRoomSummary implements
+// GET /_matrix/client/v1/room_summary/{roomIDOrAlias}.
+func (c *ClientAPI) handleRoomSummary(w http.ResponseWriter, r *http.Request, auth userapi.Authenticated) error {
+	target := r.PathValue("roomIDOrAlias")
+	via := r.URL.Query()["via"]
+
+	roomID := target
+	switch {
+	case strings.HasPrefix(target, "#"):
+		resolved, err := c.resolveAlias(r.Context(), target)
+		if err != nil {
+			return roomError(err)
+		}
+		roomID = resolved.RoomID
+		via = append(via, resolved.Servers...)
+	case id.ValidateRoomID(target) != nil:
+		return httputil.InvalidParam("%s is not a room ID or alias", target)
+	}
+
+	resp, err := c.rooms.RoomSummary(r.Context(), roomserver.RoomSummaryRequest{
+		RoomID: roomID,
+		User:   auth.UserID,
+		Via:    via,
+	})
+	if err != nil {
+		return roomError(err)
+	}
+	httputil.WriteJSON(w, http.StatusOK, resp)
+	return nil
+}

server/internal/clientapi/spaces_test.go

@@ -0,0 +1,182 @@
+package clientapi_test
+
+import (
+	"net/http"
+	"net/url"
+	"testing"
+)
+
+type hierarchyResult struct {
+	Rooms []struct {
+		RoomID           string           `json:"room_id"`
+		Name             string           `json:"name"`
+		RoomType         string           `json:"room_type"`
+		JoinRule         string           `json:"join_rule"`
+		NumJoinedMembers int              `json:"num_joined_members"`
+		ChildrenState    []map[string]any `json:"children_state"`
+	} `json:"rooms"`
+	NextBatch string `json:"next_batch"`
+}
+
+func (h hierarchyResult) ids() []string {
+	out := make([]string, 0, len(h.Rooms))
+	for _, r := range h.Rooms {
+		out = append(out, r.RoomID)
+	}
+	return out
+}
+
+func (ts *testServer) hierarchy(acc account, roomID, query string) hierarchyResult {
+	ts.t.Helper()
+	rec := ts.get("/_matrix/client/v1/rooms/"+url.PathEscape(roomID)+"/hierarchy"+query, acc.AccessToken)
+	expectStatus(ts.t, rec, http.StatusOK)
+	return decode[hierarchyResult](ts.t, rec)
+}
+
+// addChild puts a room into a space.
+func (ts *testServer) addChild(acc account, spaceID, childID string, content map[string]any) {
+	ts.t.Helper()
+	if content == nil {
+		content = map[string]any{}
+	}
+	if _, ok := content["via"]; !ok {
+		content["via"] = []string{"warp.example"}
+	}
+	rec := ts.put("/_matrix/client/v3/rooms/"+url.PathEscape(spaceID)+"/state/m.space.child/"+url.PathEscape(childID),
+		acc.AccessToken, content)
+	expectStatus(ts.t, rec, http.StatusOK)
+}
+
+func (ts *testServer) createSpace(acc account, name string, public bool) string {
+	ts.t.Helper()
+	body := map[string]any{"name": name, "creation_content": map[string]any{"type": "m.space"}}
+	if public {
+		body["preset"] = "public_chat"
+	}
+	return ts.createRoom(acc, body)
+}
+
+func TestSpaceHierarchy(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+
+	space := ts.createSpace(alice, "Space", true)
+	sub := ts.createSpace(alice, "Subspace", true)
+	general := ts.createRoom(alice, map[string]any{"name": "General", "preset": "public_chat"})
+	random := ts.createRoom(alice, map[string]any{"name": "Random", "preset": "public_chat"})
+	secret := ts.createRoom(alice, map[string]any{"name": "Secret"})
+	deep := ts.createRoom(alice, map[string]any{"name": "Deep", "preset": "public_chat"})
+
+	ts.addChild(alice, space, random, map[string]any{"order": "b"})
+	ts.addChild(alice, space, general, map[string]any{"order": "a", "suggested": true})
+	ts.addChild(alice, space, sub, nil)
+	ts.addChild(alice, space, secret, nil)
+	ts.addChild(alice, sub, deep, nil)
+	// A child event with no via is a removed child.
+	removed := ts.createRoom(alice, map[string]any{"name": "Gone", "preset": "public_chat"})
+	ts.addChild(alice, space, removed, map[string]any{"via": []string{}})
+
+	// Alice is in every room, so she sees all of them: the root, its
+	// children by order and then by timestamp, then the subspace's child.
+	all := ts.hierarchy(alice, space, "")
+	want := []string{space, general, random, sub, secret, deep}
+	if got := all.ids(); !equalStrings(got, want) {
+		t.Fatalf("alice's hierarchy = %v, want %v", got, want)
+	}
+	if all.Rooms[0].RoomType != "m.space" || len(all.Rooms[0].ChildrenState) != 4 {
+		t.Errorf("root = %+v, want a space with four live children", all.Rooms[0])
+	}
+
+	// Bob is in nothing: the invite-only room is hidden from him.
+	if got := ts.hierarchy(bob, space, "").ids(); !equalStrings(got, []string{space, general, random, sub, deep}) {
+		t.Errorf("bob's hierarchy = %v", got)
+	}
+
+	if got := ts.hierarchy(alice, space, "?max_depth=1").ids(); !equalStrings(got, []string{space, general, random, sub, secret}) {
+		t.Errorf("max_depth=1 = %v", got)
+	}
+	if got := ts.hierarchy(alice, space, "?suggested_only=true").ids(); !equalStrings(got, []string{space, general}) {
+		t.Errorf("suggested_only = %v", got)
+	}
+
+	// Paging two at a time walks the same order.
+	var paged []string
+	from := ""
+	for range 10 {
+		query := "?limit=2"
+		if from != "" {
+			query += "&from=" + url.QueryEscape(from)
+		}
+		page := ts.hierarchy(alice, space, query)
+		paged = append(paged, page.ids()...)
+		if page.NextBatch == "" {
+			break
+		}
+		from = page.NextBatch
+	}
+	if !equalStrings(paged, want) {
+		t.Errorf("paged hierarchy = %v, want %v", paged, want)
+	}
+}
+
+func TestSpaceHierarchyAccess(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+	carol := ts.register("carol", "correct-horse-battery-staple")
+
+	private := ts.createSpace(alice, "Private", false)
+	rec := ts.get("/_matrix/client/v1/rooms/"+url.PathEscape(private)+"/hierarchy", bob.AccessToken)
+	expectStatus(t, rec, http.StatusForbidden)
+
+	// A restricted room is visible to the members of the room it lets in.
+	space := ts.createSpace(alice, "Space", true)
+	restricted := ts.createRoom(alice, map[string]any{
+		"name": "Members only",
+		"initial_state": []map[string]any{{
+			"type": "m.room.join_rules", "state_key": "",
+			"content": map[string]any{
+				"join_rule": "restricted",
+				"allow":     []map[string]any{{"type": "m.room_membership", "room_id": space}},
+			},
+		}},
+	})
+	ts.addChild(alice, space, restricted, nil)
+	expectStatus(t, ts.post("/_matrix/client/v3/join/"+url.PathEscape(space), bob.AccessToken, map[string]any{}), http.StatusOK)
+
+	if got := ts.hierarchy(bob, space, "").ids(); !equalStrings(got, []string{space, restricted}) {
+		t.Errorf("a member of the space sees %v, want the restricted room too", got)
+	}
+	if got := ts.hierarchy(carol, space, "").ids(); !equalStrings(got, []string{space}) {
+		t.Errorf("a stranger sees %v, want the space alone", got)
+	}
+}
+
+func TestRoomSummary(t *testing.T) {
+	ts := newTestServer(t, nil)
+	alice := ts.register("alice", "correct-horse-battery-staple")
+	bob := ts.register("bob", "correct-horse-battery-staple")
+	public := ts.createRoom(alice, map[string]any{
+		"name": "Lobby", "topic": "Say hello", "preset": "public_chat", "room_alias_name": "lobby",
+	})
+	private := ts.createRoom(alice, map[string]any{"name": "Private"})
+
+	for _, target := range []string{public, "#lobby:warp.example"} {
+		rec := ts.get("/_matrix/client/v1/room_summary/"+url.PathEscape(target), bob.AccessToken)
+		expectStatus(t, rec, http.StatusOK)
+		body := jsonBody(t, rec)
+		if body["room_id"] != public || body["name"] != "Lobby" || body["topic"] != "Say hello" ||
+			body["membership"] != "leave" || body["join_rule"] != "public" || body["room_version"] == nil {
+			t.Errorf("summary of %s = %v", target, body)
+		}
+	}
+
+	rec := ts.get("/_matrix/client/v1/room_summary/"+url.PathEscape(private), bob.AccessToken)
+	expectStatus(t, rec, http.StatusForbidden)
+	rec = ts.get("/_matrix/client/v1/room_summary/"+url.PathEscape(private), alice.AccessToken)
+	expectStatus(t, rec, http.StatusOK)
+	if jsonBody(t, rec)["membership"] != "join" {
+		t.Errorf("alice's summary of her own room says membership %v", jsonBody(t, rec)["membership"])
+	}
+}

server/internal/clientapi/sync.go

@@ -34,6 +34,8 @@ func syncError(err error) error {
 		return httputil.InvalidParam("%s", err.Error())
 	case errors.Is(err, syncapi.ErrInvalidToken):
 		return httputil.InvalidParam("%s", err.Error())
+	case errors.Is(err, syncapi.ErrUnknownPos):
+		return httputil.NewError(http.StatusBadRequest, httputil.ErrCodeUnknownPos, "%s", err.Error())
 	case errors.Is(err, syncapi.ErrPresenceDisabled):
 		return httputil.Forbidden("Presence is disabled on this server")