Add an admin API to get the space hierarchy

changelog.d/19021.feature

@@ -0,0 +1,2 @@
+Add an [Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html) to allow an admin
+to search for room details and any children in a provided room.

docs/admin_api/rooms.md

@@ -1115,3 +1115,76 @@ Example response:
   ]
 }
 ```
+
+# Admin Space Hierarchy Endpoint
+
+This API allows an admin to fetch the space/room hierarchy for a given space, returning details about that room and any children
+the room may have, paginating over the space tree in a depth-first manner to locate child rooms. This is functionally similar to the [CS Hierarchy](https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv1roomsroomidhierarchy) endpoint but does not return information about any remote
+rooms that the server is not currently participating in and does not check for room membership when returning room summaries.
+
+**Parameters**
+
+The following query parameters are available:
+
+* `from` - An optional pagination token, provided when there are more rooms to return than the limit. 
+* `limit` - Maximum amount of rooms to return. Must be a non-negative integer, defaults to `50`.
+* `max_depth` - The maximum depth in the tree to explore, must be a non-negative integer. 0 would correspond to just the root room, 1 would include just the root room's children, etc.  If not provided will recurse into the space tree without limit.
+
+Request:
+
+```http
+GET /_synapse/admin/v1/rooms/<room_id>/hierarchy
+```
+
+Response:
+
+```json
+{
+  "rooms":
+      [
+        {"aliases": [],
+        "children_state": [
+            {
+              "content": {
+                "via": ["local_test_server"]
+              },
+              "origin_server_ts": 1500,
+              "sender": "@user:test",
+              "state_key": "!QrMkkqBSwYRIFNFCso:test",
+              "type": "m.space.child"
+            }
+        ],
+        "creation_event_id": "$bVkNVtm4aDw4c0LRf_U5Ad7mZSo4WKzzQKImrk_rQcg",
+        "creator": "@user:test",
+        "guest_can_join": false,
+        "is_space": true,
+        "join_rule": "public",
+        "name": null,
+        "num_joined_members": 1,
+        "power_users": ["@user:test"],
+        "room_creation_ts": 1400,
+        "room_id": "!sPOpNyMHbZAoAOsOFL:test",
+        "room_type": "m.space",
+        "topic": null, 
+        "world_readable": false
+      },
+
+      {
+        "aliases": [],
+        "children_state": [],
+        "creation_event_id": "$kymNeN-gA5kzLwZ6FEQUu0_2MfeenYKINSO3dUuLYf8",
+        "creator": "@user:test",
+        "guest_can_join": true,
+        "is_space": false,
+        "join_rule": "invite",
+        "name": "nefarious",
+        "num_joined_members": 1,
+        "power_users": ["@user:test"],
+        "room_creation_ts": 999,
+        "room_id": "!QrMkkqBSwYRIFNFCso:test",
+        "topic": "being bad",
+        "world_readable": false}
+    ],
+  "next_batch": "KUYmRbeSpAoaAIgOKGgyaCEn"
+}
+```

synapse/handlers/room_summary.py

@@ -116,6 +116,8 @@ def __init__(self, hs: "HomeServer"):
                 str,
                 str,
                 bool,
+                bool,
+                bool,
                 Optional[int],
                 Optional[int],
                 Optional[str],
@@ -133,6 +135,8 @@ async def get_room_hierarchy(
         requester: Requester,
         requested_room_id: str,
         suggested_only: bool = False,
+        omit_remote_rooms: bool = False,
+        admin_skip_room_visibility_check: bool = False,
         max_depth: Optional[int] = None,
         limit: Optional[int] = None,
         from_token: Optional[str] = None,
@@ -146,6 +150,9 @@ async def get_room_hierarchy(
             requested_room_id: The room ID to start the hierarchy at (the "root" room).
             suggested_only: Whether we should only return children with the "suggested"
                 flag set.
+            omit_remote_rooms: Whether to omit rooms which the server is not currently participating in
+            admin_skip_room_visibility_check: Whether to skip checking if the room can be accessed by the requester,
+                used for the admin endpoints.
             max_depth: The maximum depth in the tree to explore, must be a
                 non-negative integer.
 
@@ -173,6 +180,8 @@ async def get_room_hierarchy(
                 requester.user.to_string(),
                 requested_room_id,
                 suggested_only,
+                omit_remote_rooms,
+                admin_skip_room_visibility_check,
                 max_depth,
                 limit,
                 from_token,
@@ -182,6 +191,8 @@ async def get_room_hierarchy(
             requester.user.to_string(),
             requested_room_id,
             suggested_only,
+            omit_remote_rooms,
+            admin_skip_room_visibility_check,
             max_depth,
             limit,
             from_token,
@@ -193,6 +204,8 @@ async def _get_room_hierarchy(
         requester: str,
         requested_room_id: str,
         suggested_only: bool = False,
+        omit_remote_rooms: bool = False,
+        admin_skip_room_visibility_check: bool = False,
         max_depth: Optional[int] = None,
         limit: Optional[int] = None,
         from_token: Optional[str] = None,
@@ -204,17 +217,18 @@ async def _get_room_hierarchy(
         local_room = await self._store.is_host_joined(
             requested_room_id, self._server_name
         )
-        if local_room and not await self._is_local_room_accessible(
-            requested_room_id, requester
-        ):
-            raise UnstableSpecAuthError(
-                403,
-                "User %s not in room %s, and room previews are disabled"
-                % (requester, requested_room_id),
-                errcode=Codes.NOT_JOINED,
-            )
+        if not admin_skip_room_visibility_check:
+            if local_room and not await self._is_local_room_accessible(
+                requested_room_id, requester
+            ):
+                raise UnstableSpecAuthError(
+                    403,
+                    "User %s not in room %s, and room previews are disabled"
+                    % (requester, requested_room_id),
+                    errcode=Codes.NOT_JOINED,
+                )
 
-        if not local_room:
+        if not local_room and not omit_remote_rooms:
             room_hierarchy = await self._summarize_remote_room_hierarchy(
                 _RoomQueueEntry(requested_room_id, remote_room_hosts or ()),
                 False,
@@ -247,6 +261,9 @@ async def _get_room_hierarchy(
                 or requested_room_id != pagination_session["room_id"]
                 or suggested_only != pagination_session["suggested_only"]
                 or max_depth != pagination_session["max_depth"]
+                or omit_remote_rooms != pagination_session["omit_remote_rooms"]
+                or admin_skip_room_visibility_check
+                != pagination_session["admin_skip_room_visibility_check"]
             ):
                 raise SynapseError(400, "Unknown pagination token", Codes.INVALID_PARAM)
 
@@ -301,10 +318,11 @@ async def _get_room_hierarchy(
                     None,
                     room_id,
                     suggested_only,
+                    admin_skip_room_visibility_check=admin_skip_room_visibility_check,
                 )
 
             # Otherwise, attempt to use information for federation.
-            else:
+            elif not omit_remote_rooms:
                 # A previous call might have included information for this room.
                 # It can be used if either:
                 #
@@ -378,6 +396,8 @@ async def _get_room_hierarchy(
                     "room_id": requested_room_id,
                     "suggested_only": suggested_only,
                     "max_depth": max_depth,
+                    "omit_remote_rooms": omit_remote_rooms,
+                    "admin_skip_room_visibility_check": admin_skip_room_visibility_check,
                     # The stored state.
                     "room_queue": [
                         attr.astuple(room_entry) for room_entry in room_queue
@@ -460,6 +480,7 @@ async def _summarize_local_room(
         room_id: str,
         suggested_only: bool,
         include_children: bool = True,
+        admin_skip_room_visibility_check: bool = False,
     ) -> Optional["_RoomEntry"]:
         """
         Generate a room entry and a list of event entries for a given room.
@@ -476,11 +497,16 @@ async def _summarize_local_room(
                 Otherwise, all children are returned.
             include_children:
                 Whether to include the events of any children.
+            admin_skip_room_visibility_check: Whether to skip checking if the room can be accessed by the requester,
+                used for the admin endpoints.
 
         Returns:
             A room entry if the room should be returned. None, otherwise.
         """
-        if not await self._is_local_room_accessible(room_id, requester, origin):
+        if (
+            not admin_skip_room_visibility_check
+            and not await self._is_local_room_accessible(room_id, requester, origin)
+        ):
             return None
 
         room_entry = await self._build_room_entry(room_id, for_federation=bool(origin))

synapse/rest/admin/__init__.py

@@ -74,6 +74,7 @@
     RegistrationTokenRestServlet,
 )
 from synapse.rest.admin.rooms import (
+    AdminRoomHierarchy,
     BlockRoomRestServlet,
     DeleteRoomStatusByDeleteIdRestServlet,
     DeleteRoomStatusByRoomIdRestServlet,
@@ -342,6 +343,7 @@ def register_servlets(hs: "HomeServer", http_server: HttpServer) -> None:
     ExperimentalFeaturesRestServlet(hs).register(http_server)
     SuspendAccountRestServlet(hs).register(http_server)
     ScheduledTasksRestServlet(hs).register(http_server)
+    AdminRoomHierarchy(hs).register(http_server)
     EventRestServlet(hs).register(http_server)
 
 

synapse/rest/admin/rooms.py

@@ -63,6 +63,46 @@
 logger = logging.getLogger(__name__)
 
 
+class AdminRoomHierarchy(RestServlet):
+    """
+    Given a room, returns room details on that room and any space children of the provided room.
+    Does not return information about remote rooms which the server is not currently
+    participating in
+    """
+
+    PATTERNS = admin_patterns("/rooms/(?P<room_id>[^/]*)/hierarchy$")
+
+    def __init__(self, hs: "HomeServer"):
+        self._auth = hs.get_auth()
+        self._room_summary_handler = hs.get_room_summary_handler()
+        self._store = hs.get_datastores().main
+        self._storage_controllers = hs.get_storage_controllers()
+
+    async def on_GET(
+        self, request: SynapseRequest, room_id: str
+    ) -> Tuple[int, JsonDict]:
+        requester = await self._auth.get_user_by_req(request)
+        await assert_user_is_admin(self._auth, requester)
+
+        max_depth = parse_integer(request, "max_depth")
+        limit = parse_integer(request, "limit")
+
+        # we omit returning remote rooms that the server is not currently participating in,
+        # as that information shouldn't be available to the server admin (as they are not
+        # participating in those rooms)
+        room_entry_summary = await self._room_summary_handler.get_room_hierarchy(
+            requester,
+            room_id,
+            omit_remote_rooms=True,
+            admin_skip_room_visibility_check=True,
+            max_depth=max_depth,
+            limit=limit,
+            from_token=parse_string(request, "from"),
+        )
+
+        return HTTPStatus.OK, room_entry_summary
+
+
 class RoomRestV2Servlet(RestServlet):
     """Delete a room from server asynchronously with a background task.