Fediversity/matrix/nginx/workers/README.md

---
gitea: none
include_toc: true
---

# Reverse proxy for Synapse with workers

Changing nginx's configuration from a reverse proxy for a normal, monolithi
Synapse to one for a Synapse that uses workers, quite a lot has to be changed.

As mentioned in [Synapse with workers](../synapse/workers.md#synapse), we're
changing from network sockets to UNIX sockets.

Because we're going to have to forward a lot of specific requests to all kinds
of workers, we'll split the configuration into a few bits:

* all `proxy_forward` settings
* all `location` definitions
* maps that define variables
* upstreams that point to the correct socket(s) with the correct settings
* settings for private access
* connection optimizations

Some of these go into `/etc/nginx/conf.d` because they are part of the
configuration of nginx itself, others go into `/etc/nginx/snippets` because we
need to include them several times in different places.


# Maps

A map sets a variable based on, usually, another variable. One case we use is
determining the type of sync a client is doing. A normal sync, simply
updating an existing session, is a rather lightweight operation.

An initial sync, meaning a full sync because the session is brand new, is not
so lightweight.

A normal sync can be recognised by the `since` bit in the request: it tells
the server when its last sync was. If there is no `since`, we're dealing with
an initial sync.

Initial syncs are forwarded to the `initial_sync` workers, the normal syncs to
`normal_sync`.

We decide to which type of worker to forward the sync request to by looking at
the presence or absence of `since`: if it's there, it's a normal sync and we
set the variable `$sync` to `normal_sync`. If it's not there, we set `$sync` to
`initial_sync`. 

The last bit is to foward the request to the upstream `$sync`. This is what
that map looks like:

```
map $arg_since $sync {
    default normal_sync;
    '' initial_sync;
}
```

We filter the argument `since` by using `$arg_since`, see [the index of
variables in nginx](https://nginx.org/en/docs/varindex.html) for more
variables we can use.

By default we set `$sync` to `normal_sync`, unless the argument `since` is
empty (absent); then we set `$sync` to `initial_sync`.

After that, we forward the request:

```
proxy_pass http://$sync;
```