From 4adc33d520744afb6dc922cab34c6a6f81b977e6 Mon Sep 17 00:00:00 2001 From: clokep Date: Fri, 17 Nov 2023 13:44:41 +0000 Subject: deploy: c4f5522189687c1e739d63246b5a6668d89b2d5f --- latest/print.html | 210 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 162 insertions(+), 48 deletions(-) (limited to 'latest/print.html') diff --git a/latest/print.html b/latest/print.html index ae54decfdf..b477a54e7e 100644 --- a/latest/print.html +++ b/latest/print.html @@ -77,7 +77,7 @@ @@ -3872,6 +3872,10 @@ This option replaces the previous top-level 'use_presence' option.

presence:
   enabled: false
+

enabled can also be set to a special value of "untracked" which ignores updates +received via clients and federation, while still accepting updates from the +module API.

+

The "untracked" option was added in Synapse 1.96.0.

require_auth_for_profile_requests

Whether to require authentication to retrieve profile data (avatars, display names) of other @@ -6985,53 +6989,126 @@ users by always returning an empty list for all queries. Defaults to true.

alias_creation_rules

-

The alias_creation_rules option controls who is allowed to create aliases -on this server.

-

The format of this option is a list of rules that contain globs that -match against user_id, room_id and the new alias (fully qualified with -server name). The action in the first rule that matches is taken, -which can currently either be "allow" or "deny".

-

Missing user_id/room_id/alias fields default to "*".

-

If no rules match the request is denied. An empty list means no one -can create aliases.

-

Options for the rules include:

- +

The alias_creation_rules option allows server admins to prevent unwanted +alias creation on this server.

+

This setting is an optional list of 0 or more rules. By default, no list is +provided, meaning that all alias creations are permitted.

+

Otherwise, requests to create aliases are matched against each rule in order. +The first rule that matches decides if the request is allowed or denied. If no +rule matches, the request is denied. In particular, this means that configuring +an empty list of rules will deny every alias creation request.

+

Each rule is a YAML object containing four fields, each of which is an optional string:

+ +

Each of the glob patterns is optional, defaulting to * ("match anything"). +Note that the patterns match against fully qualified IDs, e.g. against +@alice:example.com, #room:example.com and !abcdefghijk:example.com instead +of alice, room and abcedgghijk.

Example configuration:

-
alias_creation_rules:
-  - user_id: "bad_user"
-    alias: "spammy_alias"
-    room_id: "*"
+
# No rule list specified. All alias creations are allowed.
+# This is the default behaviour.
+alias_creation_rules:
+

+
# A list of one rule which allows everything.
+# This has the same effect as the previous example.
+alias_creation_rules:
+  - "action": "allow"
+

+
# An empty list of rules. All alias creations are denied.
+alias_creation_rules: []
+

+
# A list of one rule which denies everything.
+# This has the same effect as the previous example.
+alias_creation_rules:
+  - "action": "deny"
+

+
# Prevent a specific user from creating aliases.
+# Allow other users to create any alias
+alias_creation_rules:
+  - user_id: "@bad_user:example.com"
+    action: deny
+    
+  - action: allow
+

+
# Prevent aliases being created which point to a specific room.
+alias_creation_rules:
+  - room_id: "!forbiddenRoom:example.com"
     action: deny
+
+  - action: allow
 

 

 
room_list_publication_rules

-
The room_list_publication_rules option controls who can publish and
-which rooms can be published in the public room list.

+
The room_list_publication_rules option allows server admins to prevent
+unwanted entries from being published in the public room list.

 
The format of this option is the same as that for
-alias_creation_rules.

-
If the room has one or more aliases associated with it, only one of
-the aliases needs to match the alias rule. If there are no aliases
-then only rules with alias: * match.

-
If no rules match the request is denied. An empty list means no one
-can publish rooms.

-
Options for the rules include:

-
    
-
  • user_id: Matches against the creator of the alias. Defaults to "*".
    • 
-
  • alias: Matches against any current local or canonical aliases associated with the room. Defaults to "*".
    • 
-
  • room_id: Matches against the room ID being published. Defaults to "*".
    • 
-
  • action: Whether to "allow" or "deny" the request if the rule matches. Defaults to allow.
    • 
-

+alias_creation_rules: an optional list of 0 or more
+rules. By default, no list is provided, meaning that all rooms may be
+published to the room list.

+
Otherwise, requests to publish a room are matched against each rule in order.
+The first rule that matches decides if the request is allowed or denied. If no
+rule matches, the request is denied. In particular, this means that configuring
+an empty list of rules will deny every alias creation request.

+
Each rule is a YAML object containing four fields, each of which is an optional string:

+
    
+
  • user_id: a glob pattern that matches against the user publishing the room.
    • 
+
  • alias: a glob pattern that matches against one of published room's aliases.
+
      
+
    • If the room has no aliases, the alias match fails unless alias is unspecified or *.
      • 
+
    • If the room has exactly one alias, the alias match succeeds if the alias pattern matches that alias.
      • 
+
    • If the room has two or more aliases, the alias match succeeds if the pattern matches at least one of the aliases.
      • 
+
    
+
    • 
+
  • room_id: a glob pattern that matches against the room ID of the room being published.
    • 
+
  • action: either allow or deny. What to do with the request if the rule matches. Defaults to allow.
    • 
+

+
Each of the glob patterns is optional, defaulting to * ("match anything").
+Note that the patterns match against fully qualified IDs, e.g. against
+@alice:example.com, #room:example.com and !abcdefghijk:example.com instead
+of alice, room and abcedgghijk.

 
Example configuration:

-
room_list_publication_rules:
-  - user_id: "*"
-    alias: "*"
-    room_id: "*"
-    action: allow
+
# No rule list specified. Anyone may publish any room to the public list.
+# This is the default behaviour.
+room_list_publication_rules:
+

+
# A list of one rule which allows everything.
+# This has the same effect as the previous example.
+room_list_publication_rules:
+  - "action": "allow"
+

+
# An empty list of rules. No-one may publish to the room list.
+room_list_publication_rules: []
+

+
# A list of one rule which denies everything.
+# This has the same effect as the previous example.
+room_list_publication_rules:
+  - "action": "deny"
+

+
# Prevent a specific user from publishing rooms.
+# Allow other users to publish anything.
+room_list_publication_rules:
+  - user_id: "@bad_user:example.com"
+    action: deny
+    
+  - action: allow
+

+
# Prevent publication of a specific room.
+room_list_publication_rules:
+  - room_id: "!forbiddenRoom:example.com"
+    action: deny
+
+  - action: allow
+

+
# Prevent publication of rooms with at least one alias containing the word "potato".
+room_list_publication_rules:
+  - alias: "#*potato*:example.com"
+    action: deny
+
+  - action: allow
 

 

 
default_power_level_content_override

@@ -10517,9 +10594,15 @@ class EventCensorer:
         return event_dict
 

 
Presence router callbacks

-
Presence router callbacks allow module developers to specify additional users (local or remote)
-to receive certain presence updates from local users. Presence router callbacks can be 
-registered using the module API's register_presence_router_callbacks method.

+
Presence router callbacks allow module developers to define additional users
+which receive presence updates from local users. The additional users
+can be local or remote.

+
For example, it could be used to direct all of @alice:example.com (a local user)'s
+presence updates to @bob:matrix.org (a remote user), even though they don't share a
+room. (Note that those presence updates might not make it to @bob:matrix.org's client
+unless a similar presence router is running on that homeserver.)

+
Presence router callbacks can be registered using the module API's
+register_presence_router_callbacks method.

 
Callbacks

 
The available presence router callbacks are:

 
get_users_for_states

@@ -11004,6 +11087,27 @@ class CustomAccountDataModule:
             }
         )
+

Add extra fields to client events unsigned section callbacks

+

First introduced in Synapse v1.96.0

+

This callback allows modules to add extra fields to the unsigned section of +events when they get sent down to clients.

+

These get called every time an event is to be sent to clients, so care should +be taken to ensure with respect to performance.

+

API

+

To register the callback, use +register_add_extra_fields_to_unsigned_client_event_callbacks on the +ModuleApi.

+

The callback should be of the form

+
async def add_field_to_unsigned(
+    event: EventBase,
+) -> JsonDict:
+
+

where the extra fields to add to the event's unsigned section is returned. +(Modules must not attempt to modify the event directly).

+

This cannot be used to alter the "core" fields in the unsigned section emitted +by Synapse itself.

+

If multiple such callbacks try to add the same field to an event's unsigned +section, the last-registered callback wins.

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:

-

At startup,

+

At startup,