tajniak81andClaude Opus 5
b4fb60a8ab
Scaffolds the server module and everything Phase 0 of PLAN.md calls for: a binary that boots, serves its discovery endpoints and nothing else yet. - config: one YAML file plus per-field WARP_* environment overrides, unknown fields rejected, validation that reports every problem at once - logging and metrics: slog, a Prometheus registry, per-route HTTP instrumentation labelled by pattern rather than path - httputil: the Matrix error envelope, error-returning handlers, CORS, request logging, panic recovery, and a router over http.ServeMux - endpoints: /_matrix/client/versions, /.well-known/matrix/client, /.well-known/matrix/server (gated), /healthz, /metrics, and M_UNRECOGNIZED for everything else - storage: driver registry, shared database/sql base, checksummed migration runner, sqlite and postgres drivers, pocketbase stub - settings: server_settings table behind a cached service, so the federation and registration switches change without a restart - federation: the gate that makes federation a runtime mode - cmd/warp: serve, migrate, generate-keys, version - Makefile, golangci-lint v2, GitHub Actions CI (Linux and Windows tests, race on Linux, storage tests against PostgreSQL, lint, boot smoke test), Dockerfile, example config and docs Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
84 lines
4.7 KiB
Markdown
84 lines
4.7 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` | Raise before long-polling `/sync` lands in Phase 4. |
|
|
| `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. |
|
|
| `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` | |
|
|
| `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. |
|
|
|
|
## 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.
|