synapse/docs/modules/writing_a_module.md

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

Callbacks for each category can be found on their respective page of the Synapse documentation website.