From 2ae4aedac00957ede2e15bc889f61c0e5dcc8a2f Mon Sep 17 00:00:00 2001 From: tgiachi Date: Wed, 11 Nov 2026 14:46:28 +0100 Subject: [PATCH] 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 --- internal/api/http/auth_test.go | 32 ++- internal/api/http/contract_test.go | 300 +++++++++++++++++++-------- internal/api/http/docs.go | 15 +- internal/api/http/docs_test.go | 25 +++ internal/api/http/handlers_listen.go | 2 + internal/api/http/middleware.go | 8 +- internal/api/openapi/openapi.yaml | 96 +++++++-- internal/listening/listening.go | 5 +- internal/storage/listening.go | 10 + internal/storage/repos_test.go | 26 +++ 10 files changed, 405 insertions(+), 114 deletions(-) diff --git a/internal/api/http/auth_test.go b/internal/api/http/auth_test.go index 7dc9eda..e271cc1 100644 --- a/internal/api/http/auth_test.go +++ b/internal/api/http/auth_test.go @@ -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) + } +} diff --git a/internal/api/http/contract_test.go b/internal/api/http/contract_test.go index a5f7515..32622f9 100644 --- a/internal/api/http/contract_test.go +++ b/internal/api/http/contract_test.go @@ -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, checks the answer against the spec and -// returns it. headers are extra request headers. +// call sends a request to /api/v1, 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)} } diff --git a/internal/api/http/docs.go b/internal/api/http/docs.go index 49d6cf8..50d4112 100644 --- a/internal/api/http/docs.go +++ b/internal/api/http/docs.go @@ -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") } diff --git a/internal/api/http/docs_test.go b/internal/api/http/docs_test.go index 7a84da5..d30b480 100644 --- a/internal/api/http/docs_test.go +++ b/internal/api/http/docs_test.go @@ -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) + } +} diff --git a/internal/api/http/handlers_listen.go b/internal/api/http/handlers_listen.go index 40073a4..ba550e0 100644 --- a/internal/api/http/handlers_listen.go +++ b/internal/api/http/handlers_listen.go @@ -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: diff --git a/internal/api/http/middleware.go b/internal/api/http/middleware.go index 2175df9..3359f5c 100644 --- a/internal/api/http/middleware.go +++ b/internal/api/http/middleware.go @@ -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") } diff --git a/internal/api/openapi/openapi.yaml b/internal/api/openapi/openapi.yaml index b26cc71..eab9bd3 100644 --- a/internal/api/openapi/openapi.yaml +++ b/internal/api/openapi/openapi.yaml @@ -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 diff --git a/internal/listening/listening.go b/internal/listening/listening.go index 5e10416..971822a 100644 --- a/internal/listening/listening.go +++ b/internal/listening/listening.go @@ -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) } diff --git a/internal/storage/listening.go b/internal/storage/listening.go index d8d7dd8..6403e51 100644 --- a/internal/storage/listening.go +++ b/internal/storage/listening.go @@ -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) diff --git a/internal/storage/repos_test.go b/internal/storage/repos_test.go index 7e445e3..935f213 100644 --- a/internal/storage/repos_test.go +++ b/internal/storage/repos_test.go @@ -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) + } + }) +}