Merge pull request #456 from eMPee584/synapse-workers

Synapse workers

roles/matrix-synapse/defaults/main.yml

@@ -121,6 +121,18 @@ matrix_synapse_rc_login:
     per_second: 0.17
     burst_count: 3
 
+matrix_synapse_rc_admin_redaction:
+  per_second: 1
+  burst_count: 50
+
+matrix_synapse_rc_joins:
+  local:
+    per_second: 0.1
+    burst_count: 3
+  remote:
+    per_second: 0.01
+    burst_count: 3
+
 matrix_synapse_rc_federation:
   window_size: 1000
   sleep_limit: 10
@@ -290,6 +302,127 @@ matrix_synapse_metrics_port: 9100
 # See https://github.com/matrix-org/synapse/blob/master/docs/manhole.md
 matrix_synapse_manhole_enabled: false
 
+# Enable support for Synapse workers
+matrix_synapse_workers_enabled: false
+
+# Specifies worker configuration that should be used when workers are enabled.
+#
+# The posible values (as seen in `matrix_synapse_workers_presets`) are:
+# - "little-federation-helper" - a very minimal worker configuration to improve federation performance
+# - "one-of-each" - one worker of each supported type
+#
+# You can override `matrix_synapse_workers_presets` to define your own presets, which is ill-advised, because it's fragile.
+# To use a more custom configuration, start with one of these presets as a base and configure `matrix_synapse_workers_*_count` variables manually, to suit your liking.
+matrix_synapse_workers_preset: one-of-each
+
+matrix_synapse_workers_presets:
+  little-federation-helper:
+    generic_workers_count: 0
+    pusher_workers_count: 0
+    appservice_workers_count: 0
+    federation_sender_workers_count: 1
+    media_repository_workers_count: 0
+    user_dir_workers_count: 0
+    frontend_proxy_workers_count: 0
+  one-of-each:
+    generic_workers_count: 1
+    pusher_workers_count: 1
+    appservice_workers_count: 1
+    federation_sender_workers_count: 1
+    media_repository_workers_count: 1
+    # Disabled until https://github.com/matrix-org/synapse/issues/8787 is resolved.
+    user_dir_workers_count: 0
+    frontend_proxy_workers_count: 1
+
+# Controls whether the matrix-synapse container exposes the various worker ports
+# (see `port` and `metrics_port` in `matrix_synapse_workers_enabled_list`) outside of the container.
+#
+# Takes an "<ip>" value (e.g. "127.0.0.1", "0.0.0.0", etc), or empty string to not expose.
+# It takes "*" to signify "bind on all interfaces" ("0.0.0.0" is IPv4-only).
+matrix_synapse_workers_container_host_bind_address: ''
+
+matrix_synapse_workers_generic_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['generic_workers_count'] }}"
+matrix_synapse_workers_generic_workers_port_range_start: 18111
+matrix_synapse_workers_generic_workers_metrics_range_start: 19111
+
+# matrix_synapse_workers_pusher_workers_count can only be 0 or 1 for now.
+# More instances are not supported due to a playbook limitation having to do with keeping `pusher_instances` in `homeserver.yaml` updated.
+# See https://github.com/matrix-org/synapse/commit/ddfdf945064925eba761ae3748e38f3a1c73c328
+matrix_synapse_workers_pusher_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['pusher_workers_count'] }}"
+matrix_synapse_workers_pusher_workers_metrics_range_start: 19200
+
+# matrix_synapse_workers_appservice_workers_count can only be 0 or 1. More instances are not supported.
+matrix_synapse_workers_appservice_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['appservice_workers_count'] }}"
+matrix_synapse_workers_appservice_workers_metrics_range_start: 19300
+
+# matrix_synapse_workers_federation_sender_workers_count can only be 0 or 1 for now.
+# More instances are not supported due to a playbook limitation having to do with keeping `federation_sender_instances` in `homeserver.yaml` updated.
+# See https://github.com/matrix-org/synapse/blob/master/docs/workers.md#synapseappfederation_sender
+matrix_synapse_workers_federation_sender_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['federation_sender_workers_count'] }}"
+matrix_synapse_workers_federation_sender_workers_metrics_range_start: 19400
+
+matrix_synapse_workers_media_repository_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['media_repository_workers_count'] }}"
+matrix_synapse_workers_media_repository_workers_port_range_start: 18551
+matrix_synapse_workers_media_repository_workers_metrics_range_start: 19551
+
+# Disabled until https://github.com/matrix-org/synapse/issues/8787 is resolved.
+matrix_synapse_workers_user_dir_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['user_dir_workers_count'] }}"
+matrix_synapse_workers_user_dir_workers_port_range_start: 18661
+matrix_synapse_workers_user_dir_workers_metrics_range_start: 19661
+
+matrix_synapse_workers_frontend_proxy_workers_count: "{{ matrix_synapse_workers_presets[matrix_synapse_workers_preset]['frontend_proxy_workers_count'] }}"
+matrix_synapse_workers_frontend_proxy_workers_port_range_start: 18771
+matrix_synapse_workers_frontend_proxy_workers_metrics_range_start: 19771
+
+# Default list of workers to spawn.
+#
+# Unless you populate this manually, this list is dynamically generated
+# based on other variables above:
+# - `matrix_synapse_workers_*_workers_count`
+# - `matrix_synapse_workers_*_workers_port_range_start`
+# - `matrix_synapse_workers_*_workers_port_metrics_range_start`
+#
+# We advise that you use those variables and let this list be populated dynamically.
+# Doing that is simpler and also protects you from shooting yourself in the foot,
+# as certain workers can only be spawned just once.
+#
+# Each worker instance in the list defines the following fields:
+# - `type` - the type of worker (`generic_worker`, etc.)
+# - `instanceId` - a string that identifies the worker. The combination of (`type` + `instanceId`) represents the name of the worker and must be unique.
+# - `port` - an HTTP port where the worker listens for requests (can be `0` for workers that don't do HTTP request processing)
+# - `metrics_port` - an HTTP port where the worker exports Prometheus metrics
+#
+# Example of what this needs to look like, if you're defining it manually:
+# matrix_synapse_workers_enabled_list:
+#   - { type: generic_worker, instanceId: '18111', port: 18111, metrics_port: 19111 }
+#   - { type: generic_worker, instanceId: '18112', port: 18112, metrics_port: 19112 }
+#   - { type: generic_worker, instanceId: '18113', port: 18113, metrics_port: 19113 }
+#   - { type: generic_worker, instanceId: '18114', port: 18114, metrics_port: 19114 }
+#   - { type: generic_worker, instanceId: '18115', port: 18115, metrics_port: 19115 }
+#   - { type: generic_worker, instanceId: '18116', port: 18116, metrics_port: 19116 }
+#   - { type: pusher, instanceId: '0', port: 0, metrics_port: 19200 }
+#   - { type: appservice, instanceId: '0', port: 0, metrics_port: 19300 }
+#   - { type: federation_sender, instanceId: '0', port: 0, metrics_port: 19400 }
+#   - { type: media_repository, instanceId: '18551', port: 18551, metrics_port: 19551 }
+matrix_synapse_workers_enabled_list: []
+
+# Redis information
+matrix_synapse_redis_enabled: false
+matrix_synapse_redis_host: ""
+matrix_synapse_redis_port: 6379
+matrix_synapse_redis_password: ""
+
+# Controls whether Synapse starts a replication listener necessary for workers.
+#
+# If Redis is available, we prefer to use that, instead of talking over Synapse's custom replication protocol.
+#
+# matrix_synapse_replication_listener_enabled: "{{ matrix_synapse_workers_enabled and not matrix_redis_enabled }}"
+# We force-enable this listener for now until we debug why communication via Redis fails.
+matrix_synapse_replication_listener_enabled: true
+
+# Port used for communication between main synapse process and workers.
+# Only gets used if `matrix_synapse_replication_listener_enabled: true`
+matrix_synapse_replication_http_port: 9093
 
 # Send ERROR logs to sentry.io for easier tracking
 # To set this up: go to sentry.io, create a python project, and set

roles/matrix-synapse/files/workers-doc-to-yaml.awk

@@ -0,0 +1,146 @@
+#!/usr/bin/awk
+# Hackish approach to get a machine-readable list of current matrix
+# synapse REST API endpoints from the official documentation at
+# https://github.com/matrix-org/synapse/raw/master/docs/workers.md
+#
+# invoke in shell with:
+# URL=https://github.com/matrix-org/synapse/raw/master/docs/workers.md
+# curl -L ${URL} | awk -f workers-doc-to-yaml.awk -
+
+function worker_stanza_append(string) {
+    worker_stanza = worker_stanza string
+}
+
+function line_is_endpoint_url(line) {
+    # probably API endpoint if it starts with white-space and ^ or /
+    return (line ~ /^ +[\^\/].*\//)
+}
+
+# Put YAML marker at beginning of file.
+BEGIN {
+    print "---"
+    endpoint_conditional_comment = "  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually\n"
+}
+
+# Enable further processing after the introductory text.
+# Read each synapse worker section as record and its lines as fields.
+/Available worker applications/ {
+    enable_parsing = 1
+    # set record separator to markdown section header
+    RS = "\n### "
+    # set field separator to newline
+    FS = "\n"
+}
+
+# Once parsing is active, this will process each section as record.
+enable_parsing {
+    # Each worker section starts with a synapse.app.X headline
+    if ($1 ~ /synapse\.app\./) {
+
+        # get rid of the backticks and extract worker type from headline
+        gsub("`", "", $1)
+        gsub("synapse.app.", "", $1)
+        worker_type = $1
+
+        # initialize empty worker stanza
+        worker_stanza = ""
+
+        # track if any endpoints are mentioned in a specific section
+        worker_has_urls = 0
+
+        # some endpoint descriptions contain flag terms
+        endpoints_seem_conditional = 0
+
+        # also, collect a list of available workers
+        workers = (workers ? workers "\n" : "") "  - " worker_type
+
+        # loop through the lines (2 - number of fields in record)
+        for (i = 2; i < NF + 1; i++) {
+            # copy line for gsub replacements
+            line = $i
+
+            # end all lines but the last with a linefeed
+            linefeed = (i < NF - 1) ? "\n" : ""
+
+            # line starts with white-space and a hash: endpoint block headline
+            if (line ~ /^ +#/) {
+
+                # copy to output verbatim, normalizing white-space
+                gsub(/^ +/, "", line)
+                worker_stanza_append("  " line linefeed)
+
+            } else if (line_is_endpoint_url(line)) {
+
+                # mark section for special output formatting
+                worker_has_urls = 1
+
+                # remove leading white-space
+                gsub(/^ +/, "", line)
+                api_endpoint_regex = line
+
+                # FIXME: https://github.com/matrix-org/synapse/issues/new
+                # munge inconsistent media_repository endpoint notation
+                if (api_endpoint_regex == "/_matrix/media/") {
+                    api_endpoint_regex = "^" line
+                }
+
+                # FIXME: https://github.com/matrix-org/synapse/issues/7530
+                # https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/456#issuecomment-719015911
+                if (api_endpoint_regex == "^/_matrix/client/(r0|unstable)/auth/.*/fallback/web$") {
+                    worker_stanza_append("  # FIXME: possible bug with SSO and multiple generic workers\n")
+                    worker_stanza_append("  # see https://github.com/matrix-org/synapse/issues/7530\n")
+                    worker_stanza_append("  # " api_endpoint_regex linefeed)
+                    continue
+                }
+
+                # disable endpoints which specify complications
+                if (endpoints_seem_conditional) {
+                    # only add notice if previous line didn't match
+                    if (!line_is_endpoint_url($(i - 1))) {
+                        worker_stanza_append(endpoint_conditional_comment)
+                    }
+                    worker_stanza_append("  # " api_endpoint_regex linefeed)
+                } else {
+                    # output endpoint regex
+                    worker_stanza_append("  - " api_endpoint_regex linefeed)
+                }
+
+            # white-space only line?
+            } else if (line ~ /^ *$/) {
+
+                if (i > 3 && i < NF) {
+                    # print white-space lines unless 1st or last line in section
+                    worker_stanza_append(line linefeed)
+                }
+
+            # nothing of the above: the line is regular documentation text
+            } else {
+
+                # include this text line as comment
+                worker_stanza_append("  # " line linefeed)
+
+                # and take note of words hinting at additional conditions to be met
+                if (line ~ /(^| )[Ii]f |(^| )[Ff]or /) {
+                    endpoints_seem_conditional = 1
+                }
+            }
+        }
+
+        if (worker_has_urls) {
+            print "\nmatrix_synapse_workers_" worker_type "_endpoints:"
+            print worker_stanza
+        } else {
+            # include workers without endpoints as well for reference
+            print "\n# " worker_type " worker (no API endpoints) ["
+            print worker_stanza
+            print "# ]"
+        }
+    }
+}
+
+END {
+    print "\nmatrix_synapse_workers_avail_list:"
+    print workers | "sort"
+}
+
+# vim: tabstop=4 shiftwidth=4 expandtab autoindent

roles/matrix-synapse/files/workers-doc-to-yaml.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Fetch the synapse worker documentation and extract endpoint URLs
+# matrix-org/synapse master branch points to current stable release
+
+URL=https://github.com/matrix-org/synapse/raw/master/docs/workers.md
+curl -L ${URL} | awk -f workers-doc-to-yaml.awk > ../vars/workers.yml

roles/matrix-synapse/tasks/init.yml

@@ -1,7 +1,19 @@
+# Unless `matrix_synapse_workers_enabled_list` is explicitly defined,
+# we'll generate it dynamically.
+- import_tasks: "{{ role_path }}/tasks/synapse/workers/init.yml"
+  when: "matrix_synapse_enabled and matrix_synapse_workers_enabled and matrix_synapse_workers_enabled_list|length == 0"
+
 - set_fact:
     matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-synapse.service'] }}"
   when: matrix_synapse_enabled|bool
 
+- name: Ensure systemd services for workers are injected
+  include_tasks: "{{ role_path }}/tasks/synapse/workers/util/inject_systemd_services_for_worker.yml"
+  with_items: "{{ matrix_synapse_workers_enabled_list }}"
+  loop_control:
+    loop_var: matrix_synapse_worker_details
+  when: matrix_synapse_enabled|bool and matrix_synapse_workers_enabled|bool
+
 - set_fact:
     matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-goofys.service'] }}"
   when: matrix_s3_media_store_enabled|bool

roles/matrix-synapse/tasks/setup_synapse.yml

@@ -18,6 +18,8 @@
 
 - import_tasks: "{{ role_path }}/tasks/ext/setup.yml"
 
+- import_tasks: "{{ role_path }}/tasks/synapse/workers/setup.yml"
+
 - import_tasks: "{{ role_path }}/tasks/synapse/setup.yml"
 
 - import_tasks: "{{ role_path }}/tasks/goofys/setup.yml"

roles/matrix-synapse/tasks/synapse/workers/init.yml

@@ -0,0 +1,86 @@
+# Below is a huge hack for dynamically building a list of workers and finally assigning it to `matrix_synapse_workers_enabled_list`.
+#
+# set_fact within a loop does not work reliably in Ansible (it only executes on the first iteration for some reason),
+# so we're forced to do something much uglier.
+
+- name: Build generic workers
+  set_fact:
+    worker:
+      type: 'generic_worker'
+      instanceId: "{{ matrix_synapse_workers_generic_workers_port_range_start + item }}"
+      port: "{{ matrix_synapse_workers_generic_workers_port_range_start + item }}"
+      metrics_port: "{{ matrix_synapse_workers_generic_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_generic_workers"
+  loop: "{{ range(0, matrix_synapse_workers_generic_workers_count|int)|list }}"
+
+- name: Build federation sender workers
+  set_fact:
+    worker:
+      type: 'federation_sender'
+      instanceId: "{{ item }}"
+      port: 0
+      metrics_port: "{{ matrix_synapse_workers_federation_sender_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_federation_sender_workers"
+  loop: "{{ range(0, matrix_synapse_workers_federation_sender_workers_count|int)|list }}"
+
+# This type of worker can only have a count of 1, at most
+- name: Build pusher workers
+  set_fact:
+    worker:
+      type: 'pusher'
+      instanceId: "{{ item }}"
+      port: 0
+      metrics_port: "{{ matrix_synapse_workers_pusher_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_pusher_workers"
+  loop: "{{ range(0, matrix_synapse_workers_pusher_workers_count|int)|list }}"
+
+# This type of worker can only have a count of 1, at most
+- name: Build appservice workers
+  set_fact:
+    worker:
+      type: 'appservice'
+      instanceId: "{{ item }}"
+      port: 0
+      metrics_port: "{{ matrix_synapse_workers_appservice_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_appservice_workers"
+  loop: "{{ range(0, matrix_synapse_workers_appservice_workers_count|int)|list }}"
+
+- name: Build media_repository workers
+  set_fact:
+    worker:
+      type: 'media_repository'
+      instanceId: "{{ matrix_synapse_workers_media_repository_workers_port_range_start + item }}"
+      port: "{{ matrix_synapse_workers_media_repository_workers_port_range_start + item }}"
+      metrics_port: "{{ matrix_synapse_workers_media_repository_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_media_repository_workers"
+  loop: "{{ range(0, matrix_synapse_workers_media_repository_workers_count|int)|list }}"
+
+- name: Build frontend_proxy workers
+  set_fact:
+    worker:
+      type: 'frontend_proxy'
+      instanceId: "{{ matrix_synapse_workers_frontend_proxy_workers_port_range_start + item }}"
+      port: "{{ matrix_synapse_workers_frontend_proxy_workers_port_range_start + item }}"
+      metrics_port: "{{ matrix_synapse_workers_frontend_proxy_workers_metrics_range_start + item }}"
+  register: "matrix_synapse_workers_list_results_frontend_proxy_workers"
+  loop: "{{ range(0, matrix_synapse_workers_frontend_proxy_workers_count|int)|list }}"
+
+- set_fact:
+    matrix_synapse_dynamic_workers_list: "{{ matrix_synapse_dynamic_workers_list|default([]) + [item.ansible_facts.worker] }}"
+  with_items: |
+    {{
+      matrix_synapse_workers_list_results_generic_workers.results
+      +
+      matrix_synapse_workers_list_results_federation_sender_workers.results
+      +
+      matrix_synapse_workers_list_results_pusher_workers.results
+      +
+      matrix_synapse_workers_list_results_appservice_workers.results
+      +
+      matrix_synapse_workers_list_results_media_repository_workers.results
+      +
+      matrix_synapse_workers_list_results_frontend_proxy_workers.results
+    }}
+
+- set_fact:
+    matrix_synapse_workers_enabled_list: "{{ matrix_synapse_dynamic_workers_list }}"

roles/matrix-synapse/tasks/synapse/workers/setup.yml

@@ -0,0 +1,21 @@
+---
+
+# A previous version of the worker setup used this.
+# This is a temporary cleanup for people who ran that version.
+- name: Ensure old matrix-synapse.service.wants directory is gone
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-synapse.service.wants"
+    state: absent
+
+# Same. This was part of a previous version of the worker setup.
+# No longer necessary.
+- name: Ensure matrix-synapse-worker-write-pid script is removed
+  file:
+    path: "{{ matrix_local_bin_path }}/matrix-synapse-worker-write-pid"
+    state: absent
+
+- include_tasks: "{{ role_path }}/tasks/synapse/workers/setup_install.yml"
+  when: "matrix_synapse_enabled|bool and matrix_synapse_workers_enabled|bool"
+
+- include_tasks: "{{ role_path }}/tasks/synapse/workers/setup_uninstall.yml"
+  when: "not matrix_synapse_workers_enabled|bool"

roles/matrix-synapse/tasks/synapse/workers/setup_install.yml

@@ -0,0 +1,42 @@
+---
+
+- name: Determine current worker configs
+  find:
+    path: "{{ matrix_synapse_config_dir_path }}"
+    patterns: "worker.*.yaml"
+    use_regex: true
+  register: matrix_synapse_workers_current_config_files
+
+# This also deletes some things which we need. They will be recreated below.
+- name: Ensure previous worker configs are cleaned
+  file:
+    path: "{{ item.path }}"
+    state: absent
+  with_items: "{{ matrix_synapse_workers_current_config_files.files }}"
+
+- name: Determine current worker systemd services
+  find:
+    path: "{{ matrix_systemd_path }}"
+    patterns: "matrix-synapse-worker.*.service"
+    use_regex: true
+  register: matrix_synapse_workers_current_systemd_services
+
+- name: Ensure unnecessary worker systemd services are stopped and disabled
+  service:
+    name: "{{ item.path|basename }}"
+    state: stopped
+    enabled: false
+  with_items: "{{ matrix_synapse_workers_current_systemd_services.files }}"
+  when: "not ansible_check_mode and item.path|basename not in matrix_systemd_services_list"
+
+- name: Ensure unnecessary worker systemd services are cleaned
+  file:
+    path: "{{ item.path }}"
+    state: absent
+  with_items: "{{ matrix_synapse_workers_current_systemd_services.files }}"
+
+- name: Ensure creation of worker systemd service files and configuration files
+  include_tasks: "{{ role_path }}/tasks/synapse/workers/util/setup_files_for_worker.yml"
+  with_items: "{{ matrix_synapse_workers_enabled_list }}"
+  loop_control:
+    loop_var: matrix_synapse_worker_details

roles/matrix-synapse/tasks/synapse/workers/setup_uninstall.yml

@@ -0,0 +1,36 @@
+---
+
+- name: Populate service facts
+  service_facts:
+
+- name: Ensure any worker services are stopped
+  service:
+    name: "{{ item.key }}"
+    state: stopped
+  with_dict: "{{ ansible_facts.services|default({})|dict2items|selectattr('key', 'match', 'matrix-synapse-worker-.+\\.service')|list|items2dict }}"
+
+- name: Find worker configs to be cleaned
+  find:
+    path: "{{ matrix_synapse_config_dir_path }}"
+    patterns: "worker.*.yaml"
+    use_regex: true
+  register: matrix_synapse_workers_current_config_files
+
+- name: Ensure previous worker configs are cleaned
+  file:
+    path: "{{ item.path }}"
+    state: absent
+  with_items: "{{ matrix_synapse_workers_current_config_files.files }}"
+
+- name: Find worker systemd services to be cleaned
+  find:
+    path: "{{ matrix_systemd_path }}"
+    patterns: "matrix-synapse-worker.*.service"
+    use_regex: true
+  register: matrix_synapse_workers_current_systemd_services
+
+- name: Ensure previous worker systemd services are cleaned
+  file:
+    path: "{{ item.path }}"
+    state: absent
+  with_items: "{{ matrix_synapse_workers_current_systemd_services.files }}"

roles/matrix-synapse/tasks/synapse/workers/util/inject_systemd_services_for_worker.yml

@@ -0,0 +1,18 @@
+# The tasks below run before `validate_config.yml`.
+# To avoid failing with a cryptic error message, we'll do validation here.
+#
+# This check is mostly relevant to people who explicitly define `matrix_synapse_workers_enabled_list`
+# (Synapse Workers users from the earlier days of this PR - https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/456).
+#
+# In the future, it should be possible to remove this check.
+# Our own code which dynamically builds `matrix_synapse_workers_enabled_list` does things right.
+- name: Fail if instanceId not defined for worker
+  fail:
+    msg: "Synapse workers (like {{ matrix_synapse_worker_details|to_json }}) need to define an instanceId property (type + instanceId must be unique)"
+  when: "'instanceId' not in matrix_synapse_worker_details"
+
+- set_fact:
+    matrix_synapse_worker_systemd_service_name: "matrix-synapse-worker-{{ matrix_synapse_worker_details.type }}-{{ matrix_synapse_worker_details.instanceId }}.service"
+
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + [matrix_synapse_worker_systemd_service_name] }}"

roles/matrix-synapse/tasks/synapse/workers/util/setup_files_for_worker.yml

@@ -0,0 +1,19 @@
+- set_fact:
+    matrix_synapse_worker_systemd_service_name: "matrix-synapse-worker-{{ matrix_synapse_worker_details.type }}-{{ matrix_synapse_worker_details.instanceId }}"
+
+- set_fact:
+    matrix_synapse_worker_container_name: "{{ matrix_synapse_worker_systemd_service_name }}"
+
+- set_fact:
+    matrix_synapse_worker_config_file_name: "worker.{{ matrix_synapse_worker_details.type }}_{{ matrix_synapse_worker_details.instanceId }}.yaml"
+
+- name: Ensure configuration exists for {{ matrix_synapse_worker_systemd_service_name }}
+  template:
+    src: "{{ role_path }}/templates/synapse/worker.yaml.j2"
+    dest: "{{ matrix_synapse_config_dir_path }}/{{ matrix_synapse_worker_config_file_name }}"
+
+- name: Ensure systemd service exists for {{ matrix_synapse_worker_systemd_service_name }}
+  template:
+    src: "{{ role_path }}/templates/synapse/systemd/matrix-synapse-worker.service.j2"
+    dest: "{{ matrix_systemd_path }}/{{ matrix_synapse_worker_systemd_service_name }}.service"
+    mode: 0644

roles/matrix-synapse/tasks/validate_config.yml

@@ -12,6 +12,16 @@
     - "matrix_synapse_database_password"
     - "matrix_synapse_database_database"
 
+- name: Fail if asking for more than 1 instance of single-instance workers
+  fail:
+    msg: >-
+      `{{ item }}` cannot be more than 1. This is a single-instance worker.
+  when: "vars[item]|int > 1"
+  with_items:
+    - "matrix_synapse_workers_appservice_workers_count"
+    - "matrix_synapse_workers_pusher_workers_count"
+    - "matrix_synapse_workers_federation_sender_workers_count"
+
 - name: (Deprecation) Catch and report renamed settings
   fail:
     msg: >-

roles/matrix-synapse/templates/synapse/homeserver.yaml.j2

@@ -277,6 +277,41 @@ listeners:
     type: manhole
 {% endif %}
 
+{% if matrix_synapse_workers_enabled %}
+
+{% if matrix_synapse_replication_listener_enabled %}
+  # c.f. https://github.com/matrix-org/synapse/tree/master/docs/workers.md
+  # HTTP replication: for the workers to send data to the main synapse process
+  - port: {{ matrix_synapse_replication_http_port }}
+    bind_addresses: ['0.0.0.0']
+    type: http
+    resources:
+      - names: [replication]
+{% endif %}
+
+# c.f. https://github.com/matrix-org/synapse/tree/master/contrib/systemd-with-workers/README.md
+worker_app: synapse.app.homeserver
+
+# thx https://oznetnerd.com/2017/04/18/jinja2-selectattr-filter/
+# reduce the main worker's offerings to core homeserver business
+{% if matrix_synapse_workers_enabled_list|selectattr('type', 'equalto', 'appservice')|list  %}
+notify_appservices: false
+{% endif %}
+{% if matrix_synapse_workers_enabled_list|selectattr('type', 'equalto', 'federation_sender')|list  %}
+send_federation: false
+{% endif %}
+{% if matrix_synapse_workers_enabled_list|selectattr('type', 'equalto', 'media_repository')|list  %}
+enable_media_repo: false
+{% endif %}
+{% if matrix_synapse_workers_enabled_list|selectattr('type', 'equalto', 'pusher')|list  %}
+start_pushers: false
+{% endif %}
+{% if matrix_synapse_workers_enabled_list|selectattr('type', 'equalto', 'user_dir')|list  %}
+update_user_directory: false
+{% endif %}
+
+daemonize: false
+{% endif %}
 
 # Forward extremities can build up in a room due to networking delays between
 # homeservers. Once this happens in a large room, calculation of the state of
@@ -812,6 +847,7 @@ rc_login: {{ matrix_synapse_rc_login|to_json }}
 #rc_admin_redaction:
 #  per_second: 1
 #  burst_count: 50
+rc_admin_redaction: {{ matrix_synapse_rc_admin_redaction|to_json }}
 #
 #rc_joins:
 #  local:
@@ -820,6 +856,7 @@ rc_login: {{ matrix_synapse_rc_login|to_json }}
 #  remote:
 #    per_second: 0.01
 #    burst_count: 3
+rc_joins: {{ matrix_synapse_rc_joins|to_json }}
 #
 #rc_3pid_validation:
 #  per_second: 0.003
@@ -2810,16 +2847,16 @@ opentracing:
 redis:
   # Uncomment the below to enable Redis support.
   #
-  #enabled: true
+  enabled: {{ matrix_synapse_redis_enabled }}
 
   # Optional host and port to use to connect to redis. Defaults to
   # localhost and 6379
   #
-  #host: localhost
-  #port: 6379
+  host: {{ matrix_synapse_redis_host }}
+  port: {{ matrix_synapse_redis_port }}
 
   # Optional password if configured on the Redis instance
   #
-  #password: <secret_password>
+  password: {{ matrix_synapse_redis_password }}
 
 # vim:ft=yaml

roles/matrix-synapse/templates/synapse/systemd/matrix-synapse-worker.service.j2

@@ -0,0 +1,58 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=Synapse worker ({{ matrix_synapse_worker_container_name }})
+AssertPathExists={{ matrix_synapse_config_dir_path }}/{{ matrix_synapse_worker_config_file_name }}
+After=matrix-synapse.service
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+
+ExecStartPre=-{{ matrix_host_command_docker }} kill {{ matrix_synapse_worker_container_name }}
+ExecStartPre=-{{ matrix_host_command_docker }} rm {{ matrix_synapse_worker_container_name }}
+
+# Intentional delay, so that the homeserver can manage to start.
+ExecStartPre={{ matrix_host_command_sleep }} 5
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name {{ matrix_synapse_worker_container_name }} \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--entrypoint=python \
+			--read-only \
+			--tmpfs=/tmp:rw,noexec,nosuid,size={{ matrix_synapse_tmp_directory_size_mb }}m \
+			--network={{ matrix_docker_network }} \
+			{% if matrix_synapse_workers_enabled and matrix_synapse_workers_container_host_bind_address %}
+			{% if matrix_synapse_worker_details.port != 0 %}
+			-p {{ '' if matrix_synapse_workers_container_host_bind_address == '*' else (matrix_synapse_workers_container_host_bind_address + ':') }}{{ matrix_synapse_worker_details.port }}:{{ matrix_synapse_worker_details.port }} \
+			{% endif %}
+			{% if matrix_synapse_worker_details.metrics_port != 0 %}
+			-p {{ '' if matrix_synapse_workers_container_host_bind_address == '*' else (matrix_synapse_workers_container_host_bind_address + ':') }}{{ matrix_synapse_worker_details.metrics_port }}:{{ matrix_synapse_worker_details.metrics_port }} \
+			{% endif %}
+			{% endif %}
+			--mount type=bind,src={{ matrix_synapse_config_dir_path }},dst=/data,ro \
+			--mount type=bind,src={{ matrix_synapse_storage_path }},dst=/matrix-media-store-parent,bind-propagation=slave \
+			{% for volume in matrix_synapse_container_additional_volumes %}
+			-v {{ volume.src }}:{{ volume.dst }}:{{ volume.options }} \
+			{% endfor %}
+			{% for arg in matrix_synapse_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_synapse_docker_image }} \
+			-m synapse.app.{{ matrix_synapse_worker_details.type }} -c /data/homeserver.yaml -c /data/{{ matrix_synapse_worker_config_file_name }}
+
+
+ExecStop=-{{ matrix_host_command_docker }} kill {{ matrix_synapse_worker_container_name }}
+ExecStop=-{{ matrix_host_command_docker }} rm {{ matrix_synapse_worker_container_name }}
+
+ExecReload={{ matrix_host_command_docker }} exec {{ matrix_synapse_worker_container_name }} /bin/sh -c 'kill -HUP 1'
+Restart=always
+RestartSec=30
+SyslogIdentifier={{ matrix_synapse_worker_container_name }}
+
+# Intentionally not making this WantedBy=matrix-synapse.service,
+# as matrix.synapse.service already has `Wants=` lines.
+# Also, WantedBy will trigger the creation of some `matrix-synapse.service.wants/` directory,
+# which we'd have to clean, etc. Better not.
+[Install]
+WantedBy=multi-user.target

roles/matrix-synapse/templates/synapse/systemd/matrix-synapse.service.j2

@@ -4,10 +4,18 @@ Description=Synapse server
 {% for service in matrix_synapse_systemd_required_services_list %}
 Requires={{ service }}
 After={{ service }}
+
 {% endfor %}
 {% for service in matrix_synapse_systemd_wanted_services_list %}
 Wants={{ service }}
 {% endfor %}
+
+{% if matrix_synapse_workers_enabled %}
+{% for matrix_synapse_worker_details in matrix_synapse_workers_enabled_list %}
+Wants=matrix-synapse-worker-{{ matrix_synapse_worker_details.type }}-{{ matrix_synapse_worker_details.port }}.service
+{% endfor %}
+{% endif %}
+
 DefaultDependencies=no
 
 [Service]
@@ -58,7 +66,7 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-synapse \
 
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} kill matrix-synapse 2>/dev/null'
 ExecStop=-{{ matrix_host_command_sh }} -c '{{ matrix_host_command_docker }} rm matrix-synapse 2>/dev/null'
-ExecReload={{ matrix_host_command_docker }} exec matrix-synapse kill -HUP 1
+ExecReload={{ matrix_host_command_docker }} exec matrix-synapse /bin/sh -c 'kill -HUP 1'
 Restart=always
 RestartSec=30
 SyslogIdentifier=matrix-synapse

roles/matrix-synapse/templates/synapse/worker.yaml.j2

@@ -0,0 +1,45 @@
+#jinja2: lstrip_blocks: "True"
+worker_app: synapse.app.{{ matrix_synapse_worker_details.type }}
+worker_name: {{ matrix_synapse_worker_details.type ~ ':' ~ matrix_synapse_worker_details.port }}
+
+{% if matrix_synapse_replication_listener_enabled %}
+worker_replication_host: matrix-synapse
+worker_replication_http_port: {{ matrix_synapse_replication_http_port }}
+{% endif %}
+
+{% set has_listeners = (matrix_synapse_worker_details.type not in [ 'appservice', 'federation_sender', 'pusher' ] or matrix_synapse_metrics_enabled) %}
+
+{% set http_resources = [] %}
+
+{% if matrix_synapse_worker_details.type in ['generic_worker', 'frontend_proxy', 'user_dir'] %}
+  {% set http_resources = http_resources + ['client'] %}
+{% endif %}
+{% if matrix_synapse_worker_details.type in ['generic_worker'] %}
+  {% set http_resources = http_resources+ ['federation'] %}
+{% endif %}
+{% if matrix_synapse_worker_details.type in ['media_repository'] %}
+  {% set http_resources = http_resources + ['media'] %}
+{% endif %}
+
+{% if http_resources|length > 0 or matrix_synapse_metrics_enabled %}
+worker_listeners:
+{% if http_resources|length > 0 %}
+  - type: http
+    bind_addresses: ['::']
+    port: {{ matrix_synapse_worker_details.port }}
+    resources:
+      - names: {{ http_resources|to_json }}
+{% endif %}
+{% if matrix_synapse_metrics_enabled %}
+  - type: metrics
+    bind_addresses: ['0.0.0.0']
+    port: {{ matrix_synapse_worker_details.metrics_port }}
+{% endif %}
+{% endif %}
+
+{% if matrix_synapse_worker_details.type == 'frontend_proxy' %}
+worker_main_http_uri: http://matrix-synapse:8008
+{% endif %}
+
+worker_daemonize: false
+worker_log_config: /data/{{ matrix_server_fqn_matrix }}.log.config

roles/matrix-synapse/vars/main.yml

@@ -8,3 +8,28 @@ matrix_synapse_role_executed: false
 
 matrix_synapse_media_store_parent_path: "{{ matrix_synapse_media_store_path|dirname }}"
 matrix_synapse_media_store_directory_name: "{{ matrix_synapse_media_store_path|basename }}"
+
+# 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)
+# - nor always OK to forward to a worker (we're supposed to obey `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_client_api_enabled`)
+#
+# It's also not too many of these APIs (only `^/_synapse/client/password_reset/email/submit_token$` at the time of this writing / 2021-01-24),
+# so it's not that important whether we forward them or not.
+#
+# Basically, we aim to cover most things. Skipping `/_synapse/client` or a few other minor things doesn't matter too much.
+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/federation|/_matrix/key).*')| list | difference([none]) }}"

roles/matrix-synapse/vars/workers.yml

@@ -0,0 +1,313 @@
+---
+
+matrix_synapse_workers_generic_worker_endpoints:
+  # This worker can handle API requests matching the following regular
+  # expressions:
+
+  # Sync requests
+  - ^/_matrix/client/(v2_alpha|r0)/sync$
+  - ^/_matrix/client/(api/v1|v2_alpha|r0)/events$
+  - ^/_matrix/client/(api/v1|r0)/initialSync$
+  - ^/_matrix/client/(api/v1|r0)/rooms/[^/]+/initialSync$
+
+  # 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/send_join/
+  - ^/_matrix/federation/v2/send_join/
+  - ^/_matrix/federation/v1/send_leave/
+  - ^/_matrix/federation/v2/send_leave/
+  - ^/_matrix/federation/v1/invite/
+  - ^/_matrix/federation/v2/invite/
+  - ^/_matrix/federation/v1/query_auth/
+  - ^/_matrix/federation/v1/event_auth/
+  - ^/_matrix/federation/v1/exchange_third_party_invite/
+  - ^/_matrix/federation/v1/user/devices/
+  - ^/_matrix/federation/v1/get_groups_publicised$
+  - ^/_matrix/key/v2/query
+
+  # Inbound federation transaction request
+  - ^/_matrix/federation/v1/send/
+
+  # Client API requests
+  - ^/_matrix/client/(api/v1|r0|unstable)/publicRooms$
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/joined_members$
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/context/.*$
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/members$
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/state$
+  - ^/_matrix/client/(api/v1|r0|unstable)/account/3pid$
+  - ^/_matrix/client/(api/v1|r0|unstable)/devices$
+  - ^/_matrix/client/(api/v1|r0|unstable)/keys/query$
+  - ^/_matrix/client/(api/v1|r0|unstable)/keys/changes$
+  - ^/_matrix/client/versions$
+  - ^/_matrix/client/(api/v1|r0|unstable)/voip/turnServer$
+  - ^/_matrix/client/(api/v1|r0|unstable)/joined_groups$
+  - ^/_matrix/client/(api/v1|r0|unstable)/publicised_groups$
+  - ^/_matrix/client/(api/v1|r0|unstable)/publicised_groups/
+
+  # Registration/login requests
+  - ^/_matrix/client/(api/v1|r0|unstable)/login$
+  - ^/_matrix/client/(r0|unstable)/register$
+  # FIXME: possible bug with SSO and multiple generic workers
+  # see https://github.com/matrix-org/synapse/issues/7530
+  # ^/_matrix/client/(r0|unstable)/auth/.*/fallback/web$
+
+  # Event sending requests
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/redact
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/send
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/state/
+  - ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/(join|invite|leave|ban|unban|kick)$
+  - ^/_matrix/client/(api/v1|r0|unstable)/join/
+  - ^/_matrix/client/(api/v1|r0|unstable)/profile/
+
+
+  # Additionally, the following REST endpoints can be handled for GET requests:
+
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/federation/v1/groups/
+
+  # Pagination requests can also be handled, but all requests for a given
+  # room must be routed to the same instance. Additionally, care must be taken to
+  # ensure that the purge history admin API is not used while pagination requests
+  # for the room are in flight:
+
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/client/(api/v1|r0|unstable)/rooms/.*/messages$
+
+  # Additionally, the following endpoints should be included if Synapse is configured
+  # to use SSO (you only need to include the ones for whichever SSO provider you're
+  # using):
+
+  # for all SSO providers
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/client/(api/v1|r0|unstable)/login/sso/redirect
+  # ^/_synapse/client/pick_idp$
+  # ^/_synapse/client/pick_username
+  # ^/_synapse/client/new_user_consent$
+  # ^/_synapse/client/sso_register$
+
+  # OpenID Connect requests.
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_synapse/client/oidc/callback$
+
+  # SAML requests.
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_synapse/client/saml2/authn_response$
+
+  # CAS requests.
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/client/(api/v1|r0|unstable)/login/cas/ticket$
+
+  # Ensure that all SSO logins go to a single process.
+  # For multiple workers not handling the SSO endpoints properly, see
+  # [#7530](https://github.com/matrix-org/synapse/issues/7530).
+
+  # Note that a HTTP listener with `client` and `federation` resources must be
+  # configured in the `worker_listeners` option in the worker config.
+
+  # #### Load balancing
+
+  # It is possible to run multiple instances of this worker app, with incoming requests
+  # being load-balanced between them by the reverse-proxy. However, different endpoints
+  # have different characteristics and so admins
+  # may wish to run multiple groups of workers handling different endpoints so that
+  # load balancing can be done in different ways.
+
+  # For `/sync` and `/initialSync` requests it will be more efficient if all
+  # requests from a particular user are routed to a single instance. Extracting a
+  # user ID from the access token or `Authorization` header is currently left as an
+  # exercise for the reader. Admins may additionally wish to separate out `/sync`
+  # requests that have a `since` query parameter from those that don't (and
+  # `/initialSync`), as requests that don't are known as "initial sync" that happens
+  # when a user logs in on a new device and can be *very* resource intensive, so
+  # isolating these requests will stop them from interfering with other users ongoing
+  # syncs.
+
+  # Federation and client requests can be balanced via simple round robin.
+
+  # The inbound federation transaction request `^/_matrix/federation/v1/send/`
+  # should be balanced by source IP so that transactions from the same remote server
+  # go to the same process.
+
+  # Registration/login requests can be handled separately purely to help ensure that
+  # unexpected load doesn't affect new logins and sign ups.
+
+  # Finally, event sending requests can be balanced by the room ID in the URI (or
+  # the full URI, or even just round robin), the room ID is the path component after
+  # `/rooms/`. If there is a large bridge connected that is sending or may send lots
+  # of events, then a dedicated set of workers can be provisioned to limit the
+  # effects of bursts of events from that bridge on events sent by normal users.
+
+  # #### Stream writers
+
+  # Additionally, there is *experimental* support for moving writing of specific
+  # streams (such as events) off of the main process to a particular worker. (This
+  # is only supported with Redis-based replication.)
+
+  # Currently supported streams are `events` and `typing`.
+
+  # To enable this, the worker must have a HTTP replication listener configured,
+  # have a `worker_name` and be listed in the `instance_map` config. For example to
+  # move event persistence off to a dedicated worker, the shared configuration would
+  # include:
+
+  # ```yaml
+  # instance_map:
+  #     event_persister1:
+  #         host: localhost
+  #         port: 8034
+
+  # stream_writers:
+  #     events: event_persister1
+  # ```
+
+  # The `events` stream also experimentally supports having multiple writers, where
+  # work is sharded between them by room ID. Note that you *must* restart all worker
+  # instances when adding or removing event persisters. An example `stream_writers`
+  # configuration with multiple writers:
+
+  # ```yaml
+  # stream_writers:
+  #     events:
+  #         - event_persister1
+  #         - event_persister2
+  # ```
+
+  # #### Background tasks
+
+  # There is also *experimental* support for moving background tasks to a separate
+  # worker. Background tasks are run periodically or started via replication. Exactly
+  # which tasks are configured to run depends on your Synapse configuration (e.g. if
+  # stats is enabled).
+
+  # To enable this, the worker must have a `worker_name` and can be configured to run
+  # background tasks. For example, to move background tasks to a dedicated worker,
+  # the shared configuration would include:
+
+  # ```yaml
+  # run_background_tasks_on: background_worker
+  # ```
+
+  # You might also wish to investigate the `update_user_directory` and
+  # `media_instance_running_background_jobs` settings.
+
+# pusher worker (no API endpoints) [
+  # Handles sending push notifications to sygnal and email. Doesn't handle any
+  # REST endpoints itself, but you should set `start_pushers: False` in the
+  # shared configuration file to stop the main synapse sending push notifications.
+
+  # Note this worker cannot be load-balanced: only one instance should be active.
+# ]
+
+# appservice worker (no API endpoints) [
+  # Handles sending output traffic to Application Services. Doesn't handle any
+  # REST endpoints itself, but you should set `notify_appservices: False` in the
+  # shared configuration file to stop the main synapse sending appservice notifications.
+
+  # Note this worker cannot be load-balanced: only one instance should be active.
+
+# ]
+
+# federation_sender worker (no API endpoints) [
+  # Handles sending federation traffic to other servers. Doesn't handle any
+  # REST endpoints itself, but you should set `send_federation: False` in the
+  # shared configuration file to stop the main synapse sending this traffic.
+
+  # If running multiple federation senders then you must list each
+  # instance in the `federation_sender_instances` option by their `worker_name`.
+  # All instances must be stopped and started when adding or removing instances.
+  # For example:
+
+  # ```yaml
+  # federation_sender_instances:
+  #     - federation_sender1
+  #     - federation_sender2
+  # ```
+# ]
+
+matrix_synapse_workers_media_repository_endpoints:
+  # Handles the media repository. It can handle all endpoints starting with:
+
+  - ^/_matrix/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/.*$
+
+  # You should also set `enable_media_repo: False` in the shared configuration
+  # file to stop the main synapse running background jobs related to managing the
+  # media repository.
+
+  # In the `media_repository` worker configuration file, configure the http listener to
+  # expose the `media` resource. For example:
+
+  # ```yaml
+  #     worker_listeners:
+  #      - type: http
+  #        port: 8085
+  #        resources:
+  #          - names:
+  #            - media
+  # ```
+
+  # Note that if running multiple media repositories they must be on the same server
+  # and you must configure a single instance to run the background tasks, e.g.:
+
+  # ```yaml
+  #     media_instance_running_background_jobs: "media-repository-1"
+  # ```
+
+  # Note that if a reverse proxy is used , then `/_matrix/media/` must be routed for both inbound client and federation requests (if they are handled separately).
+
+matrix_synapse_workers_user_dir_endpoints:
+  # Handles searches in the user directory. It can handle REST endpoints matching
+  # the following regular expressions:
+
+  - ^/_matrix/client/(api/v1|r0|unstable)/user_directory/search$
+
+  # When using this worker you must also set `update_user_directory: False` in the
+  # shared configuration file to stop the main synapse running background
+  # jobs related to updating the user directory.
+
+matrix_synapse_workers_frontend_proxy_endpoints:
+  # Proxies some frequently-requested client endpoints to add caching and remove
+  # load from the main synapse. It can handle REST endpoints matching the following
+  # regular expressions:
+
+  - ^/_matrix/client/(api/v1|r0|unstable)/keys/upload
+
+  # If `use_presence` is False in the homeserver config, it can also handle REST
+  # endpoints matching the following regular expressions:
+
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/client/(api/v1|r0|unstable)/presence/[^/]+/status
+
+  # This "stub" presence handler will pass through `GET` request but make the
+  # `PUT` effectively a no-op.
+
+  # It will proxy any requests it cannot handle to the main synapse instance. It
+  # must therefore be configured with the location of the main instance, via
+  # the `worker_main_http_uri` setting in the `frontend_proxy` worker configuration
+  # file. For example:
+
+  #     worker_main_http_uri: http://127.0.0.1:8008
+
+matrix_synapse_workers_avail_list:
+  - appservice
+  - federation_sender
+  - frontend_proxy
+  - generic_worker
+  - media_repository
+  - pusher
+  - user_dir