From 93f626446655d28748e74558452341acb08d2df5 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Wed, 4 Feb 2026 03:53:31 +0200 Subject: [PATCH] Add CHANGELOG entry for whoami-based sync worker routing --- CHANGELOG.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d251894f0..7f8435ebc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,30 @@ +# 2026-02-04 + +## Whoami-based sync worker routing for improved sticky sessions for Synapse + +Deployments using [Synapse workers](./docs/configuring-playbook-synapse.md#load-balancing-with-workers) now benefit from improved sync worker routing via a new whoami-based mechanism (making use of the [whoami Matrix Client-Server API](https://spec.matrix.org/v1.17/client-server-api/#get_matrixclientv3accountwhoami)). + +Previously, sticky routing for sync workers relied on parsing usernames from access tokens, which only worked with native Synapse tokens (`syt__...`). This approach failed for [Matrix Authentication Service](docs/configuring-playbook-matrix-authentication-service.md) (MAS) deployments, where tokens are opaque and don't contain username information. This resulted in device-level stickiness (same token → same worker) rather than user-level stickiness (same user → same worker regardless of device), leading to suboptimal cache utilization on sync workers. + +The new implementation calls Synapse's `/whoami` endpoint to resolve access tokens to usernames, enabling proper user-level sticky routing regardless of the authentication system in use (native Synapse auth, MAS, etc.). Results are cached to minimize overhead. + +This change: +- **Automatically enables** when sync workers are configured (no action required) +- **Works universally** with any authentication system +- **Replaces the old implementation** entirely to keep the codebase simple +- **Adds minimal overhead** (one cached internal subrequest per sync request) for non-MAS deployments + +For debugging, you can enable verbose logging and/or response headers showing routing decisions: + +```yaml +# Logs cache hits/misses and routing decisions to the container's stderr +matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_logging_enabled: true + +# Adds X-Sync-Worker-Router-User-Identifier and X-Sync-Worker-Router-Upstream headers to sync responses +matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_debug_headers_enabled: true +``` + + # 2025-12-09 ## Traefik Cert Dumper upgrade