ae239280cb
Fixes: #19540 Fixes: #16290 (side effect of the proposed fix) Closes: #12804 (side effect of the proposed fix) Introduced in: https://github.com/matrix-org/synapse/pull/8932 --- This PR is a relatively simple simplification of the profile change on deactivation that appears to remove multiple bugs. This PR's **primary motivating fix** is #19540: when a user is deactivated and erased, they would be kept in the user directory. This bug appears to have been here since #8932 (previously https://github.com/matrix-org/synapse/pull/8932) (v1.26.0). The root cause of this bug is that after removing the user from the user directory, we would immediately update their displayname and avatar to empty strings (one at a time), which re-inserts the user into the user directory. With this PR, we now delete the entire `profiles` row upon user erasure, which is cleaner (from a 'your database goes back to zero after deactivating and erasing a user' point of view) and only needs one database operation (instead of doing displayname then avatar). With this PR, we also no longer send the 2 (deferred) `m.room.member` `join` events to every room to propagate the displayname and avatar_url changes. This is good for two reasons: - the user is about to get parted from those rooms anyway, so this reduces the number of state events sent per room from 3 to 1. (More efficient for us in the moment and leaves less litter in the room DAG.) - it is possible for the displayname/avatar update to be sent **after** the user parting, which seems as though it could trigger the user to be re-joined to a public room. (With that said, although this sounds vaguely familiar in my lossy memory, I can't find a ticket that actually describes this bug, so this might be fictional. Edit: #16290 seems to describe this, although the title is misleading.) Additionally, as a side effect of the proposed fix (deleting the `profiles` row), this PR also now deletes custom profile fields upon user erasure, which is a new feature/bugfix (not sure which) in its own right. I do not see a ticket that corresponds to this feature gap, possibly because custom profile fields are still a niche feature without mainstream support (to the best of my knowledge). Tests are included for the primary bugfix and for the cleanup of custom profile fields. ### `set_displayname` module API change This change includes a minor _technically_-breaking change to the module API. The change concerns `set_displayname` which is exposed to the module API with a `deactivation: bool = False` flag, matching the internal handler method it wraps. I suspect that this is a mistake caused by overly-faithfully piping through the args from the wrapped method (this Module API was introduced in https://github.com/matrix-org/synapse/pull/14629/changes#diff-0b449f6f95672437cf04f0b5512572b4a6a729d2759c438b7c206ea249619885R1592). The linked PR did the same for `by_admin` originally before it was changed. The `deactivation` flag's only purpose is to be piped through to other Module API callbacks when a module has registered to be notified about profile changes. My claim is that it makes no sense for the Module API to have this flag because it is not the one doing the deactivation, thus it should never be in a position to set this to `True`. My proposed change keeps the flag (for function signature compatibility), but turns it into a no-op (with a `ERROR` log when it's set to True by the module). The Module API callback notifying of the module-caused displayname change will therefore now always have `deactivation = False`. *Discussed in [`#synapse-dev:matrix.org`](https://matrix.to/#/!i5D5LLct_DYG-4hQprLzrxdbZ580U9UB6AEgFnk6rZQ/$1f8N6G_EJUI_I_LvplnVAF2UFZTw_FzgsPfB6pbcPKk?via=element.io&via=matrix.org&via=beeper.com)* --------- Signed-off-by: Olivier 'reivilibre <oliverw@matrix.org>
Synapse Documentation
The documentation is currently hosted here. Please update any links to point to the new website instead.
About
This directory currently holds a series of markdown files documenting how to install, use and develop Synapse. The documentation is readable directly from this repository, but it is recommended to instead browse through the website for easier discoverability.
Adding to the documentation
Most of the documentation currently exists as top-level files, as when organising them into
a structured website, these files were kept in place so that existing links would not break.
The rest of the documentation is stored in folders, such as setup, usage, and development
etc. All new documentation files should be placed in structured folders. For example:
To create a new user-facing documentation page about a new Single Sign-On protocol named "MyCoolProtocol", one should create a new file with a relevant name, such as "my_cool_protocol.md". This file might fit into the documentation structure at:
- Usage
- Configuration
- User Authentication
- Single Sign-On
- My Cool Protocol
- Single Sign-On
- User Authentication
- Configuration
Given that, one would place the new file under
usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md.
Note that the structure of the documentation (and thus the left sidebar on the website) is determined by the list in SUMMARY.md. The final thing to do when adding a new page is to add a new line linking to the new documentation file:
- [My Cool Protocol](usage/configuration/user_authentication/single_sign_on/my_cool_protocol.md)
Building the documentation
The documentation is built with mdbook, and the outline of the documentation is determined by the structure of SUMMARY.md.
First, get mdbook. Then, from the root of the repository, build the documentation with:
mdbook build
The rendered contents will be outputted to a new book/ directory at the root of the repository. Please note that
index.html is not built by default, it is created by copying over the file welcome_and_overview.html to index.html
during deployment. Thus, when running mdbook serve locally the book will initially show a 404 in place of the index
due to the above. Do not be alarmed!
You can also have mdbook host the docs on a local webserver with hot-reload functionality via:
mdbook serve
The URL at which the docs can be viewed at will be logged.
Synapse configuration documentation
The Configuration Manual page is generated from a YAML file, schema/synapse-config.schema.yaml. To add new options or modify existing ones, first edit that file, then run scripts-dev/gen_config_documentation.py to generate an updated Configuration Manual markdown file.
Build the book as described above to preview it in a web browser.
Configuration and theming
The look and behaviour of the website is configured by the book.toml file at the root of the repository. See mdbook's documentation on configuration for available options.
The site can be themed and additionally extended with extra UI and features. See website_files/README.md for details.