Track workers endpoint list in repo instead of regenerating on user side

.gitignore

@@ -3,7 +3,5 @@
 !/inventory/host_vars/.gitkeep
 !/inventory/scripts
 /roles/*/files/scratchpad
-/roles/matrix-synapse/files/workers.upstream-documentation.md
-/roles/matrix-synapse/vars/workers.yml
 .DS_Store
 .python-version

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/workers/setup_install.yml

@@ -1,21 +1,5 @@
 ---
 
-- name: Download synapse workers doc
-  local_action:
-    module: get_url
-    url: https://github.com/matrix-org/synapse/raw/master/docs/workers.md
-    dest: "{{ role_path }}/files/workers.upstream-documentation.md"
-  vars:
-    ansible_become: no
-
-- name: Download synapse workers doc and convert into YAML
-  local_action:
-    module: shell
-    cmd: "awk -f '{{ role_path }}/files/workers-doc-to-yaml.awk' -- '{{ role_path }}/files/workers.upstream-documentation.md' > '{{ role_path }}/vars/workers.yml'"
-    creates: "{{ role_path }}/vars/workers.yml"
-  vars:
-    ansible_become: no
-
 - name: Load list of available worker apps and endpoints
   include_vars: "{{ role_path }}/vars/workers.yml"
 

roles/matrix-synapse/vars/workers.yml

@@ -0,0 +1,308 @@
+---
+
+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)/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/
+  - ^/_synapse/client/password_reset/email/submit_token$
+
+  # 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):
+
+  # OpenID Connect requests.
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/client/(api/v1|r0|unstable)/login/sso/redirect$
+  # ^/_synapse/oidc/callback$
+
+  # SAML requests.
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/client/(api/v1|r0|unstable)/login/sso/redirect$
+  # ^/_matrix/saml2/authn_response$
+
+  # CAS requests.
+  # FIXME: ADDITIONAL CONDITIONS REQUIRED: to be enabled manually
+  # ^/_matrix/client/(api/v1|r0|unstable)/login/(cas|sso)/redirect$
+  # ^/_matrix/client/(api/v1|r0|unstable)/login/cas/ticket$
+
+  # Note that a HTTP listener with `client` and `federation` resources must be
+  # configured in the `worker_listeners` option in the worker config.
+
+  # Ensure that all SSO logins go to a single process (usually the main process). 
+  # For multiple workers not handling the SSO endpoints properly, see
+  # [#7530](https://github.com/matrix-org/synapse/issues/7530).
+
+  # #### 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