Warp/docs/development.md

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

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.

Running a server locally

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:

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:

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:

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:

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.