Files
matrix-docker-ansible-deploy/roles/custom/matrix-synapse-reverse-proxy-companion/templates/nginx/nginx.conf.j2
Slavi Pantaleev 5cc69ca7eb Add whoami-based sync worker routing for user-level sticky sessions
This adds a new routing mechanism for sync workers that resolves access tokens
to usernames via Synapse's whoami endpoint, enabling true user-level sticky
routing regardless of which device or token is used.

Previously, sticky routing relied on parsing the username from native Synapse
tokens (`syt_<base64 username>_...`), which only works with native Synapse auth
and provides device-level stickiness at best. This new approach works with any
auth system (native Synapse, MAS, etc.) because Synapse handles token validation
internally.

Implementation uses nginx's auth_request module with an njs script because:
- The whoami lookup requires an async HTTP subrequest (ngx.fetch)
- js_set handlers must return synchronously and don't support async operations
- auth_request allows the async lookup to complete, then captures the result
  via response headers into nginx variables

The njs script:
- Extracts access tokens from Authorization header or query parameter
- Calls Synapse's whoami endpoint to resolve token -> username
- Caches results in a shared memory zone to minimize latency
- Returns the username via a `X-User-Identifier` header

The username is then used by nginx's upstream hash directive for consistent
worker selection. This leverages nginx's built-in health checking and failover.
2026-02-04 04:06:59 +02:00

94 lines
3.7 KiB
Django/Jinja

#jinja2: lstrip_blocks: True
# This is a custom nginx configuration file that we use in the container (instead of the default one),
# because it allows us to run nginx with a non-root user.
#
# For this to work, the default vhost file (`/etc/nginx/conf.d/default.conf`) also needs to be removed.
#
# The following changes have been done compared to a default nginx configuration file:
# - various temp paths are changed to `/tmp`, so that a non-root user can write to them
# - the `user` directive was removed, as we don't want nginx to switch users
# load_module directives must be first or nginx will choke with:
# > [emerg] "load_module" directive is specified too late.
{% if matrix_synapse_reverse_proxy_companion_njs_enabled %}
load_module modules/ngx_http_js_module.so;
{% endif %}
worker_processes {{ matrix_synapse_reverse_proxy_companion_worker_processes }};
error_log /var/log/nginx/error.log warn;
pid /tmp/nginx.pid;
{% for configuration_block in matrix_synapse_reverse_proxy_companion_additional_configuration_blocks %}
{{- configuration_block }}
{% endfor %}
events {
worker_connections {{ matrix_synapse_reverse_proxy_companion_worker_connections }};
{% for configuration_block in matrix_synapse_reverse_proxy_companion_event_additional_configuration_blocks %}
{{- configuration_block }}
{% endfor %}
}
http {
proxy_temp_path /tmp/proxy_temp;
client_body_temp_path /tmp/client_temp;
fastcgi_temp_path /tmp/fastcgi_temp;
uwsgi_temp_path /tmp/uwsgi_temp;
scgi_temp_path /tmp/scgi_temp;
include /etc/nginx/mime.types;
default_type application/octet-stream;
{% if matrix_synapse_reverse_proxy_companion_njs_enabled %}
js_path /njs/;
{% endif %}
{% if matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_enabled %}
# njs module for whoami-based sync worker routing
js_import whoami_sync_worker_router from whoami_sync_worker_router.js;
js_shared_dict_zone zone=whoami_sync_worker_router_cache:{{ matrix_synapse_reverse_proxy_companion_whoami_sync_worker_router_cache_size_mb }}m;
{% endif %}
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
{% if matrix_synapse_reverse_proxy_companion_access_log_enabled %}
access_log /var/log/nginx/access.log main;
{% else %}
access_log off;
{% endif %}
{% if matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_enabled %}
log_format prometheus_fmt 'matrix-synapse-reverse-proxy-companion $server_name - $upstream_addr - $remote_addr - $remote_user [$time_local] '
'$host "$request" '
'$status "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log syslog:server={{ matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_server_port }},tag={{ matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_tag }} prometheus_fmt;
{% endif %}
{% if not matrix_synapse_reverse_proxy_companion_access_log_enabled and not matrix_synapse_reverse_proxy_companion_access_log_syslog_integration_enabled %}
access_log off;
{% endif %}
proxy_connect_timeout {{ matrix_synapse_reverse_proxy_companion_proxy_connect_timeout }};
proxy_send_timeout {{ matrix_synapse_reverse_proxy_companion_proxy_send_timeout }};
proxy_read_timeout {{ matrix_synapse_reverse_proxy_companion_proxy_read_timeout }};
send_timeout {{ matrix_synapse_reverse_proxy_companion_send_timeout }};
sendfile on;
#tcp_nopush on;
keepalive_timeout 65;
server_tokens off;
{# Map directive needed for proxied WebSocket upgrades #}
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
include /etc/nginx/conf.d/*.conf;
}