Merge pull request 'feat(api): OpenAPI spec and an offline Swagger UI' (#16) from feat/openapi-docs into main

This commit is contained in:
squidd 2026-11-11 14:47:08 +01:00
commit e258c9d182
16 changed files with 2007 additions and 10 deletions

View file

@ -13,6 +13,7 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr
- **Scanner.** Reads MP3 and FLAC tags and audio properties with several workers in parallel. Rescans are incremental, renamed files keep their identity, vanished files are flagged (never deleted), and a library whose folder looks empty or unreadable (an unmounted NAS) is left alone instead of being wiped. Audio in other formats (m4a, ogg, opus, wav, wma and similar) is not read yet, but it is counted as `unsupported` in the scan result instead of disappearing silently. NAS housekeeping folders (`@Recycle`, `#recycle`, `@eaDir`, `.@__thumb`, `$RECYCLE.BIN`) are skipped.
- **Catalog.** Browse and search artists, albums and tracks, with paging, by library, artist or album. Only tracks you can actually play are listed.
- **Streaming.** `GET` and `HEAD` with `Range` support, so players can seek. Opening or prefetching a stream does not record a listen.
- **API documentation.** The full API is described in OpenAPI and browsable with Swagger UI, served by Sonda itself. The UI is embedded in the binary, so opening it contacts no other server.
- **Listening history.** Clients report explicit `play`, `complete` and `skip` events. They stay in your database; nothing is sent anywhere. Sonda makes no outbound network requests at all.
## What is not there yet
@ -170,6 +171,8 @@ curl -s -X POST $BASE/users -H "$AUTH" -d '{"username":"bob","password":"another
Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"error":{"code":"...","message":"..."}}`.
**Interactive documentation:** open `http://127.0.0.1:8080/api/docs/` in a browser. Use *Authorize* with the `access_token` from the login to try the protected operations. The OpenAPI file itself is at `/api/v1/openapi.yaml`. Both are public, since they describe the API and contain no data.
| Who | Method and path | What it does |
|---|---|---|
| anyone | `GET /health` | Liveness check. |
@ -222,7 +225,8 @@ Layout:
```
cmd/sondad/ the server: wiring, config, logging, shutdown
internal/api/http/ the REST API (thin handlers)
internal/api/http/ the REST API (thin handlers) and the docs routes
internal/api/openapi/ the OpenAPI spec, embedded in the binary
internal/auth/ users, roles, passwords, access and refresh tokens
internal/catalog/ browsing and searching artists, albums, tracks
internal/library/ libraries, the scanner, the event hub, the tag reader
@ -232,8 +236,10 @@ internal/streaming/ opening a track's file safely
migrations/ SQL migrations, one folder per database
```
The API description is `internal/api/openapi/openapi.yaml`, written by hand and embedded in the binary. Two tests keep it in step with the code: one fails when a route and the spec disagree in either direction, and a contract test sends real requests through every operation and validates each response (status, headers, JSON body) against the spec. Adding or changing an endpoint therefore means updating the spec in the same change. Response objects are closed (`additionalProperties: false`), so a field added in the code and forgotten in the spec fails the build.
Migrations are plain SQL files in `migrations/sqlite` and `migrations/postgres`. They must describe the same schema, and a test checks that both folders hold the same files. Add a new numbered file to both whenever the schema changes.
## Third-party code
Audio tags are read with `go.senan.xyz/taglib`, which embeds [TagLib](https://github.com/taglib/taglib) compiled to WebAssembly and is licensed under the LGPL 2.1. The other dependencies are listed in `go.mod`.
Audio tags are read with `go.senan.xyz/taglib`, which embeds [TagLib](https://github.com/taglib/taglib) compiled to WebAssembly and is licensed under the LGPL 2.1. The Swagger UI assets come from `github.com/swaggest/swgui` (Apache-2.0), which embeds [Swagger UI](https://github.com/swagger-api/swagger-ui) (Apache-2.0). The other dependencies are listed in `go.mod`.

7
go.mod
View file

@ -3,10 +3,12 @@ module codeberg.org/squidd/sonda
go 1.27.1
require (
github.com/getkin/kin-openapi v0.153.0
github.com/gin-gonic/gin v1.12.0
github.com/golang-jwt/jwt/v5 v5.3.1
github.com/jackc/pgx/v5 v5.12.0
github.com/pelletier/go-toml/v2 v2.4.3
github.com/swaggest/swgui v1.8.9
github.com/uptrace/bun v1.3.0
github.com/uptrace/bun/dialect/pgdialect v1.3.0
github.com/uptrace/bun/dialect/sqlitedialect v1.3.0
@ -24,6 +26,8 @@ require (
github.com/dustin/go-humanize v1.1.0 // indirect
github.com/gabriel-vasile/mimetype v1.4.12 // indirect
github.com/gin-contrib/sse v1.1.0 // indirect
github.com/go-openapi/jsonpointer v0.22.5 // indirect
github.com/go-openapi/swag/jsonname v0.25.5 // indirect
github.com/go-playground/locales v0.14.1 // indirect
github.com/go-playground/universal-translator v0.18.1 // indirect
github.com/go-playground/validator/v10 v10.30.1 // indirect
@ -45,14 +49,17 @@ require (
github.com/quic-go/qpack v0.6.0 // indirect
github.com/quic-go/quic-go v0.59.0 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
github.com/tetratelabs/wazero v1.11.1-0.20260428013916-2bbd517b7633 // indirect
github.com/tmthrgd/go-hex v0.0.0-20190904060850-447a3041c3bc // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.3.1 // indirect
github.com/vearutop/statigz v1.4.0 // indirect
github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
go.yaml.in/yaml/v4 v4.0.0 // indirect
golang.org/x/arch v0.22.0 // indirect
golang.org/x/net v0.60.0 // indirect
golang.org/x/sync v0.24.0 // indirect

22
go.sum
View file

@ -1,3 +1,7 @@
github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs=
github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
github.com/bool64/dev v0.2.45 h1:3nLKhAS/6Oklk3Mt2lHYSN/Cb4tdAD77KLwzeP+6eYE=
github.com/bool64/dev v0.2.45/go.mod h1:iJbh1y/HkunEPhgebWRNcs8wfGq7sjvJ6W5iabL8ACg=
github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
@ -9,14 +13,24 @@ github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gE
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg=
github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI=
github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
github.com/getkin/kin-openapi v0.153.0 h1:Qo4qWW+Pj8o90LUTE6MDyG5TJAtWnfvrcWOBcWg7eBw=
github.com/getkin/kin-openapi v0.153.0/go.mod h1:mEZ6Ip3gyqPDokUsJsttZhv3r46/NeH3tGwrFUMcoSE=
github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
github.com/gin-gonic/gin v1.12.0 h1:b3YAbrZtnf8N//yjKeU2+MQsh2mY5htkZidOM7O0wG8=
github.com/gin-gonic/gin v1.12.0/go.mod h1:VxccKfsSllpKshkBWgVgRniFFAzFb9csfngsqANjnLc=
github.com/go-openapi/jsonpointer v0.22.5 h1:8on/0Yp4uTb9f4XvTrM2+1CPrV05QPZXu+rvu2o9jcA=
github.com/go-openapi/jsonpointer v0.22.5/go.mod h1:gyUR3sCvGSWchA2sUBJGluYMbe1zazrYWIkWPjjMUY0=
github.com/go-openapi/swag/jsonname v0.25.5 h1:8p150i44rv/Drip4vWI3kGi9+4W9TdI3US3uUYSFhSo=
github.com/go-openapi/swag/jsonname v0.25.5/go.mod h1:jNqqikyiAK56uS7n8sLkdaNY/uq6+D2m2LANat09pKU=
github.com/go-openapi/testify/v2 v2.4.0 h1:8nsPrHVCWkQ4p8h1EsRVymA2XABB4OT40gcvAu+voFM=
github.com/go-openapi/testify/v2 v2.4.0/go.mod h1:HCPmvFFnheKK2BuwSA0TbbdxJ3I16pjwMkYkP4Ywn54=
github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
@ -77,6 +91,8 @@ github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SA
github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
@ -89,6 +105,8 @@ github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXl
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/swaggest/swgui v1.8.9 h1:cxAgIwouPpZPlvX68jY5fpwarzLbkc8/IL6DMj+H460=
github.com/swaggest/swgui v1.8.9/go.mod h1:eTJfgwudbyw9xMwqO26vs82ei2u6//JnUAofx2vGB3M=
github.com/tetratelabs/wazero v1.11.1-0.20260428013916-2bbd517b7633 h1:6GN/lazdqr69FIzz1U6c4TF/ppE2dInMR4GzU9QKxjg=
github.com/tetratelabs/wazero v1.11.1-0.20260428013916-2bbd517b7633/go.mod h1:3ghOSSWYnzX0zd/3Ns4ni2tKxcXDE9/QgkwuH1PW3Rs=
github.com/tmthrgd/go-hex v0.0.0-20190904060850-447a3041c3bc h1:9lRDQMhESg+zvGYmW5DyG0UqvY96Bu5QYsTLvCHdrgo=
@ -103,6 +121,8 @@ github.com/uptrace/bun/dialect/pgdialect v1.3.0 h1:0ZkGqGugxaPCxko4DV2f4d7i+FnM2
github.com/uptrace/bun/dialect/pgdialect v1.3.0/go.mod h1:kP5HGEpAX8iJCqj3WHm04XnoeBPacdCN1P2HiwMtHpg=
github.com/uptrace/bun/dialect/sqlitedialect v1.3.0 h1:XzxkORYksxkLsIQLJHFYUb3yDvqSQHzTungyKpJhHTw=
github.com/uptrace/bun/dialect/sqlitedialect v1.3.0/go.mod h1:x2D1sY50Itio0I/FVdNe30oMUT2ObiAS+oILcMR+Wys=
github.com/vearutop/statigz v1.4.0 h1:RQL0KG3j/uyA/PFpHeZ/L6l2ta920/MxlOAIGEOuwmU=
github.com/vearutop/statigz v1.4.0/go.mod h1:LYTolBLiz9oJISwiVKnOQoIwhO1LWX1A7OECawGS8XE=
github.com/vmihailenco/msgpack/v5 v5.4.1 h1:cQriyiUvjTwOHg8QZaPihLWeRAAVoCpE00IUPn0Bjt8=
github.com/vmihailenco/msgpack/v5 v5.4.1/go.mod h1:GaZTsDaehaPpQVyxrf5mtQlH+pc21PIudVV/E3rRQok=
github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
@ -121,6 +141,8 @@ go.uber.org/zap v1.28.0 h1:IZzaP1Fv73/T/pBMLk4VutPl36uNC+OSUh3JLG3FIjo=
go.uber.org/zap v1.28.0/go.mod h1:rDLpOi171uODNm/mxFcuYWxDsqWSAVkFdX4XojSKg/Q=
go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
golang.org/x/crypto v0.58.0 h1:COkYLr4k7nDI4r6QtMML2AfzeIswWHAJthLS6K/M/54=

View file

@ -12,6 +12,7 @@ import (
"time"
"github.com/gin-gonic/gin"
"github.com/uptrace/bun"
"go.uber.org/zap"
"codeberg.org/squidd/sonda/internal/auth"
@ -39,6 +40,21 @@ func newTestAPIWithScan(t *testing.T, scan scanService) http.Handler {
// newTestAPIWith wires real services and lets a test replace parts of Deps.
func newTestAPIWith(t *testing.T, mutate func(*Deps)) http.Handler {
t.Helper()
h, _ := newTestEnv(t, mutate)
return h
}
// newTestEnv is newTestAPIWith that also returns the database, for tests that
// need to look at or seed it.
func newTestEnv(t *testing.T, mutate func(*Deps)) (http.Handler, *bun.DB) {
t.Helper()
return newTestEnvDB(t, func(d *Deps, _ *bun.DB) { mutate(d) })
}
// newTestEnvDB lets the mutate function see the database as well, for tests
// that build services on top of it.
func newTestEnvDB(t *testing.T, mutate func(*Deps, *bun.DB)) (http.Handler, *bun.DB) {
t.Helper()
db, err := storage.Open(storage.DriverSQLite, filepath.Join(t.TempDir(), "api.db"))
if err != nil {
@ -66,8 +82,8 @@ func newTestAPIWith(t *testing.T, mutate func(*Deps)) http.Handler {
Libraries: library.NewLibraries(storage.NewLibraryRepo(db)),
Streams: streaming.NewService(noFiles{}),
}
mutate(&deps)
return NewRouter(deps)
mutate(&deps, db)
return NewRouter(deps), db
}
// noFiles is a streaming source with nothing to play.

View file

@ -330,7 +330,6 @@ func TestAuthorizationHeaderMustUseTheBearerScheme(t *testing.T) {
for name, header := range map[string]string{
"bare token": tok,
"basic scheme": "Basic " + tok,
"lowercase": "bearer " + tok,
"token scheme": "Token " + tok,
"empty bearer": "Bearer ",
"bearer no gap": "Bearer" + tok,
@ -352,3 +351,34 @@ func TestAuthorizationHeaderMustUseTheBearerScheme(t *testing.T) {
t.Errorf("proper Bearer header: %d", rec.Code)
}
}
// RFC 7235: the name of the authentication scheme is case-insensitive.
func TestBearerSchemeIsCaseInsensitive(t *testing.T) {
h := newTestAPI(t)
tok := registerAndLogin(t, h)
for _, scheme := range []string{"Bearer", "bearer", "BEARER", "bEaReR"} {
req := httptest.NewRequest("GET", "/api/v1/auth/me", nil)
req.Header.Set("Authorization", scheme+" "+tok)
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
if rec.Code != http.StatusOK {
t.Errorf("scheme %q: status %d, want 200", scheme, rec.Code)
}
}
}
// An access token outlives a deleted account for a few minutes. Reporting a
// listen with it must be a 401, not a database error.
func TestListenWithADeletedAccountsTokenIsUnauthorized(t *testing.T) {
h := newTestAPI(t)
admin := registerAndLogin(t, h)
bobID, bob := addUser(t, h, admin, "bob", false)
if r := do(t, h, "DELETE", userPath(bobID), admin, nil); r.Code != http.StatusNoContent {
t.Fatalf("delete: %d", r.Code)
}
body := map[string]any{"track_id": 1, "event_type": "play", "idempotency_key": "k"}
r := do(t, h, "POST", "/api/v1/listens", bob, body)
if r.Code != http.StatusUnauthorized || errCode(r) != "unauthorized" {
t.Fatalf("listen after the account was deleted: %d %v", r.Code, r.Body)
}
}

View file

@ -0,0 +1,450 @@
package httpapi
import (
"bytes"
"context"
"encoding/json"
"io"
"mime"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strconv"
"sync"
"testing"
"time"
"github.com/getkin/kin-openapi/openapi3filter"
"github.com/getkin/kin-openapi/routers"
"github.com/getkin/kin-openapi/routers/legacy"
"github.com/uptrace/bun"
"codeberg.org/squidd/sonda/internal/catalog"
"codeberg.org/squidd/sonda/internal/library"
"codeberg.org/squidd/sonda/internal/storage"
"codeberg.org/squidd/sonda/internal/streaming"
)
// Contract tests: real requests against the real services, with every request
// that succeeds and every response checked against openapi.yaml (status,
// headers, parameters, JSON bodies). A field that is added, renamed or dropped
// in the code without the spec fails here, and so does an error code that
// changes, because every error case also asserts its `code`.
// contractReader gives the fixture files their tags without real audio. While a
// gate is held it blocks, so a test can look at a scan that is still running.
type contractReader struct {
mu sync.Mutex
gate chan struct{}
}
// hold makes the next reads wait until the returned channel is closed.
func (r *contractReader) hold() chan struct{} {
r.mu.Lock()
defer r.mu.Unlock()
r.gate = make(chan struct{})
return r.gate
}
func (r *contractReader) Read(path string) (library.Metadata, error) {
r.mu.Lock()
gate := r.gate
r.mu.Unlock()
if gate != nil {
<-gate
}
m := library.Metadata{
Tags: library.Tags{Artists: []string{"Artist X"}, Album: "Album Y", AlbumArtist: "Artist X", DiscNo: 1},
Properties: library.Properties{DurationMs: 180000, SampleRate: 44100},
}
switch filepath.Base(path) {
case "a.mp3":
m.Title, m.TrackNo, m.Format = "Song A", 1, "mpeg"
case "b.flac":
m.Title, m.TrackNo, m.Format = "Song B", 2, "flac"
case "c.mp3": // a track that belongs to no album
m.Title, m.Format = "Loose Song", "mpeg"
m.Album, m.AlbumArtist, m.DiscNo = "", "", 0
default:
return library.Metadata{}, library.ErrUnreadable
}
return m, nil
}
// scanAdapter lets the API start scans on a real manager.
type scanAdapter struct{ m *library.Manager }
func (a scanAdapter) Start() error { return a.m.Start(context.Background()) }
func (a scanAdapter) StartLibrary(id int64) error { return a.m.StartLibrary(context.Background(), id) }
func (a scanAdapter) Status() library.Status { return a.m.Status() }
type contract struct {
t *testing.T
h http.Handler
db *bun.DB
reader *contractReader
router routers.Router
seen map[string]bool // "METHOD /path" of every operation exercised
music string
}
func newContract(t *testing.T) *contract {
t.Helper()
reader := &contractReader{}
h, db := newTestEnvDB(t, func(d *Deps, db *bun.DB) {
repo := storage.NewLibraryRepo(db)
mgr := library.NewManager(library.NewScanner(repo, reader, library.NewHub(), 2), repo)
libs := library.NewLibraries(repo)
libs.SetBusy(func() bool { return mgr.Status().Running })
d.Scan = scanAdapter{mgr}
d.Libraries = libs
d.Catalog = catalog.NewService(storage.NewCatalogRepo(db))
d.Streams = streaming.NewService(repo)
})
router, err := legacy.NewRouter(loadSpec(t))
if err != nil {
t.Fatal(err)
}
music := t.TempDir()
for _, f := range []string{"a.mp3", "b.flac", "c.mp3"} {
if err := os.WriteFile(filepath.Join(music, f), bytes.Repeat([]byte{0xAB}, 400), 0o644); err != nil {
t.Fatal(err)
}
}
return &contract{t: t, h: h, db: db, reader: reader, router: router, seen: map[string]bool{}, music: music}
}
// call sends a request to /api/v1<path>, checks it and its answer against the
// spec, and returns the answer. headers are extra request headers, in pairs.
func (c *contract) call(method, path, token string, body any, headers ...string) *httptest.ResponseRecorder {
c.t.Helper()
var payload []byte
if body != nil {
var err error
if payload, err = json.Marshal(body); err != nil {
c.t.Fatal(err)
}
}
req := httptest.NewRequest(method, "/api/v1"+path, bytes.NewReader(payload))
if body != nil {
req.Header.Set("Content-Type", "application/json")
}
if token != "" {
req.Header.Set("Authorization", "Bearer "+token)
}
for i := 0; i+1 < len(headers); i += 2 {
req.Header.Set(headers[i], headers[i+1])
}
rec := httptest.NewRecorder()
c.h.ServeHTTP(rec, req)
c.validate(req, payload, rec)
return rec
}
func (c *contract) validate(req *http.Request, payload []byte, rec *httptest.ResponseRecorder) {
c.t.Helper()
route, params, err := c.router.FindRoute(req)
if err != nil {
c.t.Errorf("%s %s is not in the spec: %v", req.Method, req.URL.Path, err)
return
}
c.seen[req.Method+" "+route.Path] = true
opts := &openapi3filter.Options{AuthenticationFunc: openapi3filter.NoopAuthenticationFunc}
where := req.Method + " " + req.URL.RequestURI()
// A request the server accepted must also be valid for the spec: that keeps
// the request schemas, parameters and headers honest.
if rec.Code < 400 {
clone := req.Clone(context.Background())
clone.Body = io.NopCloser(bytes.NewReader(payload))
in := &openapi3filter.RequestValidationInput{Request: clone, PathParams: params, Route: route, Options: opts}
if err := openapi3filter.ValidateRequest(context.Background(), in); err != nil {
c.t.Errorf("%s was accepted but does not match the spec: %v", where, err)
}
}
responses := route.Operation.Responses
documented := responses.Status(rec.Code)
if documented == nil && responses.Default() == nil {
c.t.Errorf("%s -> %d: this status is not documented in the spec", where, rec.Code)
return
}
// The library skips HEAD and redirects, and cannot read audio or YAML.
// Those are checked by hand: the status above, and the content type here.
skipBody := req.Method == http.MethodHead || route.Path == "/openapi.yaml" ||
(rec.Code >= 300 && rec.Code < 400) || (route.Path == "/tracks/{id}/stream" && rec.Code/100 == 2)
if skipBody && documented != nil && documented.Value != nil && rec.Code/100 == 2 && req.Method != http.MethodHead && route.Path == "/tracks/{id}/stream" {
mediaType, _, err := mime.ParseMediaType(rec.Header().Get("Content-Type"))
if err != nil || documented.Value.Content.Get(mediaType) == nil {
c.t.Errorf("%s -> %d: Content-Type %q is not one the spec lists", where, rec.Code, rec.Header().Get("Content-Type"))
}
}
in := &openapi3filter.RequestValidationInput{Request: req, PathParams: params, Route: route, Options: opts}
out := &openapi3filter.ResponseValidationInput{
RequestValidationInput: in,
Status: rec.Code,
Header: rec.Header(),
Options: &openapi3filter.Options{IncludeResponseStatus: true, ExcludeResponseBody: skipBody},
}
out.SetBodyBytes(rec.Body.Bytes())
if err := openapi3filter.ValidateResponse(context.Background(), out); err != nil {
c.t.Errorf("%s -> %d does not match the spec: %v\nbody: %.300s", where, rec.Code, err, rec.Body.String())
}
}
// expect checks the status and decodes a JSON body. For an error status the
// error code must be given and is compared too.
func (c *contract) expect(rec *httptest.ResponseRecorder, want int, what string, code ...string) map[string]any {
c.t.Helper()
if rec.Code != want {
c.t.Fatalf("%s: status %d, want %d: %s", what, rec.Code, want, rec.Body.String())
}
out := map[string]any{}
_ = json.Unmarshal(rec.Body.Bytes(), &out)
if want >= 400 {
if len(code) == 0 {
c.t.Fatalf("%s: an error case must say which error code it expects", what)
}
got, _ := out["error"].(map[string]any)["code"].(string)
if got != code[0] {
c.t.Fatalf("%s: error code %q, want %q", what, got, code[0])
}
}
return out
}
func idOf(m map[string]any) string { return strconv.FormatInt(int64(m["id"].(float64)), 10) }
// scanDone waits for the running scan to finish.
func (c *contract) scanDone(token string) {
c.t.Helper()
deadline := time.Now().Add(10 * time.Second)
for time.Now().Before(deadline) {
st := c.expect(c.call("GET", "/library/scan", token, nil), 200, "scan status")
if st["running"] == false {
return
}
time.Sleep(20 * time.Millisecond)
}
c.t.Fatal("the scan did not finish in time")
}
func TestResponsesMatchTheSpec(t *testing.T) {
c := newContract(t)
// ---- system ----
c.expect(c.call("GET", "/health", "", nil), 200, "health")
c.expect(c.call("GET", "/openapi.yaml", "", nil), 200, "openapi.yaml")
// ---- auth ----
creds := map[string]string{"username": "alice", "password": "correct horse"}
c.expect(c.call("POST", "/auth/register", "", map[string]string{"username": "x", "password": "short"}), 400, "register invalid", "invalid_input")
c.expect(c.call("POST", "/auth/register", "", creds), 201, "register")
c.expect(c.call("POST", "/auth/register", "", map[string]string{"username": "eve", "password": "correct horse"}), 403, "register closed", "registration_closed")
c.expect(c.call("POST", "/auth/login", "", map[string]string{"username": "alice", "password": "wrong password"}), 401, "login wrong", "invalid_credentials")
c.expect(c.call("POST", "/auth/login", "", "not an object"), 400, "login with a bad body", "invalid_input")
session := c.expect(c.call("POST", "/auth/login", "", creds), 200, "login")
token := session["access_token"].(string)
refresh := session["refresh_token"].(string)
c.expect(c.call("GET", "/auth/me", "", nil), 401, "me without token", "unauthorized")
c.expect(c.call("GET", "/auth/me", token, nil), 200, "me")
renewed := c.expect(c.call("POST", "/auth/refresh", "", map[string]string{"refresh_token": refresh}), 200, "refresh")
c.expect(c.call("POST", "/auth/refresh", "", map[string]string{"refresh_token": refresh}), 401, "refresh replay", "invalid_refresh_token")
c.expect(c.call("POST", "/auth/refresh", "", "not an object"), 400, "refresh bad body", "invalid_input")
c.expect(c.call("POST", "/auth/logout", "", map[string]string{"refresh_token": renewed["refresh_token"].(string)}), 204, "logout")
c.expect(c.call("POST", "/auth/logout", "", "not an object"), 400, "logout bad body", "invalid_input")
c.expect(c.call("POST", "/auth/password", token, map[string]string{"current_password": "nope nope nope", "new_password": "brand new pass"}), 403, "password wrong current", "invalid_credentials")
c.expect(c.call("POST", "/auth/password", token, map[string]string{"current_password": "correct horse", "new_password": "x"}), 400, "password weak", "invalid_input")
c.expect(c.call("POST", "/auth/password", "", map[string]string{}), 401, "password without token", "unauthorized")
c.expect(c.call("POST", "/auth/password", token, map[string]string{"current_password": "correct horse", "new_password": "brand new pass"}), 204, "password changed")
creds["password"] = "brand new pass"
token = c.expect(c.call("POST", "/auth/login", "", creds), 200, "login again")["access_token"].(string)
// ---- users ----
bob := c.expect(c.call("POST", "/users", token, map[string]any{"username": "bob", "password": "bobs long pass"}), 201, "create user")
c.expect(c.call("POST", "/users", token, map[string]any{"username": "BOB", "password": "bobs long pass"}), 409, "create duplicate", "username_taken")
c.expect(c.call("POST", "/users", token, map[string]any{"username": "x", "password": "bobs long pass"}), 400, "create invalid", "invalid_input")
bobToken := c.expect(c.call("POST", "/auth/login", "", map[string]string{"username": "bob", "password": "bobs long pass"}), 200, "bob logs in")["access_token"].(string)
c.expect(c.call("GET", "/users", bobToken, nil), 403, "users as non-admin", "admin_required")
c.expect(c.call("GET", "/users", token, nil), 200, "list users")
bobID := idOf(bob)
c.expect(c.call("PATCH", "/users/"+bobID, token, map[string]bool{"is_admin": true}), 200, "promote")
c.expect(c.call("PATCH", "/users/"+bobID, token, map[string]bool{"is_admin": false}), 200, "demote")
c.expect(c.call("PATCH", "/users/999", token, map[string]bool{"is_admin": true}), 404, "patch unknown user", "user_not_found")
aliceID := idOf(c.expect(c.call("GET", "/auth/me", token, nil), 200, "me again"))
c.expect(c.call("PATCH", "/users/"+aliceID, token, map[string]bool{"is_admin": false}), 409, "demote the last admin", "last_admin")
c.expect(c.call("PUT", "/users/"+bobID+"/password", token, map[string]string{"password": "reset password"}), 204, "reset password")
c.expect(c.call("PUT", "/users/999/password", token, map[string]string{"password": "reset password"}), 404, "reset unknown", "user_not_found")
c.expect(c.call("DELETE", "/users/"+bobID, token, nil), 204, "delete user")
c.expect(c.call("DELETE", "/users/"+bobID, token, nil), 404, "delete twice", "user_not_found")
c.expect(c.call("DELETE", "/users/"+aliceID, token, nil), 409, "delete the last admin", "last_admin")
// A deleted admin's token stops working on admin routes at once.
c.expect(c.call("GET", "/users", bobToken, nil), 401, "a deleted account's token on an admin route", "unauthorized")
// ---- libraries and scan ----
c.expect(c.call("POST", "/library/scan", token, nil), 409, "scan with no library", "no_libraries")
lib := c.expect(c.call("POST", "/libraries", token, map[string]string{"name": "Music", "path": c.music}), 201, "create library")
libID := idOf(lib)
c.expect(c.call("POST", "/libraries", token, map[string]string{"name": "music", "path": t.TempDir()}), 409, "duplicate library name", "library_exists")
c.expect(c.call("POST", "/libraries", token, map[string]string{"name": "Bad", "path": "relative/path"}), 400, "invalid library", "invalid_input")
c.expect(c.call("GET", "/libraries", token, nil), 200, "list libraries")
c.expect(c.call("PATCH", "/libraries/"+libID, token, map[string]string{"name": "My music"}), 200, "rename library")
c.expect(c.call("PATCH", "/libraries/999", token, map[string]string{"name": "x"}), 404, "patch unknown library", "library_not_found")
c.expect(c.call("PATCH", "/libraries/"+libID, token, map[string]string{"foo": "bar"}), 400, "patch with nothing to change", "invalid_input")
// A second library to collide with, and to delete at the end.
extra := c.expect(c.call("POST", "/libraries", token, map[string]string{"name": "Extra", "path": t.TempDir()}), 201, "second library")
extraID := idOf(extra)
c.expect(c.call("PATCH", "/libraries/"+extraID, token, map[string]string{"name": "my MUSIC"}), 409, "rename onto another name", "library_exists")
c.expect(c.call("POST", "/libraries/999/scan", token, nil), 404, "scan unknown library", "library_not_found")
// A scan that is still running: everything that must wait says so.
gate := c.reader.hold()
c.expect(c.call("POST", "/libraries/"+libID+"/scan", token, nil), 202, "scan one library")
if st := c.expect(c.call("GET", "/library/scan", token, nil), 200, "status while scanning"); st["running"] != true {
t.Fatalf("status = %v, want running", st)
}
c.expect(c.call("POST", "/library/scan", token, nil), 409, "scan all while scanning", "scan_running")
c.expect(c.call("POST", "/libraries/"+libID+"/scan", token, nil), 409, "scan one while scanning", "scan_running")
c.expect(c.call("PATCH", "/libraries/"+libID, token, map[string]string{"path": t.TempDir()}), 409, "move a library while scanning", "scan_running")
c.expect(c.call("DELETE", "/libraries/"+libID, token, nil), 409, "delete a library while scanning", "scan_running")
close(gate)
c.scanDone(token)
c.expect(c.call("POST", "/library/scan", token, nil), 202, "scan everything")
c.scanDone(token)
status := c.expect(c.call("GET", "/library/scan", token, nil), 200, "scan status")
last, _ := status["last"].(map[string]any)
if last["libraries"] != float64(2) || last["found"] != float64(3) || last["added"] != float64(0) || last["unchanged"] != float64(3) {
t.Fatalf("second scan = %v, want 3 files in 2 libraries, all unchanged", last)
}
c.expect(c.call("DELETE", "/libraries/"+extraID, token, nil), 204, "delete library")
c.expect(c.call("DELETE", "/libraries/"+extraID, token, nil), 404, "delete library twice", "library_not_found")
// An album without an album artist, with a track whose file is gone from disk.
orphan := c.addOrphan(libID)
// ---- catalog ----
artists := c.expect(c.call("GET", "/artists?q=artist&limit=10&library_id="+libID, token, nil), 200, "artists")
artistID := idOf(artists["items"].([]any)[0].(map[string]any))
if page := c.expect(c.call("GET", "/artists?limit=0", token, nil), 200, "artists with limit 0"); page["limit"] != float64(50) {
t.Fatalf("limit=0 gave limit %v, want the default 50", page["limit"])
}
c.expect(c.call("GET", "/artists?limit=abc", token, nil), 400, "artists bad limit", "invalid_input")
c.expect(c.call("GET", "/artists/"+artistID, token, nil), 200, "artist")
c.expect(c.call("GET", "/artists/999", token, nil), 404, "artist unknown", "artist_not_found")
albums := c.expect(c.call("GET", "/albums?artist_id="+artistID, token, nil), 200, "albums")
albumID := idOf(albums["items"].([]any)[0].(map[string]any))
c.expect(c.call("GET", "/albums?offset=-1", token, nil), 400, "albums bad offset", "invalid_input")
c.expect(c.call("GET", "/albums/"+albumID, token, nil), 200, "album")
c.expect(c.call("GET", "/albums/999", token, nil), 404, "album unknown", "album_not_found")
orphanAlbum := c.expect(c.call("GET", "/albums/"+orphan.album, token, nil), 200, "an album without an album artist")
if v, present := orphanAlbum["artist"]; !present || v != nil {
t.Fatalf("album.artist = %#v, want an explicit null", v)
}
tracks := c.expect(c.call("GET", "/tracks?album_id="+albumID+"&artist_id="+artistID, token, nil), 200, "tracks")
items := tracks["items"].([]any)
if len(items) != 2 || tracks["total"] != float64(2) {
t.Fatalf("tracks = %v, want the two files of the album", tracks)
}
trackID := idOf(items[0].(map[string]any))
c.expect(c.call("GET", "/tracks?limit=-1", token, nil), 400, "tracks bad limit", "invalid_input")
c.expect(c.call("GET", "/tracks/"+trackID, token, nil), 200, "track")
c.expect(c.call("GET", "/tracks/999", token, nil), 404, "track unknown", "track_not_found")
loose := c.expect(c.call("GET", "/tracks?q=loose", token, nil), 200, "a track without an album")["items"].([]any)[0].(map[string]any)
if v, present := loose["album"]; !present || v != nil {
t.Fatalf("track.album = %#v, want an explicit null", v)
}
// ---- playback ----
stream := "/tracks/" + trackID + "/stream"
c.expect(c.call("GET", stream, "", nil), 401, "stream without token", "unauthorized")
if rec := c.call("GET", stream, token, nil); rec.Code != 200 || rec.Body.Len() != 400 {
t.Fatalf("stream: %d, %d bytes", rec.Code, rec.Body.Len())
}
if rec := c.call("GET", stream+"?access_token="+token, "", nil); rec.Code != 200 {
t.Fatalf("stream with a query token: %d", rec.Code)
}
if rec := c.call("GET", stream, token, nil, "Range", "bytes=0-99"); rec.Code != 206 || rec.Body.Len() != 100 {
t.Fatalf("stream range: %d, %d bytes", rec.Code, rec.Body.Len())
}
if rec := c.call("GET", stream, token, nil, "Range", "bytes=0-1,5-6"); rec.Code != 206 {
t.Fatalf("stream with two ranges: %d", rec.Code)
} else if mt, _, _ := mime.ParseMediaType(rec.Header().Get("Content-Type")); mt != "multipart/byteranges" {
t.Fatalf("two ranges answered with %q", rec.Header().Get("Content-Type"))
}
if rec := c.call("GET", stream, token, nil, "Range", "bytes=5000-"); rec.Code != 416 {
t.Fatalf("stream range past the end: %d", rec.Code)
}
future := time.Now().Add(time.Hour).UTC().Format(http.TimeFormat)
if rec := c.call("GET", stream, token, nil, "If-Modified-Since", future); rec.Code != 304 {
t.Fatalf("stream conditional: %d", rec.Code)
}
if rec := c.call("GET", stream, token, nil, "If-Unmodified-Since", "Mon, 01 Jan 2001 00:00:00 GMT"); rec.Code != 412 {
t.Fatalf("stream with a failed precondition: %d", rec.Code)
}
if rec := c.call("HEAD", stream, token, nil); rec.Code != 200 || rec.Body.Len() != 0 {
t.Fatalf("stream HEAD: %d, %d bytes", rec.Code, rec.Body.Len())
}
if rec := c.call("HEAD", stream, token, nil, "Range", "bytes=0-9"); rec.Code != 206 {
t.Fatalf("stream HEAD with a range: %d", rec.Code)
}
if rec := c.call("HEAD", stream, token, nil, "If-Modified-Since", future); rec.Code != 304 {
t.Fatalf("stream HEAD conditional: %d", rec.Code)
}
c.expect(c.call("GET", "/tracks/999/stream", token, nil), 404, "stream unknown track", "track_not_found")
c.expect(c.call("GET", "/tracks/"+orphan.track+"/stream", token, nil), 404, "stream a file that is gone", "file_missing")
tid, _ := strconv.Atoi(trackID)
listen := map[string]any{"track_id": tid, "event_type": "complete", "duration_played_ms": 1000, "idempotency_key": "k1", "occurred_at": "2026-01-02T03:04:05Z"}
c.expect(c.call("POST", "/listens", token, listen), 201, "listen")
c.expect(c.call("POST", "/listens", token, listen), 200, "listen again")
c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": 999, "event_type": "play", "idempotency_key": "k2"}), 404, "listen unknown track", "track_not_found")
c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": tid, "event_type": "dance", "idempotency_key": "k3"}), 400, "listen invalid", "invalid_input")
// ---- every operation in the spec was exercised ----
var missing []string
for _, op := range specOperations(loadSpec(t)) {
if !c.seen[op] {
missing = append(missing, op)
}
}
if len(missing) > 0 {
t.Errorf("operations the contract test never called (add a request for each):\n %v", missing)
}
}
type orphanIDs struct{ album, track string }
// addOrphan inserts an album with no album artist and a track in it whose file
// does not exist, the way rows from an older version or a removed file look.
func (c *contract) addOrphan(libraryID string) orphanIDs {
c.t.Helper()
var album, track int64
if err := c.db.QueryRow(`INSERT INTO albums (title, title_key) VALUES ('Orphan Album', 'orphan album') RETURNING id`).Scan(&album); err != nil {
c.t.Fatal(err)
}
if err := c.db.QueryRow(`INSERT INTO tracks (title, title_key, album_id) VALUES ('Orphan Song', 'orphan song', ?) RETURNING id`, album).Scan(&track); err != nil {
c.t.Fatal(err)
}
if _, err := c.db.Exec(`INSERT INTO audio_files (track_id, library_id, rel_path, format, size_bytes, mtime_unix)
VALUES (?, ?, 'no-such-file.mp3', 'mp3', 1, 1)`, track, libraryID); err != nil {
c.t.Fatal(err)
}
return orphanIDs{album: strconv.FormatInt(album, 10), track: strconv.FormatInt(track, 10)}
}

40
internal/api/http/docs.go Normal file
View file

@ -0,0 +1,40 @@
package httpapi
import (
"net/http"
"github.com/gin-gonic/gin"
"github.com/swaggest/swgui/v5emb"
"codeberg.org/squidd/sonda/internal/api/openapi"
)
const (
specPath = "/api/v1/openapi.yaml"
docsPath = "/api/docs/"
)
// registerDocs serves the OpenAPI spec and a Swagger UI for it. Both are public:
// they describe the API and contain no data. The UI's assets are embedded in the
// binary, so opening it never contacts another server.
func registerDocs(r *gin.Engine, v1 *gin.RouterGroup) {
v1.GET("/openapi.yaml", func(c *gin.Context) {
c.Header("Cache-Control", "no-cache")
c.Data(http.StatusOK, "application/yaml; charset=utf-8", openapi.Spec)
})
ui := gin.WrapH(v5emb.New("Sonda API", specPath, docsPath))
r.GET("/api/docs", func(c *gin.Context) { c.Redirect(http.StatusMovedPermanently, docsPath) })
r.GET("/api/docs/*any", docsHeaders, ui)
r.HEAD("/api/docs/*any", docsHeaders, ui)
}
// docsHeaders protects the page where people paste their token: it cannot be
// framed by another site, and the browser must not guess content types.
func docsHeaders(c *gin.Context) {
h := c.Writer.Header()
h.Set("X-Frame-Options", "DENY")
h.Set("Content-Security-Policy", "frame-ancestors 'none'")
h.Set("X-Content-Type-Options", "nosniff")
h.Set("Referrer-Policy", "no-referrer")
}

View file

@ -0,0 +1,238 @@
package httpapi
import (
"context"
"net/http"
"net/http/httptest"
"net/url"
"regexp"
"sort"
"strings"
"testing"
"github.com/getkin/kin-openapi/openapi3"
"github.com/gin-gonic/gin"
"codeberg.org/squidd/sonda/internal/api/openapi"
)
func loadSpec(t *testing.T) *openapi3.T {
t.Helper()
loader := openapi3.NewLoader()
doc, err := loader.LoadFromData(openapi.Spec)
if err != nil {
t.Fatalf("the spec does not load: %v", err)
}
return doc
}
func TestSpecIsValidOpenAPI(t *testing.T) {
if err := loadSpec(t).Validate(context.Background()); err != nil {
t.Fatalf("the spec is not valid OpenAPI: %v", err)
}
}
// specOperations lists "METHOD /path" for every operation in the spec.
func specOperations(doc *openapi3.T) []string {
var out []string
for path, item := range doc.Paths.Map() {
for method := range item.Operations() {
out = append(out, method+" "+path)
}
}
sort.Strings(out)
return out
}
// routerOperations lists "METHOD /path" for every /api/v1 route the router serves,
// written the way the spec writes them: relative to /api/v1, with {id}.
func routerOperations(t *testing.T, h http.Handler) []string {
t.Helper()
engine, ok := h.(*gin.Engine)
if !ok {
t.Fatalf("handler is a %T, want *gin.Engine", h)
}
param := regexp.MustCompile(`:([A-Za-z_]+)`)
var out []string
for _, r := range engine.Routes() {
rest, ok := strings.CutPrefix(r.Path, "/api/v1")
if !ok {
continue // the docs UI lives outside /api/v1
}
out = append(out, r.Method+" "+param.ReplaceAllString(rest, "{$1}"))
}
sort.Strings(out)
return out
}
func diff(a, b []string) []string {
in := map[string]bool{}
for _, x := range b {
in[x] = true
}
var out []string
for _, x := range a {
if !in[x] {
out = append(out, x)
}
}
return out
}
// The spec and the router must describe the same API, in both directions.
func TestSpecAndRoutesAgree(t *testing.T) {
h := newTestAPI(t)
spec, routes := specOperations(loadSpec(t)), routerOperations(t, h)
if missing := diff(routes, spec); len(missing) > 0 {
t.Errorf("routes that are not in the spec (add them to openapi.yaml):\n %s", strings.Join(missing, "\n "))
}
if extra := diff(spec, routes); len(extra) > 0 {
t.Errorf("operations in the spec that no route serves (remove them or add the route):\n %s", strings.Join(extra, "\n "))
}
if len(spec) == 0 {
t.Fatal("the spec has no operations")
}
}
func TestSpecOperationsAreWellFormed(t *testing.T) {
doc := loadSpec(t)
declared := map[string]bool{}
for _, tag := range doc.Tags {
declared[tag.Name] = true
}
seen := map[string]string{}
for path, item := range doc.Paths.Map() {
for method, op := range item.Operations() {
where := method + " " + path
if op.OperationID == "" {
t.Errorf("%s has no operationId", where)
} else if other, dup := seen[op.OperationID]; dup {
t.Errorf("%s and %s share the operationId %q", where, other, op.OperationID)
}
seen[op.OperationID] = where
if strings.TrimSpace(op.Summary) == "" {
t.Errorf("%s has no summary", where)
}
if len(op.Tags) == 0 {
t.Errorf("%s has no tag", where)
}
for _, tag := range op.Tags {
if !declared[tag] {
t.Errorf("%s uses the undeclared tag %q", where, tag)
}
}
// An operation that needs a token must say what a missing one looks like,
// and an admin-only one must say what a normal user gets.
if op.Security != nil && len(*op.Security) > 0 && op.Responses.Value("401") == nil {
t.Errorf("%s needs authentication but does not document 401", where)
}
if strings.HasPrefix(op.Description, "Admin only") && op.Responses.Value("403") == nil {
t.Errorf("%s is admin only but does not document 403", where)
}
}
}
}
// ---- serving ----
func TestSpecIsServedWithoutAuthentication(t *testing.T) {
h := newTestAPI(t)
req := httptest.NewRequest("GET", "/api/v1/openapi.yaml", nil)
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
if rec.Code != http.StatusOK {
t.Fatalf("status = %d", rec.Code)
}
if ct := rec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "application/yaml") {
t.Errorf("Content-Type = %q", ct)
}
if rec.Body.String() != string(openapi.Spec) {
t.Error("the served spec differs from the embedded one")
}
}
func fetch(h http.Handler, path string) *httptest.ResponseRecorder {
rec := httptest.NewRecorder()
h.ServeHTTP(rec, httptest.NewRequest("GET", path, nil))
return rec
}
func TestDocsRedirectToTheTrailingSlash(t *testing.T) {
rec := fetch(newTestAPI(t), "/api/docs")
if rec.Code != http.StatusMovedPermanently || rec.Header().Get("Location") != "/api/docs/" {
t.Fatalf("status %d, Location %q", rec.Code, rec.Header().Get("Location"))
}
}
// Opening the docs must never contact another server: the page and every asset
// it needs come from Sonda itself.
func TestSwaggerUIWorksOffline(t *testing.T) {
h := newTestAPI(t)
page := fetch(h, "/api/docs/")
if page.Code != http.StatusOK || !strings.HasPrefix(page.Header().Get("Content-Type"), "text/html") {
t.Fatalf("docs page: %d %q", page.Code, page.Header().Get("Content-Type"))
}
html := page.Body.String()
if !strings.Contains(html, "/api/v1/openapi.yaml") {
t.Error("the page does not point at the spec")
}
// The page's own script builds addresses from window.location, so look at what
// it loads (src and href), not at every "//" in the text.
refs := regexp.MustCompile(`(?:src|href)="([^"]+)"`).FindAllStringSubmatch(html, -1)
if len(refs) == 0 {
t.Fatal("the page references no assets")
}
base, _ := url.Parse("http://sonda.local/api/docs/")
for _, m := range refs {
u, err := base.Parse(m[1])
if err != nil {
t.Fatalf("bad reference %q: %v", m[1], err)
}
if u.Host != base.Host {
t.Errorf("asset %q is served from another host", m[1])
continue
}
asset := fetch(h, u.Path)
if asset.Code != http.StatusOK || asset.Body.Len() == 0 {
t.Errorf("asset %s: status %d, %d bytes", u.Path, asset.Code, asset.Body.Len())
}
}
}
func TestDocsAreAvailableWithoutAToken(t *testing.T) {
h := newTestAPI(t)
for _, path := range []string{"/api/docs/", "/api/v1/openapi.yaml"} {
if rec := fetch(h, path); rec.Code != http.StatusOK {
t.Errorf("%s without a token: %d", path, rec.Code)
}
}
}
func TestDocsPageIsHardenedAndAnswersHead(t *testing.T) {
h := newTestAPI(t)
page := fetch(h, "/api/docs/")
for header, want := range map[string]string{
"X-Frame-Options": "DENY",
"Content-Security-Policy": "frame-ancestors 'none'",
"X-Content-Type-Options": "nosniff",
"Referrer-Policy": "no-referrer",
} {
if got := page.Header().Get(header); got != want {
t.Errorf("%s = %q, want %q", header, got, want)
}
}
// The assets carry the same protection.
if got := fetch(h, "/api/docs/swagger-ui.css").Header().Get("X-Content-Type-Options"); got != "nosniff" {
t.Errorf("asset X-Content-Type-Options = %q", got)
}
rec := httptest.NewRecorder()
h.ServeHTTP(rec, httptest.NewRequest("HEAD", "/api/docs/", nil))
if rec.Code != http.StatusOK {
t.Errorf("HEAD /api/docs/: %d", rec.Code)
}
}

View file

@ -52,6 +52,8 @@ func (h *listenHandlers) record(c *gin.Context) {
switch {
case errors.Is(err, listening.ErrInvalidEvent):
writeError(c, http.StatusBadRequest, "invalid_input", err.Error())
case errors.Is(err, listening.ErrUserNotFound):
writeError(c, http.StatusUnauthorized, "unauthorized", "account no longer exists")
case errors.Is(err, listening.ErrTrackNotFound):
writeError(c, http.StatusNotFound, "track_not_found", err.Error())
case err != nil:

View file

@ -87,12 +87,14 @@ func requireAuth(tokens tokenParser, allowQuery bool) gin.HandlerFunc {
return func(c *gin.Context) {
token := ""
if header := c.GetHeader("Authorization"); header != "" {
var ok bool
if token, ok = strings.CutPrefix(header, "Bearer "); !ok {
// Any other scheme, or a bare token, is not accepted.
// The scheme name is case-insensitive (RFC 7235). Any other scheme,
// or a bare token, is not accepted.
const scheme = "Bearer "
if len(header) < len(scheme) || !strings.EqualFold(header[:len(scheme)], scheme) {
writeError(c, http.StatusUnauthorized, "unauthorized", "missing bearer token")
return
}
token = header[len(scheme):]
} else if allowQuery {
token = c.Query("access_token")
}

View file

@ -89,6 +89,7 @@ func NewRouter(d Deps) *gin.Engine {
v1 := r.Group("/api/v1")
v1.GET("/health", health)
registerDocs(r, v1)
a := &authHandlers{svc: d.Auth}
v1.POST("/auth/register", a.register)

View file

@ -0,0 +1,13 @@
// Package openapi holds the OpenAPI description of the Sonda API.
//
// The spec is written by hand and embedded in the binary. Tests keep it honest:
// they fail when a route and the spec disagree, and they validate real
// responses against it.
package openapi
import _ "embed"
// Spec is the OpenAPI 3.0 document, in YAML.
//
//go:embed openapi.yaml
var Spec []byte

File diff suppressed because it is too large Load diff

View file

@ -15,6 +15,7 @@ import (
var (
ErrInvalidEvent = errors.New("invalid listening event")
ErrTrackNotFound = errors.New("track not found")
ErrUserNotFound = errors.New("user not found") // the account was deleted
)
// EventType says what the listener did.
@ -42,8 +43,8 @@ type Event struct {
// Store persists events.
type Store interface {
// Record saves e. It returns created=false when an event with the same
// (user, idempotency key) already exists, and ErrTrackNotFound for an
// unknown track.
// (user, idempotency key) already exists, ErrTrackNotFound for an unknown
// track and ErrUserNotFound for an account that no longer exists.
Record(ctx context.Context, e Event) (created bool, err error)
}

View file

@ -36,6 +36,16 @@ func NewListeningRepo(db *bun.DB) *ListeningRepo { return &ListeningRepo{db: db}
// Record inserts e. A repeated (user, idempotency key) is ignored and reported
// as created=false.
func (r *ListeningRepo) Record(ctx context.Context, e listening.Event) (bool, error) {
// An access token outlives a deleted account for a few minutes. Say so
// instead of failing on the foreign key.
userExists, err := r.db.NewSelect().Model((*userRow)(nil)).Where("id = ?", e.UserID).Exists(ctx)
if err != nil {
return false, fmt.Errorf("check user: %w", err)
}
if !userExists {
return false, listening.ErrUserNotFound
}
exists, err := r.db.NewSelect().Model((*trackRow)(nil)).Where("id = ?", e.TrackID).Exists(ctx)
if err != nil {
return false, fmt.Errorf("check track: %w", err)

View file

@ -125,3 +125,29 @@ func TestListeningRepo(t *testing.T) {
}
})
}
func TestListeningRepoRefusesADeletedUser(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
ctx := context.Background()
users := NewUserRepo(db)
u, err := users.CreateUser(ctx, "gone", "h", false)
if err != nil {
t.Fatal(err)
}
var trackID int64
if err := db.QueryRow("INSERT INTO tracks (title) VALUES ('t') RETURNING id").Scan(&trackID); err != nil {
t.Fatal(err)
}
if err := users.DeleteUser(ctx, u.ID); err != nil {
t.Fatal(err)
}
_, err = NewListeningRepo(db).Record(ctx, listening.Event{
UserID: u.ID, TrackID: trackID, Type: listening.Play,
OccurredAt: time.Unix(1_700_000_000, 0), IdempotencyKey: "k",
})
if !errors.Is(err, listening.ErrUserNotFound) {
t.Fatalf("err = %v, want ErrUserNotFound (not a foreign-key failure)", err)
}
})
}