From 74b65bfc5f3c58005e3892b314e73cfde32355f6 Mon Sep 17 00:00:00 2001 From: erikjohnston Date: Tue, 2 Nov 2021 14:27:50 +0000 Subject: deploy: 2d44ee6868805d4ff23489a8dd6b4072ff358663 --- latest/print.html | 514 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 391 insertions(+), 123 deletions(-) (limited to 'latest/print.html') diff --git a/latest/print.html b/latest/print.html index 0970b4bafd..982a0caad3 100644 --- a/latest/print.html +++ b/latest/print.html @@ -101,7 +101,7 @@ @@ -1647,8 +1647,8 @@ of this endpoint modifying the media store.

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

@@ -1678,9 +1678,9 @@ particular server:

Upgrading to v1.37.0

Deprecation of the current spam checker interface

The current spam checker interface is deprecated in favour of a new generic modules system. -Authors of spam checker modules can refer to this -documentation -to update their modules. Synapse administrators can refer to this +Authors of spam checker modules can refer to [this +documentation](modules/porting_legacy_module.md +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 spam checker interface in August 2021.

@@ -1758,20 +1758,20 @@ Synapse v1.30.0.

Upgrading to v1.29.0

Requirement for X-Forwarded-Proto header

When using Synapse with a reverse proxy (in particular, when using the -[x_forwarded]{.title-ref} option on an HTTP listener), Synapse now -expects to receive an [X-Forwarded-Proto]{.title-ref} header on incoming +x_forwarded option on an HTTP listener), Synapse now +expects to receive an X-Forwarded-Proto header on incoming HTTP requests. If it is not set, Synapse will log a warning on each received request.

To avoid the warning, administrators using a reverse proxy should ensure -that the reverse proxy sets [X-Forwarded-Proto]{.title-ref} header to -[https]{.title-ref} or [http]{.title-ref} to indicate the protocol used +that the reverse proxy sets X-Forwarded-Proto header to +https or http to indicate the protocol used by the client.

-

Synapse also requires the [Host]{.title-ref} header to be preserved.

+

Synapse also requires the Host header to be preserved.

See the reverse proxy documentation, where the example configurations have been updated to show how to set these headers.

(Users of Caddy are unaffected, since we -believe it sets [X-Forwarded-Proto]{.title-ref} by default.)

+believe it sets X-Forwarded-Proto by default.)

Upgrading to v1.27.0

Changes to callback URI for OAuth2 / OpenID Connect and SAML2

This version changes the URI used for callbacks from OAuth2 and SAML2 @@ -1909,13 +1909,13 @@ mapping provider to specify different algorithms, instead of the default way.

If your Synapse configuration uses a custom mapping provider -([oidc_config.user_mapping_provider.module]{.title-ref} is specified and +(oidc_config.user_mapping_provider.module is specified and not equal to -[synapse.handlers.oidc_handler.JinjaOidcMappingProvider]{.title-ref}) -then you must ensure that [map_user_attributes]{.title-ref} of the +synapse.handlers.oidc_handler.JinjaOidcMappingProvider) +then you must ensure that map_user_attributes of the mapping provider performs some normalisation of the -[localpart]{.title-ref} returned. To match previous behaviour you can -use the [map_username_to_mxid_localpart]{.title-ref} function provided +localpart returned. To match previous behaviour you can +use the map_username_to_mxid_localpart function provided by Synapse. An example is shown below:

from synapse.types import map_username_to_mxid_localpart
 
@@ -1940,7 +1940,7 @@ v1.24.0. The Admin API is now only accessible under:

 
    
 
  • /_synapse/admin/v1
    • 
 

-
The only exception is the [/admin/whois]{.title-ref} endpoint, which is
+
The only exception is the /admin/whois endpoint, which is
 also available via the client-server
 API.

 
The deprecation of the old endpoints was announced with Synapse 1.20.0
@@ -1994,7 +1994,7 @@ used if a custom template cannot be found.

 
This page will appear to the user after clicking a password reset link
 that has been emailed to them.

 
To complete password reset, the page must include a way to make a
-[POST]{.title-ref} request to
+POST request to
 /_synapse/client/password_reset/{medium}/submit_token with the query
 parameters from the original link, presented as a URL-encoded form. See
 the file itself for more details.

@@ -2012,15 +2012,15 @@ but the parameters are slightly different:

 of why a user is seeing the error page.
 
 
Upgrading to v1.18.0

-
Docker [-py3]{.title-ref} suffix will be removed in future versions

+
Docker -py3 suffix will be removed in future versions

 
From 10th August 2020, we will no longer publish Docker images with the
-[-py3]{.title-ref} tag suffix. The images tagged with the
-[-py3]{.title-ref} suffix have been identical to the non-suffixed tags
+-py3 tag suffix. The images tagged with the
+-py3 suffix have been identical to the non-suffixed tags
 since release 0.99.0, and the suffix is obsolete.

-
On 10th August, we will remove the [latest-py3]{.title-ref} tag.
-Existing per-release tags (such as [v1.18.0-py3]{.title-ref}) will not
-be removed, but no new [-py3]{.title-ref} tags will be added.

-
Scripts relying on the [-py3]{.title-ref} suffix will need to be
+
On 10th August, we will remove the latest-py3 tag.
+Existing per-release tags (such as v1.18.0-py3 will not
+be removed, but no new -py3 tags will be added.

+
Scripts relying on the -py3 suffix will need to be
 updated.

 
 
When setting up worker processes, we now recommend the use of a Redis
@@ -2045,8 +2045,8 @@ from v1.2.1 or earlier, to versions between v1.4.0 and v1.12.x.

 are affected can be repaired as follows:

 
    
 
  1. 
-
    Run the following sql from a [psql]{.title-ref} or
-[sqlite3]{.title-ref} console:
    
+
    Run the following sql from a psql or
+sqlite3 console:
    
 
    INSERT INTO background_updates (update_name, progress_json, depends_on) VALUES
    ('populate_stats_process_rooms', '{}', 'current_state_events_membership');
 
@@ -2107,8 +2107,8 @@ of any problems.
    
 
    2. 
 
  2. 
 
    As an initial check to see if you will be affected, you can try
-running the following query from the [psql]{.title-ref} or
-[sqlite3]{.title-ref} console. It is safe to run it while Synapse is
+running the following query from the psql or
+sqlite3 console. It is safe to run it while Synapse is
 still running.
    
 
    SELECT MAX(q.v) FROM (
   SELECT (
@@ -2586,9 +2586,9 @@ used on mobile devices).
    
 first need to upgrade the database by running:
    
 
    python scripts/upgrade_db_to_v0.6.0.py <db> <server_name> <signing_key>
 
    
-
    Where []{.title-ref} is the location of the database,
-[<server_name>]{.title-ref} is the server name as specified in the
-synapse configuration, and [<signing_key>]{.title-ref} is the location
+
    Where <db> is the location of the database,
+<server_name> is the server name as specified in the
+synapse configuration, and <signing_key> is the location
 of the signing key as specified in the synapse configuration.
    
 
    This may take some time to complete. Failures of signatures and content
 hashes can safely be ignored.
    
@@ -3511,6 +3511,48 @@ limit_remote_rooms:
 #
 #user_ips_max_age: 14d
 
+# Inhibits the /requestToken endpoints from returning an error that might leak
+# information about whether an e-mail address is in use or not on this
+# homeserver.
+# Note that for some endpoints the error situation is the e-mail already being
+# used, and for others the error is entering the e-mail being unused.
+# If this option is enabled, instead of returning an error, these endpoints will
+# act as if no error happened and return a fake session ID ('sid') to clients.
+#
+#request_token_inhibit_3pid_errors: true
+
+# A list of domains that the domain portion of 'next_link' parameters
+# must match.
+#
+# This parameter is optionally provided by clients while requesting
+# validation of an email or phone number, and maps to a link that
+# users will be automatically redirected to after validation
+# succeeds. Clients can make use this parameter to aid the validation
+# process.
+#
+# The whitelist is applied whether the homeserver or an
+# identity server is handling validation.
+#
+# The default value is no whitelist functionality; all domains are
+# allowed. Setting this value to an empty list will instead disallow
+# all domains.
+#
+#next_link_domain_whitelist: ["matrix.org"]
+
+# Templates to use when generating email or HTML page contents.
+#
+templates:
+  # Directory in which Synapse will try to find template files to use to generate
+  # email or HTML page contents.
+  # If not set, or a file is not found within the template directory, a default
+  # template from within the Synapse package will be used.
+  #
+  # See https://matrix-org.github.io/synapse/latest/templates.html for more
+  # information about using custom templates.
+  #
+  #custom_template_directory: /path/to/custom/templates/
+
+
 # Message retention policy at the server level.
 #
 # Room admins and mods can define a retention period for their rooms using the
@@ -3580,47 +3622,6 @@ retention:
   #  - shortest_max_lifetime: 3d
   #    interval: 1d
 
-# Inhibits the /requestToken endpoints from returning an error that might leak
-# information about whether an e-mail address is in use or not on this
-# homeserver.
-# Note that for some endpoints the error situation is the e-mail already being
-# used, and for others the error is entering the e-mail being unused.
-# If this option is enabled, instead of returning an error, these endpoints will
-# act as if no error happened and return a fake session ID ('sid') to clients.
-#
-#request_token_inhibit_3pid_errors: true
-
-# A list of domains that the domain portion of 'next_link' parameters
-# must match.
-#
-# This parameter is optionally provided by clients while requesting
-# validation of an email or phone number, and maps to a link that
-# users will be automatically redirected to after validation
-# succeeds. Clients can make use this parameter to aid the validation
-# process.
-#
-# The whitelist is applied whether the homeserver or an
-# identity server is handling validation.
-#
-# The default value is no whitelist functionality; all domains are
-# allowed. Setting this value to an empty list will instead disallow
-# all domains.
-#
-#next_link_domain_whitelist: ["matrix.org"]
-
-# Templates to use when generating email or HTML page contents.
-#
-templates:
-  # Directory in which Synapse will try to find template files to use to generate
-  # email or HTML page contents.
-  # If not set, or a file is not found within the template directory, a default
-  # template from within the Synapse package will be used.
-  #
-  # See https://matrix-org.github.io/synapse/latest/templates.html for more
-  # information about using custom templates.
-  #
-  #custom_template_directory: /path/to/custom/templates/
-
 
 ## TLS ##
 
@@ -5299,34 +5300,6 @@ email:
     #email_validation: "[%(server_name)s] Validate your email"
 
 
-# Password providers allow homeserver administrators to integrate
-# their Synapse installation with existing authentication methods
-# ex. LDAP, external tokens, etc.
-#
-# For more information and known implementations, please see
-# https://matrix-org.github.io/synapse/latest/password_auth_providers.html
-#
-# Note: instances wishing to use SAML or CAS authentication should
-# instead use the `saml2_config` or `cas_config` options,
-# respectively.
-#
-password_providers:
-#    # Example config for an LDAP auth provider
-#    - module: "ldap_auth_provider.LdapAuthProvider"
-#      config:
-#        enabled: true
-#        uri: "ldap://ldap.example.com:389"
-#        start_tls: true
-#        base: "ou=users,dc=example,dc=com"
-#        attributes:
-#           uid: "cn"
-#           mail: "email"
-#           name: "givenName"
-#        #bind_dn:
-#        #bind_password:
-#        #filter: "(objectClass=posixAccount)"
-
-
 
 ## Push ##
 
@@ -5691,11 +5664,11 @@ redis:
 
    Logging Sample Configuration File
    
 
    Below is a sample logging configuration file. This file can be tweaked to control how your
 homeserver will output logs. A restart of the server is generally required to apply any
-changes made to this file.
    
-
    Note that the contents below are not intended to be copied and used as the basis for
-a real homeserver.yaml. Instead, if you are starting from scratch, please generate
-a fresh config using Synapse by following the instructions in
-Installation.
    
+changes made to this file. The value of the log_config option in your homeserver
+config should be the path to this file.
    
+
    Note that a default logging configuration (shown below) is created automatically alongside
+the homeserver config when following the installation instructions.
+It should be named <SERVERNAME>.log.config by default.
    
 
    # Log configuration for Synapse.
 #
 # This is a YAML file containing a standard Python logging configuration
@@ -6903,7 +6876,12 @@ complete registration using methods from the ModuleApi.
    
 
    Synapse has a built-in SAML mapping provider if a custom provider isn't
 specified in the config. It is located at
 synapse.handlers.saml.DefaultSamlMappingProvider.
    
-
    Password auth provider modules
    
+
    
+This page of the Synapse documentation is now deprecated. For up to date
+documentation on setting up or writing a password auth provider module, please see
+this page.
+
    
+
    Password auth provider modules
    
 
    Password auth providers offer a way for server administrators to
 integrate their Synapse installation with an existing authentication
 system.
    
@@ -7656,6 +7634,10 @@ operating system, the server admin needs to run VACUUM FULL; (or
 PostgreSQL documentation).
    
 
    Modules
    
 
    Synapse supports extending its functionality by configuring external modules.
    
+
    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.
    
 
    Using modules
    
 
    To use a module on Synapse, add it to the modules section of the configuration file:
    
 
    modules:
@@ -7667,18 +7649,30 @@ operating system, the server admin needs to run VACUUM FULL; (or
 
    
 
    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.
    
+
    Using multiple modules
    
+
    The order in which modules are listed in this section is important. When processing an
+action that can be handled by several modules, Synapse will always prioritise the module
+that appears first (i.e. is the highest in the list). This means:
    
+
      
+
    • If several modules register the same callback, the callback registered by the module
+that appears first is used.
      • 
+
    • If several modules try to register a handler for the same HTTP path, only the handler
+registered by the module that appears first is used. Handlers registered by the other
+module(s) are ignored and Synapse will log a warning message about them.
      • 
+
    
+
    Note that Synapse doesn't allow multiple modules implementing authentication checkers via
+the password auth provider feature for the same login type with different fields. If this
+happens, Synapse will refuse to start.
    
+
    Current status
    
+
    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 following pre-existing interfaces are compatible with this new system:
    
 
      
 
    • spam checker
      • 
 
    • third-party rules
      • 
 
    • presence router
      • 
+
    • password auth providers
      • 
 
    
 
    Writing a module
    
 
    A module is a Python class that uses Synapse's module API to interact with the
@@ -7690,6 +7684,17 @@ either the output of the module's parse_config static method (see b
 configuration associated with the module in Synapse's configuration file.
    
 
    See the documentation for the ModuleApi class
 here.
    
+
    When Synapse runs with several modules configured
    
+
    If Synapse is running with other modules configured, the order each module appears in
+within the modules section of the Synapse configuration file might restrict what it can
+or cannot register. See this section for more
+information.
    
+
    On top of the rules listed in the link above, if a callback returns a value that should
+cause the current operation to fail (e.g. if a callback checking an event returns with a
+value that should cause the event to be denied), Synapse will fail the operation and
+ignore any subsequent callbacks that should have been run after this one.
    
+
    The documentation for each callback mentions how Synapse behaves when
+multiple modules implement it.
    
 
    Handling the module's configuration
    
 
    A module can implement the following static method:
    
 
    @staticmethod
@@ -7737,13 +7742,19 @@ Synapse instances. Spam checker callbacks can be registered using the module API
 
    Callbacks
    
 
    The available spam checker callbacks are:
    
 
    check_event_for_spam
    
+
    First introduced in Synapse v1.37.0
    
 
    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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns False, Synapse falls through to the next one. The value of the first
+callback that does not return False will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    user_may_join_room
    
+
    First introduced in Synapse v1.37.0
    
 
    async def user_may_join_room(user: str, room: str, is_invited: bool) -> bool
 
    
 
    Called when a user is trying to join a room. The module must return a bool to indicate
@@ -7753,13 +7764,23 @@ whether the user can join the room. The user is represented by their Matrix user
 currently has a pending invite in the room.
    
 
    This callback isn't called if the join is performed by a server administrator, or in the
 context of a room creation.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    user_may_invite
    
+
    First introduced in Synapse v1.37.0
    
 
    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).
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    user_may_send_3pid_invite
    
+
    First introduced in Synapse v1.45.0
    
 
    async def user_may_send_3pid_invite(
     inviter: str,
     medium: str,
@@ -7785,12 +7806,22 @@ for more information regarding third-party identifiers.
    
 
    
 
    Note: If the third-party identifier is already associated with a matrix user ID,
 user_may_invite will be used instead.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    user_may_create_room
    
+
    First introduced in Synapse v1.37.0
    
 
    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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    user_may_create_room_with_invites
    
+
    First introduced in Synapse v1.44.0
    
 
    async def user_may_create_room_with_invites(
     user: str,
     invites: List[str],
@@ -7811,19 +7842,34 @@ corresponding list(s) will be empty.
    
 
    Note: This callback is not called when a room is cloned (e.g. during a room upgrade)
 since no invites are sent when cloning a room. To cover this case, modules also need to
 implement user_may_create_room.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    user_may_create_room_alias
    
+
    First introduced in Synapse v1.37.0
    
 
    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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    user_may_publish_room
    
+
    First introduced in Synapse v1.37.0
    
 
    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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    check_username_for_spam
    
+
    First introduced in Synapse v1.37.0
    
 
    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
@@ -7836,7 +7882,12 @@ is represented as a dictionary with the following keys:
    
 
 
    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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns False, Synapse falls through to the next one. The value of the first
+callback that does not return False will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    check_registration_for_spam
    
+
    First introduced in Synapse v1.37.0
    
 
    async def check_registration_for_spam(
     email_threepid: Optional[dict],
     username: Optional[str],
@@ -7857,7 +7908,13 @@ second item is an IP address. These user agents and IP addresses are the ones th
 used during the registration process.
    3. 
 
  3. auth_provider_id: The identifier of the SSO authentication provider, if any.
    4. 
 
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns RegistrationBehaviour.ALLOW, Synapse falls through to the next one.
+The value of the first callback that does not return RegistrationBehaviour.ALLOW will
+be used. If this happens, Synapse will not call any of the subsequent implementations of
+this callback.
    
 
    check_media_file_for_spam
    
+
    First introduced in Synapse v1.37.0
    
 
    async def check_media_file_for_spam(
     file_wrapper: "synapse.rest.media.v1.media_storage.ReadableFileWrapper",
     file_info: "synapse.rest.media.v1._base.FileInfo",
@@ -7865,6 +7922,10 @@ 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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns False, Synapse falls through to the next one. The value of the first
+callback that does not return False will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    Example
    
 
    The example below is a module that implements the spam checker callback
 check_event_for_spam to deny any message sent by users whose Matrix user IDs are
@@ -7915,6 +7976,7 @@ the module API's register_third_party_rules_callbacks method.
    
 
    Callbacks
    
 
    The available third party rules callbacks are:
    
 
    check_event_allowed
    
+
    First introduced in Synapse v1.39.0
    
 
    async def check_event_allowed(
     event: "synapse.events.EventBase",
     state_events: "synapse.types.StateMap",
@@ -7942,7 +8004,12 @@ that, it is recommended the module calls event.get_dict() to get th
 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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    on_create_room
    
+
    First introduced in Synapse v1.39.0
    
 
    async def on_create_room(
     requester: "synapse.types.Requester",
     request_content: dict,
@@ -7956,7 +8023,13 @@ for a list of possible parameters), and a boolean indicating whether the user pe
 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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns without raising an exception, Synapse falls through to the next one. The
+room creation will be forbidden as soon as one of the callbacks raises an exception. If
+this happens, Synapse will not call any of the subsequent implementations of this
+callback.
    
 
    check_threepid_can_be_invited
    
+
    First introduced in Synapse v1.39.0
    
 
    async def check_threepid_can_be_invited(
     medium: str,
     address: str,
@@ -7965,7 +8038,12 @@ or deny the room's creation by raising a module_api.errors.SynapseError
    
 
    Called when processing an invite via a third-party identifier (i.e. email or phone number).
 The module must return a boolean indicating whether the invite can go through.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    check_visibility_can_be_modified
    
+
    First introduced in Synapse v1.39.0
    
 
    async def check_visibility_can_be_modified(
     room_id: str,
     state_events: "synapse.types.StateMap",
@@ -7975,6 +8053,10 @@ The module must return a boolean indicating whether the invite can go through.Called when changing the visibility of a room in the local public room directory. The
 visibility is a string that's either "public" or "private". The module must return a
 boolean indicating whether the change can go through.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns True, Synapse falls through to the next one. The value of the first
+callback that does not return True will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    Example
    
 
    The example below is a module that implements the third-party rules callback
 check_event_allowed to censor incoming messages as dictated by a third-party service.
    
@@ -8012,6 +8094,7 @@ registered using the module API's register_presence_router_callbacksCallbacks
 
    The available presence router callbacks are:
    
 
    get_users_for_states
    
+
    First introduced in Synapse v1.42.0
    
 
    async def get_users_for_states(
     state_updates: Iterable["synapse.api.UserPresenceState"],
 ) -> Dict[str, Set["synapse.api.UserPresenceState"]]
@@ -8022,7 +8105,11 @@ be used to instruct the server to forward that presence state to specific users.
 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.
    
+
    If multiple modules implement this callback, Synapse merges all the dictionaries returned
+by the callbacks. If multiple callbacks return a dictionary containing the same key,
+Synapse concatenates the sets associated with this key from each dictionary. 
    
 
    get_interested_users
    
+
    First introduced in Synapse v1.42.0
    
 
    async def get_interested_users(
     user_id: str
 ) -> Union[Set[str], "synapse.module_api.PRESENCE_ALL_USERS"]
@@ -8036,6 +8123,11 @@ should return the Matrix user IDs of the users whose presence state they are all
 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.
    
+
    If multiple modules implement this callback, they will be considered in order. Synapse
+calls each callback one by one, and use a concatenation of all the sets returned by the
+callbacks. If one callback returns synapse.module_api.PRESENCE_ALL_USERS, Synapse uses
+this value instead. If this happens, Synapse does not call any of the subsequent
+implementations of this callback.
    
 
    Example
    
 
    The example below is a module that implements both presence router callbacks, and ensures
 that @alice:example.org receives all presence updates from @bob:example.com and
@@ -8084,6 +8176,7 @@ Synapse instance. Account validity callbacks can be registered using the module
 register_account_validity_callbacks method.
    
 
    The available account validity callbacks are:
    
 
    is_user_expired
    
+
    First introduced in Synapse v1.39.0
    
 
    async def is_user_expired(user: str) -> Optional[bool]
 
    
 
    Called when processing any authenticated request (except for logout requests). The module
@@ -8093,12 +8186,169 @@ 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.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns None, Synapse falls through to the next one. The value of the first
+callback that does not return None will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback.
    
 
    on_user_registration
    
+
    First introduced in Synapse v1.39.0
    
 
    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.
    
+
    If multiple modules implement this callback, Synapse runs them all in order.
    
+
    Password auth provider callbacks
    
+
    Password auth providers offer a way for server administrators to integrate
+their Synapse installation with an external authentication system. The callbacks can be
+registered by using the Module API's register_password_auth_provider_callbacks method.
    
+
    Callbacks
    
+
    auth_checkers
    
+
    First introduced in Synapse v1.46.0
    
+
     auth_checkers: Dict[Tuple[str,Tuple], Callable]
+
    
+
    A dict mapping from tuples of a login type identifier (such as m.login.password) and a
+tuple of field names (such as ("password", "secret_thing")) to authentication checking
+callbacks, which should be of the following form:
    
+
    async def check_auth(
+    user: str,
+    login_type: str,
+    login_dict: "synapse.module_api.JsonDict",
+) -> Optional[
+    Tuple[
+        str, 
+        Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]]
+    ]
+]
+
    
+
    The login type and field names should be provided by the user in the
+request to the /login API. The Matrix specification
+defines some types, however user defined ones are also allowed.
    
+
    The callback is passed the user field provided by the client (which might not be in
+@username:server form), the login type, and a dictionary of login secrets passed by
+the client.
    
+
    If the authentication is successful, the module must return the user's Matrix ID (e.g. 
+@alice:example.com) and optionally a callback to be called with the response to the
+/login request. If the module doesn't wish to return a callback, it must return None
+instead.
    
+
    If the authentication is unsuccessful, the module must return None.
    
+
    If multiple modules register an auth checker for the same login type but with different
+fields, Synapse will refuse to start.
    
+
    If multiple modules register an auth checker for the same login type with the same fields,
+then the callbacks will be executed in order, until one returns a Matrix User ID (and
+optionally a callback). In that case, the return value of that callback will be accepted
+and subsequent callbacks will not be fired. If every callback returns None, then the
+authentication fails.
    
+
    check_3pid_auth
    
+
    First introduced in Synapse v1.46.0
    
+
    async def check_3pid_auth(
+    medium: str, 
+    address: str,
+    password: str,
+) -> Optional[
+    Tuple[
+        str, 
+        Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]]
+    ]
+]
+
    
+
    Called when a user attempts to register or log in with a third party identifier,
+such as email. It is passed the medium (eg. email), an address (eg. jdoe@example.com)
+and the user's password.
    
+
    If the authentication is successful, the module must return the user's Matrix ID (e.g. 
+@alice:example.com) and optionally a callback to be called with the response to the /login request.
+If the module doesn't wish to return a callback, it must return None instead.
    
+
    If the authentication is unsuccessful, the module must return None.
    
+
    If multiple modules implement this callback, they will be considered in order. If a
+callback returns None, Synapse falls through to the next one. The value of the first
+callback that does not return None will be used. If this happens, Synapse will not call
+any of the subsequent implementations of this callback. If every callback return None,
+the authentication is denied.
    
+
    on_logged_out
    
+
    First introduced in Synapse v1.46.0
    
+
    async def on_logged_out(
+    user_id: str,
+    device_id: Optional[str],
+    access_token: str
+) -> None
+
    
+
    Called during a logout request for a user. It is passed the qualified user ID, the ID of the
+deactivated device (if any: access tokens are occasionally created without an associated
+device ID), and the (now deactivated) access token.
    
+
    If multiple modules implement this callback, Synapse runs them all in order.
    
+
    Example
    
+
    The example module below implements authentication checkers for two different login types: 
    
+
      
+
    • my.login.type 
+
        
+
      • Expects a my_field field to be sent to /login
        • 
+
      • Is checked by the method: self.check_my_login
        • 
+
      
+
      • 
+
    • m.login.password (defined in the spec)
+
        
+
      • Expects a password field to be sent to /login
        • 
+
      • Is checked by the method: self.check_pass 
        • 
+
      
+
      • 
+
    
+
    from typing import Awaitable, Callable, Optional, Tuple
+
+import synapse
+from synapse import module_api
+
+
+class MyAuthProvider:
+    def __init__(self, config: dict, api: module_api):
+
+        self.api = api
+
+        self.credentials = {
+            "bob": "building",
+            "@scoop:matrix.org": "digging",
+        }
+
+        api.register_password_auth_provider_callbacks(
+            auth_checkers={
+                ("my.login_type", ("my_field",)): self.check_my_login,
+                ("m.login.password", ("password",)): self.check_pass,
+            },
+        )
+
+    async def check_my_login(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "my.login_type":
+            return None
+
+        if self.credentials.get(username) == login_dict.get("my_field"):
+            return self.api.get_qualified_user_id(username)
+
+    async def check_pass(
+        self,
+        username: str,
+        login_type: str,
+        login_dict: "synapse.module_api.JsonDict",
+    ) -> Optional[
+        Tuple[
+            str,
+            Optional[Callable[["synapse.module_api.LoginResponse"], Awaitable[None]]],
+        ]
+    ]:
+        if login_type != "m.login.password":
+            return None
+
+        if self.credentials.get(username) == login_dict.get("password"):
+            return self.api.get_qualified_user_id(username)
+
    
 
    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:
    
 
    
 
    URL Parameters
    
 
      
-
    • unix_timestamp_in_ms: string representing a positive integer - Unix timestamp in ms.
+
    • unix_timestamp_in_ms: string representing a positive integer - Unix timestamp in milliseconds.
 All cached media that was last accessed before this timestamp will be removed.
      • 
 
    
 
    Response:
    
@@ -9358,7 +9610,7 @@ token will be returned as a registration token object in the response body.
    
 
    The request body must be a JSON object and can contain the following fields:
    
 
    
 
    URL parameters:
    
@@ -10312,7 +10565,8 @@ specific user_id.
    
     ],
     "avatar_url": "<avatar_url>",
     "admin": false,
-    "deactivated": false
+    "deactivated": false,
+    "user_type": null
 }
 
    
 
    To use it, you will need to authenticate by providing an access_token for a
@@ -10355,6 +10609,9 @@ in homeserver configuration.
 unchanged on existing accounts and set to false for new accounts.
 A user cannot be erased by deactivating with this API. For details on
 deactivating users see Deactivate Account.
+
  4. user_type - string or null, optional. If provided, the user type will be
+adjusted. If null given, the user type will be cleared. Other 
+allowed options are: bot and support.
    5. 
 
 
    If the user already exists then optional parameters default to the current value.
    
 
    In order to re-activate an account deactivated must be set to false. If
@@ -10542,6 +10799,7 @@ An empty body may be passed for backwards compatibility.
    
 
  5. Remove all 3PIDs from the homeserver
    6. 
 
  6. Delete all devices and E2EE keys
    7. 
 
  7. Delete all access tokens
    8. 
+
  8. Delete all pushers
    9. 
 
  9. Delete the password hash
    10. 
 
  10. Removal from all rooms the user is a member of
    11. 
 
  11. Remove the user from the user directory
    12. 
@@ -10555,6 +10813,16 @@ is set to true:
    
 
  12. Remove the user's avatar URL
    13. 
 
  13. Mark the user as erased
    14. 
 
+
    The following actions are NOT performed. The list may be incomplete.
    
+
      
+
    • Remove mappings of SSO IDs
      • 
+
    • Delete media uploaded by user (included avatar images)
      • 
+
    • Delete sent and received messages
      • 
+
    • Delete E2E cross-signing keys
      • 
+
    • Remove the user's creation (registration) timestamp
      • 
+
    • Remove rate limit overrides
      • 
+
    • Remove from monthly active users
      • 
+
    
 
    Reset password
    
 
    Changes the password of another user. This will automatically log the user out of all their devices.
    
 
    The api is:
    
@@ -12804,7 +13072,7 @@ connection errors.
    
 received for each stream so that on reconneciton it can start streaming
 from the correct place. Note: not all RDATA have valid tokens due to
 batching. See RdataCommand for more details.
    
-
    Example
    
+
    Example
    
 
    An example iteraction is shown below. Each line is prefixed with '>'
 or '<' to indicate which side is sending, these are not included on
 the wire:
    
@@ -13099,7 +13367,7 @@ graph), and one where we remove redundant links (the transitive reduction of the
 links graph) e.g. if we have chains C3 -> C2 -> C1 then the link C3 -> C1
 would not be stored. Synapse uses the former implementations so that it doesn't
 need to recurse to test reachability between chains.
    
-
    Example
    
+
    Example
    
 
    An example auth graph would look like the following, where chains have been
 formed based on type/state_key and are denoted by colour and are labelled with
 (chain ID, sequence number). Links are denoted by the arrows (links in grey
-- 
cgit 1.5.1