Merge pull request 'feat(api): OpenAPI spec and an offline Swagger UI' (#16) from feat/openapi-docs into main
This commit is contained in:
commit
e258c9d182
16 changed files with 2007 additions and 10 deletions
10
README.md
10
README.md
|
|
@ -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
7
go.mod
|
|
@ -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
22
go.sum
|
|
@ -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=
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
450
internal/api/http/contract_test.go
Normal file
450
internal/api/http/contract_test.go
Normal 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
40
internal/api/http/docs.go
Normal 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")
|
||||
}
|
||||
238
internal/api/http/docs_test.go
Normal file
238
internal/api/http/docs_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
13
internal/api/openapi/openapi.go
Normal file
13
internal/api/openapi/openapi.go
Normal 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
|
||||
1133
internal/api/openapi/openapi.yaml
Normal file
1133
internal/api/openapi/openapi.yaml
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -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)
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue