feat: the backup can include the music, sending each library file once to music/ and again only when it changes (#6774)

With "Include the music" on, each night's run sends the library files the
destination doesn't hold yet, after the database file has landed, for up to
six hours; a large library spans several nights the first time. Files keep
their path under the library folders' common root, beside database/ in the
same folder or bucket.

backup_music_files records each file's size and mtime as sent, so a night
sends only new and changed files, and a rescan that touches a track but finds
the same file sends nothing. A changed file goes to its old name; Minstrel
never deletes there. An object the bucket refuses (a locked overwrite) is
kept with its answer and goes again once the file changes or the settings are
saved; three refusals in a row stop the night's music, since that is a key
that may not write under music/. A folder copy is written under a .part name
and renamed, keeping the file's time.

The panel shows how much of the library is in, the refused files, and each
run's music count and note. The verdict still turns on the database file.

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

internal/backup/service.go

@@ -94,6 +94,7 @@ type Config struct {
 	HasSecretKey   bool   `json:"has_secret_key"`
 	RunHour        int    `json:"run_hour"`
 	UploadLimitKiB int    `json:"upload_limit_kib"`
+	IncludeMusic   bool   `json:"include_music"`
 }
 
 // Update is a save from the admin card. An empty SecretKey keeps the stored
@@ -108,6 +109,7 @@ type Update struct {
 	SecretKey      string `json:"secret_key"`
 	RunHour        int    `json:"run_hour"`
 	UploadLimitKiB int    `json:"upload_limit_kib"`
+	IncludeMusic   bool   `json:"include_music"`
 }
 
 // Run is one attempt at a backup.
@@ -120,6 +122,10 @@ type Run struct {
 	Location   string     `json:"location"`
 	Bytes      int64      `json:"bytes"`
 	Error      string     `json:"error"`
+	// What the run sent of the music, and why that stopped early, if it did.
+	MusicFiles int    `json:"music_files"`
+	MusicBytes int64  `json:"music_bytes"`
+	MusicNote  string `json:"music_note"`
 }
 
 // Status is everything the admin panel shows: a verdict, what stands in its
@@ -136,6 +142,9 @@ type Status struct {
 	NextRun         *time.Time `json:"next_run"`
 	RunLimitSeconds int        `json:"run_limit_seconds"`
 	Runs            []Run      `json:"runs"`
+	// Music is how much of the library the backup holds, when it includes
+	// the music.
+	Music *MusicProgress `json:"music"`
 }
 
 // TestResult is what a destination test found: how many backups are there
@@ -152,6 +161,9 @@ type Service struct {
 	logger *slog.Logger
 	build  string
 	now    func() time.Time
+	// Roots lists the library's folders. The music's paths in the backup are
+	// relative to the folder holding them all.
+	Roots func() []string
 
 	base   context.Context
 	cancel context.CancelFunc
@@ -188,6 +200,7 @@ func view(st dbq.BackupSetting) Config {
 		HasSecretKey:   st.SecretKey != "",
 		RunHour:        int(st.RunHour),
 		UploadLimitKiB: int(st.UploadLimitKib),
+		IncludeMusic:   st.IncludeMusic,
 	}
 }
 
@@ -231,6 +244,7 @@ func merge(st dbq.BackupSetting, u Update) (dbq.BackupSetting, error) {
 	st.AccessKey = strings.TrimSpace(u.AccessKey)
 	st.RunHour = int16(u.RunHour)
 	st.UploadLimitKib = int32(u.UploadLimitKiB)
+	st.IncludeMusic = u.IncludeMusic
 	if u.SecretKey != "" {
 		sealed, err := secret.Seal(secret.BackupSecretKey.Purpose(), "", u.SecretKey)
 		if err != nil {
@@ -262,6 +276,7 @@ func (s *Service) Save(ctx context.Context, u Update) error {
 		SecretKey:      st.SecretKey,
 		RunHour:        st.RunHour,
 		UploadLimitKib: st.UploadLimitKib,
+		IncludeMusic:   st.IncludeMusic,
 	})
 }
 
@@ -394,12 +409,17 @@ func (s *Service) Status(ctx context.Context) (Status, error) {
 		Problems:        probs,
 		LastSuccess:     ptr(t.lastSuccess),
 		FailingSince:    ptr(t.failingSince),
-		RunLimitSeconds: int(RunLimit / time.Second),
+		RunLimitSeconds: int(runLimit(st) / time.Second),
 		Runs:            make([]Run, 0, len(rows)),
 	}
 	if out.Problems == nil {
 		out.Problems = []string{}
 	}
+	if st.IncludeMusic {
+		if out.Music, err = s.musicProgress(ctx); err != nil {
+			return Status{}, err
+		}
+	}
 	s.mu.Lock()
 	out.RunningSince = ptr(s.runningSince)
 	s.mu.Unlock()
@@ -421,6 +441,9 @@ func (s *Service) Status(ctx context.Context) (Status, error) {
 			Location:   r.Location,
 			Bytes:      r.Bytes,
 			Error:      r.Error,
+			MusicFiles: int(r.MusicFiles),
+			MusicBytes: r.MusicBytes,
+			MusicNote:  r.MusicNote,
 		})
 	}
 	return out, nil
@@ -545,6 +568,15 @@ func (s *Service) Running() time.Time {
 	return s.runningSince
 }
 
+// runLimit is the longest a run may take: the database file, and the
+// music's nightly budget when the backup includes the music.
+func runLimit(st dbq.BackupSetting) time.Duration {
+	if st.IncludeMusic {
+		return RunLimit + MusicBudget
+	}
+	return RunLimit
+}
+
 func (s *Service) run(trigger string, st dbq.BackupSetting) {
 	ctx, cancel := context.WithTimeout(s.base, RunLimit)
 	defer cancel()
@@ -555,17 +587,29 @@ func (s *Service) run(trigger string, st dbq.BackupSetting) {
 		return
 	}
 	location, size, err := s.write(ctx, st, started.StartedAt.Time)
+	// The music goes only after the database file has landed, which also
+	// proves the destination takes writes.
+	var music musicSent
+	if err == nil && st.IncludeMusic {
+		mctx, mcancel := context.WithTimeout(s.base, MusicBudget)
+		music = s.sendMusic(mctx, st)
+		mcancel()
+	}
 
 	// The finish is recorded on its own context, so a run stopped by a
 	// shutdown or its time limit still says how it ended.
 	fctx, fcancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer fcancel()
-	fin := dbq.FinishBackupRunParams{ID: started.ID, Status: "succeeded", Location: location, Bytes: size}
+	fin := dbq.FinishBackupRunParams{
+		ID: started.ID, Status: "succeeded", Location: location, Bytes: size,
+		MusicFiles: int32(music.files), MusicBytes: music.bytes, MusicNote: music.note,
+	}
 	if err != nil {
 		fin.Status, fin.Error = "failed", describe(err)
 		s.logger.Warn("backup failed", "trigger", trigger, "err", err)
 	} else {
-		s.logger.Info("backup written", "trigger", trigger, "location", location, "bytes", size)
+		s.logger.Info("backup written", "trigger", trigger, "location", location, "bytes", size,
+			"music_files", music.files, "music_bytes", music.bytes, "music_note", music.note)
 	}
 	if err := q.FinishBackupRun(fctx, fin); err != nil {
 		s.logger.Error("backup: record the run's end", "err", err)