synapse/docs/modules.md

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) -> None

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.

Modules can register callbacks using one of the module API's register_[...]_callbacks methods. The callback functions are passed to these methods as keyword arguments, with the callback name as the argument name and the function as its value. This is demonstrated in the example below. A register_[...]_callbacks method exists for each module type documented in this section.

Spam checker callbacks

Spam checker callbacks allow module developers to implement spam mitigation actions for Synapse instances. Spam checker callbacks can be registered using the module API's register_spam_checker_callbacks method.

The available spam checker callbacks are:

async 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.

async 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 (e.g. @alice:example.com).

async 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.

async 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.

async 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.

async 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.

async 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.

async 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.

Account validity callbacks

Account validity callbacks allow module developers to add extra steps to verify the validity on an account, i.e. see if a user can be granted access to their account on the Synapse instance. Account validity callbacks can be registered using the module API's register_account_validity_callbacks method.

The available account validity callbacks are:

async def is_user_expired(user: str) -> Optional[bool]

Called when processing any authenticated request (except for logout requests). The module can return a bool to indicate whether the user has expired and should be locked out of their account, or None if the module wasn't able to figure it out. The user is represented by their Matrix user ID (e.g. @alice:example.com).

If the module returns True, the current request will be denied with the error code ORG_MATRIX_EXPIRED_ACCOUNT and the HTTP status code 403. Note that this doesn't invalidate the user's access token.

async def on_user_registration(user: str) -> None

Called after successfully registering a user, in case the module needs to perform extra operations to keep track of them. (e.g. add them to a database table). The user is represented by their Matrix user ID.

Third party rules callbacks

Third party rules callbacks allow module developers to add extra checks to verify the validity of incoming events. Third party event rules callbacks can be registered using the module API's register_third_party_rules_callbacks method.

The available third party rules callbacks are:

async def check_event_allowed(
    event: "synapse.events.EventBase",
    state_events: "synapse.types.StateMap",
) -> Tuple[bool, Optional[dict]]

This callback is very experimental and can and will break without notice. Module developers are encouraged to implement check_event_for_spam from the spam checker category instead.

Called when processing any incoming event, with the event and a StateMap representing the current state of the room the event is being sent into. A StateMap is a dictionary that maps tuples containing an event type and a state key to the corresponding state event. For example retrieving the room's m.room.create event from the state_events argument would look like this: state_events.get(("m.room.create", "")). The module must return a boolean indicating whether the event can be allowed.

Note that this callback function processes incoming events coming via federation traffic (on top of client traffic). This means denying an event might cause the local copy of the room's history to diverge from that of remote servers. This may cause federation issues in the room. It is strongly recommended to only deny events using this callback function if the sender is a local user, or in a private federation in which all servers are using the same module, with the same configuration.

If the boolean returned by the module is True, it may also tell Synapse to replace the event with new data by returning the new event's data as a dictionary. In order to do that, it is recommended the module calls event.get_dict() to get the current event as a dictionary, and modify the returned dictionary accordingly.

Note that replacing the event only works for events sent by local users, not for events received over federation.

async def on_create_room(
    requester: "synapse.types.Requester",
    request_content: dict,
    is_requester_admin: bool,
) -> None

Called when processing a room creation request, with the Requester object for the user performing the request, a dictionary representing the room creation request's JSON body (see the spec for a list of possible parameters), and a boolean indicating whether the user performing the request is a server admin.

Modules can modify the request_content (by e.g. adding events to its initial_state), or deny the room's creation by raising a module_api.errors.SynapseError.

Presence router callbacks

Presence router callbacks allow module developers to specify additional users (local or remote) to receive certain presence updates from local users. Presence router callbacks can be registered using the module API's register_presence_router_callbacks method.

The available presence router callbacks are:

async def get_users_for_states(
    self,
    state_updates: Iterable["synapse.api.UserPresenceState"],
) -> Dict[str, Set["synapse.api.UserPresenceState"]]:

Requires get_interested_users to also be registered

Called when processing updates to the presence state of one or more users. This callback can be used to instruct the server to forward that presence state to specific users. The module must return a dictionary that maps from Matrix user IDs (which can be local or remote) to the UserPresenceState changes that they should be forwarded.

Synapse will then attempt to send the specified presence updates to each user when possible.

async def get_interested_users(
        self, 
        user_id: str
) -> Union[Set[str], "synapse.module_api.PRESENCE_ALL_USERS"]

Requires get_users_for_states to also be registered

Called when determining which users someone should be able to see the presence state of. This callback should return complementary results to get_users_for_state or the presence information may not be properly forwarded.

The callback is given the Matrix user ID for a local user that is requesting presence data and should return the Matrix user IDs of the users whose presence state they are allowed to query. The returned users can be local or remote.

Alternatively the callback can return synapse.module_api.PRESENCE_ALL_USERS to indicate that the user should receive updates from all known users.

For example, if the user @alice:example.org is passed to this method, and the Set {"@bob:example.com", "@charlie:somewhere.org"} is returned, this signifies that Alice should receive presence updates sent by Bob and Charlie, regardless of whether these users share a room.

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