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>
114 lines
3.9 KiB
Markdown
114 lines
3.9 KiB
Markdown
# Development
|
|
|
|
## Prerequisites
|
|
|
|
- Go 1.26+. Nothing else for the default build: the SQLite driver is pure
|
|
Go and `CGO_ENABLED=0` works everywhere.
|
|
- A C toolchain only if you want `go test -race`.
|
|
- PostgreSQL only to run the storage tests against it.
|
|
- `golangci-lint` v2 for `make lint`:
|
|
`go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest`
|
|
|
|
## Everyday commands
|
|
|
|
```sh
|
|
make build # bin/warp
|
|
make test # go test ./... in server/
|
|
make check # vet + test
|
|
make lint
|
|
make cover # coverage.html
|
|
make clean
|
|
```
|
|
|
|
Each one is a two-line shell command if you would rather not use `make`;
|
|
look at the [Makefile](../Makefile).
|
|
|
|
## Running a server locally
|
|
|
|
```sh
|
|
cp warp.yaml.example warp.yaml # set global.server_name
|
|
make build
|
|
./bin/warp generate-keys
|
|
./bin/warp serve
|
|
```
|
|
|
|
The SQLite file, the signing key and (later) the media store are written
|
|
relative to the working directory. They are in `.gitignore`.
|
|
|
|
For a throwaway server with no config file at all:
|
|
|
|
```sh
|
|
WARP_SERVER_NAME=dev.local WARP_PRIVATE_KEY=./keys/dev.key ./bin/warp generate-keys
|
|
WARP_SERVER_NAME=dev.local WARP_PRIVATE_KEY=./keys/dev.key ./bin/warp serve
|
|
```
|
|
|
|
## Adding a database migration
|
|
|
|
1. Write the same change twice, once per SQL dialect:
|
|
`server/internal/storage/sqlite/migrations/NNNN_name.sql` and
|
|
`server/internal/storage/postgres/migrations/NNNN_name.sql`.
|
|
Use the next free number; `NNNN` is zero-padded to four digits.
|
|
2. The files are embedded with `embed.FS`, so a rebuild picks them up.
|
|
3. `./bin/warp migrate --status` lists what would run, `./bin/warp migrate`
|
|
applies it. A server started with `database.auto_migrate: true` (the
|
|
default) runs them itself.
|
|
|
|
Rules the runner enforces:
|
|
|
|
- One transaction per migration. A failure rolls that file back entirely
|
|
and leaves the following ones unapplied.
|
|
- A migration that has already been applied and whose file has since
|
|
changed is an error. Write a new migration instead of editing an old
|
|
one; the checksum of every applied file is recorded.
|
|
- A database that has migrations this binary does not know about refuses
|
|
to start, so an old binary cannot run against a newer schema.
|
|
|
|
## Adding an endpoint
|
|
|
|
Routes are registered in `server/internal/setup/routes.go` on an
|
|
`httputil.Router`, which is `http.ServeMux` plus per-route metrics:
|
|
|
|
```go
|
|
r.HandleFunc("GET /_matrix/client/v3/profile/{userID}/displayname", s.handleGetDisplayName)
|
|
```
|
|
|
|
Handlers have the signature `func(http.ResponseWriter, *http.Request) error`
|
|
and return Matrix errors directly:
|
|
|
|
```go
|
|
func (s *Server) handleThing(w http.ResponseWriter, r *http.Request) error {
|
|
if somethingWrong {
|
|
return httputil.Forbidden("You are not allowed to do that")
|
|
}
|
|
httputil.WriteJSON(w, http.StatusOK, response{})
|
|
return nil
|
|
}
|
|
```
|
|
|
|
Anything returned that is not a `*httputil.MatrixError` is logged in full
|
|
and reported to the client as `M_UNKNOWN`, so internal detail never leaks.
|
|
|
|
Endpoints that belong to the federation surface are registered through the
|
|
gate instead, so they disappear when federation is switched off:
|
|
|
|
```go
|
|
r.Handle("GET /_matrix/federation/v1/version", s.federation.ProtectFunc(s.handleFederationVersion))
|
|
```
|
|
|
|
A Client-Server endpoint that would need federation to answer returns
|
|
`federation.RejectClientRequest("...")`, which is an `M_FORBIDDEN` that
|
|
says why.
|
|
|
|
## Tests
|
|
|
|
- Unit tests live next to the code. `internal/setup` holds the HTTP-level
|
|
tests; they build a whole server on an in-memory SQLite database.
|
|
- Storage tests run against every driver that is available:
|
|
SQLite always, PostgreSQL when `WARP_TEST_POSTGRES_DSN` is set.
|
|
- CI runs `gofmt -l`, `go mod tidy` (as a diff check), `go vet`, the tests
|
|
on Linux and Windows, the race detector on Linux, `golangci-lint`, and a
|
|
smoke test that boots the real binary and curls it.
|
|
|
|
Complement, the official integration suite, is wired up in Phase 1 — there
|
|
is nothing it can test before registration exists.
|