+ +

Modules

Synapse supports extending its functionality by configuring external modules.

Using modules

To use a module on Synapse, add it to the modules section of the configuration file:

modules:
+  - module: my_super_module.MySuperClass
+    config:
+      do_thing: true
+  - module: my_other_super_module.SomeClass
+    config: {}
+

Each module is defined by a path to a Python class as well as a configuration. This +information for a given module should be available in the module's own documentation.

Note: When using third-party modules, you effectively allow someone else to run +custom code on your Synapse homeserver. Server admins are encouraged to verify the +provenance of the modules they use on their homeserver and make sure the modules aren't +running malicious code on their instance.

Also note that we are currently in the process of migrating module interfaces to this +system. While some interfaces might be compatible with it, others still require +configuring modules in another part of Synapse's configuration file. Currently, only the +spam checker interface is compatible with this new system.

Writing a module

A module is a Python class that uses Synapse's module API to interact with the +homeserver. It can register callbacks that Synapse will call on specific operations, as +well as web resources to attach to Synapse's web server.

When instantiated, a module is given its parsed configuration as well as an instance of +the synapse.module_api.ModuleApi class. The configuration is a dictionary, and is +either the output of the module's parse_config static method (see below), or the +configuration associated with the module in Synapse's configuration file.

See the documentation for the ModuleApi class +here.

Handling the module's configuration

A module can implement the following static method:

@staticmethod
+def parse_config(config: dict) -> dict
+

This method is given a dictionary resulting from parsing the YAML configuration for the +module. It may modify it (for example by parsing durations expressed as strings (e.g. +"5d") into milliseconds, etc.), and return the modified dictionary. It may also verify +that the configuration is correct, and raise an instance of +synapse.module_api.errors.ConfigError if not.

Registering a web resource

Modules can register web resources onto Synapse's web server using the following module +API method:

def ModuleApi.register_web_resource(path: str, resource: IResource)
+

The path is the full absolute path to register the resource at. For example, if you +register a resource for the path /_synapse/client/my_super_module/say_hello, Synapse +will serve it at http(s)://[HS_URL]/_synapse/client/my_super_module/say_hello. Note +that Synapse does not allow registering resources for several sub-paths in the /_matrix +namespace (such as anything under /_matrix/client for example). It is strongly +recommended that modules register their web resources under the /_synapse/client +namespace.

The provided resource is a Python class that implements Twisted's IResource +interface (such as Resource).

Only one resource can be registered for a given path. If several modules attempt to +register a resource for the same path, the module that appears first in Synapse's +configuration file takes priority.

Modules must register their web resources in their __init__ method.

Registering a callback

Modules can use Synapse's module API to register callbacks. Callbacks are functions that +Synapse will call when performing specific actions. Callbacks must be asynchronous, and +are split in categories. A single module may implement callbacks from multiple categories, +and is under no obligation to implement all callbacks from the categories it registers +callbacks for.

Spam checker callbacks

To register one of the callbacks described in this section, a module needs to use the +module API's register_spam_checker_callbacks method. The callback functions are passed +to register_spam_checker_callbacks as keyword arguments, with the callback name as the +argument name and the function as its value. This is demonstrated in the example below.

The available spam checker callbacks are:

def check_event_for_spam(event: "synapse.events.EventBase") -> Union[bool, str]
+

Called when receiving an event from a client or via federation. The module can return +either a bool to indicate whether the event must be rejected because of spam, or a str +to indicate the event must be rejected because of spam and to give a rejection reason to +forward to clients.

def user_may_invite(inviter: str, invitee: str, room_id: str) -> bool
+

Called when processing an invitation. The module must return a bool indicating whether +the inviter can invite the invitee to the given room. Both inviter and invitee are +represented by their Matrix user ID (i.e. @alice:example.com).

def user_may_create_room(user: str) -> bool
+

Called when processing a room creation request. The module must return a bool indicating +whether the given user (represented by their Matrix user ID) is allowed to create a room.

def user_may_create_room_alias(user: str, room_alias: "synapse.types.RoomAlias") -> bool
+

Called when trying to associate an alias with an existing room. The module must return a +bool indicating whether the given user (represented by their Matrix user ID) is allowed +to set the given alias.

def user_may_publish_room(user: str, room_id: str) -> bool
+

Called when trying to publish a room to the homeserver's public rooms directory. The +module must return a bool indicating whether the given user (represented by their +Matrix user ID) is allowed to publish the given room.

def check_username_for_spam(user_profile: Dict[str, str]) -> bool
+

Called when computing search results in the user directory. The module must return a +bool indicating whether the given user profile can appear in search results. The profile +is represented as a dictionary with the following keys:

user_id: The Matrix ID for this user.
display_name: The user's display name.
avatar_url: The mxc:// URL to the user's avatar.

The module is given a copy of the original dictionary, so modifying it from within the +module cannot modify a user's profile when included in user directory search results.

def check_registration_for_spam(
+    email_threepid: Optional[dict],
+    username: Optional[str],
+    request_info: Collection[Tuple[str, str]],
+    auth_provider_id: Optional[str] = None,
+) -> "synapse.spam_checker_api.RegistrationBehaviour"
+

Called when registering a new user. The module must return a RegistrationBehaviour +indicating whether the registration can go through or must be denied, or whether the user +may be allowed to register but will be shadow banned.

The arguments passed to this callback are:

email_threepid: The email address used for registering, if any.
username: The username the user would like to register. Can be None, meaning that +Synapse will generate one later.
request_info: A collection of tuples, which first item is a user agent, and which +second item is an IP address. These user agents and IP addresses are the ones that were +used during the registration process.
auth_provider_id: The identifier of the SSO authentication provider, if any.

def check_media_file_for_spam(
+    file_wrapper: "synapse.rest.media.v1.media_storage.ReadableFileWrapper",
+    file_info: "synapse.rest.media.v1._base.FileInfo"
+) -> bool
+

Called when storing a local or remote file. The module must return a boolean indicating +whether the given file can be stored in the homeserver's media store.

Porting an existing module that uses the old interface

In order to port a module that uses Synapse's old module interface, its author needs to:

ensure the module's callbacks are all asynchronous.
register their callbacks using one or more of the register_[...]_callbacks methods +from the ModuleApi class in the module's __init__ method (see this section +for more info).

Additionally, if the module is packaged with an additional web resource, the module +should register this resource in its __init__ method using the register_web_resource +method from the ModuleApi class (see this section for +more info).

The module's author should also update any example in the module's configuration to only +use the new modules section in Synapse's configuration file (see this section +for more info).

Example

The example below is a module that implements the spam checker callback +user_may_create_room to deny room creation to user @evilguy:example.com, and registers +a web resource to the path /_synapse/client/demo/hello that returns a JSON object.

import json
+
+from twisted.web.resource import Resource
+from twisted.web.server import Request
+
+from synapse.module_api import ModuleApi
+
+
+class DemoResource(Resource):
+    def __init__(self, config):
+        super(DemoResource, self).__init__()
+        self.config = config
+
+    def render_GET(self, request: Request):
+        name = request.args.get(b"name")[0]
+        request.setHeader(b"Content-Type", b"application/json")
+        return json.dumps({"hello": name})
+
+
+class DemoModule:
+    def __init__(self, config: dict, api: ModuleApi):
+        self.config = config
+        self.api = api
+
+        self.api.register_web_resource(
+            path="/_synapse/client/demo/hello",
+            resource=DemoResource(self.config),
+        )
+
+        self.api.register_spam_checker_callbacks(
+            user_may_create_room=self.user_may_create_room,
+        )
+
+    @staticmethod
+    def parse_config(config):
+        return config
+
+    async def user_may_create_room(self, user: str) -> bool:
+        if user == "@evilguy:example.com":
+            return False
+
+        return True
+

+ +