chore: add on_upgrade_room() to third_party_event_rules ModuleApi

Called in the process of upgrading a room, provides access to the
`Requester` object for data about the requesting user, and access to the
`RoomVersion` object for data about the requested new version for the
room.

Returns nothing, denials should raise a `SynapseError` with appropriate
codes and messages that will be returned to the client. Multiple modules
may implement this callback, first one that raises an Exception denies
further processing of the upgrade to the room

Author: jason-famedly

synapse/handlers/room.py

@@ -220,6 +220,8 @@ async def upgrade_room(
         if old_room is None:
             raise NotFoundError("Unknown room id %s" % (old_room_id,))
 
+        await self._third_party_event_rules.on_upgrade_room(requester, new_version)
+
         new_room_id = self._generate_room_id()
 
         # Try several times, it could fail with PartialStateConflictError

synapse/module_api/__init__.py

@@ -117,6 +117,7 @@
     ON_PROFILE_UPDATE_CALLBACK,
     ON_REMOVE_USER_THIRD_PARTY_IDENTIFIER_CALLBACK,
     ON_THREEPID_BIND_CALLBACK,
+    ON_UPGRADE_ROOM_CALLBACK,
     ON_USER_DEACTIVATION_STATUS_CHANGED_CALLBACK,
 )
 from synapse.push.httppusher import HttpPusher
@@ -385,6 +386,7 @@ def register_third_party_rules_callbacks(
         on_remove_user_third_party_identifier: Optional[
             ON_REMOVE_USER_THIRD_PARTY_IDENTIFIER_CALLBACK
         ] = None,
+        on_upgrade_room: Optional[ON_UPGRADE_ROOM_CALLBACK] = None,
     ) -> None:
         """Registers callbacks for third party event rules capabilities.
 
@@ -403,6 +405,7 @@ def register_third_party_rules_callbacks(
             on_threepid_bind=on_threepid_bind,
             on_add_user_third_party_identifier=on_add_user_third_party_identifier,
             on_remove_user_third_party_identifier=on_remove_user_third_party_identifier,
+            on_upgrade_room=on_upgrade_room,
         )
 
     def register_presence_router_callbacks(

synapse/module_api/callbacks/third_party_event_rules_callbacks.py

@@ -24,6 +24,7 @@
 from twisted.internet.defer import CancelledError
 
 from synapse.api.errors import ModuleFailedException, SynapseError
+from synapse.api.room_versions import RoomVersion
 from synapse.events import EventBase
 from synapse.events.snapshot import UnpersistedEventContextBase
 from synapse.storage.roommember import ProfileInfo
@@ -54,6 +55,7 @@
 ON_THREEPID_BIND_CALLBACK = Callable[[str, str, str], Awaitable]
 ON_ADD_USER_THIRD_PARTY_IDENTIFIER_CALLBACK = Callable[[str, str, str], Awaitable]
 ON_REMOVE_USER_THIRD_PARTY_IDENTIFIER_CALLBACK = Callable[[str, str, str], Awaitable]
+ON_UPGRADE_ROOM_CALLBACK = Callable[[Requester, RoomVersion], Awaitable]
 
 
 def load_legacy_third_party_event_rules(hs: "HomeServer") -> None:
@@ -185,6 +187,7 @@ def __init__(self, hs: "HomeServer"):
         self._on_remove_user_third_party_identifier_callbacks: List[
             ON_REMOVE_USER_THIRD_PARTY_IDENTIFIER_CALLBACK
         ] = []
+        self._on_upgrade_room_callbacks: List[ON_UPGRADE_ROOM_CALLBACK] = []
 
     def register_third_party_rules_callbacks(
         self,
@@ -210,6 +213,7 @@ def register_third_party_rules_callbacks(
         on_remove_user_third_party_identifier: Optional[
             ON_REMOVE_USER_THIRD_PARTY_IDENTIFIER_CALLBACK
         ] = None,
+        on_upgrade_room: Optional[ON_UPGRADE_ROOM_CALLBACK] = None,
     ) -> None:
         """Register callbacks from modules for each hook."""
         if check_event_allowed is not None:
@@ -256,6 +260,8 @@ def register_third_party_rules_callbacks(
             self._on_remove_user_third_party_identifier_callbacks.append(
                 on_remove_user_third_party_identifier
             )
+        if on_upgrade_room is not None:
+            self._on_upgrade_room_callbacks.append(on_upgrade_room)
 
     async def check_event_allowed(
         self,
@@ -597,3 +603,29 @@ async def on_remove_user_third_party_identifier(
                 logger.exception(
                     "Failed to run module API callback %s: %s", callback, e
                 )
+
+    async def on_upgrade_room(
+        self, requester: Requester, room_version: RoomVersion
+    ) -> None:
+        """Intercept requests to upgrade a room to maybe deny it (via an exception).
+
+        Args:
+            requester
+            room_version: The RoomVersion requested for the upgrade.
+        """
+        for callback in self._on_upgrade_room_callbacks:
+            try:
+                await callback(requester, room_version)
+            except Exception as e:
+                logger.exception(
+                    "Failed to run module API callback %s: %s", callback, e
+                )
+                # Don't silence the errors raised by this callback since we expect it to
+                # raise an exception to deny the upgrade of the room; instead make sure
+                # it's a SynapseError we can send to clients.
+                if not isinstance(e, SynapseError):
+                    e = SynapseError(
+                        403, "Room upgrade forbidden with these parameters"
+                    )
+
+                raise e

tests/rest/client/test_third_party_rules.py

@@ -19,27 +19,29 @@
 #
 #
 import threading
-from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Union
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
 from unittest.mock import AsyncMock, Mock
 
 from twisted.test.proto_helpers import MemoryReactor
 
 from synapse.api.constants import EventTypes, LoginType, Membership
-from synapse.api.errors import SynapseError
+from synapse.api.errors import Codes, SynapseError
 from synapse.api.room_versions import RoomVersion
 from synapse.config.homeserver import HomeServerConfig
 from synapse.events import EventBase
 from synapse.module_api.callbacks.third_party_event_rules_callbacks import (
     load_legacy_third_party_event_rules,
 )
 from synapse.rest import admin
-from synapse.rest.client import account, login, profile, room
+from synapse.rest.client import account, login, profile, room, room_upgrade_rest_servlet
 from synapse.server import HomeServer
 from synapse.types import JsonDict, Requester, StateMap
 from synapse.util import Clock
 from synapse.util.frozenutils import unfreeze
 
 from tests import unittest
+from tests.server import make_request
 
 if TYPE_CHECKING:
     from synapse.module_api import ModuleApi
@@ -93,11 +95,33 @@ async def check_event_allowed(
         return d
 
 
+class OnUpgradeRoomModule:
+    def __init__(self, config: Dict, module_api: "ModuleApi") -> None:
+        self.allowed_room_versions: List[str] = []
+        if allowed_room_ver_from_config := config.get("allowed_room_versions"):
+            self.allowed_room_versions = allowed_room_ver_from_config
+
+        module_api.register_third_party_rules_callbacks(
+            on_upgrade_room=self.on_upgrade_room
+        )
+
+    async def on_upgrade_room(
+        self, requester: Requester, room_version: RoomVersion
+    ) -> None:
+        if room_version.identifier not in self.allowed_room_versions:
+            raise SynapseError(
+                400,
+                "You can not upgrade room to that version",
+                Codes.UNSUPPORTED_ROOM_VERSION,
+            )
+
+
 class ThirdPartyRulesTestCase(unittest.FederatingHomeserverTestCase):
     servlets = [
         admin.register_servlets,
         login.register_servlets,
         room.register_servlets,
+        room_upgrade_rest_servlet.register_servlets,
         profile.register_servlets,
         account.register_servlets,
     ]
@@ -426,6 +450,66 @@ def test_legacy_on_create_room(self) -> None:
         """
         self.helper.create_room_as(self.user_id, tok=self.tok, expect_code=403)
 
+    @unittest.override_config(
+        {
+            "third_party_event_rules": {
+                "module": __name__ + ".OnUpgradeRoomModule",
+                "config": {
+                    "allowed_room_versions": ["9", "10"],
+                },
+            }
+        }
+    )
+    def test_on_upgrade_room(self) -> None:
+        """Tests that the on_upgrade_room callbacks works correctly."""
+
+        def upgrade_room_to_version(
+            _room_id: str,
+            room_version: str,
+            tok: Optional[str] = None,
+            expect_code: int = HTTPStatus.OK,
+        ) -> Optional[str]:
+            """
+            Upgrade a room.
+
+            Args:
+                _room_id
+                room_version: The room version to upgrade the room to.
+                tok: The access token to use in the request.
+                expect_code: The expected HTTP response code.
+            Returns:
+                The ID of the newly created room, or None if the request failed.
+            """
+            path = f"/_matrix/client/r0/rooms/{_room_id}/upgrade"
+            content = {"new_version": room_version}
+
+            channel = make_request(
+                self.reactor,
+                self.site,
+                "POST",
+                path,
+                content,
+                access_token=tok,
+            )
+
+            assert channel.code == expect_code, channel.result
+
+            if expect_code == HTTPStatus.OK:
+                return channel.json_body["replacement_room"]
+            else:
+                return None
+
+        # Room in configured list
+        room_id_1 = self.helper.create_room_as(
+            self.user_id, room_version="9", tok=self.tok
+        )
+        upgrade_room_to_version(room_id_1, "10", tok=self.tok, expect_code=200)
+        # Room not in configured list
+        room_id_2 = self.helper.create_room_as(
+            self.user_id, room_version="10", tok=self.tok
+        )
+        upgrade_room_to_version(room_id_2, "11", tok=self.tok, expect_code=400)
+
     def test_sent_event_end_up_in_room_state(self) -> None:
         """Tests that a state event sent by a module while processing another state event
         doesn't get dropped from the state of the room. This is to guard against a bug