Documentation

Author: Half-Shot

changelog.d/12028.feature

@@ -0,0 +1 @@
+Add third party event rules functions `check_can_shutdown_room` and `check_can_deactivate_user`.

docs/modules/third_party_rules_callbacks.md

@@ -148,6 +148,50 @@ deny an incoming event, see [`check_event_for_spam`](spam_checker_callbacks.md#c
 
 If multiple modules implement this callback, Synapse runs them all in order.
 
+### `check_can_shutdown_room`
+
+_First introduced in Synapse v1.5X.0_
+
+```python
+async def check_can_shutdown_room(
+    user_id: str
+    room_id: str,
+) -> bool:
+```
+
+Called when a user requests the shutdown of a room. The module must return a
+boolean indicating whether the shutdown can go through. If the callback returns `False`,
+the shutdown will not proceed and the caller will see a `M_FOBIDDEN` error.
+
+If multiple modules implement this callback, they will be considered in order. If a
+callback returns `True`, Synapse falls through to the next one. The value of the first
+callback that does not return `True` will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
+
+### `check_can_deactivate_user`
+
+_First introduced in Synapse v1.5X.0_
+
+```python
+async def check_can_deactivate_user(
+    requester: "synapse.types.Requester",
+    user_id: str,
+) -> bool:
+```
+
+Called when a user requests the deactivation of a user. User deactivation may be
+performed by an admin or the user themselves, so developers are encouraged to check the
+requester when implementing this callback. The module must return a
+boolean indicating whether the deactivation can go through. If the callback returns `False`,
+the deactivation will not proceed and the caller will see a `M_FOBIDDEN` error.
+
+If multiple modules implement this callback, they will be considered in order. If a
+callback returns `True`, Synapse falls through to the next one. The value of the first
+callback that does not return `True` will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
+
+
+
 ## Example
 
 The example below is a module that implements the third-party rules callback

synapse/events/third_party_rules.py

@@ -156,7 +156,7 @@ def __init__(self, hs: "HomeServer"):
             CHECK_VISIBILITY_CAN_BE_MODIFIED_CALLBACK
         ] = []
         self._on_new_event_callbacks: List[ON_NEW_EVENT_CALLBACK] = []
-        self._check_can_delete_room: List[CHECK_CAN_SHUTDOWN_ROOM_CALLBACK] = []
+        self._check_can_shutdown_room: List[CHECK_CAN_SHUTDOWN_ROOM_CALLBACK] = []
         self._check_can_deactivate_user: List[CHECK_CAN_DEACTIVATE_USER_CALLBACK] = []
 
     def register_third_party_rules_callbacks(
@@ -194,7 +194,7 @@ def register_third_party_rules_callbacks(
             self._on_new_event_callbacks.append(on_new_event)
 
         if check_can_shutdown_room is not None:
-            self._check_can_delete_room.append(check_can_shutdown_room)
+            self._check_can_shutdown_room.append(check_can_shutdown_room)
 
         if check_can_deactivate_user is not None:
             self._check_can_deactivate_user.append(check_can_deactivate_user)
@@ -365,19 +365,20 @@ async def on_new_event(self, event_id: str) -> None:
                     "Failed to run module API callback %s: %s", callback, e
                 )
 
-    async def check_can_shutdown_room(self, requester: Requester, room_id: str) -> None:
-        """Intercept requests to delete room to maybe deny it by returning False.
+    async def check_can_shutdown_room(self, user_id: str, room_id: str) -> bool:
+        """Intercept requests to shutdown a room. If `False` is returned, the
+        room should not be shut down.
 
         Args:
-            requester
+            requester: The ID of the user requesting the shutdown.
             room_id: The ID of the room.
 
         Raises:
             ModuleFailureError if a callback raised any exception.
         """
-        for callback in self._check_can_delete_room:
+        for callback in self._check_can_shutdown_room:
             try:
-                if await callback(requester, room_id) is False:
+                if await callback(user_id, room_id) is False:
                     return False
             except Exception as e:
                 logger.exception(
@@ -387,8 +388,9 @@ async def check_can_shutdown_room(self, requester: Requester, room_id: str) -> N
 
     async def check_can_deactivate_user(
         self, requester: Requester, user_id: str
-    ) -> None:
-        """Intercept requests to deactivate a user to maybe deny it by returning False.
+    ) -> bool:
+        """Intercept requests to deactivate a user. If `False` is returned, the
+        user should not be deactivated.
 
         Args:
             requester