Upload new soundtracks through the API

A client starts an upload with the soundtrack's name, sends one MP3 per
request, and finishes it. The server then moves the songs into a new folder
in the music folder and syncs only that folder, so the soundtrack is in the
library, lists and search right away.

- POST /api/v1/soundtracks/uploads, GET/DELETE .../uploads/{id},
  PUT .../uploads/{id}/files/{file} and POST .../uploads/{id}/finish.
- Names must work as file names on every system and be free, ignoring case.
  File names are plain: clients flatten disc folders.
- Only MP3 files. Size limits from UPLOAD_MAX_FILE_MB (50) and
  UPLOAD_MAX_TOTAL_MB (2048).
- Refused while a sync runs, and a sync cannot start while an upload is
  finished. Songs equal to an existing soundtrack's are refused, as the sync
  would take them for that soundtrack renamed.
- Unfinished uploads live in MUSIC_PATH/.uploads and are removed after a day.
  The sync now skips every hidden folder.

Closes #33

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/server/api.go

@@ -148,8 +148,14 @@ func apiError(err error) error {
 		return huma.Error404NotFound(err.Error())
 	case errors.Is(err, backend.ErrInvalidName), errors.Is(err, backend.ErrInvalidImage):
 		return huma.Error400BadRequest(err.Error())
-	case errors.Is(err, backend.ErrCoversDisabled):
+	case errors.Is(err, backend.ErrCoversDisabled), errors.Is(err, backend.ErrUploadsUnavailable):
 		return huma.Error503ServiceUnavailable(err.Error())
+	case errors.Is(err, backend.ErrConflict):
+		return huma.Error409Conflict(err.Error())
+	case errors.Is(err, backend.ErrSyncing):
+		return huma.Error423Locked(err.Error())
+	case errors.Is(err, backend.ErrTooLarge):
+		return huma.Error413RequestEntityTooLarge(err.Error())
 	case errors.Is(err, backend.ErrUpstream):
 		return huma.Error502BadGateway(err.Error())
 	default:

internal/server/helpers_test.go

@@ -70,6 +70,8 @@ func newTestEnv(t *testing.T, configure ...func(*config.Config)) *testEnv {
 		FrontendPath:       filepath.Join(base, "frontend"),
 		DisableSessionAuth: true,
 		ReleasesURL:        "http://127.0.0.1:1",
+		UploadMaxFileSize:  1 << 20,
+		UploadMaxTotalSize: 3 << 20,
 	}
 	for _, c := range configure {
 		c(&cfg)

internal/server/openapi_test.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"testing"
 
+	"music-server/internal/backend"
 	"music-server/internal/config"
 
 	"github.com/getkin/kin-openapi/openapi3"
@@ -74,6 +75,7 @@ func TestOpenAPIDocumentsTheV1API(t *testing.T) {
 	}
 	slices.Sort(operations)
 	assert.Equal(t, []string{
+		"DELETE /api/v1/soundtracks/uploads/{id}",
 		"DELETE /api/v1/soundtracks/{uuid}/cover",
 		"DELETE /api/v1/token",
 		"GET /api/v1/character",
@@ -103,6 +105,7 @@ func TestOpenAPIDocumentsTheV1API(t *testing.T) {
 		"GET /api/v1/songs/{uuid}",
 		"GET /api/v1/songs/{uuid}/file",
 		"GET /api/v1/soundtracks",
+		"GET /api/v1/soundtracks/uploads/{id}",
 		"GET /api/v1/soundtracks/{uuid}",
 		"GET /api/v1/soundtracks/{uuid}/cover",
 		"GET /api/v1/statistics/songs/least-played",
@@ -117,11 +120,14 @@ func TestOpenAPIDocumentsTheV1API(t *testing.T) {
 		"GET /api/v1/sync/progress",
 		"GET /api/v1/version",
 		"GET /api/v1/version/history",
+		"POST /api/v1/soundtracks/uploads",
+		"POST /api/v1/soundtracks/uploads/{id}/finish",
 		"POST /api/v1/sync",
 		"POST /api/v1/sync/full",
 		"POST /api/v1/token",
 		"POST /api/v1/token/cleanup",
 		"PUT /api/v1/music/played",
+		"PUT /api/v1/soundtracks/uploads/{id}/files/{file}",
 		"PUT /api/v1/soundtracks/{uuid}/alternative-names",
 		"PUT /api/v1/soundtracks/{uuid}/cover",
 		"PUT /api/v1/soundtracks/{uuid}/cover/source",
@@ -222,6 +228,21 @@ func TestResponsesMatchOpenAPI(t *testing.T) {
 	v.check(http.MethodPut, coverURL+"/source", `{"source":"anilist","id":"42"}`, http.StatusNoContent)
 	v.check(http.MethodPut, coverURL+"/source", `{"source":"anilist","id":"7"}`, http.StatusNotFound)
 	v.check(http.MethodDelete, coverURL, "", http.StatusNoContent)
+
+	// Uploads.
+	started := v.check(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"Uploaded"}`, http.StatusCreated)
+	var upload backend.Upload
+	require.NoError(t, json.Unmarshal(started.Body.Bytes(), &upload))
+	up := "/api/v1/soundtracks/uploads/" + upload.ID.String()
+	v.check(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"Uploaded"}`, http.StatusConflict)
+	v.check(http.MethodPut, up+"/files/01.mp3", "ID3 song", http.StatusOK, "Content-Type", "audio/mpeg")
+	v.check(http.MethodPut, up+"/files/02.wav", "ID3 song", http.StatusBadRequest, "Content-Type", "audio/mpeg")
+	v.check(http.MethodGet, up, "", http.StatusOK)
+	v.check(http.MethodPost, up+"/finish", "", http.StatusOK)
+	v.check(http.MethodGet, up, "", http.StatusNotFound)
+	cancelled := v.check(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"Cancelled"}`, http.StatusCreated)
+	require.NoError(t, json.Unmarshal(cancelled.Body.Bytes(), &upload))
+	v.check(http.MethodDelete, "/api/v1/soundtracks/uploads/"+upload.ID.String(), "", http.StatusNoContent)
 	v.check(http.MethodGet, "/api/v1/soundtracks/00000000-0000-0000-0000-000000000000", "", http.StatusNotFound)
 	v.check(http.MethodGet, songURL, "", http.StatusOK)
 	v.check(http.MethodGet, songURL+"/file", "", http.StatusOK)

internal/server/routes.go

@@ -64,6 +64,7 @@ func (s *Server) routes() (*echo.Echo, huma.API) {
 	s.registerMusic(a)
 	s.registerLibrary(a)
 	s.registerCovers(a)
+	s.registerUploads(a)
 	s.registerStatistics(a)
 
 	// Older links to the spec and docs.

internal/server/server.go

@@ -34,6 +34,7 @@ type Server struct {
 	characters *backend.CharacterService
 	releases   *backend.ReleaseService
 	stats      *backend.StatisticsService
+	uploads    *backend.UploadService
 	search     *backend.SearchCache
 	// covers is nil when COVERS_PATH is not set.
 	covers *backend.CoverService
@@ -64,6 +65,7 @@ func New(cfg config.Config, q repository.Querier, database Database) (*Server, e
 	}
 	s.search = backend.NewSearchCache(s.music.SearchSoundtracks)
 	s.sync = backend.NewSyncService(q, cfg.MusicPath, s.afterSync)
+	s.uploads = backend.NewUploadService(q, cfg.MusicPath, s.sync, s.library, cfg.UploadMaxFileSize, cfg.UploadMaxTotalSize)
 
 	if cfg.CoversPath != "" {
 		s.covers, err = backend.NewCoverService(q, cfg.CoversPath, backend.CoverOptions{
@@ -167,6 +169,7 @@ func NewServerInstance() *Server {
 		logger.Fatal("Failed to create server", zap.Error(err))
 	}
 	prometheus.MustRegister(metrics.NewPoolCollector(database.Pool))
+	s.uploads.RemoveOld()
 	if err := s.sync.UpdateLibraryMetrics(ctx); err != nil {
 		logger.Error("Failed to count the library", zap.Error(err))
 	}

internal/server/upload_handler.go

@@ -0,0 +1,120 @@
+package server
+
+import (
+	"context"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"music-server/internal/backend"
+
+	"github.com/danielgtaylor/huma/v2"
+	"github.com/google/uuid"
+)
+
+// UploadRequest is the body of POST /soundtracks/uploads.
+type UploadRequest struct {
+	Name string `json:"name" minLength:"1" maxLength:"200" doc:"Name of the new soundtrack, also its folder name in the music folder"`
+}
+
+type startUploadInput struct {
+	Body UploadRequest
+}
+
+type uploadIDInput struct {
+	ID string `path:"id" format:"uuid" doc:"ID of the upload, from POST /soundtracks/uploads"`
+}
+
+func (in *uploadIDInput) id() uuid.UUID {
+	return uuid.MustParse(in.ID)
+}
+
+type uploadFileInput struct {
+	ID      string `path:"id" format:"uuid" doc:"ID of the upload, from POST /soundtracks/uploads"`
+	File    string `path:"file" doc:"File name of the song, e.g. \"01 Title.mp3\". Plain names only: put songs from disc folders in one folder, e.g. \"1-01 Title.mp3\"."`
+	RawBody []byte `contentType:"audio/mpeg" doc:"The MP3 file"`
+}
+
+type createdUpload struct {
+	Status int
+	Body   backend.Upload
+}
+
+func (s *Server) registerUploads(a huma.API) {
+	u := s.uploads
+	op := func(id, method, path, summary, description string, errs ...int) route {
+		return route{
+			op: huma.Operation{
+				OperationID: id,
+				Method:      method,
+				Path:        path,
+				Summary:     summary,
+				Description: description,
+				Tags:        []string{"uploads"},
+				Errors:      errs,
+			},
+			// Uploads and syncs never run at the same time.
+			locked: true,
+		}
+	}
+
+	start := op("start-upload", http.MethodPost, "/soundtracks/uploads", "Start uploading a soundtrack",
+		"Starts adding a new soundtrack. Send its songs with PUT /soundtracks/uploads/{id}/files/{file}, then "+
+			"POST /soundtracks/uploads/{id}/finish. The name must be usable as a folder name, and no soundtrack, "+
+			"folder or other upload may have it, ignoring case. Unfinished uploads are removed after a day.",
+		http.StatusBadRequest, http.StatusConflict, http.StatusServiceUnavailable)
+	start.op.DefaultStatus = http.StatusCreated
+	register(s, a, start, func(ctx context.Context, in *startUploadInput) (*createdUpload, error) {
+		upload, err := u.Start(ctx, in.Body.Name)
+		if err != nil {
+			return nil, apiError(err)
+		}
+		return &createdUpload{Status: http.StatusCreated, Body: upload}, nil
+	})
+
+	register(s, a, op("get-upload", http.MethodGet, "/soundtracks/uploads/{id}", "Get an upload",
+		"Returns an unfinished upload with the songs received so far, for example to resume it.", http.StatusNotFound),
+		func(ctx context.Context, in *uploadIDInput) (*jsonBody[backend.Upload], error) {
+			return ok(u.Get(in.id()))
+		})
+
+	file := op("upload-song", http.MethodPut, "/soundtracks/uploads/{id}/files/{file}", "Upload a song",
+		"Stores one song of the upload, replacing a song of the same name, so a failed song can be sent again. "+
+			"Only MP3 files are accepted. The size limits are set on the server with UPLOAD_MAX_FILE_MB and UPLOAD_MAX_TOTAL_MB.",
+		http.StatusBadRequest, http.StatusNotFound, http.StatusRequestEntityTooLarge)
+	file.op.MaxBodyBytes = s.cfg.UploadMaxFileSize
+	register(s, a, file, func(ctx context.Context, in *uploadFileInput) (*jsonBody[backend.UploadFile], error) {
+		id, err := uuid.Parse(in.ID)
+		if err != nil {
+			return nil, huma.Error422UnprocessableEntity("invalid upload ID")
+		}
+		// With an encoded slash (%2F) in the path, Echo leaves the file name encoded.
+		if decoded, err := url.PathUnescape(in.File); err == nil && strings.ContainsAny(decoded, `/\`) {
+			return nil, huma.Error400BadRequest("plain file names only: put songs from disc folders in one folder, e.g. \"1-01 Title.mp3\"")
+		}
+		return ok(u.PutFile(id, in.File, in.RawBody))
+	})
+
+	register(s, a, op("finish-upload", http.MethodPost, "/soundtracks/uploads/{id}/finish", "Finish an upload",
+		"Moves the songs into a new folder in the music folder, adds the soundtrack to the library and returns it. "+
+			"Refused when a soundtrack with the same songs exists.",
+		http.StatusBadRequest, http.StatusNotFound, http.StatusConflict),
+		func(ctx context.Context, in *uploadIDInput) (*jsonBody[backend.SoundtrackWithSongList], error) {
+			soundtrack, err := u.Finish(ctx, in.id())
+			if err != nil {
+				return nil, apiError(err)
+			}
+			s.soundtracksChanged(ctx)
+			return ok(soundtrack, nil)
+		})
+
+	cancel := op("cancel-upload", http.MethodDelete, "/soundtracks/uploads/{id}", "Cancel an upload",
+		"Deletes an unfinished upload and its songs.", http.StatusNotFound)
+	cancel.op.DefaultStatus = http.StatusNoContent
+	register(s, a, cancel, func(ctx context.Context, in *uploadIDInput) (*struct{}, error) {
+		if err := u.Cancel(in.id()); err != nil {
+			return nil, apiError(err)
+		}
+		return nil, nil
+	})
+}

internal/server/upload_handler_test.go

@@ -0,0 +1,106 @@
+package server
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+
+	"music-server/internal/backend"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func mp3Body(content string) []byte {
+	return append([]byte("ID3"), content...)
+}
+
+func (e *testEnv) startUpload(name string) backend.Upload {
+	e.t.Helper()
+	rec := e.doBody(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"`+name+`"}`)
+	require.Equal(e.t, http.StatusCreated, rec.Code, rec.Body.String())
+	var upload backend.Upload
+	require.NoError(e.t, json.Unmarshal(rec.Body.Bytes(), &upload))
+	return upload
+}
+
+func uploadPath(upload backend.Upload) string {
+	return "/api/v1/soundtracks/uploads/" + upload.ID.String()
+}
+
+func TestUploadSoundtrackEndpoints(t *testing.T) {
+	e := newTestEnv(t)
+	upload := e.startUpload("Chrono Trigger")
+	assert.Equal(t, "Chrono Trigger", upload.Name)
+
+	for _, song := range []string{"01 Wind Scene.mp3", "02 Corridors of Time.mp3"} {
+		rec := e.put(uploadPath(upload)+"/files/"+url.PathEscape(song), "audio/mpeg", mp3Body(song))
+		require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	}
+	rec := e.do(http.MethodGet, uploadPath(upload))
+	require.Equal(t, http.StatusOK, rec.Code)
+	assert.Contains(t, rec.Body.String(), `"name":"02 Corridors of Time.mp3"`)
+
+	rec = e.do(http.MethodPost, uploadPath(upload)+"/finish")
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	var soundtrack backend.SoundtrackWithSongList
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &soundtrack))
+	assert.Equal(t, "Chrono Trigger", soundtrack.Name)
+	assert.Len(t, soundtrack.Songs, 2)
+
+	// It is in the library, the soundtrack lists and the search right away.
+	assert.Contains(t, e.do(http.MethodGet, "/api/v1/soundtracks").Body.String(), `"name":"Chrono Trigger"`)
+	assert.Contains(t, e.do(http.MethodGet, "/api/v1/music/all/order").Body.String(), "Chrono Trigger")
+	assert.Equal(t, http.StatusNotFound, e.do(http.MethodGet, uploadPath(upload)).Code)
+}
+
+func TestUploadEndpointErrors(t *testing.T) {
+	e := newTestEnv(t)
+	e.addSong("Kingdom Hearts", "Dearly Beloved", "x")
+
+	assert.Equal(t, http.StatusConflict, e.doBody(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"kingdom hearts"}`).Code)
+	assert.Equal(t, http.StatusBadRequest, e.doBody(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"a/b"}`).Code)
+	assert.Equal(t, http.StatusUnprocessableEntity, e.doBody(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":""}`).Code)
+
+	upload := e.startUpload("Game")
+	assert.Equal(t, http.StatusBadRequest, e.put(uploadPath(upload)+"/files/song.wav", "audio/wav", mp3Body("x")).Code)
+	assert.Equal(t, http.StatusBadRequest, e.put(uploadPath(upload)+"/files/song.mp3", "audio/mpeg", []byte("text")).Code)
+	assert.Equal(t, http.StatusRequestEntityTooLarge,
+		e.put(uploadPath(upload)+"/files/big.mp3", "audio/mpeg", mp3Body(strings.Repeat("x", 1<<20))).Code)
+	assert.Equal(t, http.StatusBadRequest, e.put(uploadPath(upload)+"/files/Disc%201%2F01.mp3", "audio/mpeg", mp3Body("x")).Code,
+		"an encoded / in the file name")
+	rec := e.put(uploadPath(upload)+"/files/Disc-1/01.mp3", "audio/mpeg", mp3Body("x"))
+	assert.Equal(t, http.StatusBadRequest, rec.Code, "a / in the file name")
+	assert.Contains(t, rec.Body.String(), "plain file names only")
+	assert.Equal(t, http.StatusBadRequest, e.do(http.MethodPost, uploadPath(upload)+"/finish").Code, "no songs yet")
+
+	missing := "/api/v1/soundtracks/uploads/00000000-0000-0000-0000-000000000000"
+	assert.Equal(t, http.StatusNotFound, e.do(http.MethodGet, missing).Code)
+	assert.Equal(t, http.StatusNotFound, e.put(missing+"/files/a.mp3", "audio/mpeg", mp3Body("x")).Code)
+	assert.Equal(t, http.StatusNotFound, e.do(http.MethodPost, missing+"/finish").Code)
+	assert.Equal(t, http.StatusNotFound, e.do(http.MethodDelete, missing).Code)
+
+	assert.Equal(t, http.StatusNoContent, e.do(http.MethodDelete, uploadPath(upload)).Code)
+	assert.Equal(t, http.StatusNotFound, e.do(http.MethodGet, uploadPath(upload)).Code)
+}
+
+func TestUploadEndpointsLockedDuringSync(t *testing.T) {
+	e := newTestEnv(t)
+	upload := e.startUpload("Game")
+	require.Equal(t, http.StatusOK, e.put(uploadPath(upload)+"/files/01.mp3", "audio/mpeg", mp3Body("x")).Code)
+	release := e.blockSync()
+	require.Equal(t, http.StatusOK, e.do(http.MethodPost, "/api/v1/sync").Code)
+
+	assert.Equal(t, http.StatusLocked, e.doBody(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"Other"}`).Code)
+	assert.Equal(t, http.StatusLocked, e.do(http.MethodPost, uploadPath(upload)+"/finish").Code)
+
+	release()
+	assert.Equal(t, http.StatusOK, e.do(http.MethodPost, uploadPath(upload)+"/finish").Code)
+}
+
+func TestUploadEndpointsRequireToken(t *testing.T) {
+	e := newTestEnv(t, withAuth("secret"))
+	assert.Equal(t, http.StatusUnauthorized, e.doBody(http.MethodPost, "/api/v1/soundtracks/uploads", `{"name":"Game"}`).Code)
+}