fix(api): make the spec say what the code does, and make the tests prove it

- fix(spec): album.artist and track.album are real nullable objects (OpenAPI
  3.0 only honours nullable next to a type); the stream documents 304 on HEAD,
  412, If-Unmodified-Since and multipart/byteranges answers
- fix(spec): passwords and idempotency keys are measured in bytes, an overlap
  between libraries is a 400, a library PATCH needs a name or a path, limit 0
  means the default, login has no format rules of its own, and the wording about
  signing out says that issued access tokens live until they expire
- fix(auth): the Bearer scheme is matched ignoring case (RFC 7235)
- fix(listening): a listen with the access token of a deleted account is a 401
  instead of a database error
- fix(docs): the docs pages answer HEAD and carry X-Frame-Options, a CSP
  frame-ancestors, nosniff and no-referrer, since people paste their token there
- test: error codes are asserted in every error case; every accepted request is
  validated against the spec too; HEAD and 3xx answers are checked by hand
  because the validator skips them; the stream Content-Type must be one the
  spec lists; a scan held mid-way proves the scan_running conflicts; null album
  and null album artist, a vanished file, multi-range, 412 and HEAD 304 are
  exercised. Verified by breaking the code and the spec on purpose
This commit is contained in:
tgiachi 2026-11-11 14:46:28 +01:00
commit 2ae4aedac0
7 changed files with 405 additions and 114 deletions

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

@ -4,11 +4,14 @@ import (
"bytes"
"context"
"encoding/json"
"io"
"mime"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strconv"
"sync"
"testing"
"time"
@ -23,14 +26,35 @@ import (
"codeberg.org/squidd/sonda/internal/streaming"
)
// Contract tests: real requests against the real services, with every response
// checked against openapi.yaml (status, headers, JSON body). A field that is
// added, renamed or dropped in the code without the spec fails here.
// 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 two files of the fixture their tags without real audio.
type contractReader struct{}
// 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
}
func (contractReader) Read(path string) (library.Metadata, error) {
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},
@ -40,6 +64,9 @@ func (contractReader) Read(path string) (library.Metadata, error) {
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
}
@ -56,6 +83,8 @@ 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
@ -63,9 +92,10 @@ type contract struct {
func newContract(t *testing.T) *contract {
t.Helper()
h, _ := newTestEnvDB(t, func(d *Deps, db *bun.DB) {
reader := &contractReader{}
h, db := newTestEnvDB(t, func(d *Deps, db *bun.DB) {
repo := storage.NewLibraryRepo(db)
mgr := library.NewManager(library.NewScanner(repo, contractReader{}, library.NewHub(), 2), repo)
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}
@ -80,25 +110,29 @@ func newContract(t *testing.T) *contract {
}
music := t.TempDir()
for _, f := range []string{"a.mp3", "b.flac"} {
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, router: router, seen: map[string]bool{}, music: music}
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 the answer against the spec and
// returns it. headers are extra request headers.
// 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 buf bytes.Buffer
var payload []byte
if body != nil {
if err := json.NewEncoder(&buf).Encode(body); err != nil {
var err error
if payload, err = json.Marshal(body); err != nil {
c.t.Fatal(err)
}
}
req := httptest.NewRequest(method, "/api/v1"+path, &buf)
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)
}
@ -107,11 +141,11 @@ func (c *contract) call(method, path, token string, body any, headers ...string)
}
rec := httptest.NewRecorder()
c.h.ServeHTTP(rec, req)
c.validate(req, rec)
c.validate(req, payload, rec)
return rec
}
func (c *contract) validate(req *http.Request, rec *httptest.ResponseRecorder) {
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 {
@ -119,40 +153,89 @@ func (c *contract) validate(req *http.Request, rec *httptest.ResponseRecorder) {
return
}
c.seen[req.Method+" "+route.Path] = true
opts := &openapi3filter.Options{AuthenticationFunc: openapi3filter.NoopAuthenticationFunc}
where := req.Method + " " + req.URL.RequestURI()
in := &openapi3filter.RequestValidationInput{
Request: req, PathParams: params, Route: route,
Options: &openapi3filter.Options{AuthenticationFunc: openapi3filter.NoopAuthenticationFunc},
// 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, // a status the spec does not list is a failure
// Audio and YAML bodies are not JSON, and HEAD has no body to check.
ExcludeResponseBody: req.Method == http.MethodHead || route.Path == "/openapi.yaml" ||
(route.Path == "/tracks/{id}/stream" && rec.Code/100 == 2),
},
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 %s -> %d does not match the spec: %v\nbody: %.300s", req.Method, req.URL.Path, rec.Code, err, rec.Body.String())
c.t.Errorf("%s -> %d does not match the spec: %v\nbody: %.300s", where, rec.Code, err, rec.Body.String())
}
}
func (c *contract) expect(rec *httptest.ResponseRecorder, want int, what string) map[string]any {
// 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)
@ -162,102 +245,135 @@ func TestResponsesMatchTheSpec(t *testing.T) {
// ---- 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")
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")
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")
c.expect(c.call("POST", "/auth/login", "", nil), 400, "login without body")
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")
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")
c.expect(c.call("POST", "/auth/refresh", "", "not an object"), 400, "refresh bad body")
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")
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")
c.expect(c.call("POST", "/auth/password", token, map[string]string{"current_password": "correct horse", "new_password": "x"}), 400, "password weak")
c.expect(c.call("POST", "/auth/password", "", map[string]string{}), 401, "password without token")
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")
c.expect(c.call("POST", "/users", token, map[string]any{"username": "x", "password": "bobs long pass"}), 400, "create invalid")
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")
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")
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")
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")
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")
c.expect(c.call("DELETE", "/users/"+aliceID, token, nil), 409, "delete the last admin")
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")
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": c.music}), 409, "duplicate library")
c.expect(c.call("POST", "/libraries", token, map[string]string{"name": "Bad", "path": "relative/path"}), 400, "invalid library")
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")
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")
c.expect(c.call("POST", "/libraries/999/scan", token, nil), 404, "scan unknown library")
// 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["found"] != float64(2) || last["added"] != float64(0) || last["unchanged"] != float64(2) {
t.Fatalf("second scan = %v, want 2 files, all unchanged", last)
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)
}
extra := c.expect(c.call("POST", "/libraries", token, map[string]string{"name": "Extra", "path": t.TempDir()}), 201, "second library")
c.expect(c.call("DELETE", "/libraries/"+idOf(extra), token, nil), 204, "delete library")
c.expect(c.call("DELETE", "/libraries/"+idOf(extra), token, nil), 404, "delete library twice")
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))
c.expect(c.call("GET", "/artists?limit=abc", token, nil), 400, "artists bad limit")
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")
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")
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")
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 scanned files", tracks)
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?q="+string(rune(0x41))+"&limit=-1", token, nil), 400, "tracks bad limit")
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")
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")
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())
}
@ -267,26 +383,39 @@ func TestResponsesMatchTheSpec(t *testing.T) {
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)
}
if rec := c.call("GET", stream, token, nil, "If-Modified-Since", time.Now().Add(time.Hour).UTC().Format(http.TimeFormat)); rec.Code != 304 {
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)
}
c.expect(c.call("GET", "/tracks/999/stream", token, nil), 404, "stream unknown track")
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")
c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": tid, "event_type": "dance", "idempotency_key": "k3"}), 400, "listen invalid")
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
@ -300,23 +429,22 @@ func TestResponsesMatchTheSpec(t *testing.T) {
}
}
// scanDone waits for the running scan to finish.
func (c *contract) scanDone(token string) {
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()
deadline := time.Now().Add(10 * time.Second)
for time.Now().Before(deadline) {
rec := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/api/v1/library/scan", nil)
req.Header.Set("Authorization", "Bearer "+token)
c.h.ServeHTTP(rec, req)
var st struct {
Running bool `json:"running"`
}
_ = json.Unmarshal(rec.Body.Bytes(), &st)
if !st.Running {
return
}
time.Sleep(20 * time.Millisecond)
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)
}
c.t.Fatal("the scan did not finish in time")
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)}
}

View file

@ -23,7 +23,18 @@ func registerDocs(r *gin.Engine, v1 *gin.RouterGroup) {
c.Data(http.StatusOK, "application/yaml; charset=utf-8", openapi.Spec)
})
ui := v5emb.New("Sonda API", specPath, docsPath)
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", gin.WrapH(ui))
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

@ -211,3 +211,28 @@ func TestDocsAreAvailableWithoutAToken(t *testing.T) {
}
}
}
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

@ -104,7 +104,7 @@ paths:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/Credentials'}
schema: {$ref: '#/components/schemas/LoginRequest'}
responses:
'200':
description: A new session.
@ -127,7 +127,8 @@ paths:
Exchanges a refresh token for a new access token and a new refresh token. The old refresh
token stops working. Presenting a spent one again, more than ten seconds after it was used,
ends every session of that user; inside those ten seconds it only fails, so two tabs
refreshing together do not log each other out.
refreshing together do not log each other out. This holds for any spent token, including
one revoked by logout or by a password change.
requestBody:
required: true
content:
@ -180,7 +181,9 @@ paths:
tags: [Auth]
operationId: changePassword
summary: Change your password
description: "Signs you out everywhere: every refresh token of the account is revoked."
description: |
Revokes every refresh token of the account, so no session can be renewed. An access token
that was already issued keeps working until it expires (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
@ -286,7 +289,10 @@ paths:
tags: [Users]
operationId: deleteUser
summary: Delete a user
description: Admin only. Removes the account and its sessions. The last admin cannot be deleted.
description: |
Admin only. Removes the account and its refresh tokens. Access tokens already issued stop
working at once on admin routes, `/auth/me`, `/auth/password` and `/listens`; other routes
accept them until they expire (15 minutes by default). The last admin cannot be deleted.
security: [{bearerAuth: []}]
responses:
'204': {description: Deleted.}
@ -311,7 +317,9 @@ paths:
tags: [Users]
operationId: resetUserPassword
summary: Reset a user's password
description: Admin only. Signs that user out everywhere.
description: |
Admin only. Revokes every refresh token of that user, so no session can be renewed. Access
tokens already issued keep working until they expire (15 minutes by default).
security: [{bearerAuth: []}]
requestBody:
required: true
@ -321,7 +329,10 @@ paths:
type: object
required: [password]
properties:
password: {type: string, format: password, minLength: 8, maxLength: 256}
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
responses:
'204': {description: Password reset.}
'400': {$ref: '#/components/responses/InvalidInput'}
@ -361,7 +372,9 @@ paths:
summary: Add a library
description: |
Admin only. The path must be an absolute, existing directory, never the filesystem root,
and never inside or around another library. Names are unique ignoring case.
and never inside or around another library (a bad path or an overlap is `400 invalid_input`).
A name or path that another library already uses is `409 library_exists`. Names are unique
ignoring case.
security: [{bearerAuth: []}]
requestBody:
required: true
@ -652,6 +665,10 @@ paths:
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: The whole file.
@ -665,17 +682,22 @@ paths:
audio/flac:
schema: {type: string, format: binary}
'206':
description: The requested byte range.
description: |
The requested byte range. Several ranges in one request are answered as
`multipart/byteranges`.
headers:
Content-Range:
description: The range sent and the size of the file, for example `bytes 0-99/40635`.
description: The range sent and the size of the file, for example `bytes 0-99/40635`. Absent for a multipart answer.
schema: {type: string}
content:
audio/mpeg:
schema: {type: string, format: binary}
audio/flac:
schema: {type: string, format: binary}
multipart/byteranges:
schema: {type: string, format: binary}
'304': {description: Not modified since `If-Modified-Since`.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
@ -702,6 +724,14 @@ paths:
in: header
required: false
schema: {type: string}
- name: If-Modified-Since
in: header
required: false
schema: {type: string}
- name: If-Unmodified-Since
in: header
required: false
schema: {type: string}
responses:
'200':
description: Headers of the whole file.
@ -714,9 +744,11 @@ paths:
headers:
Content-Range:
schema: {type: string}
'304': {description: Not modified since `If-Modified-Since`.}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {description: No such track or file.}
'412': {description: '`If-Unmodified-Since` names a date before the last change of the file.'}
'416': {description: The range cannot be satisfied.}
/listens:
@ -781,8 +813,8 @@ components:
Limit:
name: limit
in: query
description: Page size. Default 50; values above 200 are lowered to 200.
schema: {type: integer, minimum: 0}
description: Page size. 50 when absent or 0; values above 200 are lowered to 200.
schema: {type: integer, minimum: 0, default: 50}
Offset:
name: offset
in: query
@ -869,7 +901,17 @@ components:
minLength: 3
maxLength: 64
pattern: '^[A-Za-z0-9._-]+$'
password: {type: string, format: password, minLength: 8, maxLength: 256}
password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
LoginRequest:
type: object
required: [username, password]
properties:
username: {type: string}
password: {type: string, format: password}
CreateUser:
allOf:
@ -909,7 +951,10 @@ components:
required: [current_password, new_password]
properties:
current_password: {type: string, format: password}
new_password: {type: string, format: password, minLength: 8, maxLength: 256}
new_password:
type: string
format: password
description: 8 to 256 bytes (UTF-8).
Library:
type: object
@ -930,7 +975,9 @@ components:
LibraryUpdate:
type: object
minProperties: 1
anyOf:
- required: [name]
- required: [path]
properties:
name: {type: string, minLength: 1, maxLength: 100}
path: {type: string}
@ -997,10 +1044,14 @@ components:
id: {type: integer, format: int64}
title: {type: string}
artist:
type: object
nullable: true
description: The album artist, if the album has one.
allOf:
- $ref: '#/components/schemas/ArtistRef'
description: The album artist; null when the album has none.
additionalProperties: false
required: [id, name]
properties:
id: {type: integer, format: int64}
name: {type: string}
track_count: {type: integer}
duration_ms: {type: integer, format: int64}
@ -1015,9 +1066,14 @@ components:
track_no: {type: integer, description: 0 when unknown.}
disc_no: {type: integer, description: 0 when unknown.}
album:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/AlbumRef'
description: The album; null for a track that belongs to none.
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
artists:
type: array
items: {$ref: '#/components/schemas/ArtistRef'}
@ -1067,7 +1123,7 @@ components:
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time, description: Defaults to now.}
duration_played_ms: {type: integer, format: int64, minimum: 0}
idempotency_key: {type: string, minLength: 1, maxLength: 128}
idempotency_key: {type: string, description: 1 to 128 bytes (UTF-8).}
ListenResult:
type: object