From 15e75103a51946498b20389dc762633616f65c55 Mon Sep 17 00:00:00 2001
From: Half-Shot <will@half-shot.uk>
Date: Fri, 18 Feb 2022 12:42:22 +0000
Subject: [PATCH] Documentation

---
 changelog.d/12028.feature                   |  1 +
 docs/modules/third_party_rules_callbacks.md | 44 +++++++++++++++++++++
 synapse/events/third_party_rules.py         | 12 +++---
 3 files changed, 51 insertions(+), 6 deletions(-)
 create mode 100644 changelog.d/12028.feature

diff --git a/changelog.d/12028.feature b/changelog.d/12028.feature
new file mode 100644
index 000000000000..31aefffa77c6
--- /dev/null
+++ b/changelog.d/12028.feature
@@ -0,0 +1 @@
+Add third party event rules functions `check_can_shutdown_room` and `check_can_deactivate_user`.
diff --git a/docs/modules/third_party_rules_callbacks.md b/docs/modules/third_party_rules_callbacks.md
index a3a17096a8f5..aa12ffe044b1 100644
--- a/docs/modules/third_party_rules_callbacks.md
+++ b/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
diff --git a/synapse/events/third_party_rules.py b/synapse/events/third_party_rules.py
index 1a8712c433a1..452cce64856b 100644
--- a/synapse/events/third_party_rules.py
+++ b/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,19 @@ 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:
+    async def check_can_shutdown_room(self, user_id: str, room_id: str) -> None:
         """Intercept requests to delete room to maybe deny it by returning False.
 
         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(