From 8a540c45ecfb30eebe4c9873dbe6c8bab45a640b Mon Sep 17 00:00:00 2001 From: reivilibre Date: Tue, 8 Mar 2022 15:38:01 +0000 Subject: deploy: b1989ced00cc0bc6214bfd1a393c7e8f8eda660c --- latest/print.html | 215 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 173 insertions(+), 42 deletions(-) (limited to 'latest/print.html') diff --git a/latest/print.html b/latest/print.html index 8b5ea5623c..038329652d 100644 --- a/latest/print.html +++ b/latest/print.html @@ -1638,6 +1638,12 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb +

Upgrading to v1.54.0

+

Legacy structured logging configuration removal

+

This release removes support for the structured: true logging configuration +which was deprecated in Synapse v1.23.0. If your logging configuration contains +structured: true then it should be modified based on the +structured logging documentation.

Upgrading to v1.53.0

Dropping support for webclient listeners and non-HTTP(S) web_client_location

Per the deprecation notice in Synapse v1.51.0, listeners of type webclient @@ -3075,7 +3081,7 @@ presence: # For example, for room version 1, default_room_version should be set # to "1". # -#default_room_version: "6" +#default_room_version: "9" # The GC threshold parameters to pass to `gc.set_threshold`, if defined # @@ -5805,13 +5811,11 @@ loggers: with the SQL layer at 'WARNING', and will log JSON formatted messages to a remote endpoint at 10.1.2.3:9999.

Upgrading from legacy structured logging configuration

-

Versions of Synapse prior to v1.23.0 included a custom structured logging -configuration which is deprecated. It used a structured: true flag and -configured drains instead of handlers and formatters.

-

Synapse currently automatically converts the old configuration to the new -configuration, but this will be removed in a future version of Synapse. The -following reference can be used to update your configuration. Based on the drain -type, we can pick a new handler:

+

Versions of Synapse prior to v1.54.0 automatically converted the legacy +structured logging configuration, which was deprecated in v1.23.0, to the standard +library logging configuration.

+

The following reference can be used to update your configuration. Based on the +drain type, we can pick a new handler:

  1. For a type of console, console_json, or console_json_terse: a handler with a class of logging.StreamHandler and a stream of ext://sys.stdout @@ -7946,10 +7950,14 @@ Synapse instances. Spam checker callbacks can be registered using the module API

    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.

    +

    Called when receiving an event from a client or via federation. The callback must return +either:

    +
      +
    • an error message string, to indicate the event must be rejected because of spam and +give a rejection reason to forward to clients;
      • +
    • the boolean True, to indicate that the event is spammy, but not provide further details; or
      • +
    • the booelan False, to indicate that the event is not considered spammy.
      • +

    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 @@ -7959,7 +7967,9 @@ any of the subsequent implementations of this callback.

    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 -whether the user can join the room. The user is represented by their Matrix user ID (e.g. +whether the user can join the room. Return False to prevent the user from joining the +room; otherwise return True to permit the joining.

    +

    The user is represented by their Matrix user ID (e.g. @alice:example.com) and the room is represented by its Matrix ID (e.g. !room:example.com). The module is also given a boolean to indicate whether the user currently has a pending invite in the room.

    @@ -7975,7 +7985,8 @@ any of the subsequent implementations of this callback.

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

    +represented by their Matrix user ID (e.g. @alice:example.com). Return False to prevent +the invitation; otherwise return True to permit it.

    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 @@ -7991,7 +8002,8 @@ any of the subsequent implementations of this callback.

    Called when processing an invitation using a third-party identifier (also called a 3PID, e.g. an email address or a phone number). The module must return a bool indicating -whether the inviter can invite the invitee to the given room.

    +whether the inviter can invite the invitee to the given room. Return False to prevent +the invitation; otherwise return True to permit it.

    The inviter is represented by their Matrix user ID (e.g. @alice:example.com), and the invitee is represented by its medium (e.g. "email") and its address (e.g. alice@example.com). See the Matrix specification @@ -8016,7 +8028,8 @@ any of the subsequent implementations of this callback.

    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.

    +whether the given user (represented by their Matrix user ID) is allowed to create a room. +Return False to prevent room creation; otherwise return True to permit it.

    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 @@ -8027,7 +8040,8 @@ any of the subsequent implementations of this callback.

    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.

    +to set the given alias. Return False to prevent the alias creation; otherwise return +True to permit it.

    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 @@ -8038,7 +8052,8 @@ any of the subsequent implementations of this callback.

    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.

    +Matrix user ID) is allowed to publish the given room. Return False to prevent the +room from being published; otherwise return True to permit its publication.

    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 @@ -8048,8 +8063,10 @@ any of the subsequent implementations of this callback.

    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 -bool indicating whether the given user profile can appear in search results. The profile -is represented as a dictionary with the following keys:

    +bool indicating whether the given user should be excluded from user directory +searches. Return True to indicate that the user is spammy and exclude them from +search results; otherwise return False.

    +

    The profile is represented as a dictionary with the following keys:

    • user_id: The Matrix ID for this user.
    • display_name: The user's display name.
      • @@ -8095,8 +8112,9 @@ this callback.

      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.

      +

      Called when storing a local or remote file. The module must return a bool indicating +whether the given file should be excluded from the homeserver's media store. Return +True to prevent this file from being stored; otherwise return False.

      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 @@ -8252,6 +8270,48 @@ it will be included in this state.

      into the room, which means this callback cannot be used to deny persisting the event. To deny an incoming event, see check_event_for_spam instead.

      If multiple modules implement this callback, Synapse runs them all in order.

      +

      on_profile_update

      +

      First introduced in Synapse v1.54.0

      +
      async def on_profile_update(
+    user_id: str,
+    new_profile: "synapse.module_api.ProfileInfo",
+    by_admin: bool,
+    deactivation: bool,
+) -> None:
+
      +

      Called after updating a local user's profile. The update can be triggered either by the +user themselves or a server admin. The update can also be triggered by a user being +deactivated (in which case their display name is set to an empty string ("") and the +avatar URL is set to None). The module is passed the Matrix ID of the user whose profile +has been updated, their new profile, as well as a by_admin boolean that is True if the +update was triggered by a server admin (and False otherwise), and a deactivated +boolean that is True if the update is a result of the user being deactivated.

      +

      Note that the by_admin boolean is also True if the profile change happens as a result +of the user logging in through Single Sign-On, or if a server admin updates their own +profile.

      +

      Per-room profile changes do not trigger this callback to be called. Synapse administrators +wishing this callback to be called on every profile change are encouraged to disable +per-room profiles globally using the allow_per_room_profiles configuration setting in +Synapse's configuration file. +This callback is not called when registering a user, even when setting it through the +get_displayname_for_registration +module callback.

      +

      If multiple modules implement this callback, Synapse runs them all in order.

      +

      on_user_deactivation_status_changed

      +

      First introduced in Synapse v1.54.0

      +
      async def on_user_deactivation_status_changed(
+    user_id: str, deactivated: bool, by_admin: bool
+) -> None:
+
      +

      Called after deactivating a local user, or reactivating them through the admin API. The +deactivation can be triggered either by the user themselves or a server admin. The module +is passed the Matrix ID of the user whose status is changed, as well as a deactivated +boolean that is True if the user is being deactivated and False if they're being +reactivated, and a by_admin boolean that is True if the deactivation was triggered by +a server admin (and False otherwise). This latter by_admin boolean is always True +if the user is being reactivated, as this operation can only be performed through the +admin API.

      +

      If multiple modules implement this callback, Synapse runs them all in order.

      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.

      @@ -8457,7 +8517,7 @@ If the module doesn't wish to return a callback, it must return None instead.

      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, +any of the subsequent implementations of this callback. If every callback returns None, the authentication is denied.

      on_logged_out

      First introduced in Synapse v1.46.0

      @@ -8517,9 +8577,30 @@ 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, +any of the subsequent implementations of this callback. If every callback returns None, the username provided by the user is used, if any (otherwise one is automatically generated).

      +

      get_displayname_for_registration

      +

      First introduced in Synapse v1.54.0

      +
      async def get_displayname_for_registration(
+    uia_results: Dict[str, Any],
+    params: Dict[str, Any],
+) -> Optional[str]
+
      +

      Called when registering a new user. The module can return a display name to set for the +user being registered by returning it as a string, or None if it doesn't wish to force a +display name for this user.

      +

      This callback is called once User-Interactive Authentication +has been completed by the user. It is not called when registering a user via SSO. It is +passed two dictionaries, which include the information that the user has provided during +the registration process. These dictionaries are identical to the ones passed to +get_username_for_registration, so refer to the +documentation of this callback for more information about them.

      +

      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 returns None, +the username will be used (e.g. alice if the user being registered is @alice:example.com).

      is_3pid_allowed

      First introduced in Synapse v1.53.0

      async def is_3pid_allowed(self, medium: str, address: str, registration: bool) -> bool
@@ -8546,7 +8627,7 @@ any of the subsequent implementations of this callback.
      
 
    • m.login.password (defined in the spec)
 
        
 
      • Expects a password field to be sent to /login
        • 
-
      • Is checked by the method: self.check_pass 
        • 
+
      • Is checked by the method: self.check_pass
        • 
 
      
 
      •
    @@ -8805,8 +8886,11 @@ recommend the use of systemd where available: for information on se Using synctl with Workers.

    Available worker applications

    synapse.app.generic_worker

    -

    This worker can handle API requests matching the following regular -expressions:

    +

    This worker can handle API requests matching the following regular expressions. +These endpoints can be routed to any worker. If a worker is set up to handle a +stream then, for maximum efficiency, additional endpoints should be routed to that +worker: refer to the stream writers section below for further +information.

    # Sync requests
 ^/_matrix/client/(v2_alpha|r0|v3)/sync$
 ^/_matrix/client/(api/v1|v2_alpha|r0|v3)/events$
@@ -8835,7 +8919,6 @@ expressions:
    
 ^/_matrix/federation/v1/user/devices/
 ^/_matrix/federation/v1/get_groups_publicised$
 ^/_matrix/key/v2/query
-^/_matrix/federation/unstable/org.matrix.msc2946/spaces/
 ^/_matrix/federation/(v1|unstable/org.matrix.msc2946)/hierarchy/
 
 # Inbound federation transaction request
@@ -8848,22 +8931,25 @@ expressions:
    
 ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/context/.*$
 ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/members$
 ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/state$
-^/_matrix/client/unstable/org.matrix.msc2946/rooms/.*/spaces$
 ^/_matrix/client/(v1|unstable/org.matrix.msc2946)/rooms/.*/hierarchy$
 ^/_matrix/client/unstable/im.nheko.summary/rooms/.*/summary$
-^/_matrix/client/(api/v1|r0|v3|unstable)/account/3pid$
-^/_matrix/client/(api/v1|r0|v3|unstable)/devices$
-^/_matrix/client/(api/v1|r0|v3|unstable)/keys/query$
-^/_matrix/client/(api/v1|r0|v3|unstable)/keys/changes$
+^/_matrix/client/(r0|v3|unstable)/account/3pid$
+^/_matrix/client/(r0|v3|unstable)/devices$
 ^/_matrix/client/versions$
 ^/_matrix/client/(api/v1|r0|v3|unstable)/voip/turnServer$
-^/_matrix/client/(api/v1|r0|v3|unstable)/joined_groups$
-^/_matrix/client/(api/v1|r0|v3|unstable)/publicised_groups$
-^/_matrix/client/(api/v1|r0|v3|unstable)/publicised_groups/
+^/_matrix/client/(r0|v3|unstable)/joined_groups$
+^/_matrix/client/(r0|v3|unstable)/publicised_groups$
+^/_matrix/client/(r0|v3|unstable)/publicised_groups/
 ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/event/
 ^/_matrix/client/(api/v1|r0|v3|unstable)/joined_rooms$
 ^/_matrix/client/(api/v1|r0|v3|unstable)/search$
 
+# Encryption requests
+^/_matrix/client/(r0|v3|unstable)/keys/query$
+^/_matrix/client/(r0|v3|unstable)/keys/changes$
+^/_matrix/client/(r0|v3|unstable)/keys/claim$
+^/_matrix/client/(r0|v3|unstable)/room_keys/
+
 # Registration/login requests
 ^/_matrix/client/(api/v1|r0|v3|unstable)/login$
 ^/_matrix/client/(r0|v3|unstable)/register$
@@ -8876,6 +8962,20 @@ expressions:
    
 ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/(join|invite|leave|ban|unban|kick)$
 ^/_matrix/client/(api/v1|r0|v3|unstable)/join/
 ^/_matrix/client/(api/v1|r0|v3|unstable)/profile/
+
+# Device requests
+^/_matrix/client/(r0|v3|unstable)/sendToDevice/
+
+# Account data requests
+^/_matrix/client/(r0|v3|unstable)/.*/tags
+^/_matrix/client/(r0|v3|unstable)/.*/account_data
+
+# Receipts requests
+^/_matrix/client/(r0|v3|unstable)/rooms/.*/receipt
+^/_matrix/client/(r0|v3|unstable)/rooms/.*/read_markers
+
+# Presence requests
+^/_matrix/client/(api/v1|r0|v3|unstable)/presence/

    Additionally, the following REST endpoints can be handled for GET requests:

    ^/_matrix/federation/v1/groups/
@@ -8941,11 +9041,10 @@ effects of bursts of events from that bridge on events sent by normal users.
    
 
    Additionally, there is experimental support for moving writing of specific
 streams (such as events) off of the main process to a particular worker. (This
 is only supported with Redis-based replication.)
    
-
    Currently supported streams are events and typing.
    
 
    To enable this, the worker must have a HTTP replication listener configured,
-have a worker_name and be listed in the instance_map config. For example to
-move event persistence off to a dedicated worker, the shared configuration would
-include:
    
+have a worker_name and be listed in the instance_map config. The same worker
+can handle multiple streams. For example, to move event persistence off to a
+dedicated worker, the shared configuration would include:
    
 
    instance_map:
     event_persister1:
         host: localhost
@@ -8954,6 +9053,10 @@ include:
    
 stream_writers:
     events: event_persister1
 
    
+
    Some of the streams have associated endpoints which, for maximum efficiency, should
+be routed to the workers handling that stream. See below for the currently supported
+streams and the endpoints associated with them:
    
+
    The events stream
    
 
    The events stream also experimentally supports having multiple writers, where
 work is sharded between them by room ID. Note that you must restart all worker
 instances when adding or removing event persisters. An example stream_writers
@@ -8963,6 +9066,33 @@ configuration with multiple writers:
    
         - event_persister1
         - event_persister2
    +
    The typing stream
    +

    The following endpoints should be routed directly to the workers configured as +stream writers for the typing stream:

    +
    ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/typing
+
    +
    The to_device stream
    +

    The following endpoints should be routed directly to the workers configured as +stream writers for the to_device stream:

    +
    ^/_matrix/client/(api/v1|r0|v3|unstable)/sendToDevice/
+
    +
    The account_data stream
    +

    The following endpoints should be routed directly to the workers configured as +stream writers for the account_data stream:

    +
    ^/_matrix/client/(api/v1|r0|v3|unstable)/.*/tags
+^/_matrix/client/(api/v1|r0|v3|unstable)/.*/account_data
+
    +
    The receipts stream
    +

    The following endpoints should be routed directly to the workers configured as +stream writers for the receipts stream:

    +
    ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/receipt
+^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/read_markers
+
    +
    The presence stream
    +

    The following endpoints should be routed directly to the workers configured as +stream writers for the presence stream:

    +
    ^/_matrix/client/(api/v1|r0|v3|unstable)/presence/
+

    Background tasks

    There is also experimental support for moving background tasks to a separate worker. Background tasks are run periodically or started via replication. Exactly @@ -11128,7 +11258,8 @@ provider for SSO (Single sign-on). Details in section sso and oidc_providers.

    • auth_provider - string. ID of the external identity provider. Value of idp_id -in homeserver configuration.
      • +in the homeserver configuration. Note that no error is raised if the provided +value is not in the homeserver configuration.
    • external_id - string, user ID in the external identity provider.
    2. @@ -12241,7 +12372,7 @@ parts of the process.

    Note that, prior to Synapse 1.41, any call which returns a coroutine will need to be wrapped in ensureDeferred.

    As a simple example, retrieving an event from the database:

    >>> from twisted.internet import defer
->>> defer.ensureDeferred(hs.get_datastore().get_event('$1416420717069yeQaw:matrix.org'))
+>>> defer.ensureDeferred(hs.get_datastores().main.get_event('$1416420717069yeQaw:matrix.org'))
 <Deferred at 0x7ff253fc6998 current result: <FrozenEvent event_id='$1416420717069yeQaw:matrix.org', type='m.room.create', state_key=''>>

    How to monitor Synapse metrics using Prometheus

    -- cgit 1.5.1