tajniak81andClaude Opus 5.5
6aaf554336
CI / Test (ubuntu-latest) (push) Canceled after 0s
CI / Test (windows-latest) (push) Canceled after 0s
CI / Storage tests on PostgreSQL (push) Canceled after 0s
CI / Complement (federation off) (push) Canceled after 0s
CI / golangci-lint (push) Canceled after 0s
CI / Smoke test the binary (push) Canceled after 0s
Implements PLAN.md Phase 5: the Server-Server API. Warp joins rooms on other servers and lets their users join its rooms, invites across servers with the invitee's server countersigning, rejects remote invites (locally if the inviter is unreachable), and exchanges events, typing, receipts and to-device messages with other homeservers — all behind the runtime switch, which now starts and stops real outbound traffic. The protocol lives in internal/federation with no knowledge of rooms: X-Matrix signing (fuzzed parser), the spec's discovery algorithm keeping the dial address and the TLS name apart, a signed client that refuses every request while the switch is off or the policy denies the destination, and a key ring that caches other servers' keys for at most a week, with optional notaries. The roomserver takes events from elsewhere through the spec's intake: signatures and hashes (a hash mismatch keeps the redacted form), the rules against the event's own auth events, against the state before it — with /get_missing_events for small gaps and /state_ids for wide ones — and against the current state, where a failure is a soft failure. Events held without their state are outliers: a column on roomserver_events, because the current state of a room joined over federation is almost all outliers, and excluded from every timeline query. Forks are resolved at the room's head. Membership across servers is make_join/send_join, make_leave/send_leave and countersigned invites, in both directions; m.room.server_acl is enforced on everything another server sends. History before a remote join is backfilled when /messages pages past it, stored at negative stream positions. internal/federationapi is the running component: the inbound endpoints, and an outbound queue that persists what it owes each destination, sends it in transactions of 50 PDUs and 100 EDUs, backs off from ten seconds to six hours, survives restarts, and drops events persisted while federation is off rather than delivering a backlog in one burst. Its Module is what the switch starts and stops. Also: a TLS listener for port 8448, trusted key servers, key validity and an outbound CA bundle in the config; per-destination health and backoff reset in the admin API; remote profiles, aliases and directories in the Client-Server API; a Complement federation profile. See docs/federation.md, including its known gaps (no partial-state joins, no key rotation). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
192 lines
11 KiB
Markdown
192 lines
11 KiB
Markdown
# 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. |
|
|
| `listen.federation_address` | `WARP_LISTEN_FEDERATION_ADDRESS` | empty | A second listener serving the same API over TLS, usually `:8448`. Empty = none; see *Federation over TLS*. |
|
|
| `listen.tls_cert_file` | `WARP_TLS_CERT_FILE` | empty | PEM certificate chain for the federation listener. Required with it. |
|
|
| `listen.tls_key_file` | `WARP_TLS_KEY_FILE` | empty | PEM key for the federation listener. Required with it. |
|
|
| `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. |
|
|
| `federation.trusted_key_servers` | `WARP_FEDERATION_TRUSTED_KEY_SERVERS` | `[]` | Notaries asked for a server's key when it cannot be reached itself, e.g. `matrix.org`. Empty = only ever ask the server. |
|
|
| `federation.key_validity_period` | `WARP_FEDERATION_KEY_VALIDITY_PERIOD` | `24h` | How long other servers may cache this server's key. At most `168h`. |
|
|
| `federation.tls_ca_file` | `WARP_FEDERATION_TLS_CA_FILE` | empty | Extra CA certificates (PEM) for outbound federation, on top of the system roots. |
|
|
| `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:
|
|
|
|
- `/_matrix/federation/*`, `/_matrix/key/*` and `/.well-known/matrix/server`
|
|
answer `404 M_UNRECOGNIZED`, exactly as on a server with no federation
|
|
API. The TLS listener on `listen.federation_address`, if there is one,
|
|
stays up and answers the same way.
|
|
- Nothing outbound runs. The transaction queue is stopped, and the
|
|
federation client refuses every request — key fetches, joins, profile
|
|
and alias lookups — before it opens a connection, so a component that
|
|
somehow missed the switch still cannot reach another server.
|
|
- Events persisted while it is off are not queued for other servers. A
|
|
remote server that cares about the room fetches what it missed the next
|
|
time it hears from this one. What was already queued when the switch
|
|
went off stays queued, and goes out when it comes back on.
|
|
- 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.
|
|
|
|
## Federation over TLS
|
|
|
|
Other servers reach this one at whatever its server name resolves to: the
|
|
address in `/.well-known/matrix/server`, an SRV record, or the name itself
|
|
on port 8448. Two deployment shapes:
|
|
|
|
- **Behind a reverse proxy** that terminates TLS — the usual one. Set
|
|
`global.well_known.server_address` to the proxy's `host:443` and leave
|
|
`listen.federation_address` empty: the proxy forwards
|
|
`/_matrix/federation` and `/_matrix/key` to `listen.address` like
|
|
everything else.
|
|
- **Warp terminates TLS itself**: set `listen.federation_address` to
|
|
`:8448` with `listen.tls_cert_file` and `listen.tls_key_file`. The
|
|
certificate must be valid for the server name (or for the delegated
|
|
name, if the well-known document delegates).
|
|
|
|
Outbound federation verifies certificates against the system roots, plus
|
|
`federation.tls_ca_file` when it is set — for a private federation whose
|
|
servers share an internal CA. There is no switch to turn verification
|
|
off.
|