kaslo/synapse
1
0
Fork 0
Code Packages Releases 124 Wiki Activity

More renaming

Browse Source
This commit is contained in:
Erik Johnston
2023-12-13 15:41:11 +00:00
parent 32447b0ca1
commit 8613f7693e
24 changed files with 115 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/consent_tracking.md
View File

@@ -24,7 +24,7 @@ To enable this, first create templates for the policy and success pages.
These should be stored on the local filesystem.
These templates use the [Jinja2](http://jinja.pocoo.org) templating language,
and [docs/privacy_policy_templates](https://github.com/matrix-org/synapse/tree/develop/docs/privacy_policy_templates/)
and [docs/privacy_policy_templates](https://github.com/element.-hq/synapse/tree/develop/docs/privacy_policy_templates/)
gives examples of the sort of thing that can be done.
Note that the templates must be stored under a name giving the language of the

10
docs/development/git.md
View File

@@ -14,11 +14,11 @@ b2dba0607`:
Note how the commit comment explains clearly what is changing and why. Also
note the *absence* of merge commits, as well as the absence of commits called
things like (to pick a few culprits):
[“pep8”](https://github.com/matrix-org/synapse/commit/84691da6c), [“fix broken
test”](https://github.com/matrix-org/synapse/commit/474810d9d),
[“oops”](https://github.com/matrix-org/synapse/commit/c9d72e457),
[“typo”](https://github.com/matrix-org/synapse/commit/836358823), or [“Who's
the president?”](https://github.com/matrix-org/synapse/commit/707374d5d).
[“pep8”](https://github.com/element.-hq/synapse/commit/84691da6c), [“fix broken
test”](https://github.com/element.-hq/synapse/commit/474810d9d),
[“oops”](https://github.com/element.-hq/synapse/commit/c9d72e457),
[“typo”](https://github.com/element.-hq/synapse/commit/836358823), or [“Who's
the president?”](https://github.com/element.-hq/synapse/commit/707374d5d).
There are a number of reasons why keeping a clean commit history is a good
thing:

6
docs/development/synapse_architecture/streams.md
View File

@@ -1,7 +1,7 @@
## Streams
Synapse has a concept of "streams", which are roughly described in [`id_generators.py`](
https://github.com/matrix-org/synapse/blob/develop/synapse/storage/util/id_generators.py
https://github.com/element.-hq/synapse/blob/develop/synapse/storage/util/id_generators.py
).
Generally speaking, streams are a series of notifications that something in Synapse's database has changed that the application might need to respond to.
For example:
@@ -11,12 +11,12 @@ For example:
- The to-device stream reports when a device has a new [to-device message](https://spec.matrix.org/v1.7/client-server-api/#send-to-device-messaging).
See [`synapse.replication.tcp.streams`](
https://github.com/matrix-org/synapse/blob/develop/synapse/replication/tcp/streams/__init__.py
https://github.com/element.-hq/synapse/blob/develop/synapse/replication/tcp/streams/__init__.py
) for the full list of streams.
It is very helpful to understand the streams mechanism when working on any part of Synapse that needs to respond to changes—especially if those changes are made by different workers.
To that end, let's describe streams formally, paraphrasing from the docstring of [`AbstractStreamIdGenerator`](
https://github.com/matrix-org/synapse/blob/a719b703d9bd0dade2565ddcad0e2f3a7a9d4c37/synapse/storage/util/id_generators.py#L96
https://github.com/element.-hq/synapse/blob/a719b703d9bd0dade2565ddcad0e2f3a7a9d4c37/synapse/storage/util/id_generators.py#L96
).
### Definition

4
docs/metrics-howto.md
View File

@@ -87,8 +87,8 @@
1. Restart Prometheus.
1. Consider using the [grafana dashboard](https://github.com/matrix-org/synapse/tree/master/contrib/grafana/)
and required [recording rules](https://github.com/matrix-org/synapse/tree/master/contrib/prometheus/)
1. Consider using the [grafana dashboard](https://github.com/element.-hq/synapse/tree/master/contrib/grafana/)
and required [recording rules](https://github.com/element.-hq/synapse/tree/master/contrib/prometheus/)
## Monitoring workers

12
docs/modules/writing_a_module.md
View File

@@ -10,7 +10,7 @@ either the output of the module's `parse_config` static method (see below), or t
configuration associated with the module in Synapse's configuration file.
See the documentation for the `ModuleApi` class
[here](https://github.com/matrix-org/synapse/blob/master/synapse/module_api/__init__.py).
[here](https://github.com/element.-hq/synapse/blob/master/synapse/module_api/__init__.py).
## When Synapse runs with several modules configured
@@ -109,7 +109,7 @@ from synapse.module_api import cached, ModuleApi
class MyModule:
def __init__(self, config: Any, api: ModuleApi):
self.api = api
# Register the cached function so Synapse knows how to correctly invalidate
# entries for it.
self.api.register_cached_function(self.get_user_from_id)
@@ -124,15 +124,15 @@ class MyModule:
async def do_something_with_users(self) -> None:
"""Calls the cached function and then invalidates an entry in its cache."""
user_id = "@alice:example.com"
# Get the user. Since get_department_for_user is wrapped with a cache,
# the return value for this user_id will be cached.
department = await self.get_department_for_user(user_id)
# Do something with `department`...
# Let's say something has changed with our user, and the entry we have for
# them in the cache is out of date, so we want to invalidate it.
await self.api.invalidate_cache(self.get_department_for_user, (user_id,))

4
docs/sso_mapping_providers.md
View File

@@ -115,7 +115,7 @@ A custom mapping provider must specify the following methods:
Synapse has a built-in OpenID mapping provider if a custom provider isn't
specified in the config. It is located at
[`synapse.handlers.oidc.JinjaOidcMappingProvider`](https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/oidc.py).
[`synapse.handlers.oidc.JinjaOidcMappingProvider`](https://github.com/element.-hq/synapse/blob/develop/synapse/handlers/oidc.py).
## SAML Mapping Providers
@@ -202,4 +202,4 @@ A custom mapping provider must specify the following methods:
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`](https://github.com/matrix-org/synapse/blob/develop/synapse/handlers/saml.py).
[`synapse.handlers.saml.DefaultSamlMappingProvider`](https://github.com/element.-hq/synapse/blob/develop/synapse/handlers/saml.py).

8
docs/systemd-with-workers/README.md
View File

@@ -6,10 +6,10 @@ well as a `matrix-synapse-worker@` service template for any workers you
require. Additionally, to group the required services, it sets up a
`matrix-synapse.target`.
See the folder [system](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/)
See the folder [system](https://github.com/element.-hq/synapse/tree/develop/docs/systemd-with-workers/system/)
for the systemd unit files.
The folder [workers](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/workers/)
The folder [workers](https://github.com/element.-hq/synapse/tree/develop/docs/systemd-with-workers/workers/)
contains an example configuration for the `generic_worker` worker.
## Synapse configuration files
@@ -33,7 +33,7 @@ There is no need for a separate configuration file for the master process.
## Set up
1. Adjust synapse configuration files as above.
1. Copy the `*.service` and `*.target` files in [system](https://github.com/matrix-org/synapse/tree/develop/docs/systemd-with-workers/system/)
1. Copy the `*.service` and `*.target` files in [system](https://github.com/element.-hq/synapse/tree/develop/docs/systemd-with-workers/system/)
to `/etc/systemd/system`.
1. Run `systemctl daemon-reload` to tell systemd to load the new unit files.
1. Run `systemctl enable matrix-synapse.service`. This will configure the
@@ -74,7 +74,7 @@ systemctl restart matrix-synapse.target
**Optional:** If further hardening is desired, the file
`override-hardened.conf` may be copied from
[contrib/systemd/override-hardened.conf](https://github.com/matrix-org/synapse/tree/develop/contrib/systemd/)
[contrib/systemd/override-hardened.conf](https://github.com/element.-hq/synapse/tree/develop/contrib/systemd/)
in this repository to the location
`/etc/systemd/system/matrix-synapse.service.d/override-hardened.conf` (the
directory may have to be created). It enables certain sandboxing features in

4
docs/templates.md
View File

@@ -3,7 +3,7 @@
Synapse uses parametrised templates to generate the content of emails it sends and
webpages it shows to users.
By default, Synapse will use the templates listed [here](https://github.com/matrix-org/synapse/tree/master/synapse/res/templates).
By default, Synapse will use the templates listed [here](https://github.com/element.-hq/synapse/tree/master/synapse/res/templates).
Server admins can configure an additional directory for Synapse to look for templates
in, allowing them to specify custom templates:
@@ -128,7 +128,7 @@ registration and password reset:
page above.
When rendering, `password_reset_success.html` is given no variable, and
`password_reset_failure.html` is given a `failure_reason`, which contains the reason
for the password reset failure.
for the password reset failure.
* `registration_success.html` and `registration_failure.html`: HTML pages for success and
failure that a user will see when they follow the link in an address verification email
sent during registration.

32
docs/upgrade.md
View File

@@ -110,13 +110,13 @@ date.
## App service query parameter authorization is now a configuration option
Synapse v1.81.0 deprecated application service authorization via query parameters as this is
considered insecure - and from Synapse v1.71.0 forwards the application service token has also been sent via
considered insecure - and from Synapse v1.71.0 forwards the application service token has also been sent via
[the `Authorization` header](https://spec.matrix.org/v1.6/application-service-api/#authorization)], making the insecure
query parameter authorization redundant. Since removing the ability to continue to use query parameters could break
backwards compatibility it has now been put behind a configuration option, `use_appservice_legacy_authorization`.
This option defaults to false, but can be activated by adding
query parameter authorization redundant. Since removing the ability to continue to use query parameters could break
backwards compatibility it has now been put behind a configuration option, `use_appservice_legacy_authorization`.
This option defaults to false, but can be activated by adding
```yaml
use_appservice_legacy_authorization: true
use_appservice_legacy_authorization: true
```
to your configuration.
@@ -184,7 +184,7 @@ When using workers,
* `worker_replication_host`
* `worker_replication_http_port`
* `worker_replication_http_tls`
should now be removed from individual worker YAML configurations and the main process should instead be added to the `instance_map`
in the shared YAML configuration, using the name `main`.
@@ -260,7 +260,7 @@ worker_listeners:
worker_log_config: /etc/matrix-synapse/generic-worker-log.yaml
```
Notes:
Notes:
* `tls` is optional but mirrors the functionality of `worker_replication_http_tls`
@@ -352,8 +352,8 @@ and device replication will resume as normal.
## Minimum version of Poetry is now 1.3.2
The minimum supported version of Poetry is now 1.3.2 (previously 1.2.0, [since
Synapse 1.67](#upgrading-to-v1670)). If you have used `poetry install` to
The minimum supported version of Poetry is now 1.3.2 (previously 1.2.0, [since
Synapse 1.67](#upgrading-to-v1670)). If you have used `poetry install` to
install Synapse from a source checkout, you should upgrade poetry: see its
[installation instructions](https://python-poetry.org/docs/#installation).
For all other installation methods, no acction is required.
@@ -1068,7 +1068,7 @@ As announced with the release of [Synapse 1.47.0](#deprecation-of-the-user_may_c
the deprecated `user_may_create_room_with_invites` module callback has been removed.
Modules relying on it can instead implement [`user_may_invite`](https://matrix-org.github.io/synapse/latest/modules/spam_checker_callbacks.html#user_may_invite)
and use the [`get_room_state`](https://github.com/matrix-org/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876)
and use the [`get_room_state`](https://github.com/element.-hq/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876)
module API to infer whether the invite is happening while creating a room (see [this function](https://github.com/matrix-org/synapse-domain-rule-checker/blob/e7d092dd9f2a7f844928771dbfd9fd24c2332e48/synapse_domain_rule_checker/__init__.py#L56-L89)
as an example). Alternately, modules can also implement [`on_create_room`](https://matrix-org.github.io/synapse/latest/modules/third_party_rules_callbacks.html#on_create_room).
@@ -1124,7 +1124,7 @@ Any scripts still using the above APIs should be converted to use the
The `user_may_create_room_with_invites` is deprecated and will be removed in a future
version of Synapse. Modules implementing this callback can instead implement
[`user_may_invite`](https://matrix-org.github.io/synapse/latest/modules/spam_checker_callbacks.html#user_may_invite)
and use the [`get_room_state`](https://github.com/matrix-org/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876)
and use the [`get_room_state`](https://github.com/element.-hq/synapse/blob/872f23b95fa980a61b0866c1475e84491991fa20/synapse/module_api/__init__.py#L869-L876)
module API method to infer whether the invite is happening in the context of creating a
room.
@@ -1171,8 +1171,8 @@ Any scripts still using the above APIs should be converted to use the
## User-interactive authentication fallback templates can now display errors
This may affect you if you make use of custom HTML templates for the
[reCAPTCHA (`synapse/res/templates/recaptcha.html`)](https://github.com/matrix-org/synapse/tree/develop/synapse/res/templates/recaptcha.html) or
[terms (`synapse/res/templates/terms.html`)](https://github.com/matrix-org/synapse/tree/develop/synapse/res/templates/terms.html) fallback pages.
[reCAPTCHA (`synapse/res/templates/recaptcha.html`)](https://github.com/element.-hq/synapse/tree/develop/synapse/res/templates/recaptcha.html) or
[terms (`synapse/res/templates/terms.html`)](https://github.com/element.-hq/synapse/tree/develop/synapse/res/templates/terms.html) fallback pages.
The template is now provided an `error` variable if the authentication
process failed. See the default templates linked above for an example.
@@ -1671,7 +1671,7 @@ update your reverse proxy configuration to reflect this change.
## New HTML templates
A new HTML template,
[password_reset_confirmation.html](https://github.com/matrix-org/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html),
[password_reset_confirmation.html](https://github.com/element.-hq/synapse/blob/develop/synapse/res/templates/password_reset_confirmation.html),
has been added to the `synapse/res/templates` directory. If you are
using a custom template directory, you may want to copy the template
over and modify it.
@@ -1770,7 +1770,7 @@ New templates (`sso_auth_confirm.html`, `sso_auth_success.html`, and
is configured to use SSO and a custom
`sso_redirect_confirm_template_dir` configuration then these templates
will need to be copied from
[`synapse/res/templates`](https://github.com/matrix-org/synapse/tree/develop/synapse/res/templates) into that directory.
[`synapse/res/templates`](https://github.com/element.-hq/synapse/tree/develop/synapse/res/templates) into that directory.
## Synapse SSO Plugins Method Deprecation
@@ -1923,7 +1923,7 @@ included.
Synapse will expect these files to exist inside the configured template
directory, and **will fail to start** if they are absent. To view the
default templates, see
[synapse/res/templates](https://github.com/matrix-org/synapse/tree/master/synapse/res/templates).
[synapse/res/templates](https://github.com/element.-hq/synapse/tree/master/synapse/res/templates).
## 3pid verification changes

2
docs/usage/administration/request_log.md
View File

@@ -1,6 +1,6 @@
# Request log format
HTTP request logs are written by synapse (see [`synapse/http/site.py`](https://github.com/matrix-org/synapse/tree/develop/synapse/http/site.py) for details).
HTTP request logs are written by synapse (see [`synapse/http/site.py`](https://github.com/element.-hq/synapse/tree/develop/synapse/http/site.py) for details).
See the following for how to decode the dense data available from the default logging configuration.

21
docs/usage/administration/understanding_synapse_through_grafana_graphs.md
View File

@@ -1,14 +1,14 @@
## Understanding Synapse through Grafana graphs
It is possible to monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io)
metrics and [Grafana](https://grafana.com/).
A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md)
and information on setting up Grafana is [here](https://github.com/matrix-org/synapse/tree/master/contrib/grafana).
It is possible to monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io)
metrics and [Grafana](https://grafana.com/).
A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md)
and information on setting up Grafana is [here](https://github.com/element.-hq/synapse/tree/master/contrib/grafana).
In this setup, Prometheus will periodically scrape the information Synapse provides and
store a record of it over time. Grafana is then used as an interface to query and
present this information through a series of pretty graphs.
Once you have grafana set up, and assuming you're using [our grafana dashboard template](https://github.com/matrix-org/synapse/blob/master/contrib/grafana/synapse.json), look for the following graphs when debugging a slow/overloaded Synapse:
Once you have grafana set up, and assuming you're using [our grafana dashboard template](https://github.com/element.-hq/synapse/blob/master/contrib/grafana/synapse.json), look for the following graphs when debugging a slow/overloaded Synapse:
## Message Event Send Time
@@ -57,7 +57,7 @@ Cross-referencing this with the Eviction Rate graph, which shows that entries ar
![image](https://user-images.githubusercontent.com/1342360/82240766-de95df80-9932-11ea-8c15-5acfc57c48da.png)
we should probably consider raising the size of that cache by raising its cache factor (a multiplier value for the size of an individual cache). Information on doing so is available [here](https://github.com/matrix-org/synapse/blob/ee421e524478c1ad8d43741c27379499c2f6135c/docs/sample_config.yaml#L608-L642) (note that the configuration of individual cache factors through the configuration file is available in Synapse v1.14.0+, whereas doing so through environment variables has been supported for a very long time). Note that this will increase Synapse's overall memory usage.
we should probably consider raising the size of that cache by raising its cache factor (a multiplier value for the size of an individual cache). Information on doing so is available [here](https://github.com/element.-hq/synapse/blob/ee421e524478c1ad8d43741c27379499c2f6135c/docs/sample_config.yaml#L608-L642) (note that the configuration of individual cache factors through the configuration file is available in Synapse v1.14.0+, whereas doing so through environment variables has been supported for a very long time). Note that this will increase Synapse's overall memory usage.
## Forward Extremities
@@ -71,14 +71,13 @@ If a room has >10 forward extremities, it's worth checking which room is the cul
![image](https://user-images.githubusercontent.com/1342360/82241911-da6ac180-9934-11ea-9a0d-a311fe22acd0.png)
Large spikes in garbage collection times (bigger than shown here, I'm talking in the
multiple seconds range), can cause lots of problems in Synapse performance. It's more an
Large spikes in garbage collection times (bigger than shown here, I'm talking in the
multiple seconds range), can cause lots of problems in Synapse performance. It's more an
indicator of problems, and a symptom of other problems though, so check other graphs for what might be causing it.
## Final Thoughts
If you're still having performance problems with your Synapse instance and you've
If you're still having performance problems with your Synapse instance and you've
tried everything you can, it may just be a lack of system resources. Consider adding
more CPU and RAM, and make use of [worker mode](../../workers.md)
more CPU and RAM, and make use of [worker mode](../../workers.md)
to make use of multiple CPU cores / multiple machines for your homeserver.

4
docs/usage/configuration/config_documentation.md
View File

@@ -1416,7 +1416,7 @@ kill -HUP [PID_OF_SYNAPSE_PROCESS]
If you are running multiple workers, you must individually update the worker
config file and send this signal to each worker process.
If you're using the [example systemd service](https://github.com/matrix-org/synapse/blob/develop/contrib/systemd/matrix-synapse.service)
If you're using the [example systemd service](https://github.com/element.-hq/synapse/blob/develop/contrib/systemd/matrix-synapse.service)
file in Synapse's `contrib` directory, you can send a `SIGHUP` signal by using
`systemctl reload matrix-synapse`.
@@ -2777,7 +2777,7 @@ 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

10
docs/welcome_and_overview.md
View File

@@ -1,6 +1,6 @@
# Introduction
Welcome to the documentation repository for Synapse, a
Welcome to the documentation repository for Synapse, a
[Matrix](https://matrix.org) homeserver implementation developed by Element.
## Installing and using Synapse
@@ -36,17 +36,17 @@ following documentation:
* Read the [Contributing Guide](development/contributing_guide.md). It is meant
to walk new contributors through the process of developing and submitting a
change to the Synapse codebase (which is [hosted on
GitHub](https://github.com/matrix-org/synapse)).
GitHub](https://github.com/element.-hq/synapse)).
* Set up your [development
environment](development/contributing_guide.md#2-what-do-i-need), then learn
how to [lint](development/contributing_guide.md#run-the-linters) and
[test](development/contributing_guide.md#8-test-test-test) your code.
* Look at [the issue tracker](https://github.com/matrix-org/synapse/issues) for
* Look at [the issue tracker](https://github.com/element.-hq/synapse/issues) for
bugs to fix or features to add. If you're new, it may be best to start with
those labeled [good first
issue](https://github.com/matrix-org/synapse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
issue](https://github.com/element.-hq/synapse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
* Understand [how Synapse is
built](development/internal_documentation/index.html), how to [migrate
@@ -58,7 +58,7 @@ following documentation:
do so!
* And finally, contribute to this documentation! The source for which is
[located here](https://github.com/matrix-org/synapse/tree/develop/docs).
[located here](https://github.com/element.-hq/synapse/tree/develop/docs).
## Reporting a security vulnerability