sonda/internal/catalog/catalog.go
tgiachi ccee5e8719 feat: OpenSubsonic playback, covers, lists and search
Apps can play and browse: stream and download send the original file (Range,
HEAD), getCoverArt serves the cover of an album, an artist or the album of a
song (300 pixels or less is the small one), getAlbumList2 knows every kind of
list, getRandomSongs and getSongsByGenre list songs, search3 finds artists,
albums and songs, and the starred calls answer with nothing so apps do not break.

- catalog.Filter has IDs to read albums and songs by id
- storage.SubsonicRepo answers the album and song lists (random, newest,
  frequent, recent, by name, by artist, by year, by genre)
2026-11-16 09:45:07 +01:00

205 lines
5.9 KiB
Go

// Package catalog is the read side of the library: browsing and searching
// artists, albums and tracks.
//
// Only tracks with at least one file that is not flagged missing are visible,
// so everything the catalog shows can be played. File paths are never part of
// the data returned here.
package catalog
import (
"context"
"errors"
"fmt"
"strings"
"unicode/utf8"
)
// Errors returned by the service.
var (
ErrNotFound = errors.New("not found")
ErrInvalidQuery = errors.New("invalid query")
)
// The orders of a list of albums.
const (
SortTitle = "title"
SortRecent = "recent" // by the date of the newest file of the album that is not missing, then the newest album
)
// Paging and search bounds.
const (
DefaultLimit = 50
MaxLimit = 200
MaxQueryLen = 200 // characters
)
// Filter selects and pages a list. Zero IDs mean "any". Each list uses the
// fields that make sense for it and ignores the others.
type Filter struct {
Query string // case-insensitive substring of the name or title (accents are kept)
LibraryID int64 // only items with a playable file in this library
ArtistID int64 // albums: album artist; tracks: credited artist
AlbumID int64 // tracks only
Sort string // albums only: "" or SortTitle (by title), SortRecent (the newest files first)
IDs []int64 // albums and tracks: only these ids (at most MaxLimit); nil is no limit
Limit int
Offset int
}
// Page is one page of a list together with the size of the whole result.
type Page[T any] struct {
Items []T
Total int
Limit int
Offset int
}
// ArtistRef and AlbumRef are the short forms used inside other items.
type ArtistRef struct {
ID int64
Name string
}
type AlbumRef struct {
ID int64
Title string
}
// Artist is an artist with the amount of music that can be played.
type Artist struct {
ID int64
Name string
AlbumCount int
TrackCount int
}
// Album is an album with its album artist, if it has one.
type Album struct {
ID int64
Title string
Artist *ArtistRef
TrackCount int
DurationMs int64
}
// ReplayGain is what the first playable file of a track says about its loudness; a field it does not say is nil.
// Gains are in decibels, peaks a fraction of full scale (1 is the loudest a sample can be).
type ReplayGain struct {
TrackGain, AlbumGain *float64
TrackPeak, AlbumPeak *float64
}
// Track is a playable track. Format and ReplayGain are those of its first playable file; ReplayGain is nil when the
// file says nothing about its loudness.
type Track struct {
ID int64
Title string
DurationMs int64
TrackNo int
DiscNo int
Album *AlbumRef
Artists []ArtistRef
Format string
ReplayGain *ReplayGain
}
// Store reads the catalog. Lists are ordered deterministically and must load
// related data in batches. Get methods return ErrNotFound for an id that does
// not exist or has nothing playable.
type Store interface {
ListArtists(ctx context.Context, f Filter) (Page[Artist], error)
ListAlbums(ctx context.Context, f Filter) (Page[Album], error)
ListTracks(ctx context.Context, f Filter) (Page[Track], error)
GetArtist(ctx context.Context, id int64) (Artist, error)
GetAlbum(ctx context.Context, id int64) (Album, error)
GetTrack(ctx context.Context, id int64) (Track, error)
}
// Service validates queries and reads the catalog.
type Service struct{ store Store }
// NewService builds a Service.
func NewService(store Store) *Service { return &Service{store: store} }
// normalize validates f and fills in the paging defaults.
func normalize(f Filter) (Filter, error) {
if f.Limit < 0 || f.Offset < 0 {
return f, fmt.Errorf("%w: limit and offset cannot be negative", ErrInvalidQuery)
}
if len(f.IDs) > MaxLimit {
return f, fmt.Errorf("%w: at most %d ids", ErrInvalidQuery, MaxLimit)
}
if f.LibraryID < 0 || f.ArtistID < 0 || f.AlbumID < 0 {
return f, fmt.Errorf("%w: ids cannot be negative", ErrInvalidQuery)
}
switch {
case f.Limit == 0:
f.Limit = DefaultLimit
case f.Limit > MaxLimit:
f.Limit = MaxLimit
}
// The text ends up inside the SQL statement text: a NUL byte cannot be
// represented there, and PostgreSQL rejects bytes that are not UTF-8.
if strings.IndexByte(f.Query, 0) >= 0 || !utf8.ValidString(f.Query) {
return f, fmt.Errorf("%w: q is not valid text", ErrInvalidQuery)
}
f.Query = strings.TrimSpace(f.Query)
if utf8.RuneCountInString(f.Query) > MaxQueryLen {
return f, fmt.Errorf("%w: q is longer than %d characters", ErrInvalidQuery, MaxQueryLen)
}
return f, nil
}
// Artists lists artists that have something playable.
func (s *Service) Artists(ctx context.Context, f Filter) (Page[Artist], error) {
f, err := normalize(f)
if err != nil {
return Page[Artist]{}, err
}
return s.store.ListArtists(ctx, f)
}
// Albums lists albums that have something playable.
func (s *Service) Albums(ctx context.Context, f Filter) (Page[Album], error) {
f, err := normalize(f)
if err != nil {
return Page[Album]{}, err
}
if f.Sort != "" && f.Sort != SortTitle && f.Sort != SortRecent {
return Page[Album]{}, fmt.Errorf("%w: sort must be title or recent", ErrInvalidQuery)
}
return s.store.ListAlbums(ctx, f)
}
// Tracks lists playable tracks.
func (s *Service) Tracks(ctx context.Context, f Filter) (Page[Track], error) {
f, err := normalize(f)
if err != nil {
return Page[Track]{}, err
}
return s.store.ListTracks(ctx, f)
}
// Artist returns one artist.
func (s *Service) Artist(ctx context.Context, id int64) (Artist, error) {
if id <= 0 {
return Artist{}, ErrNotFound
}
return s.store.GetArtist(ctx, id)
}
// Album returns one album.
func (s *Service) Album(ctx context.Context, id int64) (Album, error) {
if id <= 0 {
return Album{}, ErrNotFound
}
return s.store.GetAlbum(ctx, id)
}
// Track returns one track.
func (s *Service) Track(ctx context.Context, id int64) (Track, error) {
if id <= 0 {
return Track{}, ErrNotFound
}
return s.store.GetTrack(ctx, id)
}