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>

Dockerfile

@@ -27,7 +27,8 @@ COPY --from=build /app/main .
 COPY --from=frontend /usr/share/nginx/html /frontend
 COPY ./songs/ ./songs/
 
-# The music volume must be readable by uid 1000, and writable for the .id file cleanup during sync.
+# The music volume must be readable by uid 1000, and writable for the .id file cleanup during sync
+# and for soundtrack uploads (kept in .uploads until finished).
 USER 1000:1000
 EXPOSE 8080
 # Prometheus metrics (METRICS_PORT). Keep it off the public proxy.
@@ -38,6 +39,7 @@ VOLUME /characters
 # Required: DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_NAME, MUSIC_PATH, CHARACTERS_PATH
 # Covers (optional): COVERS_PATH, a writable folder such as a /covers volume, turns covers on.
 # STEAMGRIDDB_API_KEY also turns on the automatic search (SteamGridDB, then AniList).
+# Uploads (optional): UPLOAD_MAX_FILE_MB (default 50) and UPLOAD_MAX_TOTAL_MB (default 2048).
 ENV PORT=8080
 
 CMD ["./main"]

internal/backend/errors.go

@@ -15,6 +15,14 @@ var (
 	ErrInvalidImage = errors.New("invalid image")
 	// ErrCoversDisabled is returned when covers are used but COVERS_PATH is not set.
 	ErrCoversDisabled = errors.New("covers are not enabled on this server")
+	// ErrConflict is returned when something with the same name already exists.
+	ErrConflict = errors.New("already exists")
+	// ErrSyncing is returned when the music folder is being synced.
+	ErrSyncing = errors.New("syncing is in progress")
+	// ErrTooLarge is returned when an upload is over its size limit.
+	ErrTooLarge = errors.New("too large")
+	// ErrUploadsUnavailable is returned when the music folder cannot be written to.
+	ErrUploadsUnavailable = errors.New("uploads are not possible: the music folder cannot be written to")
 	// ErrUpstream is returned when an external service could not be reached.
 	ErrUpstream = errors.New("upstream service unavailable")
 )

internal/backend/sync.go

@@ -35,8 +35,15 @@ const (
 	brokenWorkers     = 50
 )
 
-// foldersToSkip are directories in the music path that are never synced.
+// foldersToSkip are directories in the music path that are never synced, besides hidden
-var foldersToSkip = map[string]struct{}{".sync": {}, "characters": {}, "dist": {}, "old": {}}
+// ones like .sync and .uploads.
+var foldersToSkip = map[string]struct{}{"characters": {}, "dist": {}, "old": {}}
+
+// skipFolder reports whether a directory in the music path is not a soundtrack.
+func skipFolder(name string) bool {
+	_, skip := foldersToSkip[name]
+	return skip || strings.HasPrefix(name, ".")
+}
 
 type SyncResponse struct {
 	SoundtracksAdded          []string          `json:"soundtracks_added"`
@@ -117,6 +124,37 @@ func (s *SyncService) Start(full bool) bool {
 	return true
 }
 
+// SyncFolder runs prepare and then syncs the soundtrack folder name, while no other sync
+// can run. It returns ErrSyncing when a sync is running. prepare can put the folder in
+// place; when it fails, nothing is synced. onComplete is not called, as only one
+// soundtrack changes.
+func (s *SyncService) SyncFolder(ctx context.Context, name string, prepare func() error) (repository.Soundtrack, error) {
+	if !s.running.CompareAndSwap(false, true) {
+		return repository.Soundtrack{}, ErrSyncing
+	}
+	defer s.running.Store(false)
+
+	existing, err := s.q.GetAllSoundtracksIncludingDeleted(ctx)
+	if err != nil {
+		return repository.Soundtrack{}, err
+	}
+	if err := prepare(); err != nil {
+		return repository.Soundtrack{}, err
+	}
+	run := &syncRun{q: s.q, musicPath: s.musicPath, existing: existing, progress: func() {}}
+	run.syncSoundtrack(ctx, name)
+	if len(run.errs) > 0 {
+		return repository.Soundtrack{}, fmt.Errorf("syncing %q: %s", name, strings.Join(run.errs, "; "))
+	}
+	if len(run.foundIDs) != 1 {
+		return repository.Soundtrack{}, fmt.Errorf("syncing %q found %d soundtracks", name, len(run.foundIDs))
+	}
+	if err := s.UpdateLibraryMetrics(ctx); err != nil {
+		logging.GetLogger().Error("Failed to count the library", zap.Error(err))
+	}
+	return s.q.GetSoundtrackById(ctx, run.foundIDs[0])
+}
+
 // Wait blocks until the running sync, if any, has finished.
 func (s *SyncService) Wait() {
 	s.wg.Wait()
@@ -276,7 +314,7 @@ func (r *syncRun) execute(ctx context.Context, setTotal func(int)) SyncResponse
 	for _, dir := range directories {
 		g.Go(func() error {
 			defer r.progress()
-			if _, skip := foldersToSkip[dir.Name()]; dir.IsDir() && !skip {
+			if dir.IsDir() && !skipFolder(dir.Name()) {
 				r.syncSoundtrack(ctx, dir.Name())
 			}
 			return nil

internal/backend/uploads.go

@@ -0,0 +1,412 @@
+package backend
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"music-server/internal/db/repository"
+	"music-server/internal/logging"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+)
+
+const (
+	// uploadsFolder is where unfinished uploads are kept, inside the music folder. The
+	// sync skips it, like every hidden folder.
+	uploadsFolder = ".uploads"
+	// uploadMaxAge is how long an unfinished upload is kept.
+	uploadMaxAge = 24 * time.Hour
+	// maxUploadNameLength is the longest soundtrack or file name, in bytes.
+	maxUploadNameLength = 200
+)
+
+// Upload is an unfinished soundtrack upload.
+type Upload struct {
+	ID        uuid.UUID    `json:"id"`
+	Name      string       `json:"name" doc:"Name of the new soundtrack, also its folder name"`
+	Started   time.Time    `json:"started"`
+	Files     []UploadFile `json:"files" doc:"The songs received so far, sorted by name"`
+	TotalSize int64        `json:"total_size" doc:"Size of all songs received so far, in bytes"`
+}
+
+// UploadFile is a song received for an upload.
+type UploadFile struct {
+	Name string `json:"name"`
+	Size int64  `json:"size"`
+}
+
+// uploadInfo is stored next to an upload's folder, as <id>.json.
+type uploadInfo struct {
+	Name    string    `json:"name"`
+	Started time.Time `json:"started"`
+}
+
+// UploadService adds new soundtracks from uploaded songs. An upload is started with a name,
+// gets one song per request, and is finished by moving its folder into the music folder
+// and syncing it.
+type UploadService struct {
+	q         repository.Querier
+	musicPath string
+	sync      *SyncService
+	library   *LibraryService
+	// MaxFileSize and MaxTotalSize limit a song and a whole upload, in bytes.
+	MaxFileSize  int64
+	MaxTotalSize int64
+	now          func() time.Time
+
+	// mu keeps requests for the same upload, and the name checks, from interleaving.
+	mu sync.Mutex
+}
+
+// NewUploadService creates an UploadService for the music folder.
+func NewUploadService(q repository.Querier, musicPath string, syncService *SyncService, library *LibraryService,
+	maxFileSize, maxTotalSize int64) *UploadService {
+	return &UploadService{
+		q: q, musicPath: musicPath, sync: syncService, library: library,
+		MaxFileSize: maxFileSize, MaxTotalSize: maxTotalSize, now: time.Now,
+	}
+}
+
+func (u *UploadService) uploadsDir() string {
+	return filepath.Join(u.musicPath, uploadsFolder)
+}
+
+func (u *UploadService) dir(id uuid.UUID) string {
+	return filepath.Join(u.uploadsDir(), id.String())
+}
+
+func (u *UploadService) infoPath(id uuid.UUID) string {
+	return filepath.Join(u.uploadsDir(), id.String()+".json")
+}
+
+// Start begins an upload of a new soundtrack called name. The name must be usable as a
+// folder name, and no soundtrack, folder or other upload may have it.
+func (u *UploadService) Start(ctx context.Context, name string) (Upload, error) {
+	name = strings.TrimSpace(name)
+	if err := checkUploadName(name, "soundtrack"); err != nil {
+		return Upload{}, err
+	}
+	if skipFolder(name) {
+		return Upload{}, fmt.Errorf("%w: %q is used for other things in the music folder", ErrInvalidName, name)
+	}
+	if u.sync.IsSyncing() {
+		return Upload{}, ErrSyncing
+	}
+
+	u.mu.Lock()
+	defer u.mu.Unlock()
+	u.removeOld()
+	if err := os.MkdirAll(u.uploadsDir(), 0o755); err != nil {
+		logging.GetLogger().Error("Failed to create the uploads folder", zap.Error(err))
+		return Upload{}, ErrUploadsUnavailable
+	}
+	if err := u.checkNameFree(ctx, name, uuid.Nil); err != nil {
+		return Upload{}, err
+	}
+
+	upload := Upload{ID: uuid.New(), Name: name, Started: u.now(), Files: []UploadFile{}}
+	if err := os.Mkdir(u.dir(upload.ID), 0o755); err != nil {
+		return Upload{}, err
+	}
+	info, err := json.Marshal(uploadInfo{Name: name, Started: upload.Started})
+	if err == nil {
+		err = os.WriteFile(u.infoPath(upload.ID), info, 0o644)
+	}
+	if err != nil {
+		_ = os.RemoveAll(u.dir(upload.ID))
+		return Upload{}, err
+	}
+	logging.GetLogger().Info("Soundtrack upload started", zap.String("name", name), zap.Stringer("id", upload.ID))
+	return upload, nil
+}
+
+// checkNameFree returns ErrConflict when an active soundtrack, a folder in the music folder
+// or an upload other than except already has name, ignoring case. Call with mu held.
+func (u *UploadService) checkNameFree(ctx context.Context, name string, except uuid.UUID) error {
+	soundtracks, err := u.q.FindAllSoundtracks(ctx)
+	if err != nil {
+		return err
+	}
+	for _, s := range soundtracks {
+		if strings.EqualFold(s.SoundtrackName, name) {
+			return fmt.Errorf("%w: a soundtrack called %q", ErrConflict, s.SoundtrackName)
+		}
+	}
+	entries, err := os.ReadDir(u.musicPath)
+	if err != nil {
+		return err
+	}
+	for _, entry := range entries {
+		if strings.EqualFold(entry.Name(), name) {
+			return fmt.Errorf("%w: a folder called %q in the music folder", ErrConflict, entry.Name())
+		}
+	}
+	uploads, err := u.list()
+	if err != nil {
+		return err
+	}
+	for _, other := range uploads {
+		if other.id != except && strings.EqualFold(other.info.Name, name) {
+			return fmt.Errorf("%w: an unfinished upload of %q", ErrConflict, other.info.Name)
+		}
+	}
+	return nil
+}
+
+// checkUploadName checks that name can be used as a file or folder name on every system.
+func checkUploadName(name, what string) error {
+	switch {
+	case name == "":
+		return fmt.Errorf("%w: the %s name is empty", ErrInvalidName, what)
+	case len(name) > maxUploadNameLength:
+		return fmt.Errorf("%w: the %s name is longer than %d bytes", ErrInvalidName, what, maxUploadNameLength)
+	case !utf8.ValidString(name):
+		return fmt.Errorf("%w: the %s name is not valid UTF-8", ErrInvalidName, what)
+	case strings.HasPrefix(name, "."):
+		return fmt.Errorf("%w: the %s name cannot start with a dot", ErrInvalidName, what)
+	case strings.TrimRight(name, ". ") != name:
+		return fmt.Errorf("%w: the %s name cannot end with a dot or a space", ErrInvalidName, what)
+	case strings.ContainsAny(name, `/\:*?"<>|`):
+		return fmt.Errorf(`%w: the %s name cannot contain / \ : * ? " < > |`, ErrInvalidName, what)
+	case strings.ContainsFunc(name, unicode.IsControl):
+		return fmt.Errorf("%w: the %s name cannot contain control characters", ErrInvalidName, what)
+	}
+	return nil
+}
+
+type storedUpload struct {
+	id   uuid.UUID
+	info uploadInfo
+}
+
+// list returns all unfinished uploads. Call with mu held.
+func (u *UploadService) list() ([]storedUpload, error) {
+	entries, err := os.ReadDir(u.uploadsDir())
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	var uploads []storedUpload
+	for _, entry := range entries {
+		idText, ok := strings.CutSuffix(entry.Name(), ".json")
+		id, err := uuid.Parse(idText)
+		if !ok || err != nil {
+			continue
+		}
+		info, err := u.readInfo(id)
+		if err == nil {
+			uploads = append(uploads, storedUpload{id: id, info: info})
+		}
+	}
+	return uploads, nil
+}
+
+func (u *UploadService) readInfo(id uuid.UUID) (uploadInfo, error) {
+	data, err := os.ReadFile(u.infoPath(id))
+	if errors.Is(err, fs.ErrNotExist) {
+		return uploadInfo{}, ErrNotFound
+	}
+	if err != nil {
+		return uploadInfo{}, err
+	}
+	var info uploadInfo
+	if err := json.Unmarshal(data, &info); err != nil {
+		return uploadInfo{}, err
+	}
+	return info, nil
+}
+
+// Get returns an unfinished upload with the songs received so far.
+func (u *UploadService) Get(id uuid.UUID) (Upload, error) {
+	u.mu.Lock()
+	defer u.mu.Unlock()
+	return u.get(id)
+}
+
+func (u *UploadService) get(id uuid.UUID) (Upload, error) {
+	info, err := u.readInfo(id)
+	if err != nil {
+		return Upload{}, err
+	}
+	upload := Upload{ID: id, Name: info.Name, Started: info.Started, Files: []UploadFile{}}
+	entries, err := os.ReadDir(u.dir(id))
+	if err != nil {
+		return Upload{}, err
+	}
+	for _, entry := range entries {
+		if !isSong(entry) {
+			continue
+		}
+		fileInfo, err := entry.Info()
+		if err != nil {
+			return Upload{}, err
+		}
+		upload.Files = append(upload.Files, UploadFile{Name: entry.Name(), Size: fileInfo.Size()})
+		upload.TotalSize += fileInfo.Size()
+	}
+	return upload, nil
+}
+
+// PutFile stores data as the song fileName of an upload, replacing a song of the same name.
+// Only MP3 files are accepted, like the sync.
+func (u *UploadService) PutFile(id uuid.UUID, fileName string, data []byte) (UploadFile, error) {
+	if err := checkUploadName(fileName, "file"); err != nil {
+		return UploadFile{}, err
+	}
+	if !strings.EqualFold(filepath.Ext(fileName), ".mp3") {
+		return UploadFile{}, fmt.Errorf("%w: only .mp3 files can be uploaded", ErrInvalidName)
+	}
+	if int64(len(data)) > u.MaxFileSize {
+		return UploadFile{}, fmt.Errorf("%w: a song can be at most %d MB", ErrTooLarge, u.MaxFileSize>>20)
+	}
+	if !isMP3(data) {
+		return UploadFile{}, fmt.Errorf("%w: %q is not an MP3 file", ErrInvalidName, fileName)
+	}
+
+	u.mu.Lock()
+	defer u.mu.Unlock()
+	upload, err := u.get(id)
+	if err != nil {
+		return UploadFile{}, err
+	}
+	total := upload.TotalSize + int64(len(data))
+	for _, f := range upload.Files {
+		if f.Name == fileName {
+			total -= f.Size // replaced
+		}
+	}
+	if total > u.MaxTotalSize {
+		return UploadFile{}, fmt.Errorf("%w: an upload can be at most %d MB", ErrTooLarge, u.MaxTotalSize>>20)
+	}
+
+	tmp, err := os.CreateTemp(u.dir(id), ".part-*")
+	if err != nil {
+		return UploadFile{}, err
+	}
+	defer os.Remove(tmp.Name())
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		return UploadFile{}, err
+	}
+	if err := tmp.Close(); err != nil {
+		return UploadFile{}, err
+	}
+	if err := os.Rename(tmp.Name(), filepath.Join(u.dir(id), fileName)); err != nil {
+		return UploadFile{}, err
+	}
+	return UploadFile{Name: fileName, Size: int64(len(data))}, nil
+}
+
+// isMP3 reports whether data starts like an MP3 file: an ID3 tag or an MPEG audio frame.
+func isMP3(data []byte) bool {
+	if bytes.HasPrefix(data, []byte("ID3")) {
+		return true
+	}
+	return len(data) >= 2 && data[0] == 0xFF && data[1]&0xE0 == 0xE0
+}
+
+// Finish moves the upload's folder into the music folder, adds the soundtrack to the
+// library and returns it with its songs.
+func (u *UploadService) Finish(ctx context.Context, id uuid.UUID) (SoundtrackWithSongList, error) {
+	u.mu.Lock()
+	defer u.mu.Unlock()
+	upload, err := u.get(id)
+	if err != nil {
+		return SoundtrackWithSongList{}, err
+	}
+	if len(upload.Files) == 0 {
+		return SoundtrackWithSongList{}, fmt.Errorf("%w: the upload has no songs", ErrInvalidName)
+	}
+
+	target := filepath.Join(u.musicPath, upload.Name)
+	soundtrack, err := u.sync.SyncFolder(ctx, upload.Name, func() error {
+		if err := u.checkNameFree(ctx, upload.Name, upload.ID); err != nil {
+			return err
+		}
+		if err := u.checkNotDuplicate(ctx, upload); err != nil {
+			return err
+		}
+		return os.Rename(u.dir(id), target)
+	})
+	if err != nil {
+		return SoundtrackWithSongList{}, err
+	}
+	if err := os.Remove(u.infoPath(id)); err != nil {
+		logging.GetLogger().Warn("Failed to remove upload info", zap.Error(err))
+	}
+	logging.GetLogger().Info("Soundtrack uploaded", zap.String("name", upload.Name),
+		zap.Int("songs", len(upload.Files)), zap.Int64("bytes", upload.TotalSize))
+	return u.library.Soundtrack(ctx, soundtrack.Uuid)
+}
+
+// checkNotDuplicate refuses an upload with the same songs as an active soundtrack. The sync
+// would otherwise take it for that soundtrack renamed.
+func (u *UploadService) checkNotDuplicate(ctx context.Context, upload Upload) error {
+	existing, err := u.q.GetAllSoundtracksIncludingDeleted(ctx)
+	if err != nil {
+		return err
+	}
+	hash, err := dirHash(u.dir(upload.ID) + "/")
+	if err != nil {
+		return err
+	}
+	if status, match := classify(existing, upload.Name, hash); status == TitleChanged && match.Deleted == nil {
+		return fmt.Errorf("%w: soundtrack %q has the same songs", ErrConflict, match.SoundtrackName)
+	}
+	return nil
+}
+
+// Cancel deletes an unfinished upload and its songs.
+func (u *UploadService) Cancel(id uuid.UUID) error {
+	u.mu.Lock()
+	defer u.mu.Unlock()
+	if _, err := u.readInfo(id); err != nil {
+		return err
+	}
+	return u.remove(id)
+}
+
+func (u *UploadService) remove(id uuid.UUID) error {
+	if err := os.RemoveAll(u.dir(id)); err != nil {
+		return err
+	}
+	return os.Remove(u.infoPath(id))
+}
+
+// RemoveOld deletes uploads that were started more than a day ago and never finished.
+func (u *UploadService) RemoveOld() {
+	u.mu.Lock()
+	defer u.mu.Unlock()
+	u.removeOld()
+}
+
+func (u *UploadService) removeOld() {
+	uploads, err := u.list()
+	if err != nil {
+		logging.GetLogger().Warn("Failed to list uploads", zap.Error(err))
+		return
+	}
+	for _, upload := range uploads {
+		if u.now().Sub(upload.info.Started) > uploadMaxAge {
+			if err := u.remove(upload.id); err != nil {
+				logging.GetLogger().Warn("Failed to remove an old upload", zap.Error(err))
+				continue
+			}
+			logging.GetLogger().Info("Removed unfinished upload", zap.String("name", upload.info.Name))
+		}
+	}
+}

internal/backend/uploads_integration_test.go

@@ -0,0 +1,77 @@
+//go:build integration
+
+package backend
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+
+	"music-server/internal/db/repository"
+	"music-server/internal/testutil/pgtest"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestUploadWithPostgres uploads songs and checks the soundtrack in a real database.
+func TestUploadWithPostgres(t *testing.T) {
+	ctx := context.Background()
+	q := repository.New(pgtest.NewMigratedDatabase(t).Pool)
+	musicDir := t.TempDir()
+	writeFile(t, filepath.Join(musicDir, "Original", "01 Song.mp3"), string(mp3("original one")))
+	writeFile(t, filepath.Join(musicDir, "Original", "02 Song.mp3"), string(mp3("original two")))
+	s := NewSyncService(q, musicDir, nil)
+	require.True(t, s.Start(false))
+	s.Wait()
+	require.Empty(t, s.Result().CatchedErrors)
+	library := NewLibraryService(q)
+	uploads := NewUploadService(q, musicDir, s, library, 50<<20, 500<<20)
+
+	upload := func(name string, songs map[string]string) Upload {
+		u, err := uploads.Start(ctx, name)
+		require.NoError(t, err)
+		for file, content := range songs {
+			_, err := uploads.PutFile(u.ID, file, mp3(content))
+			require.NoError(t, err)
+		}
+		return u
+	}
+
+	// The songs of an existing soundtrack under a new name are refused.
+	duplicate := upload("Copy", map[string]string{"01 Song.mp3": "original one", "02 Song.mp3": "original two"})
+	_, err := uploads.Finish(ctx, duplicate.ID)
+	assert.ErrorIs(t, err, ErrConflict)
+	require.NoError(t, uploads.Cancel(duplicate.ID))
+
+	// The name of an existing soundtrack is refused.
+	_, err = uploads.Start(ctx, "original")
+	assert.ErrorIs(t, err, ErrConflict)
+
+	added := upload("Uploaded Soundtrack", map[string]string{"1-01 First.mp3": "first", "1-02 Second.mp3": "second"})
+	soundtrack, err := uploads.Finish(ctx, added.ID)
+	require.NoError(t, err)
+	assert.Equal(t, "Uploaded Soundtrack", soundtrack.Name)
+	require.Len(t, soundtrack.Songs, 2)
+	assert.Equal(t, "1-01 First", soundtrack.Songs[0].Name)
+	path, err := library.SongPath(ctx, soundtrack.Songs[0].Uuid)
+	require.NoError(t, err)
+	assert.FileExists(t, path)
+
+	count, err := q.CountLibrary(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, int64(2), count.Soundtracks)
+	assert.Equal(t, int64(4), count.Songs)
+
+	// A sync afterwards changes nothing.
+	require.True(t, s.Start(false))
+	s.Wait()
+	result := s.Result()
+	assert.Empty(t, result.CatchedErrors)
+	assert.Empty(t, result.SoundtracksAdded)
+	assert.Empty(t, result.SoundtracksChangedTitle)
+	assert.Empty(t, result.SoundtracksRemoved)
+	again, err := library.Soundtrack(ctx, soundtrack.Uuid)
+	require.NoError(t, err)
+	assert.Len(t, again.Songs, 2)
+}

internal/backend/uploads_test.go

@@ -0,0 +1,270 @@
+package backend
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"music-server/internal/db/repository"
+	"music-server/internal/testutil/fakedb"
+
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// mp3 returns data that starts like an MP3 file, made unique by content.
+func mp3(content string) []byte {
+	return append([]byte("ID3"), content...)
+}
+
+type uploadFixture struct {
+	t        *testing.T
+	musicDir string
+	store    *fakedb.Store
+	sync     *SyncService
+	uploads  *UploadService
+}
+
+func newUploadFixture(t *testing.T) *uploadFixture {
+	musicDir := t.TempDir()
+	store := fakedb.New()
+	syncService := NewSyncService(store, musicDir, nil)
+	return &uploadFixture{
+		t: t, musicDir: musicDir, store: store, sync: syncService,
+		uploads: NewUploadService(store, musicDir, syncService, NewLibraryService(store), 1<<20, 3<<20),
+	}
+}
+
+func (f *uploadFixture) start(name string) Upload {
+	f.t.Helper()
+	upload, err := f.uploads.Start(context.Background(), name)
+	require.NoError(f.t, err)
+	return upload
+}
+
+func (f *uploadFixture) put(id uuid.UUID, fileName, content string) {
+	f.t.Helper()
+	_, err := f.uploads.PutFile(id, fileName, mp3(content))
+	require.NoError(f.t, err)
+}
+
+func TestUploadSoundtrack(t *testing.T) {
+	f := newUploadFixture(t)
+	ctx := context.Background()
+
+	upload := f.start("  Chrono Trigger  ")
+	assert.Equal(t, "Chrono Trigger", upload.Name, "the name is trimmed")
+	f.put(upload.ID, "02 Corridors of Time.mp3", "b")
+	f.put(upload.ID, "01 Wind Scene.MP3", "a")
+	f.put(upload.ID, "02 Corridors of Time.mp3", "b2") // sent again
+
+	got, err := f.uploads.Get(upload.ID)
+	require.NoError(t, err)
+	assert.Equal(t, []UploadFile{{Name: "01 Wind Scene.MP3", Size: 4}, {Name: "02 Corridors of Time.mp3", Size: 5}}, got.Files)
+	assert.Equal(t, int64(9), got.TotalSize)
+	_, err = f.store.GetSoundtrackById(ctx, 1)
+	assert.Error(t, err, "nothing is in the library before finishing")
+
+	soundtrack, err := f.uploads.Finish(ctx, upload.ID)
+	require.NoError(t, err)
+	assert.Equal(t, "Chrono Trigger", soundtrack.Name)
+	require.Len(t, soundtrack.Songs, 2)
+	assert.Equal(t, "01 Wind Scene", soundtrack.Songs[0].Name)
+	assert.FileExists(t, filepath.Join(f.musicDir, "Chrono Trigger", "01 Wind Scene.MP3"))
+
+	entries, err := os.ReadDir(filepath.Join(f.musicDir, uploadsFolder))
+	require.NoError(t, err)
+	assert.Empty(t, entries, "nothing is left of the upload")
+	_, err = f.uploads.Get(upload.ID)
+	assert.ErrorIs(t, err, ErrNotFound)
+
+	// The next sync sees nothing new.
+	require.True(t, f.sync.Start(false))
+	f.sync.Wait()
+	result := f.sync.Result()
+	assert.Empty(t, result.SoundtracksAdded)
+	assert.Empty(t, result.CatchedErrors)
+}
+
+func TestUploadNames(t *testing.T) {
+	f := newUploadFixture(t)
+	ctx := context.Background()
+	f.store.AddSoundtrack(repository.Soundtrack{SoundtrackName: "Kingdom Hearts"})
+	writeFile(t, filepath.Join(f.musicDir, "Folder Only", "x.txt"), "x")
+	f.start("Pending")
+
+	for name, want := range map[string]error{
+		"":                       ErrInvalidName,
+		"   ":                    ErrInvalidName,
+		"a/b":                    ErrInvalidName,
+		`a\b`:                    ErrInvalidName,
+		"..":                     ErrInvalidName,
+		".hidden":                ErrInvalidName,
+		"ends with dot.":         ErrInvalidName,
+		"what?":                  ErrInvalidName,
+		"tab\tname":              ErrInvalidName,
+		"characters":             ErrInvalidName,
+		strings.Repeat("a", 201): ErrInvalidName,
+		"kingdom hearts":         ErrConflict,
+		"FOLDER ONLY":            ErrConflict,
+		"pending":                ErrConflict,
+	} {
+		_, err := f.uploads.Start(ctx, name)
+		assert.ErrorIs(t, err, want, "%q", name)
+	}
+	_, err := f.uploads.Start(ctx, "Ys: Origin")
+	assert.ErrorIs(t, err, ErrInvalidName, "':' is not allowed on Windows")
+	_, err = f.uploads.Start(ctx, "Pokémon HeartGold & SoulSilver (DS)")
+	assert.NoError(t, err)
+}
+
+func TestUploadFileChecks(t *testing.T) {
+	f := newUploadFixture(t)
+	upload := f.start("Game")
+
+	for fileName, want := range map[string]error{
+		"song.wav":      ErrInvalidName,
+		"song":          ErrInvalidName,
+		"Disc 1/01.mp3": ErrInvalidName,
+		"../escape.mp3": ErrInvalidName,
+		".hidden.mp3":   ErrInvalidName,
+	} {
+		_, err := f.uploads.PutFile(upload.ID, fileName, mp3("x"))
+		assert.ErrorIs(t, err, want, fileName)
+	}
+	_, err := f.uploads.PutFile(upload.ID, "text.mp3", []byte("just text"))
+	assert.ErrorIs(t, err, ErrInvalidName, "not an MP3 file")
+	_, err = f.uploads.PutFile(upload.ID, "frame.mp3", []byte{0xFF, 0xFB, 0x90, 0x00})
+	assert.NoError(t, err, "an MP3 without an ID3 tag starts with a frame")
+	_, err = f.uploads.PutFile(uuid.New(), "song.mp3", mp3("x"))
+	assert.ErrorIs(t, err, ErrNotFound)
+
+	_, err = f.uploads.PutFile(upload.ID, "big.mp3", mp3(strings.Repeat("x", 1<<20)))
+	assert.ErrorIs(t, err, ErrTooLarge, "over the size of one song")
+	for i := range 3 {
+		f.put(upload.ID, string(rune('a'+i))+".mp3", strings.Repeat("x", 1<<20-10))
+	}
+	_, err = f.uploads.PutFile(upload.ID, "d.mp3", mp3(strings.Repeat("x", 1000)))
+	assert.ErrorIs(t, err, ErrTooLarge, "over the size of the whole upload")
+	_, err = f.uploads.PutFile(upload.ID, "a.mp3", mp3("small"))
+	assert.NoError(t, err, "replacing a song counts its new size only")
+}
+
+func TestUploadFinishChecks(t *testing.T) {
+	f := newUploadFixture(t)
+	ctx := context.Background()
+
+	empty := f.start("Empty")
+	_, err := f.uploads.Finish(ctx, empty.ID)
+	assert.ErrorIs(t, err, ErrInvalidName, "an upload without songs")
+	_, err = f.uploads.Finish(ctx, uuid.New())
+	assert.ErrorIs(t, err, ErrNotFound)
+
+	// A folder of the same name appeared meanwhile, e.g. from ResilioSync.
+	clash := f.start("Clash")
+	f.put(clash.ID, "01.mp3", "c")
+	writeFile(t, filepath.Join(f.musicDir, "Clash", "01.mp3"), "other")
+	_, err = f.uploads.Finish(ctx, clash.ID)
+	assert.ErrorIs(t, err, ErrConflict)
+	assert.FileExists(t, filepath.Join(f.musicDir, uploadsFolder, clash.ID.String(), "01.mp3"), "the upload is kept")
+
+	// The same songs as a soundtrack that is already in the library.
+	original := f.start("Original")
+	f.put(original.ID, "01.mp3", "same")
+	_, err = f.uploads.Finish(ctx, original.ID)
+	require.NoError(t, err)
+	duplicate := f.start("Copy")
+	f.put(duplicate.ID, "01.mp3", "same")
+	_, err = f.uploads.Finish(ctx, duplicate.ID)
+	assert.ErrorIs(t, err, ErrConflict)
+	assert.Contains(t, err.Error(), "Original")
+	assert.NoDirExists(t, filepath.Join(f.musicDir, "Copy"))
+}
+
+func TestUploadWhileSyncing(t *testing.T) {
+	f := newUploadFixture(t)
+	release := make(chan struct{})
+	f.sync = NewSyncService(f.store, f.musicDir, func(context.Context) { <-release })
+	f.uploads.sync = f.sync
+	upload := f.start("Game")
+	f.put(upload.ID, "01.mp3", "a")
+	require.True(t, f.sync.Start(false))
+
+	_, err := f.uploads.Start(context.Background(), "Other")
+	assert.ErrorIs(t, err, ErrSyncing)
+	_, err = f.uploads.Finish(context.Background(), upload.ID)
+	assert.ErrorIs(t, err, ErrSyncing)
+	assert.NoDirExists(t, filepath.Join(f.musicDir, "Game"), "nothing was moved")
+
+	close(release)
+	f.sync.Wait()
+	_, err = f.uploads.Finish(context.Background(), upload.ID)
+	assert.NoError(t, err)
+}
+
+func TestUploadFinishBlocksASync(t *testing.T) {
+	f := newUploadFixture(t)
+	upload := f.start("Game")
+	f.put(upload.ID, "01.mp3", "a")
+	started := make(chan bool, 1)
+
+	_, err := f.sync.SyncFolder(context.Background(), "Game", func() error {
+		started <- f.sync.Start(false)
+		return os.Rename(f.uploads.dir(upload.ID), filepath.Join(f.musicDir, "Game"))
+	})
+	require.NoError(t, err)
+	assert.False(t, <-started, "a sync cannot start while a folder is being added")
+}
+
+func TestUploadCancelAndCleanup(t *testing.T) {
+	f := newUploadFixture(t)
+	cancelled := f.start("Cancelled")
+	f.put(cancelled.ID, "01.mp3", "a")
+	require.NoError(t, f.uploads.Cancel(cancelled.ID))
+	assert.NoDirExists(t, f.uploads.dir(cancelled.ID))
+	assert.ErrorIs(t, f.uploads.Cancel(cancelled.ID), ErrNotFound)
+
+	old := f.start("Old")
+	f.put(old.ID, "01.mp3", "a")
+	recent := f.start("Recent")
+	f.uploads.now = func() time.Time { return time.Now().Add(uploadMaxAge - time.Minute) }
+	f.uploads.RemoveOld()
+	_, err := f.uploads.Get(old.ID)
+	assert.NoError(t, err, "not a day old yet")
+
+	f.uploads.now = func() time.Time { return time.Now().Add(uploadMaxAge + time.Minute) }
+	f.uploads.RemoveOld()
+	_, err = f.uploads.Get(old.ID)
+	assert.ErrorIs(t, err, ErrNotFound)
+	_, err = f.uploads.Get(recent.ID)
+	assert.ErrorIs(t, err, ErrNotFound)
+
+	// A new upload of the same name works after the old one is gone.
+	f.uploads.now = time.Now
+	f.start("Old")
+}
+
+func TestSyncSkipsUploadsAndHiddenFolders(t *testing.T) {
+	f := newSyncFixture(t)
+	f.write("Game A/01.mp3", "a")
+	f.write(".uploads/123/01.mp3", "b")
+	f.write(".sync/x/01.mp3", "c")
+	result := f.run(false)
+	assert.Equal(t, []string{"Game A"}, result.SoundtracksAdded)
+}
+
+func TestUploadsUnavailableWhenMusicFolderIsReadOnly(t *testing.T) {
+	if os.Getuid() == 0 {
+		t.Skip("root can write to read-only folders")
+	}
+	f := newUploadFixture(t)
+	require.NoError(t, os.Chmod(f.musicDir, 0o555))
+	t.Cleanup(func() { os.Chmod(f.musicDir, 0o755) })
+
+	_, err := f.uploads.Start(context.Background(), "Game")
+	assert.ErrorIs(t, err, ErrUploadsUnavailable)
+}

internal/config/config.go

@@ -31,6 +31,11 @@ type Config struct {
 	CharactersPath string
 	SoundCheckPath string
 	FrontendPath   string
+	// UploadMaxFileSize and UploadMaxTotalSize limit uploaded songs, in bytes: one song and
+	// all songs of one uploaded soundtrack.
+	UploadMaxFileSize  int64
+	UploadMaxTotalSize int64
+
 	// CoversPath is the folder for soundtrack covers. Empty turns covers off.
 	CoversPath string
 
@@ -90,6 +95,15 @@ func load(getenv func(string) string) (Config, error) {
 	}
 	cfg.Port = port
 
+	cfg.UploadMaxFileSize, err = parseMegabytes(getenv("UPLOAD_MAX_FILE_MB"), DefaultUploadMaxFileMB)
+	if err != nil {
+		errs = append(errs, fmt.Errorf("UPLOAD_MAX_FILE_MB: %w", err))
+	}
+	cfg.UploadMaxTotalSize, err = parseMegabytes(getenv("UPLOAD_MAX_TOTAL_MB"), DefaultUploadMaxTotalMB)
+	if err != nil {
+		errs = append(errs, fmt.Errorf("UPLOAD_MAX_TOTAL_MB: %w", err))
+	}
+
 	cfg.MetricsPort, err = parseMetricsPort(getenv("METRICS_PORT"))
 	if err != nil {
 		errs = append(errs, fmt.Errorf("METRICS_PORT: %w", err))
@@ -138,6 +152,24 @@ func parseCIDRs(value string) ([]*net.IPNet, error) {
 	return nets, nil
 }
 
+// Upload size limits in MB, used when UPLOAD_MAX_FILE_MB and UPLOAD_MAX_TOTAL_MB are not set.
+const (
+	DefaultUploadMaxFileMB  = 50
+	DefaultUploadMaxTotalMB = 2048
+)
+
+// parseMegabytes reads a positive number of megabytes and returns it in bytes.
+func parseMegabytes(value string, defaultMB int64) (int64, error) {
+	if value == "" {
+		return defaultMB << 20, nil
+	}
+	mb, err := strconv.ParseInt(value, 10, 64)
+	if err != nil || mb < 1 || mb > 1<<20 {
+		return 0, fmt.Errorf("%q is not a number of megabytes", value)
+	}
+	return mb << 20, nil
+}
+
 // DefaultMetricsPort is used when METRICS_PORT is not set.
 const DefaultMetricsPort = 2112
 

internal/config/config_test.go

@@ -37,6 +37,27 @@ func TestLoadDefaults(t *testing.T) {
 	assert.Empty(t, cfg.SteamGridDBAPIKey)
 }
 
+func TestLoadUploadLimits(t *testing.T) {
+	cfg, err := load(env(validEnv()))
+	require.NoError(t, err)
+	assert.Equal(t, int64(DefaultUploadMaxFileMB<<20), cfg.UploadMaxFileSize)
+	assert.Equal(t, int64(DefaultUploadMaxTotalMB<<20), cfg.UploadMaxTotalSize)
+
+	values := validEnv()
+	values["UPLOAD_MAX_FILE_MB"] = "100"
+	values["UPLOAD_MAX_TOTAL_MB"] = "500"
+	cfg, err = load(env(values))
+	require.NoError(t, err)
+	assert.Equal(t, int64(100<<20), cfg.UploadMaxFileSize)
+	assert.Equal(t, int64(500<<20), cfg.UploadMaxTotalSize)
+
+	for _, invalid := range []string{"0", "-5", "lots", "1.5"} {
+		values["UPLOAD_MAX_FILE_MB"] = invalid
+		_, err = load(env(values))
+		assert.ErrorContains(t, err, "UPLOAD_MAX_FILE_MB", invalid)
+	}
+}
+
 func TestLoadCovers(t *testing.T) {
 	values := validEnv()
 	values["COVERS_PATH"] = "/covers"

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)
+}

internal/testutil/fakedb/fakedb.go

@@ -180,6 +180,17 @@ func (s *Store) AddSoundtrackPlayedByUUID(_ context.Context, id uuid.UUID) error
 	return s.Err
 }
 
+func (s *Store) GetSoundtrackById(_ context.Context, id int32) (repository.Soundtrack, error) {
+	defer s.lock()()
+	if s.Err != nil {
+		return repository.Soundtrack{}, s.Err
+	}
+	if i := s.soundtrackIndex(id); i >= 0 && s.Soundtracks[i].Deleted == nil {
+		return s.Soundtracks[i], nil
+	}
+	return repository.Soundtrack{}, pgx.ErrNoRows
+}
+
 func (s *Store) GetSoundtrackByUUID(_ context.Context, id uuid.UUID) (repository.Soundtrack, error) {
 	defer s.lock()()
 	if s.Err != nil {