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/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.
-var foldersToSkip = map[string]struct{}{".sync": {}, "characters": {}, "dist": {}, "old": {}}
+// foldersToSkip are directories in the music path that are never synced, besides hidden
+// 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)
+}