Admin API to list, filter and sort rooms (#6720)

This commit is contained in:
Andrew Morgan 2020-01-22 13:36:43 +00:00 committed by GitHub
parent ae6cf586b0
commit 90a28fb475
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 787 additions and 7 deletions

1
changelog.d/6720.feature Normal file
View File

@ -0,0 +1 @@
Add a new admin API to list and filter rooms on the server.

173
docs/admin_api/rooms.md Normal file
View File

@ -0,0 +1,173 @@
# List Room API
The List Room admin API allows server admins to get a list of rooms on their
server. There are various parameters available that allow for filtering and
sorting the returned list. This API supports pagination.
## Parameters
The following query parameters are available:
* `from` - Offset in the returned list. Defaults to `0`.
* `limit` - Maximum amount of rooms to return. Defaults to `100`.
* `order_by` - The method in which to sort the returned list of rooms. Valid values are:
- `alphabetical` - Rooms are ordered alphabetically by room name. This is the default.
- `size` - Rooms are ordered by the number of members. Largest to smallest.
* `dir` - Direction of room order. Either `f` for forwards or `b` for backwards. Setting
this value to `b` will reverse the above sort order. Defaults to `f`.
* `search_term` - Filter rooms by their room name. Search term can be contained in any
part of the room name. Defaults to no filtering.
The following fields are possible in the JSON response body:
* `rooms` - An array of objects, each containing information about a room.
- Room objects contain the following fields:
- `room_id` - The ID of the room.
- `name` - The name of the room.
- `canonical_alias` - The canonical (main) alias address of the room.
- `joined_members` - How many users are currently in the room.
* `offset` - The current pagination offset in rooms. This parameter should be
used instead of `next_token` for room offset as `next_token` is
not intended to be parsed.
* `total_rooms` - The total number of rooms this query can return. Using this
and `offset`, you have enough information to know the current
progression through the list.
* `next_batch` - If this field is present, we know that there are potentially
more rooms on the server that did not all fit into this response.
We can use `next_batch` to get the "next page" of results. To do
so, simply repeat your request, setting the `from` parameter to
the value of `next_batch`.
* `prev_batch` - If this field is present, it is possible to paginate backwards.
Use `prev_batch` for the `from` value in the next request to
get the "previous page" of results.
## Usage
A standard request with no filtering:
```
GET /_synapse/admin/rooms
{}
```
Response:
```
{
"rooms": [
{
"room_id": "!OGEhHVWSdvArJzumhm:matrix.org",
"name": "Matrix HQ",
"canonical_alias": "#matrix:matrix.org",
"joined_members": 8326
},
... (8 hidden items) ...
{
"room_id": "!xYvNcQPhnkrdUmYczI:matrix.org",
"name": "This Week In Matrix (TWIM)",
"canonical_alias": "#twim:matrix.org",
"joined_members": 314
}
],
"offset": 0,
"total_rooms": 10
}
```
Filtering by room name:
```
GET /_synapse/admin/rooms?search_term=TWIM
{}
```
Response:
```
{
"rooms": [
{
"room_id": "!xYvNcQPhnkrdUmYczI:matrix.org",
"name": "This Week In Matrix (TWIM)",
"canonical_alias": "#twim:matrix.org",
"joined_members": 314
}
],
"offset": 0,
"total_rooms": 1
}
```
Paginating through a list of rooms:
```
GET /_synapse/admin/rooms?order_by=size
{}
```
Response:
```
{
"rooms": [
{
"room_id": "!OGEhHVWSdvArJzumhm:matrix.org",
"name": "Matrix HQ",
"canonical_alias": "#matrix:matrix.org",
"joined_members": 8326
},
... (98 hidden items) ...
{
"room_id": "!xYvNcQPhnkrdUmYczI:matrix.org",
"name": "This Week In Matrix (TWIM)",
"canonical_alias": "#twim:matrix.org",
"joined_members": 314
}
],
"offset": 0,
"total_rooms": 150
"next_token": 100
}
```
The presence of the `next_token` parameter tells us that there are more rooms
than returned in this request, and we need to make another request to get them.
To get the next batch of room results, we repeat our request, setting the `from`
parameter to the value of `next_token`.
```
GET /_synapse/admin/rooms?order_by=size&from=100
{}
```
Response:
```
{
"rooms": [
{
"room_id": "!mscvqgqpHYjBGDxNym:matrix.org",
"name": "Music Theory",
"canonical_alias": "#musictheory:matrix.org",
"joined_members": 127
},
... (48 hidden items) ...
{
"room_id": "!twcBhHVdZlQWuuxBhN:termina.org.uk",
"name": "weechat-matrix",
"canonical_alias": "#weechat-matrix:termina.org.uk",
"joined_members": 137
}
],
"offset": 100,
"prev_batch": 0,
"total_rooms": 150
}
```
Once the `next_token` parameter is no longer present, we know we've reached the
end of the list.

View File

@ -29,7 +29,7 @@ from synapse.rest.admin._base import (
from synapse.rest.admin.groups import DeleteGroupAdminRestServlet
from synapse.rest.admin.media import ListMediaInRoom, register_servlets_for_media_repo
from synapse.rest.admin.purge_room_servlet import PurgeRoomServlet
from synapse.rest.admin.rooms import ShutdownRoomRestServlet
from synapse.rest.admin.rooms import ListRoomRestServlet, ShutdownRoomRestServlet
from synapse.rest.admin.server_notice_servlet import SendServerNoticeServlet
from synapse.rest.admin.users import (
AccountValidityRenewServlet,
@ -188,6 +188,7 @@ def register_servlets(hs, http_server):
Register all the admin servlets.
"""
register_servlets_for_client_rest_resource(hs, http_server)
ListRoomRestServlet(hs).register(http_server)
PurgeRoomServlet(hs).register(http_server)
SendServerNoticeServlet(hs).register(http_server)
VersionServlet(hs).register(http_server)

View File

@ -40,6 +40,21 @@ def historical_admin_path_patterns(path_regex):
)
def admin_patterns(path_regex: str):
"""Returns the list of patterns for an admin endpoint
Args:
path_regex: The regex string to match. This should NOT have a ^
as this will be prefixed.
Returns:
A list of regex patterns.
"""
admin_prefix = "^/_synapse/admin/v1"
patterns = [re.compile(admin_prefix + path_regex)]
return patterns
async def assert_requester_is_admin(auth, request):
"""Verify that the requester is an admin user

View File

@ -15,15 +15,20 @@
import logging
from synapse.api.constants import Membership
from synapse.api.errors import Codes, SynapseError
from synapse.http.servlet import (
RestServlet,
assert_params_in_dict,
parse_integer,
parse_json_object_from_request,
parse_string,
)
from synapse.rest.admin._base import (
admin_patterns,
assert_user_is_admin,
historical_admin_path_patterns,
)
from synapse.storage.data_stores.main.room import RoomSortOrder
from synapse.types import create_requester
from synapse.util.async_helpers import maybe_awaitable
@ -155,3 +160,80 @@ class ShutdownRoomRestServlet(RestServlet):
"new_room_id": new_room_id,
},
)
class ListRoomRestServlet(RestServlet):
"""
List all rooms that are known to the homeserver. Results are returned
in a dictionary containing room information. Supports pagination.
"""
PATTERNS = admin_patterns("/rooms")
def __init__(self, hs):
self.store = hs.get_datastore()
self.auth = hs.get_auth()
self.admin_handler = hs.get_handlers().admin_handler
async def on_GET(self, request):
requester = await self.auth.get_user_by_req(request)
await assert_user_is_admin(self.auth, requester.user)
# Extract query parameters
start = parse_integer(request, "from", default=0)
limit = parse_integer(request, "limit", default=100)
order_by = parse_string(request, "order_by", default="alphabetical")
if order_by not in (
RoomSortOrder.ALPHABETICAL.value,
RoomSortOrder.SIZE.value,
):
raise SynapseError(
400,
"Unknown value for order_by: %s" % (order_by,),
errcode=Codes.INVALID_PARAM,
)
search_term = parse_string(request, "search_term")
if search_term == "":
raise SynapseError(
400,
"search_term cannot be an empty string",
errcode=Codes.INVALID_PARAM,
)
direction = parse_string(request, "dir", default="f")
if direction not in ("f", "b"):
raise SynapseError(
400, "Unknown direction: %s" % (direction,), errcode=Codes.INVALID_PARAM
)
reverse_order = True if direction == "b" else False
# Return list of rooms according to parameters
rooms, total_rooms = await self.store.get_rooms_paginate(
start, limit, order_by, reverse_order, search_term
)
response = {
# next_token should be opaque, so return a value the client can parse
"offset": start,
"rooms": rooms,
"total_rooms": total_rooms,
}
# Are there more rooms to paginate through after this?
if (start + limit) < total_rooms:
# There are. Calculate where the query should start from next time
# to get the next part of the list
response["next_batch"] = start + limit
# Is it possible to paginate backwards? Check if we currently have an
# offset
if start > 0:
if start > limit:
# Going back one iteration won't take us to the start.
# Calculate new offset
response["prev_batch"] = start - limit
else:
response["prev_batch"] = 0
return 200, response

View File

@ -32,7 +32,7 @@ def client_patterns(path_regex, releases=(0,), unstable=True, v1=False):
Args:
path_regex (str): The regex string to match. This should NOT have a ^
as this will be prefixed.
as this will be prefixed.
Returns:
SRE_Pattern
"""

View File

@ -18,7 +18,8 @@ import collections
import logging
import re
from abc import abstractmethod
from typing import List, Optional, Tuple
from enum import Enum
from typing import Any, Dict, List, Optional, Tuple
from six import integer_types
@ -46,6 +47,18 @@ RatelimitOverride = collections.namedtuple(
)
class RoomSortOrder(Enum):
"""
Enum to define the sorting method used when returning rooms with get_rooms_paginate
ALPHABETICAL = sort rooms alphabetically by name
SIZE = sort rooms by membership size, highest to lowest
"""
ALPHABETICAL = "alphabetical"
SIZE = "size"
class RoomWorkerStore(SQLBaseStore):
def __init__(self, database: Database, db_conn, hs):
super(RoomWorkerStore, self).__init__(database, db_conn, hs)
@ -281,6 +294,116 @@ class RoomWorkerStore(SQLBaseStore):
desc="is_room_blocked",
)
async def get_rooms_paginate(
self,
start: int,
limit: int,
order_by: RoomSortOrder,
reverse_order: bool,
search_term: Optional[str],
) -> Tuple[List[Dict[str, Any]], int]:
"""Function to retrieve a paginated list of rooms as json.
Args:
start: offset in the list
limit: maximum amount of rooms to retrieve
order_by: the sort order of the returned list
reverse_order: whether to reverse the room list
search_term: a string to filter room names by
Returns:
A list of room dicts and an integer representing the total number of
rooms that exist given this query
"""
# Filter room names by a string
where_statement = ""
if search_term:
where_statement = "WHERE state.name LIKE ?"
# Our postgres db driver converts ? -> %s in SQL strings as that's the
# placeholder for postgres.
# HOWEVER, if you put a % into your SQL then everything goes wibbly.
# To get around this, we're going to surround search_term with %'s
# before giving it to the database in python instead
search_term = "%" + search_term + "%"
# Set ordering
if RoomSortOrder(order_by) == RoomSortOrder.SIZE:
order_by_column = "curr.joined_members"
order_by_asc = False
elif RoomSortOrder(order_by) == RoomSortOrder.ALPHABETICAL:
# Sort alphabetically
order_by_column = "state.name"
order_by_asc = True
else:
raise StoreError(
500, "Incorrect value for order_by provided: %s" % order_by
)
# Whether to return the list in reverse order
if reverse_order:
# Flip the boolean
order_by_asc = not order_by_asc
# Create one query for getting the limited number of events that the user asked
# for, and another query for getting the total number of events that could be
# returned. Thus allowing us to see if there are more events to paginate through
info_sql = """
SELECT state.room_id, state.name, state.canonical_alias, curr.joined_members
FROM room_stats_state state
INNER JOIN room_stats_current curr USING (room_id)
%s
ORDER BY %s %s
LIMIT ?
OFFSET ?
""" % (
where_statement,
order_by_column,
"ASC" if order_by_asc else "DESC",
)
# Use a nested SELECT statement as SQL can't count(*) with an OFFSET
count_sql = """
SELECT count(*) FROM (
SELECT room_id FROM room_stats_state state
%s
) AS get_room_ids
""" % (
where_statement,
)
def _get_rooms_paginate_txn(txn):
# Execute the data query
sql_values = (limit, start)
if search_term:
# Add the search term into the WHERE clause
sql_values = (search_term,) + sql_values
txn.execute(info_sql, sql_values)
# Refactor room query data into a structured dictionary
rooms = []
for room in txn:
rooms.append(
{
"room_id": room[0],
"name": room[1],
"canonical_alias": room[2],
"joined_members": room[3],
}
)
# Execute the count query
# Add the search term into the WHERE clause if present
sql_values = (search_term,) if search_term else ()
txn.execute(count_sql, sql_values)
room_count = txn.fetchone()
return rooms, room_count[0]
return await self.db.runInteraction(
"get_rooms_paginate", _get_rooms_paginate_txn,
)
@cachedInlineCallbacks(max_entries=10000)
def get_ratelimit_for_user(self, user_id):
"""Check if there are any overrides for ratelimiting for the given

View File

@ -17,6 +17,7 @@ import json
import os
import urllib.parse
from binascii import unhexlify
from typing import List, Optional
from mock import Mock
@ -26,7 +27,7 @@ import synapse.rest.admin
from synapse.http.server import JsonResource
from synapse.logging.context import make_deferred_yieldable
from synapse.rest.admin import VersionServlet
from synapse.rest.client.v1 import events, login, room
from synapse.rest.client.v1 import directory, events, login, room
from synapse.rest.client.v2_alpha import groups
from tests import unittest
@ -468,9 +469,7 @@ class QuarantineMediaTestCase(unittest.HomeserverTestCase):
)
# Extract media ID from the response
server_name_and_media_id = response["content_uri"][
6:
] # Cut off the 'mxc://' bit
server_name_and_media_id = response["content_uri"][6:] # Cut off 'mxc://'
server_name, media_id = server_name_and_media_id.split("/")
# Attempt to access the media
@ -692,3 +691,389 @@ class QuarantineMediaTestCase(unittest.HomeserverTestCase):
% server_and_media_id_2
),
)
class RoomTestCase(unittest.HomeserverTestCase):
"""Test /room admin API.
"""
servlets = [
synapse.rest.admin.register_servlets,
login.register_servlets,
room.register_servlets,
directory.register_servlets,
]
def prepare(self, reactor, clock, hs):
self.store = hs.get_datastore()
# Create user
self.admin_user = self.register_user("admin", "pass", admin=True)
self.admin_user_tok = self.login("admin", "pass")
def test_list_rooms(self):
"""Test that we can list rooms"""
# Create 3 test rooms
total_rooms = 3
room_ids = []
for x in range(total_rooms):
room_id = self.helper.create_room_as(
self.admin_user, tok=self.admin_user_tok
)
room_ids.append(room_id)
# Request the list of rooms
url = "/_synapse/admin/v1/rooms"
request, channel = self.make_request(
"GET", url.encode("ascii"), access_token=self.admin_user_tok,
)
self.render(request)
# Check request completed successfully
self.assertEqual(200, int(channel.code), msg=channel.json_body)
# Check that response json body contains a "rooms" key
self.assertTrue(
"rooms" in channel.json_body,
msg="Response body does not " "contain a 'rooms' key",
)
# Check that 3 rooms were returned
self.assertEqual(3, len(channel.json_body["rooms"]), msg=channel.json_body)
# Check their room_ids match
returned_room_ids = [room["room_id"] for room in channel.json_body["rooms"]]
self.assertEqual(room_ids, returned_room_ids)
# Check that all fields are available
for r in channel.json_body["rooms"]:
self.assertIn("name", r)
self.assertIn("canonical_alias", r)
self.assertIn("joined_members", r)
# Check that the correct number of total rooms was returned
self.assertEqual(channel.json_body["total_rooms"], total_rooms)
# Check that the offset is correct
# Should be 0 as we aren't paginating
self.assertEqual(channel.json_body["offset"], 0)
# Check that the prev_batch parameter is not present
self.assertNotIn("prev_batch", channel.json_body)
# We shouldn't receive a next token here as there's no further rooms to show
self.assertNotIn("next_batch", channel.json_body)
def test_list_rooms_pagination(self):
"""Test that we can get a full list of rooms through pagination"""
# Create 5 test rooms
total_rooms = 5
room_ids = []
for x in range(total_rooms):
room_id = self.helper.create_room_as(
self.admin_user, tok=self.admin_user_tok
)
room_ids.append(room_id)
# Set the name of the rooms so we get a consistent returned ordering
for idx, room_id in enumerate(room_ids):
self.helper.send_state(
room_id, "m.room.name", {"name": str(idx)}, tok=self.admin_user_tok,
)
# Request the list of rooms
returned_room_ids = []
start = 0
limit = 2
run_count = 0
should_repeat = True
while should_repeat:
run_count += 1
url = "/_synapse/admin/v1/rooms?from=%d&limit=%d&order_by=%s" % (
start,
limit,
"alphabetical",
)
request, channel = self.make_request(
"GET", url.encode("ascii"), access_token=self.admin_user_tok,
)
self.render(request)
self.assertEqual(
200, int(channel.result["code"]), msg=channel.result["body"]
)
self.assertTrue("rooms" in channel.json_body)
for r in channel.json_body["rooms"]:
returned_room_ids.append(r["room_id"])
# Check that the correct number of total rooms was returned
self.assertEqual(channel.json_body["total_rooms"], total_rooms)
# Check that the offset is correct
# We're only getting 2 rooms each page, so should be 2 * last run_count
self.assertEqual(channel.json_body["offset"], 2 * (run_count - 1))
if run_count > 1:
# Check the value of prev_batch is correct
self.assertEqual(channel.json_body["prev_batch"], 2 * (run_count - 2))
if "next_batch" not in channel.json_body:
# We have reached the end of the list
should_repeat = False
else:
# Make another query with an updated start value
start = channel.json_body["next_batch"]
# We should've queried the endpoint 3 times
self.assertEqual(
run_count,
3,
msg="Should've queried 3 times for 5 rooms with limit 2 per query",
)
# Check that we received all of the room ids
self.assertEqual(room_ids, returned_room_ids)
url = "/_synapse/admin/v1/rooms?from=%d&limit=%d" % (start, limit)
request, channel = self.make_request(
"GET", url.encode("ascii"), access_token=self.admin_user_tok,
)
self.render(request)
self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
def test_correct_room_attributes(self):
"""Test the correct attributes for a room are returned"""
# Create a test room
room_id = self.helper.create_room_as(self.admin_user, tok=self.admin_user_tok)
test_alias = "#test:test"
test_room_name = "something"
# Have another user join the room
user_2 = self.register_user("user4", "pass")
user_tok_2 = self.login("user4", "pass")
self.helper.join(room_id, user_2, tok=user_tok_2)
# Create a new alias to this room
url = "/_matrix/client/r0/directory/room/%s" % (urllib.parse.quote(test_alias),)
request, channel = self.make_request(
"PUT",
url.encode("ascii"),
{"room_id": room_id},
access_token=self.admin_user_tok,
)
self.render(request)
self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
# Set this new alias as the canonical alias for this room
self.helper.send_state(
room_id,
"m.room.aliases",
{"aliases": [test_alias]},
tok=self.admin_user_tok,
state_key="test",
)
self.helper.send_state(
room_id,
"m.room.canonical_alias",
{"alias": test_alias},
tok=self.admin_user_tok,
)
# Set a name for the room
self.helper.send_state(
room_id, "m.room.name", {"name": test_room_name}, tok=self.admin_user_tok,
)
# Request the list of rooms
url = "/_synapse/admin/v1/rooms"
request, channel = self.make_request(
"GET", url.encode("ascii"), access_token=self.admin_user_tok,
)
self.render(request)
self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
# Check that rooms were returned
self.assertTrue("rooms" in channel.json_body)
rooms = channel.json_body["rooms"]
# Check that only one room was returned
self.assertEqual(len(rooms), 1)
# And that the value of the total_rooms key was correct
self.assertEqual(channel.json_body["total_rooms"], 1)
# Check that the offset is correct
# We're not paginating, so should be 0
self.assertEqual(channel.json_body["offset"], 0)
# Check that there is no `prev_batch`
self.assertNotIn("prev_batch", channel.json_body)
# Check that there is no `next_batch`
self.assertNotIn("next_batch", channel.json_body)
# Check that all provided attributes are set
r = rooms[0]
self.assertEqual(room_id, r["room_id"])
self.assertEqual(test_room_name, r["name"])
self.assertEqual(test_alias, r["canonical_alias"])
def test_room_list_sort_order(self):
"""Test room list sort ordering. alphabetical versus number of members,
reversing the order, etc.
"""
# Create 3 test rooms
room_id_1 = self.helper.create_room_as(self.admin_user, tok=self.admin_user_tok)
room_id_2 = self.helper.create_room_as(self.admin_user, tok=self.admin_user_tok)
room_id_3 = self.helper.create_room_as(self.admin_user, tok=self.admin_user_tok)
# Set room names in alphabetical order. room 1 -> A, 2 -> B, 3 -> C
self.helper.send_state(
room_id_1, "m.room.name", {"name": "A"}, tok=self.admin_user_tok,
)
self.helper.send_state(
room_id_2, "m.room.name", {"name": "B"}, tok=self.admin_user_tok,
)
self.helper.send_state(
room_id_3, "m.room.name", {"name": "C"}, tok=self.admin_user_tok,
)
# Set room member size in the reverse order. room 1 -> 1 member, 2 -> 2, 3 -> 3
user_1 = self.register_user("bob1", "pass")
user_1_tok = self.login("bob1", "pass")
self.helper.join(room_id_2, user_1, tok=user_1_tok)
user_2 = self.register_user("bob2", "pass")
user_2_tok = self.login("bob2", "pass")
self.helper.join(room_id_3, user_2, tok=user_2_tok)
user_3 = self.register_user("bob3", "pass")
user_3_tok = self.login("bob3", "pass")
self.helper.join(room_id_3, user_3, tok=user_3_tok)
def _order_test(
order_type: str, expected_room_list: List[str], reverse: bool = False,
):
"""Request the list of rooms in a certain order. Assert that order is what
we expect
Args:
order_type: The type of ordering to give the server
expected_room_list: The list of room_ids in the order we expect to get
back from the server
"""
# Request the list of rooms in the given order
url = "/_synapse/admin/v1/rooms?order_by=%s" % (order_type,)
if reverse:
url += "&dir=b"
request, channel = self.make_request(
"GET", url.encode("ascii"), access_token=self.admin_user_tok,
)
self.render(request)
self.assertEqual(200, channel.code, msg=channel.json_body)
# Check that rooms were returned
self.assertTrue("rooms" in channel.json_body)
rooms = channel.json_body["rooms"]
# Check for the correct total_rooms value
self.assertEqual(channel.json_body["total_rooms"], 3)
# Check that the offset is correct
# We're not paginating, so should be 0
self.assertEqual(channel.json_body["offset"], 0)
# Check that there is no `prev_batch`
self.assertNotIn("prev_batch", channel.json_body)
# Check that there is no `next_batch`
self.assertNotIn("next_batch", channel.json_body)
# Check that rooms were returned in alphabetical order
returned_order = [r["room_id"] for r in rooms]
self.assertListEqual(expected_room_list, returned_order) # order is checked
# Test different sort orders, with forward and reverse directions
_order_test("alphabetical", [room_id_1, room_id_2, room_id_3])
_order_test("alphabetical", [room_id_3, room_id_2, room_id_1], reverse=True)
_order_test("size", [room_id_3, room_id_2, room_id_1])
_order_test("size", [room_id_1, room_id_2, room_id_3], reverse=True)
def test_search_term(self):
"""Test that searching for a room works correctly"""
# Create two test rooms
room_id_1 = self.helper.create_room_as(self.admin_user, tok=self.admin_user_tok)
room_id_2 = self.helper.create_room_as(self.admin_user, tok=self.admin_user_tok)
room_name_1 = "something"
room_name_2 = "else"
# Set the name for each room
self.helper.send_state(
room_id_1, "m.room.name", {"name": room_name_1}, tok=self.admin_user_tok,
)
self.helper.send_state(
room_id_2, "m.room.name", {"name": room_name_2}, tok=self.admin_user_tok,
)
def _search_test(
expected_room_id: Optional[str],
search_term: str,
expected_http_code: int = 200,
):
"""Search for a room and check that the returned room's id is a match
Args:
expected_room_id: The room_id expected to be returned by the API. Set
to None to expect zero results for the search
search_term: The term to search for room names with
expected_http_code: The expected http code for the request
"""
url = "/_synapse/admin/v1/rooms?search_term=%s" % (search_term,)
request, channel = self.make_request(
"GET", url.encode("ascii"), access_token=self.admin_user_tok,
)
self.render(request)
self.assertEqual(expected_http_code, channel.code, msg=channel.json_body)
if expected_http_code != 200:
return
# Check that rooms were returned
self.assertTrue("rooms" in channel.json_body)
rooms = channel.json_body["rooms"]
# Check that the expected number of rooms were returned
expected_room_count = 1 if expected_room_id else 0
self.assertEqual(len(rooms), expected_room_count)
self.assertEqual(channel.json_body["total_rooms"], expected_room_count)
# Check that the offset is correct
# We're not paginating, so should be 0
self.assertEqual(channel.json_body["offset"], 0)
# Check that there is no `prev_batch`
self.assertNotIn("prev_batch", channel.json_body)
# Check that there is no `next_batch`
self.assertNotIn("next_batch", channel.json_body)
if expected_room_id:
# Check that the first returned room id is correct
r = rooms[0]
self.assertEqual(expected_room_id, r["room_id"])
# Perform search tests
_search_test(room_id_1, "something")
_search_test(room_id_1, "thing")
_search_test(room_id_2, "else")
_search_test(room_id_2, "se")
_search_test(None, "foo")
_search_test(None, "bar")
_search_test(None, "", expected_http_code=400)