From 73984a10b1cd9a7d8b4eb622563242ef00024c88 Mon Sep 17 00:00:00 2001 From: babolivier Date: Tue, 20 Jul 2021 10:49:48 +0000 Subject: [PATCH] deploy: a743bf46949e851c9a10d8e01a138659f3af2484 --- develop/modules.html | 47 ++++++++++++- develop/print.html | 68 +++++++++++++++---- develop/sample_config.yaml | 13 ---- develop/searchindex.js | 2 +- develop/searchindex.json | 2 +- develop/upgrade.html | 8 +++ .../homeserver_sample_config.html | 13 ---- 7 files changed, 110 insertions(+), 43 deletions(-) diff --git a/develop/modules.html b/develop/modules.html index 7e6d945894..08a829b351 100644 --- a/develop/modules.html +++ b/develop/modules.html @@ -316,7 +316,7 @@ 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 @@ -341,6 +341,51 @@ invalidate the user's access token.

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:

+

Upgrading to v1.39.0

+

Deprecation of the current third-party rules module interface

+

The current third-party rules module interface is deprecated in favour of the new generic +modules system introduced in Synapse v1.37.0. Authors of third-party rules modules can refer +to this documentation +to update their modules. Synapse administrators can refer to this documentation +to update their configuration once the modules they are using have been updated.

+

We plan to remove support for the current third-party rules interface in September 2021.

Upgrading to v1.38.0

Re-indexing of events table on Postgres databases

This release includes a database schema update which requires re-indexing one of @@ -5516,19 +5524,6 @@ stats: # action: allow -# Server admins can define a Python module that implements extra rules for -# allowing or denying incoming events. In order to work, this module needs to -# override the methods defined in synapse/events/third_party_rules.py. -# -# This feature is designed to be used in closed federations only, where each -# participating server enforces the same rules. -# -#third_party_event_rules: -# module: "my_custom_project.SuperRulesSet" -# config: -# example_option: 'things' - - ## Opentracing ## # These settings enable opentracing, which implements distributed tracing. @@ -7397,7 +7392,7 @@ 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 @@ -7422,6 +7417,51 @@ invalidate the user's access token.

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:

+

Upgrading to v1.39.0

+

Deprecation of the current third-party rules module interface

+

The current third-party rules module interface is deprecated in favour of the new generic +modules system introduced in Synapse v1.37.0. Authors of third-party rules modules can refer +to this documentation +to update their modules. Synapse administrators can refer to this documentation +to update their configuration once the modules they are using have been updated.

+

We plan to remove support for the current third-party rules interface in September 2021.

Upgrading to v1.38.0

Re-indexing of events table on Postgres databases

This release includes a database schema update which requires re-indexing one of diff --git a/develop/usage/configuration/homeserver_sample_config.html b/develop/usage/configuration/homeserver_sample_config.html index d303daa415..a985897f35 100644 --- a/develop/usage/configuration/homeserver_sample_config.html +++ b/develop/usage/configuration/homeserver_sample_config.html @@ -2846,19 +2846,6 @@ stats: # action: allow -# Server admins can define a Python module that implements extra rules for -# allowing or denying incoming events. In order to work, this module needs to -# override the methods defined in synapse/events/third_party_rules.py. -# -# This feature is designed to be used in closed federations only, where each -# participating server enforces the same rules. -# -#third_party_event_rules: -# module: "my_custom_project.SuperRulesSet" -# config: -# example_option: 'things' - - ## Opentracing ## # These settings enable opentracing, which implements distributed tracing.