Prefer UUIDs in the API (Phase 3 of the UUID migration)

- New /api/v1 endpoints: GET /soundtracks, /soundtracks/{uuid},
  /songs/{uuid} and /songs/{uuid}/file (streams the song, Range support,
  locked during sync)
- UUIDs added to every response with soundtracks or songs: queue info and
  list (SoundtrackUuid, SongUuid) and statistics (soundtrack_uuid,
  song_uuid). Existing fields stay for backward compatibility
- Play counts and broken-song removal use song UUIDs instead of
  soundtrack ID + song name, so songs with the same name are counted
  separately
- Statistics return an empty song list for soundtracks without songs
  instead of a single empty entry
- The legacy .id file cleanup stays until Phase 4 (#31)

Closes #29

internal/server/handlers_test.go

@@ -13,6 +13,7 @@ import (
 	"music-server/internal/config"
 	"music-server/internal/db/repository"
 
+	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -237,6 +238,11 @@ func TestTokenRateLimit(t *testing.T) {
 	assert.Contains(t, rec.Body.String(), "Rate limit exceeded")
 }
 
+var (
+	statsSoundtrackUUID = uuid.New()
+	statsSongUUID       = uuid.New()
+)
+
 // statsStore returns canned statistics.
 type statsStore struct {
 	repository.Querier
@@ -246,8 +252,9 @@ type statsStore struct {
 func (s statsStore) GetMostPlayedSoundtracksWithSongs(_ context.Context, limit int32) ([]repository.GetMostPlayedSoundtracksWithSongsRow, error) {
 	return []repository.GetMostPlayedSoundtracksWithSongsRow{{
 		SoundtrackID:   int32(limit),
+		SoundtrackUuid: statsSoundtrackUUID,
 		SoundtrackName: "Game A",
-		Songs:          []byte(`[{"song_name":"Song","times_played":3}]`),
+		Songs:          []byte(`[{"song_uuid":"` + statsSongUUID.String() + `","song_name":"Song","times_played":3}]`),
 	}}, s.err
 }
 
@@ -265,6 +272,8 @@ func TestStatisticsEndpoints(t *testing.T) {
 	require.Len(t, soundtracks, 1)
 	assert.Equal(t, int32(10), soundtracks[0].SoundtrackID, "default limit")
 	assert.Equal(t, "Song", soundtracks[0].Songs[0].SongName)
+	assert.Equal(t, statsSoundtrackUUID, soundtracks[0].SoundtrackUuid)
+	assert.Equal(t, statsSongUUID, soundtracks[0].Songs[0].SongUuid)
 
 	require.NoError(t, json.Unmarshal(e.do(http.MethodGet, "/api/v1/statistics/soundtracks/most-played?limit=500").Body.Bytes(), &soundtracks))
 	assert.Equal(t, int32(100), soundtracks[0].SoundtrackID, "limit is capped")

internal/server/library_handler.go

@@ -0,0 +1,111 @@
+package server
+
+import (
+	"net/http"
+
+	"music-server/internal/backend"
+
+	"github.com/google/uuid"
+	"github.com/labstack/echo/v5"
+)
+
+type LibraryHandler struct {
+	library *backend.LibraryService
+}
+
+func NewLibraryHandler(library *backend.LibraryService) *LibraryHandler {
+	return &LibraryHandler{library: library}
+}
+
+// uuidParam parses the :uuid path parameter.
+func uuidParam(ctx *echo.Context) (uuid.UUID, error) {
+	id, err := uuid.Parse(ctx.Param("uuid"))
+	if err != nil {
+		return uuid.Nil, echo.NewHTTPError(http.StatusBadRequest, "invalid uuid")
+	}
+	return id, nil
+}
+
+// GetSoundtracks godoc
+//
+//	@Summary		List soundtracks
+//	@Description	Returns all soundtracks with their UUIDs, sorted by name
+//	@Tags			library
+//	@Produce		json
+//	@Success		200	{array}	backend.Soundtrack
+//	@Router			/api/v1/soundtracks [get]
+func (l *LibraryHandler) GetSoundtracks(ctx *echo.Context) error {
+	soundtracks, err := l.library.Soundtracks(ctx.Request().Context())
+	if err != nil {
+		return songError(err)
+	}
+	return ctx.JSON(http.StatusOK, soundtracks)
+}
+
+// GetSoundtrack godoc
+//
+//	@Summary		Get soundtrack
+//	@Description	Returns a soundtrack with its songs
+//	@Tags			library
+//	@Produce		json
+//	@Param			uuid	path		string	true	"Soundtrack UUID"
+//	@Success		200		{object}	backend.SoundtrackWithSongList
+//	@Failure		400		{string}	string	"invalid uuid"
+//	@Failure		404		{string}	string	"not found"
+//	@Router			/api/v1/soundtracks/{uuid} [get]
+func (l *LibraryHandler) GetSoundtrack(ctx *echo.Context) error {
+	id, err := uuidParam(ctx)
+	if err != nil {
+		return err
+	}
+	soundtrack, err := l.library.Soundtrack(ctx.Request().Context(), id)
+	if err != nil {
+		return songError(err)
+	}
+	return ctx.JSON(http.StatusOK, soundtrack)
+}
+
+// GetSong godoc
+//
+//	@Summary		Get song
+//	@Description	Returns information about a song
+//	@Tags			library
+//	@Produce		json
+//	@Param			uuid	path		string	true	"Song UUID"
+//	@Success		200		{object}	backend.Song
+//	@Failure		400		{string}	string	"invalid uuid"
+//	@Failure		404		{string}	string	"not found"
+//	@Router			/api/v1/songs/{uuid} [get]
+func (l *LibraryHandler) GetSong(ctx *echo.Context) error {
+	id, err := uuidParam(ctx)
+	if err != nil {
+		return err
+	}
+	song, err := l.library.Song(ctx.Request().Context(), id)
+	if err != nil {
+		return songError(err)
+	}
+	return ctx.JSON(http.StatusOK, song)
+}
+
+// GetSongFile godoc
+//
+//	@Summary		Stream song
+//	@Description	Returns the audio file of a song. Supports Range requests.
+//	@Tags			library
+//	@Produce		audio/mpeg
+//	@Param			uuid	path		string	true	"Song UUID"
+//	@Success		200		{file}		file
+//	@Success		206		{file}		file
+//	@Failure		400		{string}	string	"invalid uuid"
+//	@Failure		404		{string}	string	"not found"
+//	@Failure		423		{string}	string	"Syncing is in progress"
+//	@Router			/api/v1/songs/{uuid}/file [get]
+func (l *LibraryHandler) GetSongFile(ctx *echo.Context) error {
+	id, err := uuidParam(ctx)
+	if err != nil {
+		return err
+	}
+	path, err := l.library.SongPath(ctx.Request().Context(), id)
+	return serveSong(ctx, path, err)
+}

internal/server/library_handler_test.go

@@ -0,0 +1,87 @@
+package server
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"music-server/internal/backend"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLibraryEndpoints(t *testing.T) {
+	e := newTestEnv(t)
+	song := e.addSong("Game A", "Song", "0123456789")
+	e.addSong("Game B", "Other", "x")
+
+	var soundtracks []backend.Soundtrack
+	rec := e.do(http.MethodGet, "/api/v1/soundtracks")
+	require.Equal(t, http.StatusOK, rec.Code)
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &soundtracks))
+	require.Len(t, soundtracks, 2)
+	assert.Equal(t, "Game A", soundtracks[0].Name)
+	assert.Equal(t, song.SoundtrackUuid, soundtracks[0].Uuid)
+
+	var soundtrack backend.SoundtrackWithSongList
+	require.NoError(t, json.Unmarshal(e.do(http.MethodGet, "/api/v1/soundtracks/"+song.SoundtrackUuid.String()).Body.Bytes(), &soundtrack))
+	require.Len(t, soundtrack.Songs, 1)
+	assert.Equal(t, song.Uuid, soundtrack.Songs[0].Uuid)
+
+	var info backend.Song
+	require.NoError(t, json.Unmarshal(e.do(http.MethodGet, "/api/v1/songs/"+song.Uuid.String()).Body.Bytes(), &info))
+	assert.Equal(t, "Song", info.Name)
+	assert.Equal(t, "Game A", info.SoundtrackName)
+
+	rec = e.do(http.MethodGet, "/api/v1/songs/"+song.Uuid.String()+"/file", "Range", "bytes=0-3")
+	assert.Equal(t, http.StatusPartialContent, rec.Code)
+	assert.Equal(t, "0123", rec.Body.String())
+	assert.Equal(t, "audio/mpeg", rec.Header().Get("Content-Type"))
+}
+
+func TestLibraryEndpointErrors(t *testing.T) {
+	e := newTestEnv(t)
+	missing := uuid.New().String()
+	for _, path := range []string{"/api/v1/soundtracks/" + missing, "/api/v1/songs/" + missing, "/api/v1/songs/" + missing + "/file"} {
+		assert.Equal(t, http.StatusNotFound, e.do(http.MethodGet, path).Code, path)
+	}
+	for _, path := range []string{"/api/v1/soundtracks/not-a-uuid", "/api/v1/songs/123", "/api/v1/songs/123/file"} {
+		assert.Equal(t, http.StatusBadRequest, e.do(http.MethodGet, path).Code, path)
+	}
+}
+
+func TestLibraryEndpointsRequireToken(t *testing.T) {
+	e := newTestEnv(t, withAuth("secret"))
+	assert.Equal(t, http.StatusUnauthorized, e.do(http.MethodGet, "/api/v1/soundtracks").Code)
+	assert.Equal(t, http.StatusNotFound, e.do(http.MethodGet, "/soundtracks").Code, "not available on legacy routes")
+}
+
+func TestSongFileLockedDuringSync(t *testing.T) {
+	e := newTestEnv(t)
+	song := e.addSong("Game A", "Song", "x")
+	release := e.blockSync()
+	defer release()
+
+	require.Equal(t, http.StatusOK, e.do(http.MethodPost, "/api/v1/sync").Code)
+	assert.Equal(t, http.StatusLocked, e.do(http.MethodGet, "/api/v1/songs/"+song.Uuid.String()+"/file").Code)
+	assert.Equal(t, http.StatusOK, e.do(http.MethodGet, "/api/v1/songs/"+song.Uuid.String()).Code, "song info stays available")
+}
+
+func TestQueueResponsesIncludeUUIDs(t *testing.T) {
+	e := newTestEnv(t)
+	song := e.addSong("Game A", "Song", "x")
+	require.Equal(t, http.StatusOK, e.do(http.MethodGet, "/music/rand").Code)
+	require.Equal(t, http.StatusOK, e.do(http.MethodGet, "/music/addQue").Code)
+
+	var info map[string]any
+	require.NoError(t, json.Unmarshal(e.do(http.MethodGet, "/music/info").Body.Bytes(), &info))
+	assert.Equal(t, song.Uuid.String(), info["SongUuid"])
+	assert.Equal(t, song.SoundtrackUuid.String(), info["SoundtrackUuid"])
+
+	var list []map[string]any
+	require.NoError(t, json.Unmarshal(e.do(http.MethodGet, "/api/v1/music/list").Body.Bytes(), &list))
+	require.Len(t, list, 1)
+	assert.Equal(t, song.Uuid.String(), list[0]["SongUuid"])
+}

internal/server/routes.go

@@ -38,6 +38,7 @@ type handlers struct {
 	download   *DownloadHandler
 	sync       *SyncHandler
 	music      *MusicHandler
+	library    *LibraryHandler
 	statistics *StatisticsHandler
 	token      *TokenHandler
 }
@@ -50,6 +51,7 @@ func (s *Server) handlers() handlers {
 		download:   NewDownloadHandler(s.releases),
 		sync:       NewSyncHandler(s.sync),
 		music:      NewMusicHandler(s.music),
+		library:    NewLibraryHandler(s.library),
 		statistics: NewStatisticsHandler(s.stats),
 		token:      NewTokenHandler(s.q, s.cfg.APIPassword, s.cfg.DisableSessionAuth),
 	}
@@ -103,6 +105,11 @@ func (s *Server) RegisterRoutes() http.Handler {
 	registerCommon(protected, h, syncLock)
 	protected.GET("/character/list", h.character.GetCharacterList)
 
+	protected.GET("/soundtracks", h.library.GetSoundtracks)
+	protected.GET("/soundtracks/:uuid", h.library.GetSoundtrack)
+	protected.GET("/songs/:uuid", h.library.GetSong)
+	protected.GET("/songs/:uuid/file", h.library.GetSongFile, syncLock)
+
 	stats := protected.Group("/statistics")
 	stats.GET("/soundtracks/most-played", h.statistics.GetMostPlayedSoundtracks)
 	stats.GET("/soundtracks/least-played", h.statistics.GetLeastPlayedSoundtracks)

internal/server/server.go

@@ -27,6 +27,7 @@ type Server struct {
 	db         Database
 	q          repository.Querier
 	music      *backend.MusicService
+	library    *backend.LibraryService
 	sync       *backend.SyncService
 	characters *backend.CharacterService
 	releases   *backend.ReleaseService
@@ -47,6 +48,7 @@ func New(cfg config.Config, q repository.Querier, database Database) (*Server, e
 		db:         database,
 		q:          q,
 		music:      backend.NewMusicService(q, cfg.SoundCheckPath),
+		library:    backend.NewLibraryService(q),
 		characters: characters,
 		releases:   backend.NewReleaseService(cfg.ReleasesURL),
 		stats:      backend.NewStatisticsService(q),