diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md
index 2efb4099e5..57cac7ed16 100644
--- a/docs/development/contributing_guide.md
+++ b/docs/development/contributing_guide.md
@@ -66,7 +66,7 @@ Of their installation methods, we recommend
```shell
pip install --user pipx
-pipx install poetry==1.5.2 # Problems with Poetry 1.6, see https://github.com/matrix-org/synapse/issues/16147
+pipx install poetry==1.5.1 # Problems with Poetry 1.6, see https://github.com/matrix-org/synapse/issues/16147
```
but see poetry's [installation instructions](https://python-poetry.org/docs/#installation)
diff --git a/docs/modules/account_validity_callbacks.md b/docs/modules/account_validity_callbacks.md
index 3cd0e72198..f5eefcd7d6 100644
--- a/docs/modules/account_validity_callbacks.md
+++ b/docs/modules/account_validity_callbacks.md
@@ -42,3 +42,16 @@ operations to keep track of them. (e.g. add them to a database table). The user
represented by their Matrix user ID.
If multiple modules implement this callback, Synapse runs them all in order.
+
+### `on_user_login`
+
+_First introduced in Synapse v1.98.0_
+
+```python
+async def on_user_login(user_id: str, auth_provider_type: str, auth_provider_id: str) -> None
+```
+
+Called after successfully login or registration of a user for cases when module needs to perform extra operations after auth.
+represented by their Matrix user ID.
+
+If multiple modules implement this callback, Synapse runs them all in order.
diff --git a/docs/reverse_proxy.md b/docs/reverse_proxy.md
index fe9519b4b6..20854035d1 100644
--- a/docs/reverse_proxy.md
+++ b/docs/reverse_proxy.md
@@ -181,7 +181,11 @@ frontend matrix-federation
backend matrix
server matrix 127.0.0.1:8008
```
-
+Example configuration, if using a UNIX socket. The configuration lines regarding the frontends do not need to be modified.
+```
+backend matrix
+ server matrix unix@/run/synapse/main_public.sock
+```
[Delegation](delegate.md) example:
```
diff --git a/docs/server_notices.md b/docs/server_notices.md
index 339d10a0ab..33b2f4c9ee 100644
--- a/docs/server_notices.md
+++ b/docs/server_notices.md
@@ -44,17 +44,22 @@ section, which should look like this:
server_notices:
system_mxid_localpart: server
system_mxid_display_name: "Server Notices"
- system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ"
+ system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ"
room_name: "Server Notices"
+ room_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ"
+ room_topic: "Room used by your server admin to notice you of important information"
+ auto_join: true
```
The only compulsory setting is `system_mxid_localpart`, which defines the user
id of the Server Notices user, as above. `room_name` defines the name of the
-room which will be created.
+room which will be created, `room_avatar_url` its avatar and `room_topic` its topic.
`system_mxid_display_name` and `system_mxid_avatar_url` can be used to set the
displayname and avatar of the Server Notices user.
+`auto_join` will autojoin users to the notices room instead of sending an invite.
+
## Sending notices
To send server notices to users you can use the
diff --git a/docs/upgrade.md b/docs/upgrade.md
index ba2f7703bc..329c9c7787 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -88,6 +88,15 @@ process, for example:
dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
```
+Generally Synapse database schemas are compatible across multiple versions, once
+a version of Synapse is deployed you may not be able to rollback automatically.
+The following table gives the version ranges and the earliest version they can
+be rolled back to. E.g. Synapse versions v1.58.0 through v1.61.1 can be rolled
+back safely to v1.57.0, but starting with v1.62.0 it is only safe to rollback to
+v1.61.0.
+
+<!-- REPLACE_WITH_SCHEMA_VERSIONS -->
+
# Upgrading to v1.93.0
## Minimum supported Rust version
diff --git a/docs/usage/configuration/config_documentation.md b/docs/usage/configuration/config_documentation.md
index 7c4e742cd5..4efbd91dde 100644
--- a/docs/usage/configuration/config_documentation.md
+++ b/docs/usage/configuration/config_documentation.md
@@ -33,6 +33,23 @@ In addition, configuration options referring to size use the following suffixes:
For example, setting `max_avatar_size: 10M` means that Synapse will not accept files larger than 10,485,760 bytes
for a user avatar.
+## Config Validation
+
+The configuration file can be validated with the following command:
+```bash
+python -m synapse.config read <config key to print> -c <path to config>
+```
+
+To validate the entire file, omit `read <config key to print>`:
+```bash
+python -m synapse.config -c <path to config>
+```
+
+To see how to set other options, check the help reference:
+```bash
+python -m synapse.config --help
+```
+
### YAML
The configuration file is a [YAML](https://yaml.org/) file, which means that certain syntax rules
apply if you want your config file to be read properly. A few helpful things to know:
@@ -478,10 +495,10 @@ Unix socket support (_Added in Synapse 1.89.0_):
* **Note**: The use of both `path` and `port` options for the same `listener` is not
compatible.
* The `x_forwarded` option defaults to true when using Unix sockets and can be omitted.
- * Other options that would not make sense to use with a UNIX socket, such as
+ * Other options that would not make sense to use with a UNIX socket, such as
`bind_addresses` and `tls` will be ignored and can be removed.
* `mode`: The file permissions to set on the UNIX socket. Defaults to `666`
-* **Note:** Must be set as `type: http` (does not support `metrics` and `manhole`).
+* **Note:** Must be set as `type: http` (does not support `metrics` and `manhole`).
Also make sure that `metrics` is not included in `resources` -> `names`
@@ -566,7 +583,7 @@ listeners:
# Note that x_forwarded will default to true, when using a UNIX socket. Please see
# https://matrix-org.github.io/synapse/latest/reverse_proxy.html.
#
- - path: /var/run/synapse/main_public.sock
+ - path: /run/synapse/main_public.sock
type: http
resources:
- names: [client, federation]
@@ -663,6 +680,11 @@ This setting has the following sub-options:
has missed. Disabled by default.
* `notif_for_new_users`: Set to false to disable automatic subscription to email
notifications for new users. Enabled by default.
+* `notif_delay_before_mail`: The time to wait before emailing about a notification.
+ This gives the user a chance to view the message via push or an open client.
+ Defaults to 10 minutes.
+
+ _New in Synapse 1.99.0._
* `client_base_url`: Custom URL for client links within the email notifications. By default
links will be based on "https://matrix.to". (This setting used to be called `riot_base_url`;
the old name is still supported for backwards-compatibility but is now deprecated.)
@@ -2755,7 +2777,11 @@ enable_metrics: true
### `sentry`
Use this option to enable sentry integration. Provide the DSN assigned to you by sentry
-with the `dsn` setting.
+with the `dsn` setting.
+
+ An optional `environment` field can be used to specify an environment. This allows
+ for log maintenance based on different environments, ensuring better organization
+ and analysis..
NOTE: While attempts are made to ensure that the logs don't contain
any sensitive information, this cannot be guaranteed. By enabling
@@ -2766,6 +2792,7 @@ through insecure notification channels if so configured.
Example configuration:
```yaml
sentry:
+ environment: "production"
dsn: "..."
```
---
@@ -2915,7 +2942,7 @@ access tokens via a query parameter.
Example configuration:
```yaml
-use_appservice_legacy_authorization: true
+use_appservice_legacy_authorization: true
```
---
@@ -3596,7 +3623,7 @@ This setting has the following sub-options:
* `enabled`: Defaults to true.
Set to false to disable password authentication.
Set to `only_for_reauth` to allow users with existing passwords to use them
- to log in and reauthenticate, whilst preventing new users from setting passwords.
+ to reauthenticate (not log in), whilst preventing new users from setting passwords.
* `localdb_enabled`: Set to false to disable authentication against the local password
database. This is ignored if `enabled` is false, and is only useful
if you have other `password_providers`. Defaults to true.
@@ -3815,14 +3842,23 @@ Sub-options for this setting include:
* `system_mxid_display_name`: set the display name of the "notices" user
* `system_mxid_avatar_url`: set the avatar for the "notices" user
* `room_name`: set the room name of the server notices room
+* `room_avatar_url`: optional string. The room avatar to use for server notice rooms. If set to the empty string `""`, notice rooms will not be given an avatar. Defaults to the empty string. _Added in Synapse 1.99.0._
+* `room_topic`: optional string. The topic to use for server notice rooms. If set to the empty string `""`, notice rooms will not be given a topic. Defaults to the empty string. _Added in Synapse 1.99.0._
+* `auto_join`: boolean. If true, the user will be automatically joined to the room instead of being invited.
+ Defaults to false. _Added in Synapse 1.98.0._
+
+Note that the name, topic and avatar of existing server notice rooms will only be updated when a new notice event is sent.
Example configuration:
```yaml
server_notices:
system_mxid_localpart: notices
system_mxid_display_name: "Server Notices"
- system_mxid_avatar_url: "mxc://server.com/oumMVlgDnLYFaPVkExemNVVZ"
+ system_mxid_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ"
room_name: "Server Notices"
+ room_avatar_url: "mxc://example.com/oumMVlgDnLYFaPVkExemNVVZ"
+ room_topic: "Room used by your server admin to notice you of important information"
+ auto_join: true
```
---
### `enable_room_list_search`
@@ -3845,7 +3881,7 @@ 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
+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.
@@ -3857,7 +3893,7 @@ Each rule is a YAML object containing four fields, each of which is an optional
* `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
+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`.
@@ -3894,7 +3930,7 @@ alias_creation_rules:
alias_creation_rules:
- user_id: "@bad_user:example.com"
action: deny
-
+
- action: allow
```
@@ -3972,7 +4008,7 @@ room_list_publication_rules:
room_list_publication_rules:
- user_id: "@bad_user:example.com"
action: deny
-
+
- action: allow
```
@@ -4215,9 +4251,9 @@ Example configuration(#2, for UNIX sockets):
```yaml
instance_map:
main:
- path: /var/run/synapse/main_replication.sock
+ path: /run/synapse/main_replication.sock
worker1:
- path: /var/run/synapse/worker1_replication.sock
+ path: /run/synapse/worker1_replication.sock
```
---
### `stream_writers`
@@ -4388,7 +4424,7 @@ must be declared, in the same way as the [`listeners` option](#listeners)
in the shared config.
Workers declared in [`stream_writers`](#stream_writers) and [`instance_map`](#instance_map)
- will need to include a `replication` listener here, in order to accept internal HTTP
+ will need to include a `replication` listener here, in order to accept internal HTTP
requests from other workers.
Example configuration:
@@ -4403,13 +4439,13 @@ Example configuration(#2, using UNIX sockets with a `replication` listener):
```yaml
worker_listeners:
- type: http
- path: /var/run/synapse/worker_public.sock
+ path: /run/synapse/worker_replication.sock
resources:
- - names: [client, federation]
+ - names: [replication]
- type: http
- path: /var/run/synapse/worker_replication.sock
+ path: /run/synapse/worker_public.sock
resources:
- - names: [replication]
+ - names: [client, federation]
```
---
### `worker_manhole`
diff --git a/docs/website_files/README.md b/docs/website_files/README.md
index 04d191479b..bc51c4865e 100644
--- a/docs/website_files/README.md
+++ b/docs/website_files/README.md
@@ -24,6 +24,11 @@ Finally, we also stylise the chapter titles in the left sidebar by indenting the
slightly so that they are more visually distinguishable from the section headers
(the bold titles). This is done through the `indent-section-headers.css` file.
+In addition to these modifications, we have added a version picker to the documentation.
+Users can switch between documentations for different versions of Synapse.
+This functionality was implemented through the `version-picker.js` and
+`version-picker.css` files.
+
More information can be found in mdbook's official documentation for
[injecting page JS/CSS](https://rust-lang.github.io/mdBook/format/config.html)
and
diff --git a/docs/website_files/theme/index.hbs b/docs/website_files/theme/index.hbs
index 3b7a5b6163..9cf7521e80 100644
--- a/docs/website_files/theme/index.hbs
+++ b/docs/website_files/theme/index.hbs
@@ -131,6 +131,18 @@
<i class="fa fa-search"></i>
</button>
{{/if}}
+ <div class="version-picker">
+ <div class="dropdown">
+ <div class="select">
+ <span></span>
+ <i class="fa fa-chevron-down"></i>
+ </div>
+ <input type="hidden" name="version">
+ <ul class="dropdown-menu">
+ <!-- Versions will be added dynamically in version-picker.js -->
+ </ul>
+ </div>
+ </div>
</div>
<h1 class="menu-title">{{ book_title }}</h1>
@@ -309,4 +321,4 @@
{{/if}}
</body>
-</html>
\ No newline at end of file
+</html>
diff --git a/docs/website_files/version-picker.css b/docs/website_files/version-picker.css
new file mode 100644
index 0000000000..28e5d5219a
--- /dev/null
+++ b/docs/website_files/version-picker.css
@@ -0,0 +1,78 @@
+.version-picker {
+ display: flex;
+ align-items: center;
+}
+
+.version-picker .dropdown {
+ width: 130px;
+ max-height: 29px;
+ margin-left: 10px;
+ display: inline-block;
+ border-radius: 4px;
+ border: 1px solid var(--theme-popup-border);
+ position: relative;
+ font-size: 13px;
+ color: var(--fg);
+ height: 100%;
+ text-align: left;
+}
+.version-picker .dropdown .select {
+ cursor: pointer;
+ display: block;
+ padding: 5px 2px 5px 15px;
+}
+.version-picker .dropdown .select > i {
+ font-size: 10px;
+ color: var(--fg);
+ cursor: pointer;
+ float: right;
+ line-height: 20px !important;
+}
+.version-picker .dropdown:hover {
+ border: 1px solid var(--theme-popup-border);
+}
+.version-picker .dropdown:active {
+ background-color: var(--theme-popup-bg);
+}
+.version-picker .dropdown.active:hover,
+.version-picker .dropdown.active {
+ border: 1px solid var(--theme-popup-border);
+ border-radius: 2px 2px 0 0;
+ background-color: var(--theme-popup-bg);
+}
+.version-picker .dropdown.active .select > i {
+ transform: rotate(-180deg);
+}
+.version-picker .dropdown .dropdown-menu {
+ position: absolute;
+ background-color: var(--theme-popup-bg);
+ width: 100%;
+ left: -1px;
+ right: 1px;
+ margin-top: 1px;
+ border: 1px solid var(--theme-popup-border);
+ border-radius: 0 0 4px 4px;
+ overflow: hidden;
+ display: none;
+ max-height: 300px;
+ overflow-y: auto;
+ z-index: 9;
+}
+.version-picker .dropdown .dropdown-menu li {
+ font-size: 12px;
+ padding: 6px 20px;
+ cursor: pointer;
+}
+.version-picker .dropdown .dropdown-menu {
+ padding: 0;
+ list-style: none;
+}
+.version-picker .dropdown .dropdown-menu li:hover {
+ background-color: var(--theme-hover);
+}
+.version-picker .dropdown .dropdown-menu li.active::before {
+ display: inline-block;
+ content: "✓";
+ margin-inline-start: -14px;
+ width: 14px;
+}
\ No newline at end of file
diff --git a/docs/website_files/version-picker.js b/docs/website_files/version-picker.js
new file mode 100644
index 0000000000..bb35a7d896
--- /dev/null
+++ b/docs/website_files/version-picker.js
@@ -0,0 +1,127 @@
+
+const dropdown = document.querySelector('.version-picker .dropdown');
+const dropdownMenu = dropdown.querySelector('.dropdown-menu');
+
+fetchVersions(dropdown, dropdownMenu).then(() => {
+ initializeVersionDropdown(dropdown, dropdownMenu);
+});
+
+/**
+ * Initialize the dropdown functionality for version selection.
+ *
+ * @param {Element} dropdown - The dropdown element.
+ * @param {Element} dropdownMenu - The dropdown menu element.
+ */
+function initializeVersionDropdown(dropdown, dropdownMenu) {
+ // Toggle the dropdown menu on click
+ dropdown.addEventListener('click', function () {
+ this.setAttribute('tabindex', 1);
+ this.classList.toggle('active');
+ dropdownMenu.style.display = (dropdownMenu.style.display === 'block') ? 'none' : 'block';
+ });
+
+ // Remove the 'active' class and hide the dropdown menu on focusout
+ dropdown.addEventListener('focusout', function () {
+ this.classList.remove('active');
+ dropdownMenu.style.display = 'none';
+ });
+
+ // Handle item selection within the dropdown menu
+ const dropdownMenuItems = dropdownMenu.querySelectorAll('li');
+ dropdownMenuItems.forEach(function (item) {
+ item.addEventListener('click', function () {
+ dropdownMenuItems.forEach(function (item) {
+ item.classList.remove('active');
+ });
+ this.classList.add('active');
+ dropdown.querySelector('span').textContent = this.textContent;
+ dropdown.querySelector('input').value = this.getAttribute('id');
+
+ window.location.href = changeVersion(window.location.href, this.textContent);
+ });
+ });
+};
+
+/**
+ * This function fetches the available versions from a GitHub repository
+ * and inserts them into the version picker.
+ *
+ * @param {Element} dropdown - The dropdown element.
+ * @param {Element} dropdownMenu - The dropdown menu element.
+ * @returns {Promise<Array<string>>} A promise that resolves with an array of available versions.
+ */
+function fetchVersions(dropdown, dropdownMenu) {
+ return new Promise((resolve, reject) => {
+ window.addEventListener("load", () => {
+
+ fetch("https://api.github.com/repos/matrix-org/synapse/git/trees/gh-pages", {
+ cache: "force-cache",
+ }).then(res =>
+ res.json()
+ ).then(resObject => {
+ const excluded = ['dev-docs', 'v1.91.0', 'v1.80.0', 'v1.69.0'];
+ const tree = resObject.tree.filter(item => item.type === "tree" && !excluded.includes(item.path));
+ const versions = tree.map(item => item.path).sort(sortVersions);
+
+ // Create a list of <li> items for versions
+ versions.forEach((version) => {
+ const li = document.createElement("li");
+ li.textContent = version;
+ li.id = version;
+
+ if (window.SYNAPSE_VERSION === version) {
+ li.classList.add('active');
+ dropdown.querySelector('span').textContent = version;
+ dropdown.querySelector('input').value = version;
+ }
+
+ dropdownMenu.appendChild(li);
+ });
+
+ resolve(versions);
+
+ }).catch(ex => {
+ console.error("Failed to fetch version data", ex);
+ reject(ex);
+ })
+ });
+ });
+}
+
+/**
+ * Custom sorting function to sort an array of version strings.
+ *
+ * @param {string} a - The first version string to compare.
+ * @param {string} b - The second version string to compare.
+ * @returns {number} - A negative number if a should come before b, a positive number if b should come before a, or 0 if they are equal.
+ */
+function sortVersions(a, b) {
+ // Put 'develop' and 'latest' at the top
+ if (a === 'develop' || a === 'latest') return -1;
+ if (b === 'develop' || b === 'latest') return 1;
+
+ const versionA = (a.match(/v\d+(\.\d+)+/) || [])[0];
+ const versionB = (b.match(/v\d+(\.\d+)+/) || [])[0];
+
+ return versionB.localeCompare(versionA);
+}
+
+/**
+ * Change the version in a URL path.
+ *
+ * @param {string} url - The original URL to be modified.
+ * @param {string} newVersion - The new version to replace the existing version in the URL.
+ * @returns {string} The updated URL with the new version.
+ */
+function changeVersion(url, newVersion) {
+ const parsedURL = new URL(url);
+ const pathSegments = parsedURL.pathname.split('/');
+
+ // Modify the version
+ pathSegments[2] = newVersion;
+
+ // Reconstruct the URL
+ parsedURL.pathname = pathSegments.join('/');
+
+ return parsedURL.href;
+}
\ No newline at end of file
diff --git a/docs/website_files/version.js b/docs/website_files/version.js
new file mode 100644
index 0000000000..73f7e67f6a
--- /dev/null
+++ b/docs/website_files/version.js
@@ -0,0 +1 @@
+window.SYNAPSE_VERSION = "latest";
|
