From e14c523828dfb19799776846a9acd8e000795f5b Mon Sep 17 00:00:00 2001 From: tgiachi Date: Wed, 11 Nov 2026 13:43:38 +0100 Subject: [PATCH] feat(catalog): add the read API for artists, albums and tracks - feat(api): GET /api/v1/artists, /albums and /tracks with q (case and accent insensitive substring), limit and offset (default 50, at most 200) and a total; filters library_id, artist_id and album_id; GET /artists/{id}, /albums/{id} and /tracks/{id}; any signed-in user can read - feat(catalog): only tracks with a file that is not flagged missing are visible, so everything shown can be played; a track with several files is listed once; album artists without credited tracks (compilations) are listed - feat(storage): results are ordered the same way on SQLite and PostgreSQL (plain byte order), LIKE wildcards in the search text are escaped, and a page costs a fixed number of queries: related items and counts are loaded in batches - feat(storage): tracks get a title_key computed in Go (migration 0006, with a startup refresh), like artists and albums - test: ordering, paging, search with accents and wildcards, library filter, duplicate encodings, missing files, details, and a query-count guard on both databases --- cmd/sondad/main.go | 2 + internal/api/http/catalog_test.go | 257 ++++++++++ internal/api/http/handlers_catalog.go | 230 +++++++++ internal/api/http/router.go | 19 + internal/catalog/catalog.go | 177 +++++++ internal/catalog/catalog_test.go | 136 ++++++ internal/storage/catalog.go | 486 +++++++++++++++++++ internal/storage/catalog_test.go | 479 ++++++++++++++++++ internal/storage/library.go | 22 +- internal/storage/storage_test.go | 4 +- migrations/postgres/0006_track_title_key.sql | 7 + migrations/sqlite/0006_track_title_key.sql | 7 + 12 files changed, 1821 insertions(+), 5 deletions(-) create mode 100644 internal/api/http/catalog_test.go create mode 100644 internal/api/http/handlers_catalog.go create mode 100644 internal/catalog/catalog.go create mode 100644 internal/catalog/catalog_test.go create mode 100644 internal/storage/catalog.go create mode 100644 internal/storage/catalog_test.go create mode 100644 migrations/postgres/0006_track_title_key.sql create mode 100644 migrations/sqlite/0006_track_title_key.sql diff --git a/cmd/sondad/main.go b/cmd/sondad/main.go index 5c93fed..96b4e79 100644 --- a/cmd/sondad/main.go +++ b/cmd/sondad/main.go @@ -16,6 +16,7 @@ import ( httpapi "codeberg.org/squidd/sonda/internal/api/http" "codeberg.org/squidd/sonda/internal/auth" + "codeberg.org/squidd/sonda/internal/catalog" "codeberg.org/squidd/sonda/internal/config" "codeberg.org/squidd/sonda/internal/library" "codeberg.org/squidd/sonda/internal/listening" @@ -103,6 +104,7 @@ func run() error { Listening: listening.NewService(storage.NewListeningRepo(db)), Scan: scanControl{ctx: ctx, m: scans}, Libraries: libraries, + Catalog: catalog.NewService(storage.NewCatalogRepo(db)), Streams: streaming.NewService(libraryRepo), }) diff --git a/internal/api/http/catalog_test.go b/internal/api/http/catalog_test.go new file mode 100644 index 0000000..58b0c83 --- /dev/null +++ b/internal/api/http/catalog_test.go @@ -0,0 +1,257 @@ +package httpapi + +import ( + "context" + "net/http" + "sort" + "testing" + + "codeberg.org/squidd/sonda/internal/catalog" +) + +// fakeCatalog returns canned data and records the last filter it received. +type fakeCatalog struct { + last catalog.Filter + err error + artists []catalog.Artist + albums []catalog.Album + tracks []catalog.Track +} + +func (f *fakeCatalog) Artists(_ context.Context, fl catalog.Filter) (catalog.Page[catalog.Artist], error) { + f.last = fl + return catalog.Page[catalog.Artist]{Items: f.artists, Total: 123, Limit: fl.Limit, Offset: fl.Offset}, f.err +} +func (f *fakeCatalog) Albums(_ context.Context, fl catalog.Filter) (catalog.Page[catalog.Album], error) { + f.last = fl + return catalog.Page[catalog.Album]{Items: f.albums, Total: 7, Limit: fl.Limit, Offset: fl.Offset}, f.err +} +func (f *fakeCatalog) Tracks(_ context.Context, fl catalog.Filter) (catalog.Page[catalog.Track], error) { + f.last = fl + return catalog.Page[catalog.Track]{Items: f.tracks, Total: 9, Limit: fl.Limit, Offset: fl.Offset}, f.err +} +func (f *fakeCatalog) Artist(_ context.Context, id int64) (catalog.Artist, error) { + if f.err != nil { + return catalog.Artist{}, f.err + } + return catalog.Artist{ID: id, Name: "Radiohead", AlbumCount: 2, TrackCount: 20}, nil +} +func (f *fakeCatalog) Album(_ context.Context, id int64) (catalog.Album, error) { + if f.err != nil { + return catalog.Album{}, f.err + } + return catalog.Album{ID: id, Title: "OK Computer", TrackCount: 12, DurationMs: 3200000, + Artist: &catalog.ArtistRef{ID: 1, Name: "Radiohead"}}, nil +} +func (f *fakeCatalog) Track(_ context.Context, id int64) (catalog.Track, error) { + if f.err != nil { + return catalog.Track{}, f.err + } + return catalog.Track{ID: id, Title: "Airbag", DurationMs: 284000, TrackNo: 1, DiscNo: 1, Format: "flac", + Album: &catalog.AlbumRef{ID: 3, Title: "OK Computer"}, + Artists: []catalog.ArtistRef{{ID: 1, Name: "Radiohead"}}}, nil +} + +var catalogRoutes = []string{ + "/api/v1/artists", "/api/v1/albums", "/api/v1/tracks", + "/api/v1/artists/1", "/api/v1/albums/1", "/api/v1/tracks/1", +} + +func catalogAPI(t *testing.T, fc *fakeCatalog) (http.Handler, string) { + t.Helper() + h := newTestAPIWith(t, func(d *Deps) { d.Catalog = fc }) + return h, registerAndLogin(t, h) +} + +func keys(m map[string]any) []string { + var out []string + for k := range m { + out = append(out, k) + } + sort.Strings(out) + return out +} + +func sameKeys(t *testing.T, what string, got map[string]any, want ...string) { + t.Helper() + sort.Strings(want) + g := keys(got) + if len(g) != len(want) { + t.Errorf("%s keys = %v, want %v", what, g, want) + return + } + for i := range g { + if g[i] != want[i] { + t.Errorf("%s keys = %v, want %v", what, g, want) + return + } + } +} + +func TestCatalogRoutesRequireAuth(t *testing.T) { + h, _ := catalogAPI(t, &fakeCatalog{}) + for _, path := range catalogRoutes { + if r := do(t, h, "GET", path, "", nil); r.Code != http.StatusUnauthorized { + t.Errorf("GET %s without a token: %d", path, r.Code) + } + if r := do(t, h, "GET", path+"?access_token=x", "", nil); r.Code != http.StatusUnauthorized { + t.Errorf("GET %s: a token in the URL must not work here: %d", path, r.Code) + } + } +} + +func TestAnySignedInUserCanBrowse(t *testing.T) { + fc := &fakeCatalog{} + h, admin := catalogAPI(t, fc) + _, bob := addUser(t, h, admin, "bob", false) + for _, path := range catalogRoutes { + if r := do(t, h, "GET", path, bob, nil); r.Code != http.StatusOK { + t.Errorf("GET %s as a normal user: %d %v", path, r.Code, r.Body) + } + } +} + +func TestCatalogListShapeAndPaging(t *testing.T) { + fc := &fakeCatalog{ + artists: []catalog.Artist{{ID: 1, Name: "Björk", AlbumCount: 3, TrackCount: 30}}, + albums: []catalog.Album{{ID: 2, Title: "Post", TrackCount: 11, DurationMs: 2400000, Artist: &catalog.ArtistRef{ID: 1, Name: "Björk"}}}, + tracks: []catalog.Track{{ID: 3, Title: "Army of Me", DurationMs: 235000, TrackNo: 1, DiscNo: 1, Format: "flac", + Album: &catalog.AlbumRef{ID: 2, Title: "Post"}, Artists: []catalog.ArtistRef{{ID: 1, Name: "Björk"}}}}, + } + h, tok := catalogAPI(t, fc) + + r := do(t, h, "GET", "/api/v1/artists?limit=20&offset=40", tok, nil) + if r.Code != http.StatusOK || r.Body["total"] != float64(123) || r.Body["limit"] != float64(20) || r.Body["offset"] != float64(40) { + t.Fatalf("artists page: %d %v", r.Code, r.Body) + } + sameKeys(t, "artists response", r.Body, "items", "total", "limit", "offset") + a := r.Body["items"].([]any)[0].(map[string]any) + sameKeys(t, "artist", a, "id", "name", "album_count", "track_count") + if a["name"] != "Björk" || a["album_count"] != float64(3) || a["track_count"] != float64(30) { + t.Errorf("artist = %v", a) + } + + r = do(t, h, "GET", "/api/v1/albums", tok, nil) + al := r.Body["items"].([]any)[0].(map[string]any) + sameKeys(t, "album", al, "id", "title", "artist", "track_count", "duration_ms") + sameKeys(t, "album artist", al["artist"].(map[string]any), "id", "name") + + r = do(t, h, "GET", "/api/v1/tracks", tok, nil) + tr := r.Body["items"].([]any)[0].(map[string]any) + // No file path, root or library path may ever appear. + sameKeys(t, "track", tr, "id", "title", "duration_ms", "track_no", "disc_no", "album", "artists", "format") + sameKeys(t, "track album", tr["album"].(map[string]any), "id", "title") + if tr["format"] != "flac" || len(tr["artists"].([]any)) != 1 { + t.Errorf("track = %v", tr) + } +} + +func TestCatalogEmptyListIsAnArrayNotNull(t *testing.T) { + h, tok := catalogAPI(t, &fakeCatalog{}) + for _, path := range []string{"/api/v1/artists", "/api/v1/albums", "/api/v1/tracks"} { + r := do(t, h, "GET", path, tok, nil) + items, ok := r.Body["items"].([]any) + if !ok || len(items) != 0 { + t.Errorf("%s: items = %#v, want an empty array", path, r.Body["items"]) + } + } +} + +func TestTrackWithoutAlbumHasNullAlbum(t *testing.T) { + fc := &fakeCatalog{tracks: []catalog.Track{{ID: 1, Title: "Loose", Artists: nil}}} + h, tok := catalogAPI(t, fc) + r := do(t, h, "GET", "/api/v1/tracks", tok, nil) + tr := r.Body["items"].([]any)[0].(map[string]any) + if v, present := tr["album"]; !present || v != nil { + t.Errorf("album = %#v, want an explicit null", v) + } + if arts, ok := tr["artists"].([]any); !ok || len(arts) != 0 { + t.Errorf("artists = %#v, want an empty array", tr["artists"]) + } +} + +func TestCatalogQueryParametersReachTheService(t *testing.T) { + fc := &fakeCatalog{} + h, tok := catalogAPI(t, fc) + + do(t, h, "GET", "/api/v1/tracks?q=black+sabbath&limit=25&offset=50&library_id=2&artist_id=3&album_id=4", tok, nil) + want := catalog.Filter{Query: "black sabbath", Limit: 25, Offset: 50, LibraryID: 2, ArtistID: 3, AlbumID: 4} + if fc.last != want { + t.Errorf("filter = %+v, want %+v", fc.last, want) + } + + do(t, h, "GET", "/api/v1/albums?artist_id=9", tok, nil) + if fc.last.ArtistID != 9 || fc.last.Limit != 0 { + t.Errorf("album filter = %+v (unset paging must stay 0 for the service to default)", fc.last) + } + + // Special characters survive URL decoding. + do(t, h, "GET", "/api/v1/artists?q=100%25+%26+more", tok, nil) + if fc.last.Query != "100% & more" { + t.Errorf("q = %q", fc.last.Query) + } +} + +func TestCatalogRejectsBadParameters(t *testing.T) { + fc := &fakeCatalog{} + h, tok := catalogAPI(t, fc) + for _, qs := range []string{"limit=abc", "offset=x", "library_id=1.5", "artist_id=-", "album_id=%20", "limit=99999999999999999999"} { + r := do(t, h, "GET", "/api/v1/tracks?"+qs, tok, nil) + if r.Code != http.StatusBadRequest || errCode(r) != "invalid_input" { + t.Errorf("?%s: %d %v", qs, r.Code, r.Body) + } + } + + // The service's own validation is a 400 too. + fc.err = catalog.ErrInvalidQuery + r := do(t, h, "GET", "/api/v1/tracks?limit=-1", tok, nil) + if r.Code != http.StatusBadRequest || errCode(r) != "invalid_input" { + t.Errorf("service rejection: %d %v", r.Code, r.Body) + } +} + +func TestCatalogDetails(t *testing.T) { + h, tok := catalogAPI(t, &fakeCatalog{}) + + r := do(t, h, "GET", "/api/v1/artists/5", tok, nil) + sameKeys(t, "artist", r.Body, "id", "name", "album_count", "track_count") + if r.Code != http.StatusOK || r.Body["id"] != float64(5) { + t.Errorf("artist: %d %v", r.Code, r.Body) + } + r = do(t, h, "GET", "/api/v1/albums/6", tok, nil) + sameKeys(t, "album", r.Body, "id", "title", "artist", "track_count", "duration_ms") + r = do(t, h, "GET", "/api/v1/tracks/7", tok, nil) + sameKeys(t, "track", r.Body, "id", "title", "duration_ms", "track_no", "disc_no", "album", "artists", "format") + if r.Code != http.StatusOK || r.Body["id"] != float64(7) { + t.Errorf("track: %d %v", r.Code, r.Body) + } +} + +func TestCatalogDetailErrors(t *testing.T) { + fc := &fakeCatalog{err: catalog.ErrNotFound} + h, tok := catalogAPI(t, fc) + for path, code := range map[string]string{ + "/api/v1/artists/1": "artist_not_found", + "/api/v1/albums/1": "album_not_found", + "/api/v1/tracks/1": "track_not_found", + } { + r := do(t, h, "GET", path, tok, nil) + if r.Code != http.StatusNotFound || errCode(r) != code { + t.Errorf("%s: %d %v, want 404 %s", path, r.Code, r.Body, code) + } + } + for _, path := range []string{"/api/v1/artists/abc", "/api/v1/albums/0", "/api/v1/tracks/-1"} { + if r := do(t, h, "GET", path, tok, nil); r.Code != http.StatusBadRequest { + t.Errorf("%s: %d, want 400", path, r.Code) + } + } +} + +// The stream route lives under /tracks/{id}: the detail route must not shadow it. +func TestTrackDetailDoesNotShadowTheStreamRoute(t *testing.T) { + h, tok := catalogAPI(t, &fakeCatalog{}) + r := do(t, h, "GET", "/api/v1/tracks/1/stream", tok, nil) + if r.Code == http.StatusOK && r.Body["title"] != nil { + t.Fatal("the stream URL answered with track details") + } +} diff --git a/internal/api/http/handlers_catalog.go b/internal/api/http/handlers_catalog.go new file mode 100644 index 0000000..bf9edbc --- /dev/null +++ b/internal/api/http/handlers_catalog.go @@ -0,0 +1,230 @@ +package httpapi + +import ( + "errors" + "net/http" + "strconv" + + "github.com/gin-gonic/gin" + + "codeberg.org/squidd/sonda/internal/catalog" +) + +// catalogHandlers serve the read-only catalog to any signed-in user. No file +// path, library path or directory is ever part of these responses. +type catalogHandlers struct{ svc catalogService } + +type artistRefJSON struct { + ID int64 `json:"id"` + Name string `json:"name"` +} + +type albumRefJSON struct { + ID int64 `json:"id"` + Title string `json:"title"` +} + +type artistJSON struct { + ID int64 `json:"id"` + Name string `json:"name"` + AlbumCount int `json:"album_count"` + TrackCount int `json:"track_count"` +} + +type albumJSON struct { + ID int64 `json:"id"` + Title string `json:"title"` + Artist *artistRefJSON `json:"artist"` + TrackCount int `json:"track_count"` + DurationMs int64 `json:"duration_ms"` +} + +type trackJSON struct { + ID int64 `json:"id"` + Title string `json:"title"` + DurationMs int64 `json:"duration_ms"` + TrackNo int `json:"track_no"` + DiscNo int `json:"disc_no"` + Album *albumRefJSON `json:"album"` + Artists []artistRefJSON `json:"artists"` + Format string `json:"format"` +} + +func toArtistJSON(a catalog.Artist) artistJSON { + return artistJSON{ID: a.ID, Name: a.Name, AlbumCount: a.AlbumCount, TrackCount: a.TrackCount} +} + +func toAlbumJSON(a catalog.Album) albumJSON { + out := albumJSON{ID: a.ID, Title: a.Title, TrackCount: a.TrackCount, DurationMs: a.DurationMs} + if a.Artist != nil { + out.Artist = &artistRefJSON{ID: a.Artist.ID, Name: a.Artist.Name} + } + return out +} + +func toTrackJSON(t catalog.Track) trackJSON { + out := trackJSON{ + ID: t.ID, Title: t.Title, DurationMs: t.DurationMs, TrackNo: t.TrackNo, DiscNo: t.DiscNo, + Format: t.Format, Artists: make([]artistRefJSON, len(t.Artists)), + } + if t.Album != nil { + out.Album = &albumRefJSON{ID: t.Album.ID, Title: t.Album.Title} + } + for i, a := range t.Artists { + out.Artists[i] = artistRefJSON{ID: a.ID, Name: a.Name} + } + return out +} + +// parseFilter reads q, limit, offset and the id filters from the query string. +// Unset values stay zero so the service can apply its defaults. +func parseFilter(c *gin.Context) (catalog.Filter, bool) { + f := catalog.Filter{Query: c.Query("q")} + for _, p := range []struct { + name string + dst *int64 + }{ + {"library_id", &f.LibraryID}, {"artist_id", &f.ArtistID}, {"album_id", &f.AlbumID}, + } { + v, ok := queryInt(c, p.name) + if !ok { + return f, false + } + *p.dst = v + } + limit, ok := queryInt(c, "limit") + if !ok { + return f, false + } + offset, ok := queryInt(c, "offset") + if !ok { + return f, false + } + // Clamp before narrowing, so a huge number cannot wrap into a small one. + f.Limit, f.Offset = clampInt(limit), clampInt(offset) + return f, true +} + +// queryInt reads an optional integer parameter; it answers 400 itself when the +// value is not a number. +func queryInt(c *gin.Context, name string) (int64, bool) { + raw := c.Query(name) + if raw == "" { + return 0, true + } + n, err := strconv.ParseInt(raw, 10, 64) + if err != nil { + writeError(c, http.StatusBadRequest, "invalid_input", name+" must be a whole number") + return 0, false + } + return n, true +} + +func clampInt(n int64) int { + const max = 1 << 31 + switch { + case n > max: + return max + case n < -max: + return -max + } + return int(n) +} + +func writeCatalogError(c *gin.Context, err error, notFoundCode string) { + switch { + case errors.Is(err, catalog.ErrInvalidQuery): + writeError(c, http.StatusBadRequest, "invalid_input", err.Error()) + case errors.Is(err, catalog.ErrNotFound): + writeError(c, http.StatusNotFound, notFoundCode, "not found") + default: + _ = c.Error(err) + writeError(c, http.StatusInternalServerError, "internal", "internal error") + } +} + +func writePage[T any, J any](c *gin.Context, p catalog.Page[T], conv func(T) J) { + items := make([]J, len(p.Items)) + for i, it := range p.Items { + items[i] = conv(it) + } + c.JSON(http.StatusOK, gin.H{"items": items, "total": p.Total, "limit": p.Limit, "offset": p.Offset}) +} + +func (h *catalogHandlers) listArtists(c *gin.Context) { + f, ok := parseFilter(c) + if !ok { + return + } + p, err := h.svc.Artists(c.Request.Context(), f) + if err != nil { + writeCatalogError(c, err, "artist_not_found") + return + } + writePage(c, p, toArtistJSON) +} + +func (h *catalogHandlers) listAlbums(c *gin.Context) { + f, ok := parseFilter(c) + if !ok { + return + } + p, err := h.svc.Albums(c.Request.Context(), f) + if err != nil { + writeCatalogError(c, err, "album_not_found") + return + } + writePage(c, p, toAlbumJSON) +} + +func (h *catalogHandlers) listTracks(c *gin.Context) { + f, ok := parseFilter(c) + if !ok { + return + } + p, err := h.svc.Tracks(c.Request.Context(), f) + if err != nil { + writeCatalogError(c, err, "track_not_found") + return + } + writePage(c, p, toTrackJSON) +} + +func (h *catalogHandlers) getArtist(c *gin.Context) { + id, ok := pathID(c) + if !ok { + return + } + a, err := h.svc.Artist(c.Request.Context(), id) + if err != nil { + writeCatalogError(c, err, "artist_not_found") + return + } + c.JSON(http.StatusOK, toArtistJSON(a)) +} + +func (h *catalogHandlers) getAlbum(c *gin.Context) { + id, ok := pathID(c) + if !ok { + return + } + a, err := h.svc.Album(c.Request.Context(), id) + if err != nil { + writeCatalogError(c, err, "album_not_found") + return + } + c.JSON(http.StatusOK, toAlbumJSON(a)) +} + +func (h *catalogHandlers) getTrack(c *gin.Context) { + id, ok := pathID(c) + if !ok { + return + } + t, err := h.svc.Track(c.Request.Context(), id) + if err != nil { + writeCatalogError(c, err, "track_not_found") + return + } + c.JSON(http.StatusOK, toTrackJSON(t)) +} diff --git a/internal/api/http/router.go b/internal/api/http/router.go index 4e8b3a8..f23b5cb 100644 --- a/internal/api/http/router.go +++ b/internal/api/http/router.go @@ -11,6 +11,7 @@ import ( "go.uber.org/zap" "codeberg.org/squidd/sonda/internal/auth" + "codeberg.org/squidd/sonda/internal/catalog" "codeberg.org/squidd/sonda/internal/library" "codeberg.org/squidd/sonda/internal/listening" "codeberg.org/squidd/sonda/internal/streaming" @@ -51,6 +52,15 @@ type scanService interface { Status() library.Status } +type catalogService interface { + Artists(ctx context.Context, f catalog.Filter) (catalog.Page[catalog.Artist], error) + Albums(ctx context.Context, f catalog.Filter) (catalog.Page[catalog.Album], error) + Tracks(ctx context.Context, f catalog.Filter) (catalog.Page[catalog.Track], error) + Artist(ctx context.Context, id int64) (catalog.Artist, error) + Album(ctx context.Context, id int64) (catalog.Album, error) + Track(ctx context.Context, id int64) (catalog.Track, error) +} + type libraryService interface { List(ctx context.Context) ([]library.Library, error) Create(ctx context.Context, name, path string) (library.Library, error) @@ -66,6 +76,7 @@ type Deps struct { Listening listenService Scan scanService Libraries libraryService + Catalog catalogService Streams streamService } @@ -95,6 +106,14 @@ func NewRouter(d Deps) *gin.Engine { lib := &libraryHandlers{scan: d.Scan} protected.GET("/library/scan", lib.scanStatus) + cat := &catalogHandlers{svc: d.Catalog} + protected.GET("/artists", cat.listArtists) + protected.GET("/artists/:id", cat.getArtist) + protected.GET("/albums", cat.listAlbums) + protected.GET("/albums/:id", cat.getAlbum) + protected.GET("/tracks", cat.listTracks) + protected.GET("/tracks/:id", cat.getTrack) + // Audio loaded by an