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>
2026-10-15 21:38:26 +02:00
1 parent 439ffede18
commit a7e2280969
@@ -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))
+		}
+	}
+}