Admin API for reported events

docs/admin_api/event_reports.rst

@@ -12,7 +12,7 @@ server admin: see `README.rst <README.rst>`_.
 
 It returns a JSON body like the following:
 
-.. code:: json
+.. code:: jsonc
 
     {
         "event_reports": [
@@ -70,7 +70,8 @@ It returns a JSON body like the following:
                 },
                 "event_id": "$3IcdZsDaN_En-S1DF4EMCy3v4gNRKeOJs8W5qTOKj4I",
                 "event_json": {
-                    "_comment": "... (hidden items) ..."
+                    // hidden items
+                    // see above
                 },
                 "id": 3,
                 "reason": "bar",
@@ -81,7 +82,7 @@ It returns a JSON body like the following:
                 "user_id": "@bar:matrix.org"
             }
         ],
-        "next_token": "2",
+        "next_token": 2,
         "total": 4
     }
 
@@ -93,30 +94,36 @@ reports to paginate through.
 
 **URL parameters:**
 
-- ``limit``: Is optional but is used for pagination,
+- ``limit``: integer - Is optional but is used for pagination,
   denoting the maximum number of items to return in this call. Defaults to ``100``.
-- ``from``: Is optional but used for pagination,
+- ``from``: integer - Is optional but used for pagination,
   denoting the offset in the returned results. This should be treated as an opaque value and
   not explicitly set to anything other than the return value of ``next_token`` from a previous call.
   Defaults to ``0``.
-- ``dir`` - Direction of event report order. Whether to fetch the most recent first (``b``) or the
+- ``dir``: string - Direction of event report order. Whether to fetch the most recent first (``b``) or the
   oldest first (``f``). Defaults to ``b``.
-- ``user_id``: Is optional and filters to only return users with user IDs that contain this value.
+- ``user_id``: string - Is optional and filters to only return users with user IDs that contain this value.
   This is the user who reported the event and wrote the reason.
-- ``room_id``: Is optional and filters to only return rooms with room IDs that contain this value.
+- ``room_id``: string - Is optional and filters to only return rooms with room IDs that contain this value.
 
 **Response**
 
 The following fields are returned in the JSON response body:
 
-- ``id``: Id of event report.
-- ``received_ts``: The timestamp (in milliseconds since the unix epoch) when this report was sent.
-- ``room_id``: The ID of the room.
-- ``event_id``: The ID of the reported event.
-- ``user_id``: This is the user who reported the event and wrote the reason.
-- ``reason``: Comment made by the ``user_id`` in this report.
-- ``content``: Content of reported event.
-- ``sender``: This is the ID of the user who sent the original message/event that was reported.
-- ``room_alias``: The alias of the room.
-- ``event_json``: Details of the original event that was reported.
+- ``id``: integer - ID of event report.
+- ``received_ts``: integer - The timestamp (in milliseconds since the unix epoch) when this report was sent.
+- ``room_id``: string - The ID of the room in which the event being reported is located.
+- ``event_id``: string - The ID of the reported event.
+- ``user_id``: string - This is the user who reported the event and wrote the reason.
+- ``reason``: string - Comment made by the ``user_id`` in this report. May be blank.
+- ``content``: object - Content of reported event.
+
+  - ``reason``: string - Comment made by the ``user_id`` in this report. May be blank.
+  - ``score``: integer - Content is reported based upon a negative score, where -100 is "most offensive" and 0 is "inoffensive".
+
+- ``sender``: string - This is the ID of the user who sent the original message/event that was reported.
+- ``room_alias``: string - The alias of the room. ``null`` if the room does not have a canonical alias set.
+- ``event_json``: object - Details of the original event that was reported.
+- ``next_token``: integer - Indication for pagination. See above.
+- ``total``: integer - Total number of event reports related to the query (``user_id`` and ``room_id``).
 

synapse/rest/admin/event_reports.py

@@ -26,7 +26,7 @@ class EventReportsRestServlet(RestServlet):
     """
     List all reported events that are known to the homeserver. Results are returned
     in a dictionary containing report information. Supports pagination.
-    This needs user to have administrator access in Synapse.
+    The requester must have administrator access in Synapse.
 
     GET /_synapse/admin/v1/event_reports
     returns:
@@ -82,7 +82,7 @@ async def on_GET(self, request):
             start, limit, direction, user_id, room_id
         )
         ret = {"event_reports": event_reports, "total": total}
-        if len(event_reports) >= limit:
-            ret["next_token"] = str(start + len(event_reports))
+        if (start + limit) < total:
+            ret["next_token"] = start + len(event_reports)
 
         return 200, ret

synapse/storage/databases/main/room.py

@@ -1325,16 +1325,16 @@ async def get_event_reports_paginate(
         start: int,
         limit: int,
         direction: str = "b",
-        user_id: str = None,
-        room_id: str = None,
+        user_id: Optional[str] = None,
+        room_id: Optional[str] = None,
     ) -> Tuple[List[Dict[str, Any]], int]:
         """Retrieve a paginated list of event reports
 
         Args:
             start: event offset to begin the query from
             limit: number of rows to retrieve
             direction: Whether to fetch the most recent first (`"b"`) or the
-                oldest first (`"f"`).
+                oldest first (`"f"`)
             user_id: search for user_id. Ignored if user_id is None
             room_id: search for room_id. Ignored if room_id is None
         Returns:

tests/rest/admin/test_event_reports.py

@@ -112,7 +112,7 @@ def test_limit(self):
         self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
         self.assertEqual(channel.json_body["total"], 20)
         self.assertEqual(len(channel.json_body["event_reports"]), 5)
-        self.assertEqual(channel.json_body["next_token"], "5")
+        self.assertEqual(channel.json_body["next_token"], 5)
         self._check_fields(channel.json_body["event_reports"])
 
     def test_from(self):
@@ -143,7 +143,7 @@ def test_limit_and_from(self):
 
         self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
         self.assertEqual(channel.json_body["total"], 20)
-        self.assertEqual(channel.json_body["next_token"], "15")
+        self.assertEqual(channel.json_body["next_token"], 15)
         self.assertEqual(len(channel.json_body["event_reports"]), 10)
         self._check_fields(channel.json_body["event_reports"])
 
@@ -290,6 +290,60 @@ def test_from_is_negative(self):
         self.assertEqual(400, int(channel.result["code"]), msg=channel.result["body"])
         self.assertEqual(Codes.INVALID_PARAM, channel.json_body["errcode"])
 
+    def test_next_token(self):
+        """
+        Testing that ``next_token`` appears at the right place
+        """
+
+        #  ``next_token`` does not appears
+        # Number of results is number of entries
+        request, channel = self.make_request(
+            "GET", self.url + "?limit=20", access_token=self.admin_user_tok,
+        )
+        self.render(request)
+
+        self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
+        self.assertEqual(channel.json_body["total"], 20)
+        self.assertEqual(len(channel.json_body["event_reports"]), 20)
+        self.assertNotIn("next_token", channel.json_body)
+
+        #  ``next_token`` does not appears
+        # Number of max results is larger than number of entries
+        request, channel = self.make_request(
+            "GET", self.url + "?limit=21", access_token=self.admin_user_tok,
+        )
+        self.render(request)
+
+        self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
+        self.assertEqual(channel.json_body["total"], 20)
+        self.assertEqual(len(channel.json_body["event_reports"]), 20)
+        self.assertNotIn("next_token", channel.json_body)
+
+        #  ``next_token`` does appears
+        # Number of max results is smaller than number of entries
+        request, channel = self.make_request(
+            "GET", self.url + "?limit=19", access_token=self.admin_user_tok,
+        )
+        self.render(request)
+
+        self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
+        self.assertEqual(channel.json_body["total"], 20)
+        self.assertEqual(len(channel.json_body["event_reports"]), 19)
+        self.assertEqual(channel.json_body["next_token"], 19)
+
+        # Check
+        # Set ``from`` to value of ``next_token`` for request remaining entries
+        #  ``next_token`` does not appears
+        request, channel = self.make_request(
+            "GET", self.url + "?from=19", access_token=self.admin_user_tok,
+        )
+        self.render(request)
+
+        self.assertEqual(200, int(channel.result["code"]), msg=channel.result["body"])
+        self.assertEqual(channel.json_body["total"], 20)
+        self.assertEqual(len(channel.json_body["event_reports"]), 1)
+        self.assertNotIn("next_token", channel.json_body)
+
     def _create_event_and_report(self, room_id, user_tok):
         """Create and report events
         """