From 73182ee518b001a45f7400c3e3fb2c918d42812e Mon Sep 17 00:00:00 2001 From: babolivier Date: Fri, 16 Jul 2021 16:12:31 +0000 Subject: [PATCH] deploy: 36dc15412de9fc1bb2ba955c8b6f2da20d2ca20f --- develop/modules.html | 36 +++++- develop/print.html | 121 +++++------------- develop/sample_config.yaml | 85 ------------ develop/searchindex.js | 2 +- develop/searchindex.json | 2 +- .../homeserver_sample_config.html | 85 ------------ 6 files changed, 62 insertions(+), 269 deletions(-) diff --git a/develop/modules.html b/develop/modules.html index 06a41d1e7c..7e6d945894 100644 --- a/develop/modules.html +++ b/develop/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 @@ -317,6 +321,26 @@ used during the registration process.

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.

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: