Changed behaviour of query parameter deactivated moved to UsersRestSe…

…rvletV3

changelog.d/16874.feature

@@ -1 +1 @@
-Query parameter `deactivated` of [List Accounts](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) refactored, to filter deactivated users in user queries.
+Handling of the query parameter `deactivated` in [List Accounts (V3)](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) adjusted, to filter deactivated users in user queries.

docs/admin_api/user_admin_api.md

@@ -163,7 +163,7 @@ Body parameters:
   not be changed. If `null` is given, the user type will be cleared.
   Other allowed options are: `bot` and `support`.
 
-## List Accounts
+## List Accounts (V2)
 
 This API returns all local user accounts.
 By default, the response is ordered by ascending user ID.
@@ -226,10 +226,8 @@ The following parameters should be set in the URL:
   Defaults to `true` to include guest users. This parameter is not supported when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
 - `admins` - Optional flag to filter admins. If `true`, only admins are queried. If `false`, admins are excluded from
   the query. When the flag is absent (the default), **both** admins and non-admins are included in the search results.
-- `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are queried. 
-  If `false`, deactivated users are excluded from the query. When the flag is absent (the default), 
-  **both** active and deactivated users are included in the 
-  search results.
+- `deactivated` - string representing a bool - Is optional and if `true` will **include** deactivated users.
+  Defaults to `false` to exclude deactivated users.
 - `limit` - string representing a positive integer - Is optional but is used for pagination,
   denoting the maximum number of items to return in this call. Defaults to `100`.
 - `from` - string representing a positive integer - Is optional but used for pagination,
@@ -289,6 +287,21 @@ The following fields are returned in the JSON response body:
 
 *Added in Synapse 1.93:* the `locked` query parameter and response field.
 
+
+## List Accounts (V3)
+
+This API returns all local user accounts (see v2). In contrast to v2, the query parameter `deactivated` is handled differently.
+
+```
+GET /_synapse/admin/v3/users
+```
+
+**Parameters**
+- `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are queried.
+  If `false`, deactivated users are excluded from the query. When the flag is absent (the default),
+  **both** active and deactivated users are included in the
+  search results.
+
 ## Query current sessions for a user
 
 This API returns information about the active sessions for a specific user.

synapse/rest/admin/__init__.py

@@ -109,6 +109,7 @@
     UserReplaceMasterCrossSigningKeyRestServlet,
     UserRestServletV2,
     UsersRestServletV2,
+    UsersRestServletV3,
     UserTokenRestServlet,
     WhoisRestServlet,
 )
@@ -289,6 +290,7 @@ def register_servlets(hs: "HomeServer", http_server: HttpServer) -> None:
         UserTokenRestServlet(hs).register(http_server)
     UserRestServletV2(hs).register(http_server)
     UsersRestServletV2(hs).register(http_server)
+    UsersRestServletV3(hs).register(http_server)
     UserMediaStatisticsRestServlet(hs).register(http_server)
     LargestRoomsStatistics(hs).register(http_server)
     EventReportDetailRestServlet(hs).register(http_server)

synapse/rest/admin/users.py

@@ -72,7 +72,7 @@ class UsersRestServletV2(RestServlet):
     The parameter `user_id` can be used to filter by user id.
     The parameter `name` can be used to filter by user id or display name.
     The parameter `guests` can be used to exclude guest users.
-    The parameter `deactivated` can be used to filter deactivated users.
+    The parameter `deactivated` can be used to include deactivated users.
     The parameter `order_by` can be used to order the result.
     The parameter `not_user_type` can be used to exclude certain user types.
     The parameter `locked` can be used to include locked users.
@@ -118,7 +118,8 @@ async def on_GET(self, request: SynapseRequest) -> Tuple[int, JsonDict]:
                 errcode=Codes.INVALID_PARAM,
             )
 
-        deactivated = parse_boolean(request, "deactivated")
+        deactivated = self.__parse_parameter_deactivated(request)
+
         locked = parse_boolean(request, "locked", default=False)
         admins = parse_boolean(request, "admins")
 
@@ -182,6 +183,16 @@ def _filter(a: attr.Attribute) -> bool:
 
         return HTTPStatus.OK, ret
 
+    def __parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+        return None if parse_boolean(request, "deactivated") else False
+
+
+class UsersRestServletV3(UsersRestServletV2):
+    PATTERNS = admin_patterns("/users$", "v3")
+
+    def __parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+        return parse_boolean(request, "deactivated")
+
 
 class UserRestServletV2(RestServlet):
     PATTERNS = admin_patterns("/users/(?P<user_id>[^/]*)$", "v2")

tests/rest/admin/test_user.py

@@ -503,7 +503,7 @@ def test_all_users(self) -> None:
 
         channel = self.make_request(
             "GET",
-            self.url,
+            self.url + "?deactivated=true",
             {},
             access_token=self.admin_user_tok,
         )
@@ -987,6 +987,7 @@ def test_filter_deactivated_users(self) -> None:
         Tests whether the various values of the query parameter `deactivated` lead to the
         expected result set.
         """
+        users_url_v3 = self.url.replace("v2", "v3")
 
         # Register an additional non admin user
         user_id = self.register_user("user", "pass", admin=False)
@@ -1002,7 +1003,7 @@ def test_filter_deactivated_users(self) -> None:
         # Query all users
         channel = self.make_request(
             "GET",
-            f"{self.url}",
+            users_url_v3,
             access_token=self.admin_user_tok,
         )
 
@@ -1012,7 +1013,7 @@ def test_filter_deactivated_users(self) -> None:
         # Query deactivated users
         channel = self.make_request(
             "GET",
-            f"{self.url}?deactivated=true",
+            f"{users_url_v3}?deactivated=true",
             access_token=self.admin_user_tok,
         )
 
@@ -1023,7 +1024,7 @@ def test_filter_deactivated_users(self) -> None:
         # Query deactivated users
         channel = self.make_request(
             "GET",
-            f"{self.url}?deactivated=false",
+            f"{users_url_v3}?deactivated=false",
             access_token=self.admin_user_tok,
         )