Synapse v1.152 introduces a new `quarantined_media_changes` stream and
requires that any worker serving `/_synapse/admin/v1/quarantine_media/`
be declared as a writer for that stream. Otherwise quarantining media
fails on the worker.
Add `quarantined_media_changes` as a web-facing stream writer alongside
the other stream-backed APIs and route the admin endpoint via the same
explicit writer-or-main model used for `device_lists`, `thread_subscriptions`,
etc. The endpoint is removed from `matrix_synapse_workers_media_repository_endpoints`
so the old media-repository route does not shadow (or conflict with) the
new writer-or-main route. Without that move, the previously-shipping
default of routing `/quarantine_media` to the `media_repository` worker
would silently break after the v1.152.0 image bump.
Default count is 1 in the `one-of-each` and `specialized-workers` presets
(matching `device_lists`), and 0 in `little-federation-helper` (which
also has no media-repository worker, so falling back to main is fine).
Refs:
- https://github.com/element-hq/synapse/blob/develop/docs/upgrade.md#upgrading-to-v11520
- https://element-hq.github.io/synapse/latest/workers.html#the-quarantined_media_changes-stream
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add `thread_subscriptions` as a supported web-facing stream writer in MDAD and
route its unstable client endpoints via the same explicit writer-or-main model
used for the other web-facing stream-backed APIs.
This is not just another generic worker route. Current Synapse gives thread
subscriptions their own `writers.thread_subscriptions` configuration, backs them
with a multi-writer stream, and asserts on store writes that the current
instance is an allowed thread-subscriptions writer.
Explicit early routing is also required here because the subscription endpoint is
room-scoped. In MDAD's specialized-worker model, the existing room-worker regex
would otherwise match `/_matrix/client/unstable/io.element.msc4306/rooms/...`
and steal the request before it reached the correct writer-or-main fallback.
Unlike `device_lists`, support is added without enabling a thread-subscriptions
worker by default in the standard presets. The underlying MSC4306/4308 feature
remains unstable and disabled by default upstream, so the conservative default
is to keep the worker count at `0` and let the new explicit routes fall back to
`main` unless an operator opts in.
Refs:
- b99a58719b/synapse/config/workers.py (L175-L182)
- b99a58719b/synapse/rest/client/thread_subscriptions.py (L38-L247)
- b99a58719b/synapse/storage/databases/main/thread_subscriptions.py (L66-L83)
- b99a58719b/synapse/storage/databases/main/thread_subscriptions.py (L192-L322)
The client_reader route bucket had collapsed into one long alternation,
which made small worker-audit edits hard to review. Any endpoint change
rewrote the whole regex and obscured whether we were changing routing
policy or just maintaining the route list.
Refactor the variable into grouped regex entries with comments instead.
This keeps the current specialized-worker policy intact: nginx still
renders the client_reader locations in the same block, and the routes
still target the same upstream bucket. The goal here is to make future
doc/code audits, additions, and removals mechanical and reviewable.
This also matches MDAD's current worker model, where generic workers are
not mixed with the specialized room/sync/client/federation reader
routing buckets, so there is no need to derive this from the generic
worker map.
Refs:
- b99a58719b/docs/workers.md (historical-apps)
- b99a58719b/docs/workers.md (synapseappgeneric_worker)
Current Synapse registers the MatrixRTC transport discovery endpoint on
client-serving workers when MSC4143 is enabled, but MDAD does not model
that path in either its client-reader bucket or its broader generic-
worker endpoint list.
Add the unstable MatrixRTC transport discovery route so MDAD's worker
routing matches the current upstream worker surface for this endpoint.
This is a small, isolated routing addition for a simple authenticated
GET endpoint.
Refs:
- b99a58719b/synapse/rest/client/matrixrtc.py (L30-L52)
- b99a58719b/synapse/rest/__init__.py (L81-L129)
- b99a58719b/synapse/rest/__init__.py (L179-L197)
Current Synapse still documents and registers
`/_matrix/client/.../account/deactivate` on client-serving workers when
auth is not delegated. MDAD already routes neighboring account endpoints
such as `account/3pid` and `account/whoami`, but it omitted
`account/deactivate` from both its client-reader bucket and its broader
generic-worker endpoint list.
Add the missing route patterns so MDAD's worker routing matches the
current upstream worker surface in non-delegated-auth deployments. In
MAS / MSC3861 mode the endpoint is not registered upstream anyway, so
this does not expand the effective delegated-auth surface.
Refs:
- b99a58719b/docs/workers.md (synapseappgeneric_worker)
- b99a58719b/synapse/rest/client/account.py (L284-L324)
- b99a58719b/synapse/rest/client/account.py (L913-L920)
Synapse currently supports both the deprecated
`/_matrix/client/unstable/im.nheko.summary/rooms/<room>/summary`
route and the recommended
`/_matrix/client/unstable/im.nheko.summary/summary/<room>`
form. MDAD only matched the deprecated shape.
Add the recommended pattern alongside the old one so worker routing
matches the current upstream API surface while preserving backward
compatibility for the deprecated path.
Refs:
- b99a58719b/docs/workers.md (synapseappgeneric_worker)
- b99a58719b/synapse/rest/client/room.py (L1716-L1728)
Current Synapse no longer exposes device management under
`/_matrix/client/.../account/devices`. The live client API shape is
`/devices`, `/devices/{device_id}`, and `/delete_devices`, and
MDAD already routes those real device-list-sensitive endpoints through
explicit device-list handling.
Keeping `account/devices` in the old client-reader regex therefore only
preserves stale route-model residue. While touching the same area,
refresh the `/_synapse/client/*` comment to reflect current Synapse:
client-serving generic workers now mount a meaningful Synapse-specific
client tree there, but MDAD still intentionally keeps those paths out of
its broad worker regexes because they are deployment-sensitive and
auth-sensitive.
Refs:
- b99a58719b/docs/workers.md (historical-apps)
- b99a58719b/synapse/rest/client/devices.py (L49-L150)
- b99a58719b/synapse/rest/synapse/client/__init__.py (L39-L88)
Some client API endpoints (e.g. keys/upload) are backed by Synapse stream writers and
should not rely on broad worker regexes or route-order fallthrough for correctness.
When explicit per-stream routing is missing, requests may be captured by generic, room, or client_reader workers, instead of:
- going to the configured stream writer
- or to `main` when that stream writer is not enabled
This refactors synapse-reverse-proxy-companion's routing so that web-facing stream-backed endpoint families
are handled explicitly and early, with deterministic writer-or-main fallback.
Add first-class support for the missing `device_lists` stream writer,
generalize the same routing model to `push_rules`,
and remove stale broad-route ownership for device-list-sensitive endpoints.
Issues and Pull Requests were not migrated to the new
organization/repository, so `matrix-org/synapse/pull` and
`matrix-org/synapse/issues` references were kept as-is.
`matrix-org/synapse-s3-storage-provider` references were also kept,
as that module still continues living under the `matrix-org` organization.
This patch mainly aims to change documentation-related things, not actual
usage in full yet. For polish that, another more comprehensive patch is coming later.
This also updates validation tasks and documentation, pointing to
variables in the matrix-synapse role which don't currently exist yet
(e.g. `matrix_synapse_container_labels_client_synapse_admin_api_enabled`).
These variables will be added soon, as Traefik labels are added to the
`matrix-synapse` role. At that point, the `matrix-synapse-reverse-proxy-companion` role
will be updated to also use them.
This was useful when the order of these roles in relation to Synapse
mattered (when we were injecting stuff into Synapse variables during
runtime). This is no longer the case since 0ea7cb5d1812a88, so all of
this can be removed.
As stream writer workers are also powered by the `generic_worker`
Synapse app, this necessitated that we provide means for distinguishing
between them and regular `generic_workers`.
I've also taken the time to optimize nginx configuration generation
(more Jinja2 macro usage, less duplication).
Worker names have also changed.
Workers are now named sequentially like this:
- `matrix-synapse-worker-0-generic`
- `matrix-synapse-worker-1-stream-writer-typing`
- `matrix-synapse-worker-2-pusher`
instead of `matrix-synapse-worker_generic_worker-18111` (indexed with a
port number).
People who modify `matrix_synapse_workers_enabled_list` directly will
need to adjust their configuration.
I guess it didn't hurt to do it until now, but it's not great serving
federation APIs on the client-server API port, etc.
matrix-corporal doesn't work yet (still something to be solved in the
future), but its firewalling operations will also be sabotaged
by Client-Server APIs being served on the federation port (it's a way to get around its firewalling).
Slavi Pantaleev
Suguru Hirahara
Charles Wright
Alexis Yushin
Aine
Michael Collins