From 9f273f34d4ac64ef9d47721b04187ed273fc998d Mon Sep 17 00:00:00 2001 From: erikjohnston Date: Thu, 29 Jul 2021 10:09:19 +0000 Subject: deploy: c36c2777900284cf94e93e60e34c3b856bb31551 --- latest/modules.html | 83 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 76 insertions(+), 7 deletions(-) (limited to 'latest/modules.html') diff --git a/latest/modules.html b/latest/modules.html index 06a41d1e7c..08a829b351 100644 --- a/latest/modules.html +++ b/latest/modules.html @@ -226,7 +226,7 @@ that the configuration is correct, and raise an instance of

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)
+
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
@@ -247,11 +247,15 @@ Synapse will call when performing specific actions. Callbacks must be asynchrono
 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

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

+
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]
 

@@ -263,7 +267,7 @@ forward to clients.

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

+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 @@ -312,11 +316,76 @@ used during the registration process. 

async def check_media_file_for_spam(
     file_wrapper: "synapse.rest.media.v1.media_storage.ReadableFileWrapper",
-    file_info: "synapse.rest.media.v1._base.FileInfo"
+    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.

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: