tajniak81andClaude Opus 5.5
92836f8dcd
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 6: the media repository. Clients upload files, reserve an mxc:// URI and upload to it later, download and ask for thumbnails, all through the authenticated media endpoints of Matrix 1.11; other servers download this server's media through the federation media endpoints, and media uploaded elsewhere is fetched over federation on first use and kept. internal/mediaapi is the component. Content goes into a BlobStore named by its SHA-256, so the same file uploaded twice is stored once and the hash doubles as the ETag; the metadata that maps an mxc:// URI onto a blob is in media_repository and media_thumbnails. The local-filesystem store writes to a temporary file and renames it into place once hashed, so nothing ever refers to half a file. A storage driver can bring its own store through storage.BlobProvider, which is where PocketBase's filesystem abstraction (local or S3) plugs in with Phase 10. Reserved uploads belong to the user who made them, take one upload, lapse after a day, and are capped per user; a download of one waits for its content, woken in memory the moment it arrives, for as long as timeout_ms allows. Thumbnails come from a fixed set of configured sizes, so a thousand requested sizes cannot mean a thousand resizes. They are made on first request and kept, never enlarge, honour a JPEG's EXIF orientation, and point at the original when it already fits. The pixel count is checked from the header before anything is decoded, at most four resizes run at once, and concurrent requests for the same thumbnail share one. Remote media is fetched through the signed client: the multipart/mixed answer of Matrix 1.11, with a fallback to the legacy download endpoint for servers that answer M_UNRECOGNIZED, and Location redirects followed by a dialer that refuses loopback, private and link-local addresses. Concurrent requests share one fetch, detached from the request that started it. With federation off nothing is fetched, and what was cached before is still served. Downloads carry a sandboxing CSP, nosniff, inline Content-Disposition only for the types the spec lists as safe, and private immutable caching. The unauthenticated legacy download endpoints are off by default behind media.legacy_unauthenticated_downloads. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
202 lines
13 KiB
Markdown
202 lines
13 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. |
|
|
| `client_api.rate_limit.media.burst` / `.interval` | — | `100` / `20ms` | Media downloads and thumbnails: a client opening a room asks for every avatar at once. Uploads are in the default bucket. |
|
|
| `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. |
|
|
| `media.base_path` | `WARP_MEDIA_BASE_PATH` | `./media_store` | Where media content is kept. Created on the first upload. |
|
|
| `media.max_upload_bytes` | `WARP_MEDIA_MAX_UPLOAD_BYTES` | `52428800` | The largest upload (50 MiB), and the largest file fetched from another server. Reported to clients as `m.upload.size`. |
|
|
| `media.max_thumbnail_pixels` | `WARP_MEDIA_MAX_THUMBNAIL_PIXELS` | `32000000` | The largest image, in pixels, decoded to make a thumbnail. |
|
|
| `media.thumbnail_sizes` | — | five sizes, see [media.md](media.md) | The thumbnails this server makes, as `{width, height, method}`. Empty = no thumbnails. |
|
|
| `media.pending_upload_expiry` | `WARP_MEDIA_PENDING_UPLOAD_EXPIRY` | `24h` | How long an ID reserved with `POST /media/v1/create` waits for its content. |
|
|
| `media.max_pending_uploads` | `WARP_MEDIA_MAX_PENDING_UPLOADS` | `10` | How many of those one user may hold. |
|
|
| `media.legacy_unauthenticated_downloads` | `WARP_MEDIA_LEGACY_UNAUTHENTICATED_DOWNLOADS` | `false` | Also serve the deprecated `/_matrix/media/v3/download` and `/thumbnail`, which need no token. Only for clients older than Matrix 1.11. |
|
|
| `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. That
|
|
includes downloading media from another server that is not already
|
|
cached here; media fetched before the switch went off is still served.
|
|
- 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.
|