Add a new public rooms callback class, a new fetch_public_rooms callback

fetch_public_rooms is a module API callback intended to be used when a
request for the homeserver's public rooms list comes in via either the
CS or SS API. Modules can return an ordered array of public rooms that
they would like to inject into the list supplied by the homeserver.

This can be useful for exposing known rooms that users on the
homeserver have not joined yet, and the property of mixing with the
normal public rooms list is desirable versus the solution of creating
a new third-party network type to load your rooms under.

synapse/module_api/__init__.py

@@ -91,6 +91,10 @@ from synapse.module_api.callbacks.account_validity_callbacks import (
     ON_LEGACY_SEND_MAIL_CALLBACK,
     ON_USER_REGISTRATION_CALLBACK,
 )
+from synapse.module_api.callbacks.public_rooms_callbacks import (
+    FETCH_PUBLIC_ROOMS_CALLBACK,
+    PublicRoomChunk,
+)
 from synapse.module_api.callbacks.spamchecker_callbacks import (
     CHECK_EVENT_FOR_SPAM_CALLBACK,
     CHECK_MEDIA_FILE_FOR_SPAM_CALLBACK,
@@ -165,6 +169,7 @@ __all__ = [
     "DirectServeJsonResource",
     "ModuleApi",
     "PRESENCE_ALL_USERS",
+    "PublicRoomChunk",
     "LoginResponse",
     "JsonDict",
     "JsonMapping",
@@ -462,6 +467,19 @@ class ModuleApi:
             on_account_data_updated=on_account_data_updated,
         )
 
+    def register_public_rooms_callbacks(
+        self,
+        *,
+        fetch_public_rooms: Optional[FETCH_PUBLIC_ROOMS_CALLBACK] = None,
+    ) -> None:
+        """Registers callback functions related to the public room directory.
+
+        Added in Synapse v1.80.0
+        """
+        return self._callbacks.public_rooms.register_callbacks(
+            fetch_public_rooms=fetch_public_rooms,
+        )
+
     def register_web_resource(self, path: str, resource: Resource) -> None:
         """Registers a web resource to be served at the given path.
 

synapse/module_api/callbacks/__init__.py

@@ -24,8 +24,11 @@ from synapse.module_api.callbacks.spamchecker_callbacks import (
     SpamCheckerModuleApiCallbacks,
 )
 
+from .public_rooms_callbacks import PublicRoomsModuleApiCallbacks
+
 
 class ModuleApiCallbacks:
     def __init__(self, hs: "HomeServer") -> None:
         self.account_validity = AccountValidityModuleApiCallbacks()
         self.spam_checker = SpamCheckerModuleApiCallbacks(hs)
+        self.public_rooms = PublicRoomsModuleApiCallbacks()

synapse/module_api/callbacks/public_rooms_callbacks.py

@@ -0,0 +1,53 @@
+# Copyright 2023 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+from typing import Awaitable, Callable, Iterable, List, Optional, Tuple
+
+import attr
+
+logger = logging.getLogger(__name__)
+
+
+@attr.s(auto_attribs=True)
+class PublicRoomChunk:
+    room_id: str
+    name: str
+    topic: str
+    num_joined_members: int
+    canonical_alias: str
+    avatar_url: str
+    world_readable: bool
+    guest_can_join: bool
+    join_rule: str
+    room_type: str
+
+
+# Types for callbacks to be registered via the module api
+FETCH_PUBLIC_ROOMS_CALLBACK = Callable[
+    [int, Optional[int], Optional[dict], Optional[str], Optional[str]],
+    Awaitable[Tuple[Iterable[PublicRoomChunk], bool]],
+]
+
+
+class PublicRoomsModuleApiCallbacks:
+    def __init__(self) -> None:
+        self.fetch_public_rooms_callbacks: List[FETCH_PUBLIC_ROOMS_CALLBACK] = []
+
+    def register_callbacks(
+        self,
+        fetch_public_rooms: Optional[FETCH_PUBLIC_ROOMS_CALLBACK] = None,
+    ) -> None:
+        if fetch_public_rooms is not None:
+            self.fetch_public_rooms_callbacks.append(fetch_public_rooms)