# Configuration

Warp reads one YAML file. Every setting can also come from the
environment, and the environment wins. With no file at all the defaults
plus `WARP_*` variables are used, which is how the container image runs.

Where the file comes from, in order:

1. `--config <path>`
2. `$WARP_CONFIG`
3. `./warp.yaml`, if it exists
4. nothing — defaults and environment only

An unknown field is a fatal error. A typo in a security-relevant setting
must not be ignored.

List-valued variables are comma-separated. A single `-` clears a list:
`WARP_CORS_ALLOWED_ORIGINS=-`.

## Settings

| YAML | Environment | Default | Notes |
|---|---|---|---|
| `global.server_name` | `WARP_SERVER_NAME` | — | Required. Part of every ID; cannot be changed later. |
| `global.private_key` | `WARP_PRIVATE_KEY` | `./keys/signing.key` | Written by `warp generate-keys`. |
| `global.well_known.client_base_url` | `WARP_WELL_KNOWN_CLIENT_BASE_URL` | `https://<server_name>` | Advertised to clients. |
| `global.well_known.identity_server_base_url` | `WARP_WELL_KNOWN_IDENTITY_SERVER_BASE_URL` | empty | Omitted from the document when empty. |
| `global.well_known.server_address` | `WARP_WELL_KNOWN_SERVER_ADDRESS` | empty | `host:port` for other homeservers. Empty = no delegation, other servers fall back to SRV/A. |
| `listen.address` | `WARP_LISTEN_ADDRESS` | `:8008` | |
| `listen.read_header_timeout` | `WARP_READ_HEADER_TIMEOUT` | `10s` | |
| `listen.read_timeout` | `WARP_READ_TIMEOUT` | `60s` | |
| `listen.write_timeout` | `WARP_WRITE_TIMEOUT` | `120s` | Must stay above `sync.long_poll_timeout`, or a blocked `/sync` is cut off before it can answer. |
| `listen.idle_timeout` | `WARP_IDLE_TIMEOUT` | `120s` | |
| `listen.max_header_bytes` | `WARP_MAX_HEADER_BYTES` | `1048576` | |
| `listen.shutdown_timeout` | `WARP_SHUTDOWN_TIMEOUT` | `30s` | Grace period for in-flight requests. |
| `database.driver` | `WARP_DB_DRIVER` | `sqlite` | `sqlite`, `postgres`, `pocketbase` (not implemented). |
| `database.connection_string` | `WARP_DB_CONNECTION_STRING` | SQLite file in the working directory | |
| `database.max_open_conns` | `WARP_DB_MAX_OPEN_CONNS` | `10` | Ignored by SQLite: writes are serialised onto one connection. |
| `database.max_idle_conns` | `WARP_DB_MAX_IDLE_CONNS` | `5` | |
| `database.conn_max_lifetime` | `WARP_DB_CONN_MAX_LIFETIME` | `1h` | |
| `database.auto_migrate` | `WARP_DB_AUTO_MIGRATE` | `true` | `false` makes startup fail while migrations are pending. |
| `client_api.cors_allowed_origins` | `WARP_CORS_ALLOWED_ORIGINS` | `["*"]` | The spec expects any origin. |
| `client_api.trust_x_forwarded_for` | `WARP_TRUST_X_FORWARDED_FOR` | `false` | Only behind a proxy that overwrites the header; the rate limiter keys on the result. |
| `client_api.access_token_lifetime` | `WARP_ACCESS_TOKEN_LIFETIME` | `0s` | `0` = never expire. With a lifetime, clients may ask for a refresh token at login. |
| `client_api.refresh_token_lifetime` | `WARP_REFRESH_TOKEN_LIFETIME` | `0s` | `0` = never expire. |
| `client_api.rate_limit.enabled` | `WARP_RATE_LIMIT_ENABLED` | `true` | |
| `client_api.rate_limit.default.burst` / `.interval` | — | `30` / `100ms` | Every rate-limited endpoint without its own bucket. |
| `client_api.rate_limit.login.burst` / `.interval` | — | `10` / `1s` | `/login` and `/refresh`. |
| `client_api.rate_limit.register.burst` / `.interval` | — | `5` / `2s` | `/register` and `/register/available`. |
| `client_api.rate_limit.room_create.burst` / `.interval` | — | `10` / `1s` | `/createRoom`, which writes a dozen events per call. |
| `client_api.rate_limit.join.burst` / `.interval` | — | `10` / `1s` | The two join endpoints. |
| `client_api.rate_limit.sync.burst` / `.interval` | — | `100` / `20ms` | `/sync` and the writes behind it: typing, receipts, to-device, presence. |
| `sync.presence` | `WARP_SYNC_PRESENCE` | `false` | Off by default; see below. |
| `sync.typing_timeout` | `WARP_SYNC_TYPING_TIMEOUT` | `30s` | How long a typing notification lasts, and the cap on what a client may ask for. |
| `sync.long_poll_timeout` | `WARP_SYNC_LONG_POLL_TIMEOUT` | `30s` | The cap on a `/sync` `?timeout=`. |
| `federation.enabled` | `WARP_FEDERATION_ENABLED` | `false` | |
| `federation.allowlist` | `WARP_FEDERATION_ALLOWLIST` | `[]` | Non-empty = federate only with these. |
| `federation.denylist` | `WARP_FEDERATION_DENYLIST` | `[]` | Always wins over the allowlist. |
| `federation.allow_runtime_toggle` | `WARP_FEDERATION_ALLOW_RUNTIME_TOGGLE` | `true` | See below. |
| `registration.enabled` | `WARP_REGISTRATION_ENABLED` | `false` | |
| `registration.allow_runtime_toggle` | `WARP_REGISTRATION_ALLOW_RUNTIME_TOGGLE` | `true` | |
| `registration.tokens` | `WARP_REGISTRATION_TOKENS` | `[]` | Non-empty = sign-up also needs one of these, as the `m.login.registration_token` stage. |
| `logging.level` | `WARP_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error`. |
| `logging.format` | `WARP_LOG_FORMAT` | `text` | `text` or `json`. |
| `logging.add_source` | `WARP_LOG_ADD_SOURCE` | `false` | File and line in every record. |
| `metrics.enabled` | `WARP_METRICS_ENABLED` | `true` | |
| `metrics.path` | `WARP_METRICS_PATH` | `/metrics` | Served on the same listener. |

The rate limit buckets share one Go type, so per-bucket environment
variables would all collide on the same name; they are YAML only.
`WARP_RATE_LIMIT_ENABLED=false` turns the whole limiter off, which is what a
test harness wants.

## Rate limiting

Each bucket allows `burst` requests back to back and returns one slot every
`interval`, keyed per client address. Over the limit is
`429 M_LIMIT_EXCEEDED` with a `retry_after_ms` the client is expected to
honour.

Buckets are per endpoint class, so a client hammering `/login` cannot spend
the budget of `/profile`. The key is the client address and not the user,
because the limiter runs before the access token is resolved — a limiter
that had to query the database to find its own key would be a denial of
service of its own. Behind a reverse proxy, set
`client_api.trust_x_forwarded_for: true`, or every client shares one bucket.

The admin API under `/_warp/admin/v1` is not rate limited: it needs an admin
token, and bulk operations from the panel are exactly the traffic a limiter
would get in the way of.

## Presence

`sync.presence` is off by default. Presence — who is online, and the status
message they set — is the noisiest thing in Matrix: every user's state
change is published to everybody they share a room with, which over
federation is quadratic in the worst case. Synapse deployments routinely
turn it off for that reason, and a private homeserver with a dozen users
gains little from it.

With it off:

- `GET` and `PUT /presence/{userId}/status` answer `403 M_FORBIDDEN`. They
  are deliberately not unregistered: a client that gets a 404 from
  `/presence` concludes the server is too old to have it and stops asking,
  where a refusal says this one has it switched off.
- The `presence` section of a `/sync` response is empty.
- `?set_presence=` on `/sync` is ignored rather than refused — it rides on
  every sync a client sends, and failing them all would make the server
  unusable.

It is a boot-time setting, not a runtime one: turning it on starts
publishing a stream that nothing was tracking before, and a server that
could do that mid-flight would owe every connected client a resync.

## Long polling

`/sync` holds a request open until something happens or the timeout
expires, so `listen.write_timeout` has to stay above
`sync.long_poll_timeout` — otherwise the listener cuts off a blocked sync
before it can answer, and the client sees a dropped connection instead of
an empty response.

Raising `sync.long_poll_timeout` does not make a client hear about messages
sooner: a blocked sync is woken the moment anything concerning it is
written. All the timeout decides is how often an idle client
re-establishes its request.

## Settings that change at runtime

`federation.enabled` and `registration.enabled` are also stored in the
`server_settings` database table, which is what the admin API writes to.

- With `allow_runtime_toggle: true` (the default) the stored value wins
  over the config file at boot, and the admin API may change it. The
  change takes effect on the next request; no restart.
- With `allow_runtime_toggle: false` the config file is authoritative and
  the admin API refuses to change the setting. Any previously stored value
  is kept but ignored, so re-enabling the toggle restores the
  administrator's last choice.

Everything else is read once at startup.

## What federation off actually means

While `federation.enabled` is false:

- `/.well-known/matrix/server` answers `404 M_UNRECOGNIZED`, and so will
  `/_matrix/federation/*` and `/_matrix/key/*` once they exist.
- Nothing outbound runs — in Phase 0 there is nothing outbound yet; from
  Phase 5 the transaction queue, key fetcher and remote media fetch stay
  stopped.
- Client-Server endpoints that would need a remote server answer
  `M_FORBIDDEN` with a message saying federation is disabled.
- Events are still signed with the server key, and room and event IDs are
  unchanged. A room created while federation is off federates normally
  once it is switched on.