matrix-docker-ansible-deploy/roles/custom/matrix-synapse/vars/main.yml

# SPDX-FileCopyrightText: 2019 - 2024 Slavi Pantaleev
# SPDX-FileCopyrightText: 2022 Nikita Chernyi
# SPDX-FileCopyrightText: 2023 Alexis Yushin
# SPDX-FileCopyrightText: 2024 Charles Wright
# SPDX-FileCopyrightText: 2024 Suguru Hirahara
#
# SPDX-License-Identifier: AGPL-3.0-or-later

---

matrix_synapse_client_api_url_endpoint_public: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}://{{ matrix_server_fqn_matrix }}/_matrix/client/versions"
matrix_synapse_federation_api_url_endpoint_public: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}://{{ matrix_server_fqn_matrix }}:{{ matrix_federation_public_port }}/_matrix/federation/v1/version"

matrix_synapse_media_store_directory_name: "{{ matrix_synapse_media_store_path | basename }}"

# Optionally: `false` to fully disable tls on outbound smtp
matrix_synapse_email_smtp_enable_tls: true

# Room workers handle any URL that contains a room ID, either through the client-server API or the federation API
# - see https://tcpipuk.github.io/synapse/deployment/nginx.html#locationsconf
matrix_synapse_workers_room_worker_client_server_endpoints:
  - ^/_matrix/client/.*?!(?<room>[A-Za-z0-9._=\-\/]+):[A-Za-z0-9.\-]+
matrix_synapse_workers_room_worker_federation_endpoints:
  - ^/_matrix/federation/v[12]/(?:state_ids|get_missing_events)/(?:%21|!)(?<room>[A-Za-z0-9._=\-\/]+)(:|%3A)[A-Za-z0-9.\-]+

# Sync workers handle /sync and the (now deprecated) related endpoints
matrix_synapse_workers_sync_worker_client_server_endpoints:
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/(sync|events|initialSync|rooms/[^/]+/initialSync)$
  # Native Sliding Sync (MSC3575) - supported on generic workers since Synapse 1.114
  - ^/_matrix/client/unstable/org.matrix.simplified_msc3575/sync$

# Client reader workers handle generic client-server endpoints that don't contain a roomid or sync
matrix_synapse_workers_client_reader_client_server_endpoints:
  # Keep these as grouped regex entries instead of a single huge alternation.
  # This preserves the existing specialized-routing policy while making future audits
  # and endpoint-specific edits reviewable.

  # Encryption and room-key APIs
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/room_keys/
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/keys/(query|changes|claim|room_keys/)

  # MSC3814 dehydrated-device APIs:
  # Ref: https://github.com/element-hq/synapse/blob/b99a58719b274fcbb327fd8d7649185792bfd12c/synapse/rest/client/devices.py#L256-L459
  - ^/_matrix/client/unstable/org.matrix.msc3814.v1/dehydrated_device$
  - ^/_matrix/client/unstable/org.matrix.msc3814.v1/dehydrated_device/[^/]*/events$

  # Login, registration, account, and profile APIs
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/login
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/register(/available|/m.login.registration_token/validity|)?
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/password_policy
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/profile
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/account/(3pid|whoami|deactivate)

  # Room-scoped client APIs handled by client readers in the specialized-worker model
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/(joined_members|context/.*|members|state|hierarchy|relations/|event/|aliases|timestamp_to_event|redact|send|state/|(join|invite|leave|ban|unban|kick))

  # Generic client discovery and lookup APIs
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/(createRoom|publicRooms|versions|voip/turnServer|joined_rooms|search|directory/room/.*|capabilities)
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/user/.*/filter(/|$)

  # MatrixRTC transport discovery:
  # Ref: https://github.com/element-hq/synapse/blob/b99a58719b274fcbb327fd8d7649185792bfd12c/synapse/rest/client/matrixrtc.py#L30-L52
  - ^/_matrix/client/unstable/org.matrix.msc4143/rtc/transports$

# Federation reader workers handle generic federation endpoints that don't contain a roomid
matrix_synapse_workers_federation_reader_federation_endpoints:
  - ^/_matrix/(federation/(v1|v2)|key/v2)/

# A Synapse generic worker can handle both federation and client-server API endpoints.
# We wish to split these, as we normally serve federation separately and don't want them mixed up.
#
# This is some ugly Ansible/Jinja2 hack (seen here: https://stackoverflow.com/a/47831492),
# which takes a list of various strings and removes the ones NOT containing `/_matrix/client` anywhere in them.
#
# We intentionally don't do a diff between everything possible (`matrix_synapse_workers_generic_worker_endpoints`) and `matrix_synapse_workers_generic_worker_federation_endpoints`,
# because `matrix_synapse_workers_generic_worker_endpoints` also contains things like `/_synapse/client/`, etc.
# While /_synapse/client/ endpoints are somewhat client-server API-related, they're:
# - neither part of the client-server API spec (and are thus, different)
# - and they now include a meaningful Synapse-specific tree (`pick_idp`, `pick_username`, OIDC/SAML callbacks, rendezvous, etc.)
# - some of these paths are auth-sensitive or deployment-sensitive, so we intentionally keep them out of the broad worker route model unless explicitly handled elsewhere
#
# Basically, we aim to cover most spec client APIs here. Skipping `/_synapse/client` is intentional and conservative.
matrix_synapse_workers_generic_worker_client_server_endpoints: "{{ matrix_synapse_workers_generic_worker_endpoints | default([]) | map('regex_search', '.*/_matrix/client.*') | list | difference([none]) }}"

# A Synapse generic worker can handle both federation and client-server API endpoints.
# We wish to split these, as we normally serve federation separately and don't want them mixed up.
#
# This is some ugly Ansible/Jinja2 hack (seen here: https://stackoverflow.com/a/47831492),
# which takes a list of various strings and removes the ones NOT containing `/_matrix/federation` or `/_matrix/key` anywhere in them.
matrix_synapse_workers_generic_worker_federation_endpoints: "{{ matrix_synapse_workers_generic_worker_endpoints | default([]) | map('regex_search', matrix_synapse_workers_generic_worker_federation_endpoints_regex) | list | difference([none]) }}"

# matrix_synapse_workers_generic_worker_federation_endpoints_regex contains the regex used in matrix_synapse_workers_generic_worker_federation_endpoints.
# It's intentionally put in a separate variable, to avoid tripping ansible-lint's jinja[spacing] rule.
matrix_synapse_workers_generic_worker_federation_endpoints_regex: '.*(/_matrix/federation|/_matrix/key).*'

# matrix_synapse_workers_stream_writer_typing_stream_worker_client_server_endpoints contains the endpoints serviced by the `typing` stream writer.
# See: https://matrix-org.github.io/synapse/latest/workers.html#the-typing-stream
matrix_synapse_workers_stream_writer_typing_stream_worker_client_server_endpoints:
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/typing

# matrix_synapse_workers_stream_writer_to_device_stream_worker_client_server_endpoints contains the endpoints serviced by the `to_device` stream writer.
# See: https://matrix-org.github.io/synapse/latest/workers.html#the-to_device-stream
matrix_synapse_workers_stream_writer_to_device_stream_worker_client_server_endpoints:
  - ^/_matrix/client/(r0|v3|unstable)/sendToDevice/

# matrix_synapse_workers_stream_writer_account_data_stream_worker_client_server_endpoints contains the endpoints serviced by the `account_data` stream writer.
# See: https://matrix-org.github.io/synapse/latest/workers.html#the-account_data-stream
matrix_synapse_workers_stream_writer_account_data_stream_worker_client_server_endpoints:
  - ^/_matrix/client/(r0|v3|unstable)/.*/tags
  - ^/_matrix/client/(r0|v3|unstable)/.*/account_data

# matrix_synapse_workers_stream_writer_receipts_stream_worker_client_server_endpoints contains the endpoints serviced by the `recepts` stream writer.
# See: https://matrix-org.github.io/synapse/latest/workers.html#the-receipts-stream
matrix_synapse_workers_stream_writer_receipts_stream_worker_client_server_endpoints:
  - ^/_matrix/client/(r0|v3|unstable)/rooms/.*/receipt
  - ^/_matrix/client/(r0|v3|unstable)/rooms/.*/read_markers

# matrix_synapse_workers_stream_writer_presence_stream_worker_client_server_endpoints contains the endpoints serviced by the `presence` stream writer.
# See: https://matrix-org.github.io/synapse/latest/workers.html#the-presence-stream
matrix_synapse_workers_stream_writer_presence_stream_worker_client_server_endpoints:
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/presence/

# matrix_synapse_workers_stream_writer_push_rules_stream_worker_client_server_endpoints contains the endpoints serviced by the `push_rules` stream writer.
# See: https://matrix-org.github.io/synapse/latest/workers.html#the-push_rules-stream
matrix_synapse_workers_stream_writer_push_rules_stream_worker_client_server_endpoints:
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/pushrules/

# matrix_synapse_workers_stream_writer_device_lists_stream_worker_client_server_endpoints contains the endpoints serviced by the `device_lists` stream writer.
# See: https://matrix-org.github.io/synapse/latest/workers.html#the-device_lists-stream
matrix_synapse_workers_stream_writer_device_lists_stream_worker_client_server_endpoints:
  - ^/_matrix/client/(r0|v3)/delete_devices$
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/devices(/|$)
  - ^/_matrix/client/(r0|v3|unstable)/keys/upload(/|$)
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/keys/device_signing/upload$
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/keys/signatures/upload$

# matrix_synapse_workers_stream_writer_thread_subscriptions_stream_worker_client_server_endpoints contains the endpoints serviced by the `thread_subscriptions` stream writer.
# Ref: https://github.com/element-hq/synapse/blob/b99a58719b274fcbb327fd8d7649185792bfd12c/synapse/rest/client/thread_subscriptions.py#L38-L247
matrix_synapse_workers_stream_writer_thread_subscriptions_stream_worker_client_server_endpoints:
  - ^/_matrix/client/unstable/io.element.msc4306/rooms/.*/thread/.*/subscription$
  - ^/_matrix/client/unstable/io.element.msc4308/thread_subscriptions$

# matrix_synapse_workers_user_dir_worker_client_server_endpoints contains the endpoints serviced by the `type = user_dir` (`app = generic_worker`) worker.
# See: https://matrix-org.github.io/synapse/latest/workers.html#updating-the-user-directory
matrix_synapse_workers_user_dir_worker_client_server_endpoints:
  - ^/_matrix/client/(r0|v3|unstable)/user_directory/search$

# matrix_synapse_workers_known_stream_writer_stream_types contains the list of stream writer stream types that the playbook recognizes.
# This is used for validation purposes. If adding support for a new type, besides adding it to this list,
# don't forget to actually configure it where appropriate (see worker.yaml.j2`, the nginx proxy configuration, etc).
matrix_synapse_workers_known_stream_writer_stream_types: ['events', 'typing', 'to_device', 'account_data', 'receipts', 'presence', 'push_rules', 'device_lists', 'thread_subscriptions']

# matrix_synapse_workers_webserving_stream_writer_types contains a list of stream writer types that serve web (client) requests.
# Not all stream writers serve web requests. Some just perform background tasks.
matrix_synapse_workers_webserving_stream_writer_types: ['typing', 'to_device', 'account_data', 'receipts', 'presence', 'push_rules', 'device_lists', 'thread_subscriptions']

# matrix_synapse_workers_systemd_services_list contains a list of systemd services (one for each worker systemd service which serves web requests).
# This list is built during runtime.
# Not all workers serve web requests. Those that don't won't be injected here.
matrix_synapse_webserving_workers_systemd_services_list: []

# matrix_synapse_known_worker_types contains the list of known worker types.
#
# A worker type is different than a worker app (e.g. `generic_worker`).
# For example, the `stream_writer` worker type is served by the `generic_worker` app, but is a separate type that we recognize.
#
# Some other types (`appservice` and `user_dir`) used to be Synapse worker apps, which got subsequently deprecated.
# We still allow these types of workers and map them to the `generic_worker` app,
# which is why we make sure they're part of the list below.
# We use the `unique` filter because they're part of `matrix_synapse_workers_avail_list` too (for now; scheduled for removal).
matrix_synapse_known_worker_types: |
  {{
    (
      matrix_synapse_workers_avail_list
      +
      ['stream_writer']
      +
      ['appservice']
      +
      ['user_dir']
      +
      ['background']
    ) | unique
  }}

# matrix_synapse_known_instance_map_eligible_worker_types contains the list of worker types that are to be injected into `matrix_synapse_instance_map`.
matrix_synapse_known_instance_map_eligible_worker_types:
  - stream_writer

# The following section contains content that had previously been generated by a script (`workers-doc-to-yaml.awk`) processing https://github.com/element-hq/synapse/raw/master/docs/workers.md,
# but is now maintained manually due to:
# - the script being tripped up by the content and generating somewhat inaccurate definitions, which had to be fixed up manually.
# - the script being complicated and unmaintainable
### workers:start
matrix_synapse_workers_generic_worker_endpoints:
  # Sync requests
  - ^/_matrix/client/(r0|v3)/sync$
  - ^/_matrix/client/(api/v1|r0|v3)/events$
  - ^/_matrix/client/(api/v1|r0|v3)/initialSync$
  - ^/_matrix/client/(api/v1|r0|v3)/rooms/[^/]+/initialSync$
  # Native Sliding Sync (MSC3575) - supported since Synapse 1.114
  - ^/_matrix/client/unstable/org.matrix.simplified_msc3575/sync$

  # Federation requests
  - ^/_matrix/federation/v1/event/
  - ^/_matrix/federation/v1/state/
  - ^/_matrix/federation/v1/state_ids/
  - ^/_matrix/federation/v1/backfill/
  - ^/_matrix/federation/v1/get_missing_events/
  - ^/_matrix/federation/v1/publicRooms
  - ^/_matrix/federation/v1/query/
  - ^/_matrix/federation/v1/make_join/
  - ^/_matrix/federation/v1/make_leave/
  - ^/_matrix/federation/(v1|v2)/send_join/
  - ^/_matrix/federation/(v1|v2)/send_leave/
  - ^/_matrix/federation/(v1|v2)/invite/
  - ^/_matrix/federation/v1/event_auth/
  - ^/_matrix/federation/v1/timestamp_to_event/
  - ^/_matrix/federation/v1/exchange_third_party_invite/
  - ^/_matrix/federation/v1/user/devices/
  - ^/_matrix/key/v2/query
  - ^/_matrix/federation/v1/hierarchy/

  # Inbound federation transaction request
  - ^/_matrix/federation/v1/send/

  # Client API requests
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/createRoom$
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/publicRooms$
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/joined_members$
  - ^/_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/v1/rooms/.*/hierarchy$
  - ^/_matrix/client/(v1|unstable)/rooms/.*/relations/
  - ^/_matrix/client/v1/rooms/.*/threads$
  - ^/_matrix/client/unstable/im.nheko.summary/rooms/.*/summary$
  - ^/_matrix/client/unstable/im.nheko.summary/summary/.*$
  - ^/_matrix/client/unstable/org.matrix.msc4143/rtc/transports$
  - ^/_matrix/client/(r0|v3|unstable)/account/3pid$
  - ^/_matrix/client/(r0|v3|unstable)/account/whoami$
  - ^/_matrix/client/(r0|v3|unstable)/account/deactivate$
  - ^/_matrix/client/versions$
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/voip/turnServer$
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/event/
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/joined_rooms$
  - ^/_matrix/client/v1/rooms/.*/timestamp_to_event$
  - ^/_matrix/client/(api/v1|r0|v3|unstable/.*)/rooms/.*/aliases
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/search$
  - ^/_matrix/client/(r0|v3|unstable)/user/.*/filter(/|$)
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/directory/room/.*$
  - ^/_matrix/client/(r0|v3|unstable)/capabilities$
  - ^/_matrix/client/(r0|v3|unstable)/notifications$

  # 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/
  # MSC3814 dehydrated-device support:
  # Ref: https://github.com/element-hq/synapse/blob/b99a58719b274fcbb327fd8d7649185792bfd12c/synapse/rest/client/devices.py#L256-L459
  - ^/_matrix/client/unstable/org.matrix.msc3814.v1/dehydrated_device$
  - ^/_matrix/client/unstable/org.matrix.msc3814.v1/dehydrated_device/[^/]*/events$

  # Registration/login requests
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/login$
  - ^/_matrix/client/(r0|v3|unstable)/register$
  - ^/_matrix/client/(r0|v3|unstable)/register/available$
  - ^/_matrix/client/v1/register/m.login.registration_token/validity$
  - ^/_matrix/client/(r0|v3|unstable)/password_policy$

  # Event sending requests
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/redact
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/send
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/rooms/.*/state/
  - ^/_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)/knock/
  - ^/_matrix/client/(api/v1|r0|v3|unstable)/profile/

  # Unstable MSC4140 support
  - ^/_matrix/client/unstable/org.matrix.msc4140/delayed_events(/.*/restart)?$

  # Admin API requests
  - ^/_synapse/admin/v2/users/[^/]+$

  # Start of intentionally-ignored-endpoints
  #
  # We ignore these below, because they are now supposed to be owned by explicit
  # early stream-backed routing in the reverse proxy.
  #
  # The intended behavior is:
  # - if a stream writer is enabled, route to that stream writer
  # - otherwise, route to Synapse `main`
  #
  # Broad generic-worker routing must not decide fallback behavior for these.
  #
  # # 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/
  #
  # # Push rules requests
  # - ^/_matrix/client/(api/v1|r0|v3|unstable)/pushrules/
  #
  # # Device lists requests
  # - ^/_matrix/client/(r0|v3)/delete_devices$
  # - ^/_matrix/client/(api/v1|r0|v3|unstable)/devices(/|$)
  # - ^/_matrix/client/(r0|v3|unstable)/keys/upload(/|$)
  # - ^/_matrix/client/(api/v1|r0|v3|unstable)/keys/device_signing/upload$
  # - ^/_matrix/client/(api/v1|r0|v3|unstable)/keys/signatures/upload$
  #
  # # Thread subscriptions requests
  # - ^/_matrix/client/unstable/io.element.msc4306/rooms/.*/thread/.*/subscription$
  # - ^/_matrix/client/unstable/io.element.msc4308/thread_subscriptions$
  #
  # # User directory search requests
  # - ^/_matrix/client/(r0|v3|unstable)/user_directory/search$
  # End of intentionally-ignored-endpoints


matrix_synapse_workers_media_repository_endpoints:
  # Handles the media repository. It can handle all endpoints starting with:

  - ^/_matrix/media/
  - ^/_matrix/client/v1/media/
  - ^/_matrix/federation/v1/media/

  # … and the following regular expressions matching media-specific administration APIs:

  - ^/_synapse/admin/v1/purge_media_cache$
  - ^/_synapse/admin/v1/room/.*/media.*$
  - ^/_synapse/admin/v1/user/.*/media.*$
  - ^/_synapse/admin/v1/media/.*$
  - ^/_synapse/admin/v1/quarantine_media/.*$
  - ^/_synapse/admin/v1/users/.*/media$

matrix_synapse_workers_user_dir_endpoints:
  # Handles searches in the user directory. It can handle REST endpoints matching
  # the following regular expressions:

  - ^/_matrix/client/(r0|v3|unstable)/user_directory/search$

matrix_synapse_workers_avail_list:
  - appservice
  - client_reader
  - federation_reader
  - federation_sender
  - generic_worker
  - media_repository
  - pusher
  - room_worker
  - sync_worker
  - user_dir
### workers:end