🎧 Your Personal Streaming Service
Go airsonicmadsonicmedia-servermusicmusic-servernavidromeopensubsonicraspberry-piself-hostedstreamerstreaming-apistreaming-audiosubsonicsubsonic-server
feat(cli): add an artwork command group for diagnosing and re-driving artwork (#5957)
Deluan Quintãodc40bcaf808a
diff --git a/cmd/artwork.go b/cmd/artwork.gonew file mode 100644index 000000000..2b6a50164--- /dev/null+++ b/cmd/artwork.go@@ -0,0 +1,778 @@+package cmd++import (+ "cmp"+ "context"+ "errors"+ "fmt"+ "io"+ "os"+ "slices"+ "strconv"+ "strings"+ "time"++ "github.com/navidrome/navidrome/conf"+ "github.com/navidrome/navidrome/consts"+ "github.com/navidrome/navidrome/core/agents"+ "github.com/navidrome/navidrome/core/artwork"+ "github.com/navidrome/navidrome/db"+ "github.com/navidrome/navidrome/log"+ "github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/utils/slice"+ "github.com/spf13/cobra"+)++var explainLive bool++var (+ reprocessKinds []string+ reprocessSources []string+ reprocessAll bool+ reprocessDryRun bool+ reprocessYes bool+)++func init() {+ artworkExplainCmd.Flags().BoolVar(&explainLive, "live", false,+ "perform real external lookups instead of reporting what would be tried")+ artworkReprocessCmd.Flags().StringSliceVar(&reprocessKinds, "kind", nil,+ "kinds to reprocess ("+kindPrefixes(artwork.RecheckKinds)+"); repeatable")+ artworkReprocessCmd.Flags().StringSliceVar(&reprocessSources, "source", nil,+ "only items currently resolved from these sources (e.g. folder, external:deezer, absent)")+ artworkReprocessCmd.Flags().BoolVar(&reprocessAll, "all", false, "reprocess every kind")+ artworkReprocessCmd.Flags().BoolVar(&reprocessDryRun, "dry-run", false,+ "report what would be queued and exit without queueing")+ artworkReprocessCmd.Flags().BoolVarP(&reprocessYes, "yes", "y", false, "skip the confirmation prompt")+ artworkCmd.AddCommand(artworkExplainCmd)+ artworkCmd.AddCommand(artworkRefreshCmd)+ artworkCmd.AddCommand(artworkReprocessCmd)+ artworkCmd.AddCommand(artworkStatusCmd)+ rootCmd.AddCommand(artworkCmd)+}++var artworkCmd = &cobra.Command{+ Use: "artwork",+ Short: "Inspect and re-resolve artwork",+}++var artworkExplainCmd = &cobra.Command{+ Use: "explain <kind> <id>",+ Short: "Explain why an item's artwork resolved the way it did",+ Long: "Explain why an item's artwork resolved the way it did.\n\n" ++ "<kind> is one of: " + kindPrefixes(explainKinds) + ".\n" ++ "A disc artwork id is the album id and the disc number, joined by a colon: <albumID>:2",+ Args: cobra.ExactArgs(2),+ Run: func(cmd *cobra.Command, args []string) {+ kind, err := parseArtworkKind(args[0], explainKinds)+ if err != nil {+ log.Fatal(cmd.Context(), err)+ }+ runExplain(cmd.Context(), kind, args[1])+ },+}++var artworkRefreshCmd = &cobra.Command{+ Use: "refresh <kind> <id>...",+ Short: "Clear an item's artwork state and re-resolve it",+ Args: cobra.MinimumNArgs(2),+ Run: func(cmd *cobra.Command, args []string) {+ kind, err := parseArtworkKind(args[0], artwork.RefreshableKinds)+ if err != nil {+ log.Fatal(cmd.Context(), err)+ }+ runRefresh(cmd.Context(), kind, args[1:])+ },+}++var artworkReprocessCmd = &cobra.Command{+ Use: "reprocess",+ Short: "Re-enqueue artwork in bulk, by kind and/or by the source it currently resolves from",+ Args: cobra.NoArgs,+ Run: func(cmd *cobra.Command, args []string) {+ runReprocess(cmd.Context())+ },+}++var artworkStatusCmd = &cobra.Command{+ Use: "status",+ Short: "Report the artwork queue, where artwork resolves from, and the backfill state",+ Args: cobra.NoArgs,+ Run: func(cmd *cobra.Command, args []string) {+ runStatus(cmd.Context())+ },+}++func runStatus(ctx context.Context) {+ defer db.Init(ctx)()+ ds, ctx := getAdminContext(ctx)++ rep, err := collectStatus(ctx, ds)+ if err != nil {+ log.Fatal(ctx, err)+ }+ fmt.Print(formatStatus(rep))+}++type sourceCount struct {+ kind model.Kind+ source string+ count int64+}++type absentCount struct {+ kind model.Kind+ model.ArtworkAbsentStat+}++type statusReport struct {+ queue []model.ArtworkQueueStat+ sources []sourceCount+ absent []absentCount+ inputs []artwork.FingerprintInput+ stored string+ current string+}++func (r statusReport) queueTotal() int64 {+ var n int64+ for _, s := range r.queue {+ n += s.Count+ }+ return n+}++func (r statusReport) backfillQueued() int64 {+ var n int64+ for _, s := range r.queue {+ if s.Priority == model.ArtworkPriorityBackfill {+ n += s.Count+ }+ }+ return n+}++func collectStatus(ctx context.Context, ds model.DataStore) (statusReport, error) {+ q := ds.ArtworkQueue(ctx)+ var rep statusReport+ var err error+ if rep.queue, err = q.CountByKindAndPriority(); err != nil {+ return rep, fmt.Errorf("breaking the artwork queue down by kind: %w", err)+ }++ cutoff := time.Now().Add(-artwork.StaleAbsentAge)+ for _, k := range artwork.RecheckKinds {+ sources, err := q.SourcesInUse(k)+ if err != nil {+ return rep, fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)+ }+ slices.Sort(sources)+ for _, s := range sources {+ n, err := q.CountBySource(k, []string{s})+ if err != nil {+ return rep, fmt.Errorf("counting %s artwork resolved from %s: %w", k, displaySource(s), err)+ }+ rep.sources = append(rep.sources, sourceCount{kind: k, source: s, count: n})+ }+ stat, err := q.CountAbsent(k, cutoff)+ if err != nil {+ return rep, fmt.Errorf("counting absent %s artwork: %w", k, err)+ }+ rep.absent = append(rep.absent, absentCount{kind: k, ArtworkAbsentStat: stat})+ }++ rep.current, rep.inputs = artwork.ConfigFingerprint(), artwork.FingerprintInputs()+ if rep.stored, err = ds.Property(ctx).DefaultGet(consts.ArtConfFingerprintPropertyKey, ""); err != nil {+ return rep, fmt.Errorf("reading the stored artwork fingerprint: %w", err)+ }+ return rep, nil+}++func formatStatus(rep statusReport) string {+ var sb strings.Builder+ w := newTabWriter(&sb)++ fmt.Fprintln(w, "Queue")+ if len(rep.queue) == 0 {+ fmt.Fprintln(w, " (empty)")+ } else {+ fmt.Fprintln(w, " KIND\tPRIORITY\tITEMS")+ for _, s := range rep.queue {+ fmt.Fprintf(w, " %s\t%s\t%d\n", kindName(s.ItemKind), priorityName(s.Priority), s.Count)+ }+ fmt.Fprintf(w, " TOTAL\t\t%d\n", rep.queueTotal())+ }++ fmt.Fprintln(w, "\nSources")+ fmt.Fprintln(w, " KIND\tSOURCE\tITEMS")+ for _, s := range rep.sources {+ fmt.Fprintf(w, " %s\t%s\t%d\n", s.kind, displaySource(s.source), s.count)+ }++ fmt.Fprintln(w, "\nAbsent (resolved, no image found)")+ fmt.Fprintln(w, " KIND\tABSENT\tDUE FOR RECHECK")+ for _, a := range rep.absent {+ fmt.Fprintf(w, " %s\t%d\t%d\n", a.kind, a.Total, a.Stale)+ }+ fmt.Fprintf(w, " (rechecked once the last attempt is older than %gh)\n", artwork.StaleAbsentAge.Hours())++ fmt.Fprintln(w, "\nBackfill")+ fmt.Fprintf(w, " State:\t%s\n", backfillState(rep))+ fmt.Fprintf(w, " Stored fingerprint:\t%s\n", cmp.Or(rep.stored, "(none)"))+ fmt.Fprintf(w, " Current fingerprint:\t%s\n", rep.current)+ if len(rep.inputs) > 0 {+ fmt.Fprintln(w, " Fingerprint inputs (changing any of these re-resolves the whole library):")+ for _, in := range rep.inputs {+ fmt.Fprintf(w, " %s:\t%s\n", in.Name, in.Value)+ }+ }++ w.Flush()+ return sb.String()+}++// backfillState leads with the queued backlog: by the time anyone runs this, backfill has usually+// already stored the new fingerprint, and "up to date" would bury the flood it is still working through.+func backfillState(rep statusReport) string {+ pending := "fingerprint changed — every artist, album, playlist and radio will be re-enqueued on the next startup"+ if n := rep.backfillQueued(); n > 0 {+ if rep.stored != rep.current {+ return fmt.Sprintf("backfill running: %d items queued, and %s", n, pending)+ }+ return fmt.Sprintf("backfill running: %d items queued (fingerprint up to date)", n)+ }+ if rep.stored != rep.current {+ return pending+ }+ return "up to date"+}++func kindName(prefix string) string {+ if k, ok := model.ParseKind(prefix); ok {+ return k.String()+ }+ return prefix+}++func priorityName(p int) string {+ switch p {+ case model.ArtworkPriorityRecheck:+ return "recheck"+ case model.ArtworkPriorityBackfill:+ return "backfill"+ case model.ArtworkPriorityScan:+ return "scan"+ case model.ArtworkPriorityBump:+ return "bump"+ }+ return strconv.Itoa(p)+}++func runReprocess(ctx context.Context) {+ kinds, err := selectedKinds(reprocessKinds, reprocessSources, reprocessAll)+ if err != nil {+ log.Fatal(ctx, err)+ }++ defer db.Init(ctx)()+ ds, ctx := getAdminContext(ctx)++ if err := reprocessArtwork(ctx, ds, kinds, repositorySources(reprocessSources), imageAgentCount(ds),+ reprocessDryRun, reprocessConfirm(reprocessYes, os.Stdin), os.Stdout); err != nil {+ log.Fatal(ctx, err)+ }+}++func selectedKinds(kinds, sources []string, all bool) ([]model.Kind, error) {+ // A source filter on its own is already a complete selection, so it does not also need a kind.+ if all || (len(kinds) == 0 && len(sources) > 0) {+ return artwork.RecheckKinds, nil+ }+ if len(kinds) == 0 {+ return nil, fmt.Errorf("no selector given: pass --kind, --source or --all")+ }+ out := make([]model.Kind, 0, len(kinds))+ for _, k := range kinds {+ kind, err := parseArtworkKind(k, artwork.RecheckKinds)+ if err != nil {+ return nil, err+ }+ out = append(out, kind)+ }+ // A repeated kind would be counted twice, overstating the cost the operator confirms.+ return slice.Unique(out), nil+}++// absentSource is how the stored empty source — resolved, no image — is spelled on the CLI.+const absentSource = "absent"++func repositorySources(sources []string) []string {+ return slice.Map(sources, func(s string) string {+ if s == absentSource {+ return ""+ }+ return s+ })+}++func displaySource(s string) string { return cmp.Or(s, absentSource) }++type confirmFunc func(out io.Writer, total, external int64) bool++func reprocessConfirm(yes bool, in io.Reader) confirmFunc {+ if yes {+ return func(io.Writer, int64, int64) bool { return true }+ }+ return promptConfirm(in)+}++// externalEstimate claims no bound: a local hit ends the walk before any agent is asked, and plugin+// agents are unregistered in a CLI that never starts the plugin manager.+func externalEstimate(n int64) string {+ if n == 0 {+ return "none"+ }+ return fmt.Sprintf("~%d estimated (plugin agents not counted; local hits may need fewer)", n)+}++func externalLookupLine(n int64) string {+ return fmt.Sprintf("External lookups: %s.", externalEstimate(n))+}++// imageAgentCount counts only the built-in image agents, for the same reason.+func imageAgentCount(ds model.DataStore) artwork.ImageAgentCount {+ ag := agents.GetAgents(ds, getPluginManager())+ return artwork.ImageAgentCount{Artist: len(ag.ArtistImageAgents()), Album: len(ag.AlbumImageAgents())}+}++func promptConfirm(in io.Reader) confirmFunc {+ return func(out io.Writer, total, external int64) bool {+ var cost string+ if external > 0 {+ cost = fmt.Sprintf(" %s", externalLookupLine(external))+ }+ fmt.Fprintf(out, "\nThis will re-resolve %d items.%s Continue? [y/N] ", total, cost)+ var answer string+ if _, err := fmt.Fscanln(in, &answer); err != nil {+ return false+ }+ answer = strings.ToLower(strings.TrimSpace(answer))+ return answer == "y" || answer == "yes"+ }+}++// validateSources rejects a typo'd source: matching nothing silently reads as "nothing to do" when+// it means the filter was wrong. Checked table-wide, so a filter is never a typo for one --kind only.+func validateSources(q model.ArtworkQueueRepository, sources []string) error {+ if len(sources) == 0 {+ return nil+ }+ var inUse []string+ for _, k := range artwork.RecheckKinds {+ found, err := q.SourcesInUse(k)+ if err != nil {+ return fmt.Errorf("listing the sources in use by %s artwork: %w", k, err)+ }+ inUse = slice.Unique(append(inUse, found...))+ }+ var unknown []string+ for _, s := range sources {+ if s != "" && !slices.Contains(inUse, s) { // the reserved absent source is valid even when nothing is absent+ unknown = append(unknown, displaySource(s))+ }+ }+ if len(unknown) == 0 {+ return nil+ }+ valid := slice.Map(inUse, displaySource)+ slices.Sort(valid)+ return fmt.Errorf("no artwork resolves from %s; sources in use: %s",+ strings.Join(unknown, ", "), cmp.Or(strings.Join(valid, ", "), "(none)"))+}++// reprocessArtwork previews from CountBySource — rows matched — then reports what EnqueueBySource+// actually inserted; the two differ because an already-queued row is left untouched.+func reprocessArtwork(ctx context.Context, ds model.DataStore, kinds []model.Kind, sources []string,+ imageAgents artwork.ImageAgentCount, dryRun bool, confirm confirmFunc, out io.Writer) error {+ q := ds.ArtworkQueue(ctx)+ if err := validateSources(q, sources); err != nil {+ return err+ }++ matched := make([]int64, len(kinds))+ var total, external int64+ for i, k := range kinds {+ n, err := q.CountBySource(k, sources)+ if err != nil {+ return fmt.Errorf("counting %s artwork: %w", k, err)+ }+ matched[i] = n+ total += n+ external += n * artwork.ExternalLookupsPerItem(k, imageAgents)+ }+ printReprocessPreview(out, kinds, matched, total, external, sources)++ switch {+ case dryRun:+ fmt.Fprintln(out, "\nDry run: nothing was queued.")+ return nil+ case total == 0:+ fmt.Fprintln(out, "Nothing was queued.")+ return nil+ case !confirm(out, total, external):+ fmt.Fprintln(out, "Aborted: nothing was queued.")+ return nil+ }++ var queued int64+ for i, k := range kinds {+ if matched[i] == 0 {+ continue+ }+ n, err := q.EnqueueBySource(k, sources, model.ArtworkPriorityRecheck)+ if err != nil {+ return fmt.Errorf("queueing %s artwork: %w", k, err)+ }+ queued += n+ fmt.Fprintf(out, "%s: %d queued\n", k, n)+ }+ fmt.Fprintf(out, "Queued %d of %d matched items.\n", queued, total)+ if skipped := total - queued; skipped > 0 {+ fmt.Fprintf(out, "Already queued, left unchanged: %d (priority and retry backoff untouched).\n", skipped)+ }+ return nil+}++// printReprocessPreview also states the external estimate, which --dry-run must show because it+// skips the prompt that would otherwise carry it.+func printReprocessPreview(out io.Writer, kinds []model.Kind, matched []int64, total, external int64, sources []string) {+ w := newTabWriter(out)+ shown := slice.Map(sources, displaySource)+ fmt.Fprintf(w, "Sources:\t%s\n\n", cmp.Or(strings.Join(shown, ", "), "(any)"))+ fmt.Fprintln(w, "KIND\tMATCHED")+ for i, k := range kinds {+ fmt.Fprintf(w, "%s\t%d\n", k, matched[i])+ }+ fmt.Fprintf(w, "TOTAL\t%d\n", total)+ w.Flush()++ fmt.Fprintf(out, "\n%s\n", externalLookupLine(external))+ if total == 0 {+ fmt.Fprintln(out, "\nNothing matches this selection.")+ }+}++func runRefresh(ctx context.Context, kind model.Kind, ids []string) {+ defer db.Init(ctx)()+ ds, ctx := getAdminContext(ctx)++ if failed := refreshItems(ctx, ds, kind, ids, os.Stdout); failed > 0 {+ log.Fatal(ctx, "Failed to refresh artwork", "kind", kind, "failed", failed, "total", len(ids))+ }+}++// refreshItems keeps going after a failure — the ids are independent — and returns how many failed.+func refreshItems(ctx context.Context, ds model.DataStore, kind model.Kind, ids []string, out io.Writer) int {+ var failed int+ for _, id := range ids {+ // artwork.Refresh would happily queue an id that does not exist, orphaning a queue row.+ if _, err := artworkItemName(ctx, ds, kind, id); err != nil {+ log.Error(ctx, "Item not found", "kind", kind, "id", id, err)+ failed+++ continue+ }+ if err := artwork.Refresh(ctx, ds, kind, id); err != nil {+ log.Error(ctx, "Error refreshing artwork", "kind", kind, "id", id, err)+ failed+++ continue+ }+ fmt.Fprintf(out, "%s/%s: queued\n", kind.Prefix(), id)+ }+ return failed+}++// explainKinds is every kind explain accepts: it reports stored state and config too, so a kind+// with no chain to walk still has something to answer with.+var explainKinds = []model.Kind{+ model.KindArtistArtwork, model.KindAlbumArtwork, model.KindDiscArtwork,+ model.KindMediaFileArtwork, model.KindPlaylistArtwork, model.KindRadioArtwork,+}++func kindPrefixes(kinds []model.Kind) string {+ return strings.Join(slice.Map(kinds, func(k model.Kind) string { return k.Prefix() }), ", ")+}++func parseArtworkKind(s string, valid []model.Kind) (model.Kind, error) {+ kind, ok := model.ParseKind(s)+ if ok && slices.Contains(valid, kind) {+ return kind, nil+ }+ return kind, fmt.Errorf("invalid kind %q, expected one of: %s", s, kindPrefixes(valid))+}++// explainAgents accounts for every configured agent: one the CLI cannot construct (a plugin, or a+// built-in missing its credentials) never reaches the Chain, so the raw list alone overstates it.+func explainAgents(configured string, available []string) string {+ if strings.TrimSpace(configured) == "" {+ return "(none)"+ }+ var unavailable bool+ names := slice.Map(strings.Split(configured, ","), func(name string) string {+ name = strings.TrimSpace(name)+ if slices.Contains(available, name) {+ return name+ }+ unavailable = true+ return name + "*"+ })+ line := strings.Join(names, ", ")+ if unavailable {+ line += " (* not available to the CLI)"+ }+ return line+}++// availableImageAgents names the agents that can actually supply an image for kind.+func availableImageAgents(ds model.DataStore, kind model.Kind) []string {+ ag := agents.GetAgents(ds, getPluginManager())+ if kind == model.KindArtistArtwork {+ return slice.Map(ag.ArtistImageAgents(), func(a agents.ArtistImageAgent) string { return a.Name })+ }+ return slice.Map(ag.AlbumImageAgents(), func(a agents.AlbumImageAgent) string { return a.Name })+}++// explainResult states the verdict of the walk. A skipped or failed external tier, or a local+// candidate that would not open, leaves the outcome unknown: nothing observed that there is no artwork.+func explainResult(source string, steps []artwork.TraceStep) string {+ if source != "" {+ for _, s := range steps {+ if s.Outcome == artwork.OutcomeHit {+ break+ }+ if s.Outcome == artwork.OutcomeWouldTry {+ return "resolved from " + source ++ " (offline: a higher-priority external candidate was not tried; re-run with --live)"+ }+ // An external winner discards the earlier error, so the resolver settles it with no retry.+ if s.Outcome == artwork.OutcomeError && strings.HasPrefix(s.Candidate, artwork.ExternalPrefix) &&+ !strings.HasPrefix(source, artwork.ExternalPrefix) {+ return "resolved from " + source ++ " (indeterminate: a higher-priority external lookup failed; this may resolve differently on a retry)"+ }+ }+ return "resolved from " + source+ }+ for _, s := range steps {+ switch {+ case s.Outcome == artwork.OutcomeWouldTry:+ return "indeterminate (external agents not called; re-run with --live)"+ case s.Outcome == artwork.OutcomeError && strings.HasPrefix(s.Candidate, artwork.ExternalPrefix):+ return "indeterminate (an external lookup failed; the item may resolve on a later attempt)"+ // The worker treats an unreadable local candidate exactly as it treats a failed external one:+ // it retries instead of settling absent, so the verdict must not read as a clean miss.+ case s.Outcome == artwork.OutcomeUnreadable:+ return "indeterminate (a candidate exists but could not be read; the worker retries rather than settling absent)"+ }+ }+ return "not resolved"+}++// explainConfig names the setting that decides where a kind's artwork comes from, and its value.+func explainConfig(kind model.Kind) (name, value string) {+ switch kind {+ case model.KindArtistArtwork:+ return "ArtistArtPriority", conf.Server.ArtistArtPriority+ case model.KindAlbumArtwork:+ return "CoverArtPriority", conf.Server.CoverArtPriority+ case model.KindDiscArtwork:+ return "DiscArtPriority", conf.Server.DiscArtPriority+ case model.KindMediaFileArtwork:+ return "EnableMediaFileCoverArt", strconv.FormatBool(conf.Server.EnableMediaFileCoverArt)+ }+ return "", ""+}++type explainReport struct {+ kind model.Kind+ id string+ name string+ stored *model.ItemArtwork+ queued *model.ArtworkQueueItem+ agents string+ steps []artwork.TraceStep+ source string+ resolveErr error+}++func formatExplain(rep explainReport) string {+ var sb strings.Builder+ w := newTabWriter(&sb)+ explainable := artwork.Explainable(rep.kind)+ stateful := artwork.KeepsState(rep.kind)++ fmt.Fprintln(w, "Item")+ fmt.Fprintf(w, " Kind:\t%s (%s)\n", rep.kind, rep.kind.Prefix())+ fmt.Fprintf(w, " ID:\t%s\n", rep.id)+ fmt.Fprintf(w, " Name:\t%s\n", rep.name)++ fmt.Fprintln(w, "\nStored")+ switch {+ case !stateful:+ fmt.Fprintf(w, " (%s artwork is resolved on every request and never recorded)\n", rep.kind)+ case rep.stored == nil:+ fmt.Fprintln(w, " (no artwork state recorded)")+ default:+ fmt.Fprintf(w, " Source:\t%s\n", displaySource(rep.stored.Source))+ fmt.Fprintf(w, " Hash:\t%s\n", cmp.Or(rep.stored.Hash, "(absent)"))+ if rep.stored.SourcePath != "" {+ fmt.Fprintf(w, " Source path:\t%s\n", rep.stored.SourcePath)+ }+ fmt.Fprintf(w, " Attempted at:\t%s\n", formatTime(rep.stored.AttemptedAt))+ }++ fmt.Fprintln(w, "\nQueue")+ switch {+ case !stateful:+ fmt.Fprintln(w, " (never queued)")+ case rep.queued == nil:+ fmt.Fprintln(w, " (not queued)")+ default:+ fmt.Fprintf(w, " Priority:\t%s (%d)\n", priorityName(rep.queued.Priority), rep.queued.Priority)+ fmt.Fprintf(w, " Attempts:\t%d\n", rep.queued.Attempts)+ fmt.Fprintf(w, " Retry at:\t%s\n", formatTime(rep.queued.RetryAt))+ }++ fmt.Fprintln(w, "\nConfig")+ if setting, value := explainConfig(rep.kind); setting == "" {+ fmt.Fprintln(w, " (no artwork source configuration applies)")+ } else {+ fmt.Fprintf(w, " %s:\t%s\n", setting, value)+ if rep.agents != "" {+ fmt.Fprintf(w, " Agents:\t%s\n", rep.agents)+ }+ }++ fmt.Fprintln(w, "\nChain")+ if !explainable {+ fmt.Fprintf(w, " (%s artwork does not walk a priority chain)\n", rep.kind)+ } else {+ fmt.Fprintln(w, " CANDIDATE\tOUTCOME\tDETAIL")+ for _, s := range rep.steps {+ // A row with an empty last cell would end tabwriter's column block, breaking alignment.+ fmt.Fprintf(w, " %s\t%s\t%s\n", s.Candidate, s.Outcome, cmp.Or(s.Detail, "-"))+ }+ }++ fmt.Fprintln(w, "\nResult")+ switch {+ case rep.resolveErr != nil:+ fmt.Fprintf(w, " resolution failed: %s\n", rep.resolveErr)+ case !explainable:+ fmt.Fprintln(w, " not evaluated (no chain was walked; see Stored above)")+ default:+ fmt.Fprintf(w, " %s\n", explainResult(rep.source, rep.steps))+ }++ w.Flush()+ return sb.String()+}++func formatTime(t time.Time) string {+ if t.IsZero() {+ return "-"+ }+ return t.Format(time.RFC3339)+}++func runExplain(ctx context.Context, kind model.Kind, id string) {+ defer db.Init(ctx)()+ ds, ctx := getAdminContext(ctx)++ name, err := artworkItemName(ctx, ds, kind, id)+ if err != nil {+ log.Fatal(ctx, "Item not found", "kind", kind, "id", id, err)+ }+ rep := explainReport{kind: kind, id: id, name: name}+ if artwork.KeepsState(kind) {+ rep.stored, err = ds.Artwork(ctx).GetItemArtwork(kind, id, model.ImageTypePrimary)+ if err != nil && !errors.Is(err, model.ErrNotFound) {+ log.Fatal(ctx, "Failed to read artwork state", "kind", kind, "id", id, err)+ }+ rep.queued, err = ds.ArtworkQueue(ctx).Get(kind, id, model.ImageTypePrimary)+ if err != nil && !errors.Is(err, model.ErrNotFound) {+ log.Fatal(ctx, "Failed to read the artwork queue", "kind", kind, "id", id, err)+ }+ }++ if artwork.Explainable(kind) {+ if kind == model.KindArtistArtwork || kind == model.KindAlbumArtwork {+ rep.agents = explainAgents(conf.Server.Agents, availableImageAgents(ds, kind))+ }+ trace := &artwork.ChainTrace{}+ rep.source, rep.resolveErr = CreateArtworkResolver(trace, explainLive).Resolve(ctx, kind, id)+ rep.steps = trace.Steps()+ }++ fmt.Print(formatExplain(rep))+ // The steps taken before a failed walk are the diagnosis, so report them before exiting.+ if rep.resolveErr != nil {+ log.Fatal(ctx, "Failed to resolve artwork", "kind", kind, "id", id, rep.resolveErr)+ }+}++// artworkItemName looks the entity up under its own kind, so a mismatched kind/id pair is+// reported as not found instead of silently explaining another entity's artwork.+func artworkItemName(ctx context.Context, ds model.DataStore, kind model.Kind, id string) (string, error) {+ switch kind {+ case model.KindArtistArtwork:+ ar, err := ds.Artist(ctx).Get(id)+ if err != nil {+ return "", err+ }+ return ar.Name, nil+ case model.KindAlbumArtwork:+ al, err := ds.Album(ctx).Get(id)+ if err != nil {+ return "", err+ }+ return al.Name, nil+ case model.KindPlaylistArtwork:+ pls, err := ds.Playlist(ctx).Get(id)+ if err != nil {+ return "", err+ }+ return pls.Name, nil+ case model.KindRadioArtwork:+ rd, err := ds.Radio(ctx).Get(id)+ if err != nil {+ return "", err+ }+ return rd.Name, nil+ case model.KindMediaFileArtwork:+ mf, err := ds.MediaFile(ctx).Get(id)+ if err != nil {+ return "", err+ }+ return mf.Title, nil+ case model.KindDiscArtwork:+ return discArtworkName(ctx, ds, id)+ }+ return "", fmt.Errorf("unsupported kind %q", kind.Prefix())+}++func discArtworkName(ctx context.Context, ds model.DataStore, id string) (string, error) {+ albumID, discNumber, err := model.ParseDiscArtworkID(id)+ if err != nil {+ return "", err+ }+ al, err := ds.Album(ctx).Get(albumID)+ if err != nil {+ return "", err+ }+ name := fmt.Sprintf("%s (disc %d)", al.Name, discNumber)+ // The subtitle is itself a DiscArtPriority candidate, so name it where the chain can be read against it.+ if subtitle := strings.TrimSpace(al.Discs[discNumber]); subtitle != "" {+ name += ": " + subtitle+ }+ return name, nil+}diff --git a/cmd/artwork_test.go b/cmd/artwork_test.gonew file mode 100644index 000000000..949fdb42a--- /dev/null+++ b/cmd/artwork_test.go@@ -0,0 +1,899 @@+package cmd++import (+ "context"+ "errors"+ "io"+ "strings"+ "time"++ "github.com/navidrome/navidrome/conf"+ "github.com/navidrome/navidrome/conf/configtest"+ "github.com/navidrome/navidrome/consts"+ "github.com/navidrome/navidrome/core/artwork"+ "github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/tests"+ . "github.com/onsi/ginkgo/v2"+ . "github.com/onsi/gomega"+)++var _ = Describe("parseArtworkKind", func() {+ It("accepts a supported kind", func() {+ k, err := parseArtworkKind("ar", artwork.RecheckKinds)+ Expect(err).ToNot(HaveOccurred())+ Expect(k).To(Equal(model.KindArtistArtwork))+ })++ It("rejects an unknown kind and lists the valid ones", func() {+ _, err := parseArtworkKind("zz", artwork.RecheckKinds)+ Expect(err).To(HaveOccurred())+ Expect(err.Error()).To(ContainSubstring("ar"))+ Expect(err.Error()).To(ContainSubstring("al"))+ })++ It("rejects a known kind the command does not accept", func() {+ _, err := parseArtworkKind("mf", artwork.RecheckKinds)+ Expect(err).To(HaveOccurred())+ })++ DescribeTable("accepts the kinds each command supports",+ func(prefix string, valid []model.Kind) {+ _, err := parseArtworkKind(prefix, valid)+ Expect(err).ToNot(HaveOccurred())+ },+ Entry("explain reads disc artwork", "dc", explainKinds),+ Entry("explain reads media file artwork", "mf", explainKinds),+ // Disc artwork has no state to clear and the worker cannot resolve it, so refresh must not+ // accept it: the queue row would be rejected on every drain.+ Entry("refresh re-queues media files", "mf", artwork.RefreshableKinds),+ )++ It("rejects disc artwork for refresh", func() {+ _, err := parseArtworkKind("dc", artwork.RefreshableKinds)+ Expect(err).To(HaveOccurred())+ })+})++var _ = Describe("explainResult", func() {+ It("reports the winning source", func() {+ steps := []artwork.TraceStep{{Candidate: "folder", Outcome: "hit", Detail: "/music/a.jpg"}}+ Expect(explainResult("folder", steps)).To(ContainSubstring("resolved from folder"))+ })++ It("reports not resolved when every candidate was tried and missed", func() {+ steps := []artwork.TraceStep{+ {Candidate: "artist.*", Outcome: "miss"},+ {Candidate: "external:deezer", Outcome: "miss"},+ }+ Expect(explainResult("", steps)).To(Equal("not resolved"))+ })++ It("reports indeterminate when a local candidate exists but could not be read", func() {+ steps := []artwork.TraceStep{+ {Candidate: "cover.*", Outcome: "miss"},+ {Candidate: "embedded", Outcome: "unreadable"},+ }+ Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),+ "the worker retries an unreadable candidate instead of settling absent, so this is not a clean miss")+ })++ It("does not qualify a hit that an earlier unreadable candidate preceded", func() {+ // chainState.try stamps only the external error onto a hit and drops the local one, so the+ // worker settles this as found; warning about it would be a false alarm.+ steps := []artwork.TraceStep{+ {Candidate: "embedded", Outcome: "unreadable"},+ {Candidate: "cover.*", Outcome: "hit", Detail: "/music/cover.jpg"},+ }+ Expect(explainResult("folder", steps)).To(Equal("resolved from folder"))+ })++ It("reports indeterminate when an external lookup failed transiently", func() {+ steps := []artwork.TraceStep{+ {Candidate: "artist.*", Outcome: "miss"},+ {Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},+ }+ Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),+ "a failed network call is not evidence that the item has no artwork")+ })++ It("qualifies a win a skipped higher-priority external candidate could have taken", func() {+ steps := []artwork.TraceStep{+ {Candidate: "external:deezer", Outcome: "would-try"},+ {Candidate: "artist.*", Outcome: "hit", Detail: "/music/artist.jpg"},+ }+ res := explainResult("artist.*", steps)+ Expect(res).To(ContainSubstring("resolved from artist.*"))+ Expect(res).To(ContainSubstring("--live"),+ "offline, the winner is only the winner because the external tier was skipped")+ })++ It("does not qualify a win that no skipped candidate outranked", func() {+ steps := []artwork.TraceStep{+ {Candidate: "artist.*", Outcome: "hit"},+ {Candidate: "external:deezer", Outcome: "would-try"},+ }+ Expect(explainResult("artist.*", steps)).To(Equal("resolved from artist.*"))+ })++ It("reports indeterminate when external agents were never called", func() {+ steps := []artwork.TraceStep{+ {Candidate: "artist.*", Outcome: "miss"},+ {Candidate: "external:deezer", Outcome: "would-try"},+ }+ Expect(explainResult("", steps)).To(ContainSubstring("indeterminate"),+ "an offline run must not claim an item is unresolvable when external agents were skipped")+ })++ It("qualifies a win a failed higher-priority external lookup could have taken", func() {+ steps := []artwork.TraceStep{+ {Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},+ {Candidate: "artist.*", Outcome: "hit", Detail: "/music/artist.jpg"},+ }+ res := explainResult("artist.*", steps)+ Expect(res).To(ContainSubstring("resolved from artist.*"))+ Expect(res).To(ContainSubstring("indeterminate"),+ "the resolver serves this hit but retries later, so the winner is provisional")+ })++ It("does not qualify an external win that followed a failed external lookup", func() {+ steps := []artwork.TraceStep{+ {Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},+ {Candidate: "external:lastfm", Outcome: "hit", Detail: "http://img"},+ }+ Expect(explainResult("external:lastfm", steps)).To(Equal("resolved from external:lastfm"),+ "a later agent supplying the image discards the earlier error, so there is no retry to warn about")+ })++ It("does not qualify a win that outranked the failed external lookup", func() {+ steps := []artwork.TraceStep{+ {Candidate: "artist.*", Outcome: "hit"},+ {Candidate: "external:deezer", Outcome: "error", Detail: "context deadline exceeded"},+ }+ Expect(explainResult("artist.*", steps)).To(Equal("resolved from artist.*"))+ })+})++var _ = Describe("explainAgents", func() {+ It("accounts for every configured agent, marking the ones the CLI could not use", func() {+ out := explainAgents("artist-nfo-metadata,apple-music,deezer,lastfm", []string{"deezer"})+ for _, name := range []string{"artist-nfo-metadata", "apple-music", "deezer", "lastfm"} {+ Expect(out).To(ContainSubstring(name),+ "a configured agent missing from this line reads as if it had never been configured")+ }+ Expect(out).To(ContainSubstring("not available to the CLI"))+ })++ It("does not mark anything when every configured agent is available", func() {+ out := explainAgents("deezer, lastfm", []string{"lastfm", "deezer"})+ Expect(out).To(Equal("deezer, lastfm"))+ })++ It("reports an empty configuration as none, not as an unavailable agent", func() {+ Expect(explainAgents("", nil)).To(Equal("(none)"))+ })+})++var _ = Describe("formatExplain", func() {+ var rep explainReport++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.ArtistArtPriority = "external, artist.*"+ rep = explainReport{+ kind: model.KindArtistArtwork,+ id: "ar-1",+ name: "Radiohead",+ agents: "lastfm,spotify",+ steps: []artwork.TraceStep{+ {Candidate: "upload", Outcome: "skipped", Detail: "no uploaded image"},+ {Candidate: "external:deezer", Outcome: "would-try"},+ },+ source: "",+ }+ })++ It("reports the item, its config and the chain it walked", func() {+ out := formatExplain(rep)+ Expect(out).To(ContainSubstring("Radiohead"))+ Expect(out).To(ContainSubstring("ar-1"))+ Expect(out).To(ContainSubstring("ArtistArtPriority"))+ Expect(out).To(ContainSubstring("lastfm,spotify"))+ Expect(out).To(ContainSubstring("external:deezer"))+ Expect(out).To(ContainSubstring("would-try"))+ Expect(out).To(ContainSubstring("indeterminate"))+ })++ It("reports the absence of stored state and of a queue row", func() {+ out := formatExplain(rep)+ Expect(out).To(ContainSubstring("no artwork state recorded"))+ Expect(out).To(ContainSubstring("not queued"))+ })++ It("prints the stored state and the queue row when they exist", func() {+ attempted := time.Date(2026, 8, 13, 10, 0, 0, 0, time.UTC)+ rep.stored = &model.ItemArtwork{Source: "folder", Hash: "abc123",+ SourcePath: "/music/cover.jpg", AttemptedAt: attempted}+ rep.queued = &model.ArtworkQueueItem{Priority: model.ArtworkPriorityScan, Attempts: 2,+ RetryAt: attempted.Add(time.Hour)}+ rep.source = "folder"++ out := formatExplain(rep)+ Expect(out).To(ContainSubstring("abc123"))+ Expect(out).To(ContainSubstring("/music/cover.jpg"))+ Expect(out).To(ContainSubstring("2026-08-13T10:00:00Z"))+ Expect(out).To(ContainSubstring("scan (50)"), "a bare 50 makes the operator look the priority up")+ Expect(out).To(ContainSubstring("resolved from folder"))+ })++ It("marks a known-absent stored state instead of printing an empty hash", func() {+ rep.stored = &model.ItemArtwork{AttemptedAt: time.Now()}+ Expect(formatExplain(rep)).To(ContainSubstring("absent"))+ })++ It("reports a failed walk as failed, not as unresolved", func() {+ rep.resolveErr = errors.New("no such directory")++ out := formatExplain(rep)+ Expect(out).To(ContainSubstring("resolution failed: no such directory"))+ Expect(out).ToNot(ContainSubstring("indeterminate"))+ Expect(out).To(ContainSubstring("would-try"), "the steps taken before the failure still print")+ })++ It("says a kind that does not walk a chain has no chain, without an empty table", func() {+ conf.Server.CoverArtPriority = "cover.*, embedded"+ rep.kind = model.KindPlaylistArtwork+ rep.steps = nil+ rep.agents = ""++ out := formatExplain(rep)+ Expect(out).To(ContainSubstring("does not walk a priority chain"))+ Expect(out).ToNot(ContainSubstring("CANDIDATE"),+ "an empty chain table reads as 'nothing was tried', which is false")+ Expect(out).ToNot(ContainSubstring("not resolved"),+ "nothing was resolved because nothing was attempted")+ Expect(out).ToNot(ContainSubstring("CoverArtPriority"),+ "the priority chain config does not govern this kind")+ })++ It("says disc artwork keeps no state instead of reporting it as unresolved state", func() {+ conf.Server.DiscArtPriority = "cover.jpg, embedded"+ rep = explainReport{+ kind: model.KindDiscArtwork, id: "al-1:2", name: "OK Computer (disc 2)",+ steps: []artwork.TraceStep{{Candidate: "cover.jpg", Outcome: "hit", Detail: "/music/cover.jpg"}},+ source: "folder",+ }++ out := formatExplain(rep)+ Expect(out).To(ContainSubstring("never recorded"))+ Expect(out).To(ContainSubstring("never queued"))+ Expect(out).ToNot(ContainSubstring("no artwork state recorded"),+ "a missing row would read as a lookup that failed, when disc artwork has no row by design")+ Expect(out).To(ContainSubstring("DiscArtPriority"))+ Expect(out).ToNot(ContainSubstring("Agents:"), "disc artwork never asks an agent")+ Expect(out).To(ContainSubstring("resolved from folder"))+ })++ It("reports the setting that governs media file artwork", func() {+ conf.Server.EnableMediaFileCoverArt = false+ rep = explainReport{+ kind: model.KindMediaFileArtwork, id: "mf-1", name: "Airbag",+ steps: []artwork.TraceStep{+ {Candidate: "embedded", Outcome: "skipped", Detail: "EnableMediaFileCoverArt is off"},+ },+ }++ out := formatExplain(rep)+ Expect(out).To(ContainSubstring("EnableMediaFileCoverArt"))+ Expect(out).To(ContainSubstring("false"))+ Expect(out).To(ContainSubstring("not resolved"))+ Expect(out).To(ContainSubstring("no artwork state recorded"), "media files do keep state")+ })+})++var _ = Describe("explainConfig", func() {+ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.DiscArtPriority = "cover.jpg"+ conf.Server.EnableMediaFileCoverArt = true+ })++ DescribeTable("names the setting that decides where a kind's artwork comes from",+ func(kind model.Kind, setting, value string) {+ gotSetting, gotValue := explainConfig(kind)+ Expect(gotSetting).To(Equal(setting))+ Expect(gotValue).To(Equal(value))+ },+ Entry("disc", model.KindDiscArtwork, "DiscArtPriority", "cover.jpg"),+ Entry("media file", model.KindMediaFileArtwork, "EnableMediaFileCoverArt", "true"),+ Entry("playlist has none", model.KindPlaylistArtwork, "", ""),+ )+})++var _ = Describe("discArtworkName", func() {+ var ds *tests.MockDataStore++ BeforeEach(func() {+ albumRepo := tests.CreateMockAlbumRepo()+ albumRepo.SetData(model.Albums{{ID: "al-1", Name: "Sandinista!", Discs: model.Discs{2: "Side Three"}}})+ ds = &tests.MockDataStore{MockedAlbum: albumRepo}+ })++ It("names the album, the disc and its subtitle", func() {+ name, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1:2")+ Expect(err).ToNot(HaveOccurred())+ Expect(name).To(Equal("Sandinista! (disc 2): Side Three"))+ })++ It("omits the subtitle when the disc has none", func() {+ name, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1:1")+ Expect(err).ToNot(HaveOccurred())+ Expect(name).To(Equal("Sandinista! (disc 1)"))+ })++ It("rejects an id that is not <albumID>:<disc>", func() {+ _, err := artworkItemName(context.Background(), ds, model.KindDiscArtwork, "al-1")+ Expect(err).To(HaveOccurred())+ })+})++var _ = Describe("artwork refresh command", func() {+ It("requires at least a kind and one id", func() {+ Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar"})).To(HaveOccurred())+ Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar", "id1"})).ToNot(HaveOccurred())+ Expect(artworkRefreshCmd.Args(artworkRefreshCmd, []string{"ar", "id1", "id2"})).ToNot(HaveOccurred())+ })+})++var _ = Describe("artwork reprocess selection", func() {+ It("errors when no selector is given", func() {+ _, err := selectedKinds(nil, nil, false)+ Expect(err).To(HaveOccurred())+ Expect(err.Error()).To(ContainSubstring("--all"))+ })++ It("returns every kind for --all", func() {+ ks, err := selectedKinds(nil, nil, true)+ Expect(err).ToNot(HaveOccurred())+ Expect(ks).To(ConsistOf(artwork.RecheckKinds))+ })++ It("returns every kind for a source filter given without a kind", func() {+ ks, err := selectedKinds(nil, []string{"folder"}, false)+ Expect(err).ToNot(HaveOccurred())+ Expect(ks).To(ConsistOf(artwork.RecheckKinds), "--source alone is already a complete selection")+ })++ It("returns only the named kinds", func() {+ ks, err := selectedKinds([]string{"ar"}, nil, false)+ Expect(err).ToNot(HaveOccurred())+ Expect(ks).To(Equal([]model.Kind{model.KindArtistArtwork}))+ })++ It("keeps a named kind selection alongside a source filter", func() {+ ks, err := selectedKinds([]string{"ar"}, []string{"folder"}, false)+ Expect(err).ToNot(HaveOccurred())+ Expect(ks).To(Equal([]model.Kind{model.KindArtistArtwork}))+ })++ It("rejects an unknown kind", func() {+ _, err := selectedKinds([]string{"zz"}, nil, false)+ Expect(err).To(HaveOccurred())+ })++ It("counts a repeated kind once", func() {+ ks, err := selectedKinds([]string{"ar", "ar"}, nil, false)+ Expect(err).ToNot(HaveOccurred())+ Expect(ks).To(Equal([]model.Kind{model.KindArtistArtwork}))+ })+})++var _ = Describe("explain/reprocess source round trip", func() {+ ctx := context.Background()++ // storedSource reads back the Source line explain printed, as an operator would copy it.+ storedSource := func(out string) string {+ GinkgoHelper()+ for line := range strings.SplitSeq(out, "\n") {+ if after, ok := strings.CutPrefix(strings.TrimSpace(line), "Source:"); ok {+ return strings.TrimSpace(after)+ }+ }+ Fail("explain printed no Source line")+ return ""+ }++ It("names the absent state as reprocess --source accepts it", func() {+ ds := &tests.MockDataStore{}+ art := ds.Artwork(ctx).(*tests.MockArtworkRepo)+ Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: model.KindArtistArtwork.Prefix(),+ ItemID: "ar-1", ImageType: model.ImageTypePrimary})).To(Succeed())++ shown := storedSource(formatExplain(explainReport{kind: model.KindArtistArtwork, id: "ar-1",+ stored: &model.ItemArtwork{AttemptedAt: time.Now()}}))++ q := ds.ArtworkQueue(ctx)+ Expect(validateSources(q, repositorySources([]string{shown}))).To(Succeed(),+ "explain's spelling of a source must be pasteable into --source")+ Expect(validateSources(q, repositorySources([]string{"(" + shown + ")"}))).ToNot(Succeed(),+ "a parenthesised name would be rejected, so explain must not print one")+ })+})++var _ = Describe("repositorySources", func() {+ It("maps the user-facing absent name onto the stored empty source", func() {+ Expect(repositorySources([]string{"absent", "folder"})).To(Equal([]string{"", "folder"}))+ })++ It("keeps an empty selection empty, meaning every source", func() {+ Expect(repositorySources(nil)).To(BeEmpty())+ })+})++var _ = Describe("promptConfirm", func() {+ var out strings.Builder++ BeforeEach(func() { out.Reset() })++ It("states the external cost and accepts an explicit yes", func() {+ Expect(promptConfirm(strings.NewReader("y\n"))(&out, 42, 7)).To(BeTrue())+ Expect(out.String()).To(ContainSubstring("re-resolve 42 items"))+ Expect(out.String()).To(ContainSubstring("External lookups: ~7 estimated"))+ })++ It("defaults to no on anything else", func() {+ Expect(promptConfirm(strings.NewReader("\n"))(&out, 1, 1)).To(BeFalse())+ Expect(promptConfirm(strings.NewReader("nope\n"))(&out, 1, 1)).To(BeFalse())+ Expect(promptConfirm(strings.NewReader(""))(&out, 1, 1)).To(BeFalse())+ })++ It("drops the external clause when no lookup will be made", func() {+ Expect(promptConfirm(strings.NewReader("y\n"))(&out, 3, 0)).To(BeTrue())+ Expect(out.String()).To(ContainSubstring("re-resolve 3 items."))+ Expect(out.String()).ToNot(ContainSubstring("External lookups"))+ })+})++var _ = Describe("reprocessConfirm", func() {+ var out strings.Builder++ BeforeEach(func() { out.Reset() })++ It("prompts when --yes was not given", func() {+ Expect(reprocessConfirm(false, strings.NewReader("n\n"))(&out, 5, 5)).To(BeFalse())+ Expect(out.String()).To(ContainSubstring("Continue?"))+ })++ It("bypasses the prompt only for --yes", func() {+ Expect(reprocessConfirm(true, strings.NewReader(""))(&out, 5, 5)).To(BeTrue())+ Expect(out.String()).To(BeEmpty(), "--yes must not print a prompt it never reads")+ })+})++var _ = Describe("reprocessArtwork", func() {+ var ds *tests.MockDataStore+ var art *tests.MockArtworkRepo+ var queue *tests.MockArtworkQueueRepo+ var out strings.Builder+ var imageAgents artwork.ImageAgentCount+ ctx := context.Background()+ kinds := []model.Kind{model.KindArtistArtwork, model.KindAlbumArtwork}+ accept := func(io.Writer, int64, int64) bool { return true }+ decline := func(io.Writer, int64, int64) bool { return false }++ put := func(kind model.Kind, id, source string) {+ Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,+ ImageType: model.ImageTypePrimary, Hash: "h" + id, Source: source})).To(Succeed())+ }++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.CoverArtPriority = "cover.*, external"+ conf.Server.ArtistArtPriority = "artist.*, external"+ conf.Server.EnableM3UExternalAlbumArt = false+ imageAgents = artwork.ImageAgentCount{Artist: 1, Album: 1}+ ds = &tests.MockDataStore{}+ art = ds.Artwork(ctx).(*tests.MockArtworkRepo)+ queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)+ out.Reset()+ put(model.KindArtistArtwork, "ar-1", "external:deezer")+ put(model.KindArtistArtwork, "ar-2", "")+ put(model.KindAlbumArtwork, "al-1", "external:deezer")+ put(model.KindAlbumArtwork, "al-2", "folder")+ })++ It("previews the per-kind breakdown and queues nothing on a dry run", func() {+ Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, true, accept, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("external:deezer"))+ Expect(out.String()).To(ContainSubstring("artist"))+ Expect(out.String()).To(ContainSubstring("album"))+ Expect(out.String()).To(ContainSubstring("TOTAL"))+ Expect(out.String()).To(ContainSubstring("Dry run"))+ Expect(queue.Count()).To(BeZero())+ })++ It("queues nothing when the operator declines", func() {+ Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, false, decline, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("Aborted"))+ Expect(queue.Count()).To(BeZero())+ })++ It("queues the matching items at recheck priority, leaving their artwork state alone", func() {+ Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, false, accept, &out)).To(Succeed())++ Expect(queue.Count()).To(Equal(int64(2)))+ queued, err := queue.Get(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)+ Expect(err).ToNot(HaveOccurred())+ Expect(queued.Priority).To(Equal(model.ArtworkPriorityRecheck))+ _, err = queue.Get(model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)+ Expect(err).To(MatchError(model.ErrNotFound), "a non-matching source must not be queued")++ stored, err := art.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)+ Expect(err).ToNot(HaveOccurred())+ Expect(stored.Hash).To(Equal("hal-1"), "bulk reprocessing must not blank the current artwork")+ })++ It("targets the absent state", func() {+ Expect(reprocessArtwork(ctx, ds, kinds, []string{""}, imageAgents, false, accept, &out)).To(Succeed())++ Expect(queue.Count()).To(Equal(int64(1)))+ _, err := queue.Get(model.KindArtistArtwork, "ar-2", model.ImageTypePrimary)+ Expect(err).ToNot(HaveOccurred())+ })++ It("reports matched and queued separately when part of the set is already queued", func() {+ Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-1",+ ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBump})).To(Succeed())++ Expect(reprocessArtwork(ctx, ds, kinds, []string{"external:deezer"}, imageAgents, false, accept, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("Queued 1 of 2 matched items"))+ Expect(out.String()).To(ContainSubstring("Already queued, left unchanged: 1"))+ queued, err := queue.Get(model.KindArtistArtwork, "ar-1", model.ImageTypePrimary)+ Expect(err).ToNot(HaveOccurred())+ Expect(queued.Priority).To(Equal(model.ArtworkPriorityBump),+ "an already-queued row keeps its priority and backoff")+ })++ It("stops at a selection that matches nothing instead of prompting", func() {+ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindRadioArtwork}, nil, imageAgents, false,+ func(io.Writer, int64, int64) bool {+ Fail("must not prompt when there is nothing to queue")+ return true+ }, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("Nothing"))+ Expect(queue.Count()).To(BeZero())+ })++ It("reports an empty selection as a dry run when one was asked for", func() {+ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindRadioArtwork}, nil, imageAgents, true, accept, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("Nothing matches"))+ Expect(out.String()).To(ContainSubstring("Dry run"))+ })++ It("shows the external estimate on a dry run, which never reaches the prompt", func() {+ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindAlbumArtwork}, nil, imageAgents, true, accept, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("External lookups: ~2 estimated"))+ })++ It("bills every agent per item, not one lookup per item", func() {+ imageAgents = artwork.ImageAgentCount{Artist: 2, Album: 3}+ var external int64+ capture := func(_ io.Writer, _, e int64) bool { external = e; return false }++ Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, false, capture, &out)).To(Succeed())++ Expect(external).To(Equal(int64(2*2+2*3)), "2 artists at 2 agents plus 2 albums at 3 agents")+ Expect(out.String()).To(ContainSubstring("External lookups: ~10 estimated"))+ })++ It("names the estimate's blind spots instead of claiming a bound it cannot hold", func() {+ Expect(reprocessArtwork(ctx, ds, kinds, nil, imageAgents, true, accept, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("plugin agents not counted"))+ Expect(out.String()).To(ContainSubstring("local hits may need fewer"))+ Expect(out.String()).ToNot(ContainSubstring("up to"), "plugin agents make any ceiling false")+ Expect(out.String()).ToNot(ContainSubstring("at least"), "a local hit makes any floor false")+ })++ It("says so when the selection needs no external lookup", func() {+ conf.Server.CoverArtPriority = "cover.*"+ put(model.KindPlaylistArtwork, "pl-1", "playlist")++ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, imageAgents, true, accept, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("External lookups: none"))+ })++ It("counts playlists as external cost when the m3u image fetch is enabled", func() {+ conf.Server.CoverArtPriority = "cover.*"+ conf.Server.EnableM3UExternalAlbumArt = true+ put(model.KindPlaylistArtwork, "pl-1", "playlist")+ var external int64+ capture := func(_ io.Writer, _, e int64) bool { external = e; return false }++ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, imageAgents, false, capture, &out)).To(Succeed())++ Expect(external).To(Equal(int64(1)))+ Expect(out.String()).To(ContainSubstring("External lookups: ~1 estimated"))+ })++ It("bills a playlist for every album its grid samples, at every agent", func() {+ imageAgents = artwork.ImageAgentCount{Album: 3}+ put(model.KindPlaylistArtwork, "pl-1", "playlist")+ var external int64+ capture := func(_ io.Writer, _, e int64) bool { external = e; return false }++ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindPlaylistArtwork}, nil, imageAgents, false, capture, &out)).To(Succeed())++ Expect(external).To(Equal(int64(artwork.PlaylistGridSamples*3)),+ "one playlist samples 4 albums, each walking all 3 album agents")+ })++ It("counts only the kinds that call an external agent as external cost", func() {+ put(model.KindRadioArtwork, "ra-1", "upload")+ var total, external int64+ capture := func(_ io.Writer, t, e int64) bool { total, external = t, e; return false }++ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindAlbumArtwork, model.KindRadioArtwork},+ nil, imageAgents, false, capture, &out)).To(Succeed())++ Expect(total).To(Equal(int64(3)))+ Expect(external).To(Equal(int64(2)), "radio artwork never reaches an external agent")+ })++ It("rejects an unknown source and names the ones in use", func() {+ err := reprocessArtwork(ctx, ds, kinds, []string{"externa:deezer"}, imageAgents, true, accept, &out)++ Expect(err).To(HaveOccurred())+ Expect(err.Error()).To(ContainSubstring("externa:deezer"))+ Expect(err.Error()).To(ContainSubstring("external:deezer"))+ Expect(err.Error()).To(ContainSubstring("folder"))+ Expect(err.Error()).To(ContainSubstring("absent"), "the empty source prints under its user-facing name")+ Expect(queue.Count()).To(BeZero())+ })++ It("accepts the absent filter with nothing absent, still rejecting a typo", func() {+ put(model.KindArtistArtwork, "ar-2", "folder")++ Expect(reprocessArtwork(ctx, ds, kinds, repositorySources([]string{absentSource}),+ imageAgents, false, accept, &out)).To(Succeed(),+ "a reserved source must stay valid once the library has none of it")+ Expect(out.String()).To(ContainSubstring("Nothing matches"))+ Expect(queue.Count()).To(BeZero())++ Expect(reprocessArtwork(ctx, ds, kinds, repositorySources([]string{"absnt"}),+ imageAgents, true, accept, &out)).ToNot(Succeed(), "a typo must still be rejected")+ })++ It("accepts a source another kind uses, letting the empty selection report itself", func() {+ Expect(reprocessArtwork(ctx, ds, []model.Kind{model.KindArtistArtwork}, []string{"folder"},+ imageAgents, false, decline, &out)).To(Succeed())++ Expect(out.String()).To(ContainSubstring("Nothing matches"),+ "a well-formed filter must not be reported as a typo because of the kinds selected")+ Expect(queue.Count()).To(BeZero())+ })+})++var _ = Describe("artwork status command", func() {+ It("takes no arguments", func() {+ Expect(artworkStatusCmd.Args(artworkStatusCmd, []string{})).ToNot(HaveOccurred())+ Expect(artworkStatusCmd.Args(artworkStatusCmd, []string{"x"})).To(HaveOccurred())+ })+})++var _ = Describe("collectStatus", func() {+ var ds *tests.MockDataStore+ var art *tests.MockArtworkRepo+ var queue *tests.MockArtworkQueueRepo+ ctx := context.Background()++ BeforeEach(func() {+ ds = &tests.MockDataStore{}+ art = ds.Artwork(ctx).(*tests.MockArtworkRepo)+ queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)+ put := func(kind model.Kind, id, source, hash string, attempted time.Time) {+ Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: kind.Prefix(), ItemID: id,+ ImageType: model.ImageTypePrimary, Source: source, Hash: hash, AttemptedAt: attempted})).To(Succeed())+ }+ put(model.KindArtistArtwork, "ar-1", "external:deezer", "h1", time.Now())+ put(model.KindArtistArtwork, "ar-2", "", "", time.Now().Add(-48*time.Hour))+ put(model.KindArtistArtwork, "ar-3", "", "", time.Now())+ put(model.KindAlbumArtwork, "al-1", "folder", "h2", time.Now())+ Expect(queue.Enqueue(model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar-9",+ ImageType: model.ImageTypePrimary, Priority: model.ArtworkPriorityBackfill})).To(Succeed())+ })++ It("reports the queue, the source distribution and the absent ages", func() {+ rep, err := collectStatus(ctx, ds)+ Expect(err).ToNot(HaveOccurred())++ Expect(rep.queue).To(ConsistOf(model.ArtworkQueueStat{ItemKind: "ar",+ Priority: model.ArtworkPriorityBackfill, Count: 1}))+ Expect(rep.sources).To(ContainElements(+ sourceCount{kind: model.KindArtistArtwork, source: "external:deezer", count: 1},+ sourceCount{kind: model.KindArtistArtwork, source: "", count: 2},+ sourceCount{kind: model.KindAlbumArtwork, source: "folder", count: 1},+ ))+ Expect(rep.absent).To(ContainElement(absentCount{kind: model.KindArtistArtwork,+ ArtworkAbsentStat: model.ArtworkAbsentStat{Total: 2, Stale: 1}}))+ })++ It("compares the stored fingerprint against the current one", func() {+ Expect(ds.Property(ctx).Put(consts.ArtConfFingerprintPropertyKey, "old-fingerprint")).To(Succeed())++ rep, err := collectStatus(ctx, ds)+ Expect(err).ToNot(HaveOccurred())+ Expect(rep.stored).To(Equal("old-fingerprint"))+ Expect(rep.current).To(Equal(artwork.ConfigFingerprint()),+ "the CLI must report the value backfill itself compares")+ })++ It("queues nothing", func() {+ _, err := collectStatus(ctx, ds)+ Expect(err).ToNot(HaveOccurred())+ Expect(queue.Count()).To(Equal(int64(1)), "status must not enqueue anything")+ })+})++var _ = Describe("formatStatus", func() {+ var rep statusReport++ BeforeEach(func() {+ rep = statusReport{+ queue: []model.ArtworkQueueStat{+ {ItemKind: "ar", Priority: model.ArtworkPriorityBackfill, Count: 2},+ {ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1},+ },+ sources: []sourceCount{+ {kind: model.KindArtistArtwork, source: "external:deezer", count: 5},+ {kind: model.KindArtistArtwork, source: "", count: 2},+ },+ absent: []absentCount{+ {kind: model.KindArtistArtwork, ArtworkAbsentStat: model.ArtworkAbsentStat{Total: 2, Stale: 1}},+ },+ inputs: []artwork.FingerprintInput{{Name: "Agents", Value: "deezer,lastfm"}},+ stored: "abc123",+ current: "abc123",+ }+ })++ // block isolates one section, so an assertion cannot be satisfied by a coincidence elsewhere.+ block := func(out, header string) string {+ GinkgoHelper()+ _, after, found := strings.Cut(out, header+"\n")+ Expect(found).To(BeTrue(), "the %q block must be printed", header)+ body, _, _ := strings.Cut(after, "\n\n")+ return body+ }++ It("names the kind and the priority of every queued row", func() {+ queue := block(formatStatus(rep), "Queue")+ Expect(queue).To(MatchRegexp(`artist\s+backfill\s+2`))+ Expect(queue).To(MatchRegexp(`album\s+scan\s+1`))+ })++ It("totals the queue", func() {+ Expect(block(formatStatus(rep), "Queue")).To(MatchRegexp(`TOTAL\s+3`))+ })++ It("counts each source, naming the empty one absent", func() {+ sources := block(formatStatus(rep), "Sources")+ Expect(sources).To(MatchRegexp(`artist\s+external:deezer\s+5`))+ Expect(sources).To(MatchRegexp(`artist\s+absent\s+2`))+ })++ It("prints the absent total and how many are due for recheck", func() {+ absent := block(formatStatus(rep), "Absent (resolved, no image found)")+ Expect(absent).To(MatchRegexp(`artist\s+2\s+1`))+ })++ It("states the recheck window the absent counts are bucketed against", func() {+ Expect(formatStatus(rep)).To(ContainSubstring("24h"))+ })++ It("leads with the queued backlog, which is the finding, not with the fingerprint verdict", func() {+ out := block(formatStatus(rep), "Backfill")+ Expect(out).To(MatchRegexp(`State:\s+backfill running: 2 items queued`),+ "an operator scanning for trouble must not read 'up to date' while 2 items churn")+ Expect(out).To(ContainSubstring("fingerprint up to date"))+ })++ It("keeps the re-enqueue warning while a backfill is already running", func() {+ rep.stored = "older"++ out := block(formatStatus(rep), "Backfill")+ Expect(out).To(MatchRegexp(`State:\s+backfill running: 2 items queued`))+ Expect(out).To(ContainSubstring("re-enqueued"),+ "the stored fingerprint is still stale, so a second full re-enqueue is pending on top of this one")+ })++ It("reports up to date only once the backfill has drained", func() {+ rep.queue = []model.ArtworkQueueStat{{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1}}++ Expect(block(formatStatus(rep), "Backfill")).To(MatchRegexp(`State:\s+up to date`))+ })++ It("echoes the config inputs a fingerprint change would have come from", func() {+ out := block(formatStatus(rep), "Backfill")+ Expect(out).To(MatchRegexp(`Agents:\s+deezer,lastfm`))+ Expect(out).To(ContainSubstring("abc123"), "the fingerprint values themselves must be printed")+ })++ It("reports a changed fingerprint as a pending re-resolve of everything", func() {+ rep.stored = "older"+ rep.queue = nil++ out := formatStatus(rep)+ Expect(out).To(ContainSubstring("fingerprint changed"))+ Expect(out).ToNot(ContainSubstring("up to date"))+ })++ It("reports a never-recorded fingerprint without printing an empty value", func() {+ rep.stored = ""++ out := formatStatus(rep)+ Expect(out).To(ContainSubstring("(none)"))+ Expect(out).To(ContainSubstring("fingerprint changed"))+ })++ It("says the queue is empty instead of printing a headless table", func() {+ rep.queue = nil++ out := formatStatus(rep)+ Expect(out).To(ContainSubstring("empty"))+ Expect(out).ToNot(ContainSubstring("PRIORITY"))+ })+})++var _ = Describe("refreshItems", func() {+ var ds *tests.MockDataStore+ var queue *tests.MockArtworkQueueRepo+ var art *tests.MockArtworkRepo+ var out strings.Builder+ ctx := context.Background()++ BeforeEach(func() {+ albums := tests.CreateMockAlbumRepo()+ albums.SetData(model.Albums{{ID: "al-1"}, {ID: "al-3"}})+ ds = &tests.MockDataStore{MockedAlbum: albums}+ art = ds.Artwork(ctx).(*tests.MockArtworkRepo)+ queue = ds.ArtworkQueue(ctx).(*tests.MockArtworkQueueRepo)+ out.Reset()+ })++ It("clears the stored state and queues each id at Bump priority", func() {+ Expect(art.PutItemArtwork(&model.ItemArtwork{ItemKind: model.KindAlbumArtwork.Prefix(),+ ItemID: "al-1", ImageType: model.ImageTypePrimary, Hash: "abc123"})).To(Succeed())++ Expect(refreshItems(ctx, ds, model.KindAlbumArtwork, []string{"al-1", "al-3"}, &out)).To(BeZero())++ _, err := art.GetItemArtwork(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)+ Expect(err).To(MatchError(model.ErrNotFound))+ queued, err := queue.Get(model.KindAlbumArtwork, "al-1", model.ImageTypePrimary)+ Expect(err).ToNot(HaveOccurred())+ Expect(queued.Priority).To(Equal(model.ArtworkPriorityBump))+ Expect(out.String()).To(Equal("al/al-1: queued\nal/al-3: queued\n"))+ })++ It("skips an id that does not exist instead of queuing it", func() {+ Expect(refreshItems(ctx, ds, model.KindAlbumArtwork, []string{"al-2"}, &out)).To(Equal(1))++ _, err := queue.Get(model.KindAlbumArtwork, "al-2", model.ImageTypePrimary)+ Expect(err).To(MatchError(model.ErrNotFound), "a typo must not leave an orphan queue row")+ Expect(out.String()).To(BeEmpty())+ })++ It("continues past a failing id and counts the failures", func() {+ Expect(refreshItems(ctx, ds, model.KindAlbumArtwork,+ []string{"al-1", "al-2", "al-3"}, &out)).To(Equal(1))++ Expect(out.String()).To(Equal("al/al-1: queued\nal/al-3: queued\n"),+ "the ids after a failure are still refreshed")+ })+})diff --git a/cmd/plugin.go b/cmd/plugin.goindex 6cce8ea5f..ded28e969 100644--- a/cmd/plugin.go+++ b/cmd/plugin.go@@ -9,7 +9,6 @@ import ("os""strconv""strings"- "text/tabwriter""time""github.com/navidrome/navidrome/conf"@@ -314,7 +313,7 @@ func formatPluginList(list model.Plugins, format string) (string, error) {return sb.String(), w.Error()case "table":var sb strings.Builder- w := tabwriter.NewWriter(&sb, 0, 4, 2, ' ', 0)+ w := newTabWriter(&sb)fmt.Fprintln(w, "ID\tNAME\tVERSION\tENABLED\tLAST ERROR")for _, p := range list {name, version := manifestSummary(p)diff --git a/cmd/utils.go b/cmd/utils.goindex 81d646cf1..74da51828 100644--- a/cmd/utils.go+++ b/cmd/utils.go@@ -4,6 +4,8 @@ import ("context""errors""fmt"+ "io"+ "text/tabwriter""github.com/navidrome/navidrome/core/auth""github.com/navidrome/navidrome/db"@@ -13,6 +15,11 @@ import ("github.com/navidrome/navidrome/persistence")+// newTabWriter keeps every CLI table on the same column settings.+func newTabWriter(out io.Writer) *tabwriter.Writer {+ return tabwriter.NewWriter(out, 0, 4, 2, ' ', 0)+}+func getAdminContext(ctx context.Context) (model.DataStore, context.Context) {sqlDB := db.Db()ds := persistence.New(sqlDB)diff --git a/cmd/wire_gen.go b/cmd/wire_gen.goindex 4bdd48422..49a99f8ca 100644--- a/cmd/wire_gen.go+++ b/cmd/wire_gen.go@@ -223,6 +223,18 @@ func CreateArtworkWorker() *artwork.Worker {return worker}+func CreateArtworkResolver(trace *artwork.ChainTrace, live bool) *artwork.TracingResolver {+ sqlDB := db.Db()+ dataStore := persistence.New(sqlDB)+ broker := events.GetBroker()+ metricsMetrics := metrics.GetPrometheusInstance(dataStore)+ manager := plugins.GetManager(dataStore, broker, metricsMetrics)+ agentsAgents := agents.GetAgents(dataStore, manager)+ fFmpeg := ffmpeg.New()+ tracingResolver := artwork.NewTracingResolver(dataStore, agentsAgents, fFmpeg, trace, live)+ return tracingResolver+}+func getPluginManager() *plugins.Manager {sqlDB := db.Db()dataStore := persistence.New(sqlDB)diff --git a/cmd/wire_injectors.go b/cmd/wire_injectors.goindex ae24b61fa..8bc404fb1 100644--- a/cmd/wire_injectors.go+++ b/cmd/wire_injectors.go@@ -144,6 +144,13 @@ func CreateArtworkWorker() *artwork.Worker {))}+func CreateArtworkResolver(trace *artwork.ChainTrace, live bool) *artwork.TracingResolver {+ panic(wire.Build(+ allProviders,+ artwork.NewTracingResolver,+ ))+}+func getPluginManager() *plugins.Manager {panic(wire.Build(allProviders,diff --git a/core/artwork/agent_images.go b/core/artwork/agent_images.goindex c7032b62b..a6f746959 100644--- a/core/artwork/agent_images.go+++ b/core/artwork/agent_images.go@@ -47,10 +47,17 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar// Synthetic artists would otherwise get an unrelated agent result assigned to them.switch ar.ID {case consts.UnknownArtistID, consts.VariousArtistsID:+ traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped, Detail: "synthetic artist"})return nil, "", false}name := externalName(ar.Name)- for _, a := range ag.ArtistImageAgents() {+ imageAgents := ag.ArtistImageAgents()+ if len(imageAgents) == 0 {+ traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped,+ Detail: "no enabled agent provides artist images"})+ return nil, "", false+ }+ for _, a := range imageAgents {reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {imgs, err := a.Retriever.GetArtistImages(ctx, ar.ID, name, ar.MbzArtistID)if err != nil {@@ -76,7 +83,13 @@ func fetchArtistImage(ctx context.Context, ag *agents.Agents, gate gateFunc, ar// fetchAlbumImage is the album counterpart of fetchArtistImage.func fetchAlbumImage(ctx context.Context, ag *agents.Agents, gate gateFunc, al model.Album) (r io.ReadCloser, agentName string, extErr bool) {name, artist := externalName(al.Name), externalName(al.AlbumArtist)- for _, a := range ag.AlbumImageAgents() {+ imageAgents := ag.AlbumImageAgents()+ if len(imageAgents) == 0 {+ traceFrom(ctx).add(TraceStep{Candidate: externalCandidate, Outcome: OutcomeSkipped,+ Detail: "no enabled agent provides album images"})+ return nil, "", false+ }+ for _, a := range imageAgents {reader, _, err := gate(a.Name, func() (io.ReadCloser, string, error) {imgs, err := a.Retriever.GetAlbumImages(ctx, name, artist, al.MbzAlbumID)if err != nil {diff --git a/core/artwork/agent_images_test.go b/core/artwork/agent_images_test.goindex 716245c93..60a34352d 100644--- a/core/artwork/agent_images_test.go+++ b/core/artwork/agent_images_test.go@@ -173,6 +173,30 @@ var _ = Describe("agent images", func() {Expect(a.artistCalls).To(Equal(0), "synthetic artists never reach the agents")})+ It("records a skipped external candidate when no agent provides artist images", func() {+ ag := imageAgents()+ t := &ChainTrace{}++ r, _, extErr := fetchArtistImage(withTrace(ctx, t), ag, passthroughGate, model.Artist{ID: "ar1"})+ Expect(r).To(BeNil())+ Expect(extErr).To(BeFalse())+ Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "external", Outcome: OutcomeSkipped,+ Detail: "no enabled agent provides artist images"}}),+ "a configured external token must never be silently absent from the chain")+ })++ It("records a skipped external candidate for synthetic artists", func() {+ a := &fakeImageAgent{name: "agentA", imgs: []agents.ExternalImage{img("/a", 100)}}+ ag := imageAgents(a)+ t := &ChainTrace{}++ _, _, _ = fetchArtistImage(withTrace(ctx, t), ag, passthroughGate,+ model.Artist{ID: consts.VariousArtistsID, Name: "Various Artists"})+ Expect(t.Steps()).To(HaveLen(1))+ Expect(t.Steps()[0].Outcome).To(Equal(OutcomeSkipped))+ Expect(t.Steps()[0].Detail).To(ContainSubstring("synthetic"))+ })+It("clears typographic characters from the query name unless preserving unicode", func() {conf.Server.DevPreserveUnicodeInExternalCalls = falsea := &fakeImageAgent{name: "agentA"}@@ -231,6 +255,18 @@ var _ = Describe("agent images", func() {Expect(a.albumCalls).To(Equal(1))})+ It("records a skipped external candidate when no agent provides album images", func() {+ ag := imageAgents()+ t := &ChainTrace{}++ r, _, extErr := fetchAlbumImage(withTrace(ctx, t), ag, passthroughGate, model.Album{Name: "Album"})+ Expect(r).To(BeNil())+ Expect(extErr).To(BeFalse())+ Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "external", Outcome: OutcomeSkipped,+ Detail: "no enabled agent provides album images"}}),+ "a configured external token must never be silently absent from the chain")+ })+It("reports extErr when the only agent fails transiently", func() {a := &fakeImageAgent{name: "agentA", err: context.DeadlineExceeded}ag := imageAgents(a)diff --git a/core/artwork/artwork.go b/core/artwork/artwork.goindex 8ac8d9c9d..7edc80e99 100644--- a/core/artwork/artwork.go+++ b/core/artwork/artwork.go@@ -11,6 +11,7 @@ import ("github.com/navidrome/navidrome/conf""github.com/navidrome/navidrome/consts"+ "github.com/navidrome/navidrome/core/agents""github.com/navidrome/navidrome/core/ffmpeg""github.com/navidrome/navidrome/log""github.com/navidrome/navidrome/model"@@ -118,7 +119,7 @@ func (s *service) Get(ctx context.Context, artID model.ArtworkID, size int, squa}// requestRecheckAge throttles view-triggered rechecks so reopening a genuinely-absent page can't-// hammer external services; below staleAbsentAge to catch younger absences.+// hammer external services; below StaleAbsentAge to catch younger absences.const requestRecheckAge = time.Hourfunc (s *service) serveEntity(ctx context.Context, artID model.ArtworkID, size int, square bool) (*Image, error) {@@ -317,16 +318,15 @@ func (s *service) serveDisc(ctx context.Context, artID model.ArtworkID, size intreturn nil, err}// Single-disc albums run the chain too: a disc can carry art distinct from the album cover.- selectImage := func() (io.ReadCloser, string, error) {- funcs := dr.fromDiscArtPriority(ctx, s.ffmpeg, conf.Server.DiscArtPriority)- return selectImageReader(ctx, artID, funcs...)+ selectImage := func() (io.ReadCloser, error) {+ res, err := dr.selectImage(ctx, s.ffmpeg, conf.Server.DiscArtPriority, &chainState{})+ return res.reader, err}albumArtID := model.ArtworkID{Kind: model.KindAlbumArtwork, ID: dr.album.ID}// Disc art has no state row, hence no content hash: keying on id, album mtime and// DiscArtPriority lets a warm cache answer without running the chain or touching the disk.key := fmt.Sprintf("%s|%d|%s", artID.ID, dr.cacheTime().UnixNano(), conf.Server.DiscArtPriority)- img, err := s.serveSource(ctx, key, "", dr.cacheTime(), size, square,- func() (io.ReadCloser, error) { rc, _, err := selectImage(); return rc, err })+ img, err := s.serveSource(ctx, key, "", dr.cacheTime(), size, square, selectImage)if err != nil {if errors.Is(err, context.Canceled) {return nil, err@@ -386,6 +386,54 @@ func (s *service) parseArtworkID(ctx context.Context, id string) (model.ArtworkIreturn model.ArtworkID{}, model.ErrNotFound}+// TracingResolver is the CLI's read-only view of resolution: it walks the priority chain, records+// the walk and reports the winning source, without ever writing artwork state.+type TracingResolver struct {+ inner *resolver+ trace *ChainTrace+}++// NewTracingResolver builds a TracingResolver that records its priority-chain walk. With live+// false the external tier is reported but never called.+func NewTracingResolver(ds model.DataStore, ag *agents.Agents, ffm ffmpeg.FFmpeg, t *ChainTrace, live bool) *TracingResolver {+ gate := offlineGate(t)+ if live {+ // A diagnostic must show the provider's real answer, and one item is at most one call+ // per agent, so --live deliberately bypasses the rate limiter and circuit breaker.+ gate = tracingGate(t, passthroughGate)+ }+ return &TracingResolver{inner: newResolver(ds, ag, ffm, gate), trace: t}+}++// Resolve walks kind's sources for id, recording the walk, and reports the winning source+// ("" when none produced an image).+func (r *TracingResolver) Resolve(ctx context.Context, kind model.Kind, id string) (string, error) {+ switch kind {+ case model.KindArtistArtwork:+ return r.explain(ctx, r.inner.resolveArtist, id)+ case model.KindAlbumArtwork:+ return r.explain(ctx, r.inner.resolveAlbum, id)+ case model.KindDiscArtwork:+ return r.explain(ctx, r.inner.resolveDisc, id)+ case model.KindMediaFileArtwork:+ return r.explain(ctx, r.inner.resolveMediaFile, id)+ }+ return "", fmt.Errorf("artwork: %s artwork has no chain to explain", kind)+}++// explain discards the bytes: nothing downstream persists this resolution, so nothing else+// would close the reader either.+func (r *TracingResolver) explain(ctx context.Context, resolve func(context.Context, string) (resolution, error), id string) (string, error) {+ res, err := resolve(withTrace(ctx, r.trace), id)+ if err != nil {+ return "", err+ }+ if res.reader != nil {+ _ = res.reader.Close()+ }+ return res.source, nil+}+func unixMtime(mtime int64) time.Time {if mtime <= 0 {return time.Time{}diff --git a/core/artwork/disc.go b/core/artwork/disc.goindex 21f596b60..acd8a3740 100644--- a/core/artwork/disc.go+++ b/core/artwork/disc.go@@ -113,27 +113,71 @@ func newDiscArtworkReader(ctx context.Context, ds model.DataStore, artID model.A}, nil}-func (d *discArtworkReader) fromDiscArtPriority(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string) []sourceFunc {- var ff []sourceFunc+// discCandidate is one DiscArtPriority entry. skip is set when the entry maps to no source at+// all, so a chain walk can say why instead of leaving a configured entry unaccounted for.+type discCandidate struct {+ pattern string+ resolve func() (resolution, bool)+ skip string+}++func (d *discArtworkReader) discCandidates(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string) []discCandidate {+ folder := func(sf sourceFunc) func() (resolution, bool) {+ return func() (resolution, bool) { return resolveFolderSource(d.lib, sf) }+ }+ var cc []discCandidatefor pattern := range strings.SplitSeq(strings.ToLower(priority), ",") {pattern = strings.TrimSpace(pattern)+ if pattern == "" {+ continue+ }+ c := discCandidate{pattern: pattern}switch {case pattern == "embedded":- ff = append(ff,- fromTag(ctx, d.lib.FS, d.firstTrackRel),- fromFFmpegTag(ctx, ffmpeg, d.lib.Abs(d.firstTrackRel)),- )- case pattern == "external":- // Not supported for disc art, silently ignore+ c.resolve = func() (resolution, bool) {+ return resolveEmbedded(ctx, d.lib, ffmpeg, d.firstTrackRel)+ }+ case pattern == externalCandidate:+ c.skip = "external sources are not supported for disc artwork"case pattern == "discsubtitle":- if subtitle := strings.TrimSpace(d.album.Discs[d.discNumber]); subtitle != "" {- ff = append(ff, d.fromDiscSubtitle(ctx, subtitle))+ subtitle := strings.TrimSpace(d.album.Discs[d.discNumber])+ if subtitle == "" {+ c.skip = "disc has no subtitle"+ } else {+ c.resolve = folder(d.fromDiscSubtitle(ctx, subtitle))}- case len(d.imgFiles) > 0:- ff = append(ff, d.fromExternalFile(ctx, pattern))+ case len(d.imgFiles) == 0:+ c.skip = "no images in album folder"+ default:+ c.resolve = folder(d.fromExternalFile(ctx, pattern))+ }+ cc = append(cc, c)+ }+ return cc+}++// selectImage walks the DiscArtPriority entries and returns the first that yields an image.+// chain records the walk; the serving path passes an untraced one and pays nothing for it.+func (d *discArtworkReader) selectImage(ctx context.Context, ffmpeg ffmpeg.FFmpeg, priority string,+ chain *chainState) (resolution, error) {+ for _, c := range d.discCandidates(ctx, ffmpeg, priority) {+ if err := ctx.Err(); err != nil {+ return resolution{}, err+ }+ if c.skip != "" {+ chain.record(c.pattern, OutcomeSkipped, c.skip)+ continue+ }+ start := time.Now()+ res, ok := c.resolve()+ log.Trace(ctx, "Artwork: Tried a disc artwork candidate", "albumID", d.album.ID,+ "disc", d.discNumber, "pattern", c.pattern, "hit", ok, "path", res.sourcePath,+ "elapsed", time.Since(start))+ if res, ok = chain.try(c.pattern, res, ok); ok {+ return res, nil}}- return ff+ return chain.exhausted(), nil}// fromDiscSubtitle returns a sourceFunc that matches image files whose stemdiff --git a/core/artwork/disc_test.go b/core/artwork/disc_test.goindex 8264ee27b..8852741cf 100644--- a/core/artwork/disc_test.go+++ b/core/artwork/disc_test.go@@ -6,6 +6,8 @@ import ("path/filepath""github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/tests"+ "github.com/navidrome/navidrome/utils/slice". "github.com/onsi/ginkgo/v2". "github.com/onsi/gomega")@@ -179,19 +181,19 @@ var _ = Describe("Disc Artwork Reader", func() {lib: libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},}- ff := reader.fromDiscArtPriority(ctx, nil, "disc*.*, cover.*")- Expect(ff).To(HaveLen(2))- r, path, err := ff[0]()- Expect(err).ToNot(HaveOccurred())- Expect(path).To(Equal(f2))- r.Close()-- ff = reader.fromDiscArtPriority(ctx, nil, "cover.*, disc*.*")- Expect(ff).To(HaveLen(2))- r, path, err = ff[0]()- Expect(err).ToNot(HaveOccurred())- Expect(path).To(Equal(f1))- r.Close()+ cc := reader.discCandidates(ctx, nil, "disc*.*, cover.*")+ Expect(cc).To(HaveLen(2))+ res, ok := cc[0].resolve()+ Expect(ok).To(BeTrue())+ Expect(res.sourcePath).To(Equal(reader.lib.Abs(f2)))+ res.reader.Close()++ cc = reader.discCandidates(ctx, nil, "cover.*, disc*.*")+ Expect(cc).To(HaveLen(2))+ res, ok = cc[0].resolve()+ Expect(ok).To(BeTrue())+ Expect(res.sourcePath).To(Equal(reader.lib.Abs(f1)))+ res.reader.Close()})DescribeTable("numbered match wins over shared fallback within a pattern",@@ -428,64 +430,109 @@ var _ = Describe("Disc Artwork Reader", func() {})Describe("discArtworkReader", func() {- Describe("fromDiscArtPriority", func() {- var (- reader *discArtworkReader- tmpDir string- )+ var (+ reader *discArtworkReader+ tmpDir string+ )- BeforeEach(func() {- tmpDir = GinkgoT().TempDir()- reader = &discArtworkReader{- discNumber: 2,- isMultiFolder: true,- discFoldersRel: map[string]bool{"music/album/cd2": true},- imgFiles: []string{- "music/album/cd1/disc.jpg",- "music/album/cd2/disc.jpg",- "music/album/cd2/disc2.jpg",- },- firstTrackRel: "music/album/cd2/track1.flac",- lib: libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},- }+ BeforeEach(func() {+ tmpDir = GinkgoT().TempDir()+ reader = &discArtworkReader{+ discNumber: 2,+ isMultiFolder: true,+ discFoldersRel: map[string]bool{"music/album/cd2": true},+ imgFiles: []string{+ "music/album/cd1/disc.jpg",+ "music/album/cd2/disc.jpg",+ "music/album/cd2/disc2.jpg",+ },+ firstTrackRel: "music/album/cd2/track1.flac",+ lib: libraryView{FS: osDirFS{os.DirFS(tmpDir)}, absRoot: tmpDir},+ }+ })++ Describe("selectImage", func() {+ It("abandons the walk when the context is cancelled", func() {+ ctx, cancel := context.WithCancel(context.Background())+ cancel()++ res, err := reader.selectImage(ctx, nil, "disc*.*, cover.*", &chainState{})++ Expect(err).To(MatchError(context.Canceled))+ Expect(res.reader).To(BeNil())})- It("returns source funcs for glob patterns", func() {- ff := reader.fromDiscArtPriority(context.Background(), nil, "disc*.*")- Expect(ff).To(HaveLen(1))+ // "the track has no embedded art" and "the track is there but unreadable" are the two+ // answers a wrong-artwork report needs told apart; only the second is worth retrying.+ It("reports a track it cannot parse as unreadable, not as a miss", func() {+ trace := &ChainTrace{}+ track := filepath.Join(tmpDir, filepath.FromSlash(reader.firstTrackRel))+ Expect(os.MkdirAll(filepath.Dir(track), 0755)).To(Succeed())+ Expect(os.WriteFile(track, []byte("not audio"), 0600)).To(Succeed())++ res, err := reader.selectImage(context.Background(), tests.NewMockFFmpeg(""), "embedded",+ &chainState{trace: trace})++ Expect(err).ToNot(HaveOccurred())+ Expect(res.localError).To(BeTrue())+ Expect(trace.Steps()).To(Equal([]TraceStep{{Candidate: "embedded", Outcome: OutcomeUnreadable}}))})- It("returns source funcs for embedded pattern", func() {- ff := reader.fromDiscArtPriority(context.Background(), nil, "embedded")- Expect(ff).To(HaveLen(2)) // fromTag + fromFFmpegTag+ It("reports a disc with no tracks to read as a miss", func() {+ trace := &ChainTrace{}+ reader.firstTrackRel = ""++ res, err := reader.selectImage(context.Background(), tests.NewMockFFmpeg(""), "embedded",+ &chainState{trace: trace})++ Expect(err).ToNot(HaveOccurred())+ Expect(res.localError).To(BeFalse(), "there was nothing to read, so nothing failed to read")+ Expect(trace.Steps()).To(Equal([]TraceStep{{Candidate: "embedded", Outcome: OutcomeMiss}}))})+ })- It("handles multiple comma-separated patterns", func() {- ff := reader.fromDiscArtPriority(context.Background(), nil, "disc*.*, cd*.*, embedded")- Expect(ff).To(HaveLen(4)) // disc*.* + cd*.* + fromTag + fromFFmpegTag+ Describe("discCandidates", func() {+ It("returns a resolvable candidate for glob patterns", func() {+ cc := reader.discCandidates(context.Background(), nil, "disc*.*")+ Expect(cc).To(HaveLen(1))+ Expect(cc[0].resolve).ToNot(BeNil())})- It("ignores 'external' pattern silently", func() {- ff := reader.fromDiscArtPriority(context.Background(), nil, "external")- Expect(ff).To(HaveLen(0))+ It("returns one candidate per entry, in order", func() {+ cc := reader.discCandidates(context.Background(), nil, "disc*.*, cd*.*, embedded")+ Expect(slice.Map(cc, func(c discCandidate) string { return c.pattern })).+ To(Equal([]string{"disc*.*", "cd*.*", "embedded"}))})- It("returns no source funcs when imgFiles is empty and pattern is not embedded", func() {- reader.imgFiles = nil- ff := reader.fromDiscArtPriority(context.Background(), nil, "disc*.*")- Expect(ff).To(HaveLen(0))+ It("skips an empty entry rather than building a glob that matches nothing", func() {+ cc := reader.discCandidates(context.Background(), nil, "disc*.*,")+ Expect(cc).To(HaveLen(1))})+ // The skip reasons below are what `artwork explain` prints, so an entry that maps to no+ // source must say why instead of vanishing from the walk.+ DescribeTable("keeps an entry that maps to no source, with its reason",+ func(setup func(), priority, reason string) {+ setup()+ cc := reader.discCandidates(context.Background(), nil, priority)+ Expect(cc).To(HaveLen(1))+ Expect(cc[0].resolve).To(BeNil())+ Expect(cc[0].skip).To(Equal(reason))+ },+ Entry("external is unsupported", func() {}, "external",+ "external sources are not supported for disc artwork"),+ Entry("no images in the album folder", func() { reader.imgFiles = nil }, "disc*.*",+ "no images in album folder"),+ Entry("the disc has no subtitle",+ func() { reader.album = model.Album{Discs: model.Discs{2: ""}} }, "discsubtitle",+ "disc has no subtitle"),+ )+It("returns source func for discsubtitle pattern", func() {reader.album = model.Album{Discs: model.Discs{2: "Bonus Tracks"}}- ff := reader.fromDiscArtPriority(context.Background(), nil, "discsubtitle")- Expect(ff).To(HaveLen(1))- })-- It("returns no source func for discsubtitle when disc has no subtitle", func() {- reader.album = model.Album{Discs: model.Discs{2: ""}}- ff := reader.fromDiscArtPriority(context.Background(), nil, "discsubtitle")- Expect(ff).To(HaveLen(0))+ cc := reader.discCandidates(context.Background(), nil, "discsubtitle")+ Expect(cc).To(HaveLen(1))+ Expect(cc[0].resolve).ToNot(BeNil())})})})diff --git a/core/artwork/housekeeping.go b/core/artwork/housekeeping.goindex ce72a6c8e..ae1fc0a0d 100644--- a/core/artwork/housekeeping.go+++ b/core/artwork/housekeeping.go@@ -6,6 +6,8 @@ import ("encoding/hex""fmt""slices"+ "strconv"+ "strings""time""github.com/navidrome/navidrome/conf"@@ -16,27 +18,54 @@ import ("github.com/navidrome/navidrome/utils/slice")-const staleAbsentAge = 24 * time.Hour+// StaleAbsentAge is how long an absent state is trusted before a recheck retries it.+const StaleAbsentAge = 24 * time.Hour-// recheckKinds omits media files: they resolve embedded-only, at scan or on view.-var recheckKinds = []model.Kind{+// RecheckKinds omits media files: they resolve embedded-only, at scan or on view.+var RecheckKinds = []model.Kind{model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork, model.KindRadioArtwork,}+// KeepsState reports whether a kind is recorded in item_artwork and the artwork queue. Disc+// artwork is read through on every request and cached by content key, so it has neither.+func KeepsState(kind model.Kind) bool { return kind != model.KindDiscArtwork }++// RefreshableKinds is every kind Refresh can clear and re-queue, so it holds exactly the kinds+// KeepsState admits. Media files are absent from RecheckKinds but belong here: the worker+// resolves them, it just never revisits them on its own.+var RefreshableKinds = append(slices.Clone(RecheckKinds), model.KindMediaFileArtwork)+// hasRecheckPath reports whether a periodic job will revisit this kind, making an absent settle recoverable.func hasRecheckPath(prefix string) bool {kind, ok := model.ParseKind(prefix)- return ok && slices.Contains(recheckKinds, kind)+ return ok && slices.Contains(RecheckKinds, kind)}// artworkEpoch invalidates all resolution state when bumped; bump it whenever resolution semantics change.const artworkEpoch = 1-// fingerprint covers the inputs that affect resolution outcomes; a change invalidates stored state.-func fingerprint() string {- raw := fmt.Sprintf("%s|%s|%s|%s|%t|%t|%d",- conf.Server.CoverArtPriority, conf.Server.ArtistArtPriority, conf.Server.ArtistImageFolder,- conf.Server.Agents, conf.Server.EnableExternalServices, conf.Server.EnableM3UExternalAlbumArt, artworkEpoch)+// FingerprintInput is one config value the fingerprint covers, named after the setting it came from.+type FingerprintInput struct {+ Name string+ Value string+}++// FingerprintInputs is the single listing of what ConfigFingerprint hashes.+func FingerprintInputs() []FingerprintInput {+ return []FingerprintInput{+ {"CoverArtPriority", conf.Server.CoverArtPriority},+ {"ArtistArtPriority", conf.Server.ArtistArtPriority},+ {"ArtistImageFolder", conf.Server.ArtistImageFolder},+ {"Agents", conf.Server.Agents},+ {"EnableExternalServices", strconv.FormatBool(conf.Server.EnableExternalServices)},+ {"EnableM3UExternalAlbumArt", strconv.FormatBool(conf.Server.EnableM3UExternalAlbumArt)},+ }+}++// ConfigFingerprint covers the inputs that affect resolution outcomes; a change invalidates stored state.+func ConfigFingerprint() string {+ values := slice.Map(FingerprintInputs(), func(i FingerprintInput) string { return i.Value })+ raw := fmt.Sprintf("%s|%d", strings.Join(values, "|"), artworkEpoch)sum := md5.Sum([]byte(raw)) //nolint:gosec // fingerprint, not security-sensitivereturn hex.EncodeToString(sum[:])}@@ -45,7 +74,7 @@ func fingerprint() string {func backfill(ctx context.Context, ds model.DataStore) (bool, error) {start := time.Now()ctx = auth.WithAdminUser(ctx, ds)- current := fingerprint()+ current := ConfigFingerprint()props := ds.Property(ctx)stored, err := props.DefaultGet(consts.ArtConfFingerprintPropertyKey, "")if err != nil {@@ -95,9 +124,9 @@ func enqueueBackfillKind(ctx context.Context, ds model.DataStore, kind model.Kin}func enqueueStaleAbsentAll(ctx context.Context, ds model.DataStore) error {- cutoff := time.Now().Add(-staleAbsentAge)+ cutoff := time.Now().Add(-StaleAbsentAge)queue := ds.ArtworkQueue(ctx)- for _, kind := range recheckKinds {+ for _, kind := range RecheckKinds {if _, err := queue.EnqueueStaleAbsent(kind, cutoff); err != nil {return err}@@ -108,7 +137,7 @@ func enqueueStaleAbsentAll(ctx context.Context, ds model.DataStore) error {// enqueueMissingAll is the safety net for entities a scan never enqueued (added between scans, or scanner off).func enqueueMissingAll(ctx context.Context, ds model.DataStore) error {queue := ds.ArtworkQueue(ctx)- for _, kind := range recheckKinds {+ for _, kind := range RecheckKinds {if _, err := queue.EnqueueAllMissing(kind, model.ArtworkPriorityRecheck); err != nil {return err}diff --git a/core/artwork/housekeeping_test.go b/core/artwork/housekeeping_test.goindex 3b75c5186..32a7688b4 100644--- a/core/artwork/housekeeping_test.go+++ b/core/artwork/housekeeping_test.go@@ -52,6 +52,19 @@ func (o *orderTrackingQueueRepo) Enqueue(items ...model.ArtworkQueueItem) errorreturn o.MockArtworkQueueRepo.Enqueue(items...)}+var _ = Describe("RefreshableKinds", func() {+ // The two are meant to describe the same fact. Nothing but this test stops them from drifting,+ // and a drift would have `artwork explain` report state for a kind that keeps none.+ It("holds exactly the kinds that keep state", func() {+ for _, k := range []model.Kind{+ model.KindArtistArtwork, model.KindAlbumArtwork, model.KindPlaylistArtwork,+ model.KindRadioArtwork, model.KindMediaFileArtwork, model.KindDiscArtwork,+ } {+ Expect(slices.Contains(RefreshableKinds, k)).To(Equal(KeepsState(k)), k.String())+ }+ })+})+var _ = Describe("Housekeeping", func() {var (ctx context.Context@@ -93,32 +106,54 @@ var _ = Describe("Housekeeping", func() {Describe("Fingerprint", func() {It("changes when a fingerprint-affecting config value changes", func() {- f1 := fingerprint()+ f1 := ConfigFingerprint()conf.Server.CoverArtPriority = "folder, embedded"- f2 := fingerprint()+ f2 := ConfigFingerprint()Expect(f1).NotTo(Equal(f2))})It("changes when ArtistImageFolder changes", func() {conf.Server.ArtistImageFolder = "/before"- f1 := fingerprint()+ f1 := ConfigFingerprint()conf.Server.ArtistImageFolder = "/after"- Expect(fingerprint()).NotTo(Equal(f1))+ Expect(ConfigFingerprint()).NotTo(Equal(f1))})It("changes when EnableM3UExternalAlbumArt is toggled", func() {conf.Server.EnableM3UExternalAlbumArt = false- f1 := fingerprint()+ f1 := ConfigFingerprint()conf.Server.EnableM3UExternalAlbumArt = true- Expect(fingerprint()).NotTo(Equal(f1))+ Expect(ConfigFingerprint()).NotTo(Equal(f1))+ })++ // Pinned: a changed formula re-resolves every library on upgrade, flooding external providers.+ It("hashes a given config to a stable value", func() {+ conf.Server.CoverArtPriority = "cover.*, embedded"+ conf.Server.ArtistArtPriority = "artist.*, external"+ conf.Server.ArtistImageFolder = ""+ conf.Server.Agents = "lastfm,spotify"+ conf.Server.EnableExternalServices = true+ conf.Server.EnableM3UExternalAlbumArt = false++ Expect(ConfigFingerprint()).To(Equal("7e537a22febc07d3d5ca40546e88da54"))+ })++ It("reports the config inputs it hashes, so a change can be traced to a setting", func() {+ conf.Server.Agents = "lastfm,spotify"+ conf.Server.CoverArtPriority = "cover.*, embedded"++ Expect(FingerprintInputs()).To(ContainElements(+ FingerprintInput{Name: "Agents", Value: "lastfm,spotify"},+ FingerprintInput{Name: "CoverArtPriority", Value: "cover.*, embedded"},+ ))})It("does not change when the server version changes", func() {original := consts.VersionDeferCleanup(func() { consts.Version = original })- f1 := fingerprint()+ f1 := ConfigFingerprint()consts.Version = original + "-next"- Expect(fingerprint()).To(Equal(f1),+ Expect(ConfigFingerprint()).To(Equal(f1),"the version must not invalidate artwork state: it would re-resolve every entity on every build")})})@@ -126,7 +161,7 @@ var _ = Describe("Housekeeping", func() {Describe("Backfill", func() {It("enqueues nothing and returns false when the stored fingerprint matches", func() {seedEntities()- Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, fingerprint())).To(Succeed())+ Expect(propRepo.Put(consts.ArtConfFingerprintPropertyKey, ConfigFingerprint())).To(Succeed())did, err := backfill(ctx, ds)Expect(err).ToNot(HaveOccurred())@@ -150,7 +185,7 @@ var _ = Describe("Housekeeping", func() {stored, err := propRepo.Get(consts.ArtConfFingerprintPropertyKey)Expect(err).ToNot(HaveOccurred())- Expect(stored).To(Equal(fingerprint()))+ Expect(stored).To(Equal(ConfigFingerprint()))})It("enqueues a private playlist by resolving it under an admin context", func() {diff --git a/core/artwork/image_cache.go b/core/artwork/image_cache.goindex 39938a755..b1970d21d 100644--- a/core/artwork/image_cache.go+++ b/core/artwork/image_cache.go@@ -55,6 +55,10 @@ func (r *resizedItem) Reader(ctx context.Context) (io.ReadCloser, error) {if err != nil {return nil, err}+ // An open() that reports "no image" as a nil reader would otherwise panic on the Close below.+ if orig == nil {+ return nil, ErrUnavailable+ }defer orig.Close()data, err := readCapped(orig)if err != nil {diff --git a/core/artwork/image_cache_test.go b/core/artwork/image_cache_test.gonew file mode 100644index 000000000..a74c51088--- /dev/null+++ b/core/artwork/image_cache_test.go@@ -0,0 +1,41 @@+package artwork++import (+ "context"+ "errors"+ "io"+ "strings"++ . "github.com/onsi/ginkgo/v2"+ . "github.com/onsi/gomega"+)++var _ = Describe("resizedItem", func() {+ Describe("Reader", func() {+ newItem := func(open func() (io.ReadCloser, error)) *resizedItem {+ return &resizedItem{hash: "abc123", size: 300, open: open}+ }++ It("reports a nil reader as unavailable instead of panicking on it", func() {+ // Every caller is expected to report "no image" as an error, but a nil reader reaches+ // the deferred Close as a nil interface, which takes the whole request down.+ _, err := newItem(func() (io.ReadCloser, error) { return nil, nil }).Reader(context.Background())+ Expect(err).To(MatchError(ErrUnavailable))+ })++ It("propagates the open error", func() {+ boom := errors.New("boom")+ _, err := newItem(func() (io.ReadCloser, error) { return nil, boom }).Reader(context.Background())+ Expect(err).To(MatchError(boom))+ })++ It("serves the original bytes when they cannot be resized", func() {+ rc, err := newItem(func() (io.ReadCloser, error) {+ return io.NopCloser(strings.NewReader("not an image")), nil+ }).Reader(context.Background())+ Expect(err).ToNot(HaveOccurred())+ defer rc.Close()+ Expect(io.ReadAll(rc)).To(Equal([]byte("not an image")))+ })+ })+})diff --git a/core/artwork/resolve.go b/core/artwork/resolve.goindex 11711469d..518b6e100 100644--- a/core/artwork/resolve.go+++ b/core/artwork/resolve.go@@ -34,18 +34,31 @@ type resolution struct {// chainState carries what a priority walk has seen so far. A hit takes extErr with it so a// transient external failure still retries; localErr is dropped, as the scanner re-lists changes.-type chainState struct{ extErr, localErr bool }+type chainState struct {+ extErr, localErr bool+ trace *ChainTrace // nil unless the CLI asked for a trace+}// try stamps the accumulated external failure onto a hit, and records the miss otherwise.-func (c *chainState) try(res resolution, ok bool) (resolution, bool) {+func (c *chainState) try(candidate string, res resolution, ok bool) (resolution, bool) {if ok {res.extError = c.extErr+ c.record(candidate, OutcomeHit, res.sourcePath)return res, true}c.localErr = c.localErr || res.localError+ if res.localError {+ c.record(candidate, OutcomeUnreadable, "")+ } else {+ c.record(candidate, OutcomeMiss, "")+ }return resolution{}, false}+func (c *chainState) record(candidate string, out Outcome, detail string) {+ c.trace.add(TraceStep{Candidate: candidate, Outcome: out, Detail: detail})+}+// exhausted is the outcome when no source in the chain yielded an image.func (c *chainState) exhausted() resolution {return resolution{extError: c.extErr, localError: c.localErr}@@ -95,8 +108,69 @@ func (r *resolver) resolve(ctx context.Context, item model.ArtworkQueueItem) (re}}-// fetchExternalAlbum and fetchExternalArtist are the only places resolution touches the network,-// so a local-only resolver is stopped here rather than at each point in the chain walk.+// Explainable reports whether TracingResolver can walk this kind's sources and report which one+// won; playlists and radios resolve from a fixed internal order, with nothing configured to explain.+func Explainable(kind model.Kind) bool {+ switch kind {+ case model.KindArtistArtwork, model.KindAlbumArtwork, model.KindDiscArtwork, model.KindMediaFileArtwork:+ return true+ }+ return false+}++// MayFetchExternal reports whether resolving this kind can issue an external request under the+// current config. Playlists inherit the album chain: the generated grid resolves album art.+func MayFetchExternal(kind model.Kind) bool {+ switch kind {+ case model.KindArtistArtwork:+ return chainFetchesExternal(conf.Server.ArtistArtPriority)+ case model.KindAlbumArtwork:+ return chainFetchesExternal(conf.Server.CoverArtPriority)+ case model.KindPlaylistArtwork:+ return conf.Server.EnableM3UExternalAlbumArt || chainFetchesExternal(conf.Server.CoverArtPriority)+ default:+ return false+ }+}++// ImageAgentCount is how many enabled agents provide artist and album images.+type ImageAgentCount struct{ Artist, Album int }++// ExternalLookupsPerItem reports what resolving one item of this kind can cost: every image agent is+// tried, and a zero count still bills one, so agents the caller cannot see never read as free.+func ExternalLookupsPerItem(kind model.Kind, agents ImageAgentCount) int64 {+ if !MayFetchExternal(kind) {+ return 0+ }+ switch kind {+ case model.KindArtistArtwork:+ return int64(max(agents.Artist, 1))+ case model.KindAlbumArtwork:+ return int64(max(agents.Album, 1))+ case model.KindPlaylistArtwork:+ var n int64+ if conf.Server.EnableM3UExternalAlbumArt {+ n+++ }+ if chainFetchesExternal(conf.Server.CoverArtPriority) {+ n += PlaylistGridSamples * int64(max(agents.Album, 1))+ }+ return n+ }+ return 0+}++func chainFetchesExternal(priority string) bool {+ for pattern := range strings.SplitSeq(strings.ToLower(priority), ",") {+ if strings.TrimSpace(pattern) == externalCandidate {+ return true+ }+ }+ return false+}++// Album and artist fetches stop here when the resolver is local-only, rather than at each point in+// the chain walk; resolvePlaylist gates the third network path, the m3u image URL, itself.func (r *resolver) fetchExternalAlbum(ctx context.Context, al model.Album) (io.ReadCloser, string, bool) {if r.ext == nil {return nil, "", false@@ -126,24 +200,31 @@ func (r *resolver) resolveAlbum(ctx context.Context, albumID string) (resolutionreturn resolution{}, err}- var chain chainState+ chain := chainState{trace: traceFrom(ctx)}for pattern := range strings.SplitSeq(strings.ToLower(conf.Server.CoverArtPriority), ",") {pattern = strings.TrimSpace(pattern)+ if pattern == "" {+ continue+ }switch {case pattern == "embedded":- if res, ok := chain.try(resolveEmbedded(ctx, lib, r.ffmpeg, al.EmbedArtPath)); ok {+ res, ok := resolveEmbedded(ctx, lib, r.ffmpeg, al.EmbedArtPath)+ if res, ok = chain.try(pattern, res, ok); ok {return res, nil}- case pattern == "external":+ case pattern == externalCandidate:if rd, name, isErr := r.fetchExternalAlbum(ctx, *al); rd != nil {- return resolution{reader: rd, source: "external:" + name}, nil+ return resolution{reader: rd, source: ExternalPrefix + name}, nil} else if isErr {chain.extErr = true}case len(imgFiles) > 0:- if res, ok := chain.try(resolveFolderFile(ctx, lib, imgFiles, pattern)); ok {+ res, ok := resolveFolderFile(ctx, lib, imgFiles, pattern)+ if res, ok = chain.try(pattern, res, ok); ok {return res, nil}+ default:+ chain.record(pattern, OutcomeSkipped, "no images in album folder")}}return chain.exhausted(), nil@@ -155,9 +236,10 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resolutiif err != nil {return resolution{}, err}- upload, ok := resolveLocalFile(ar.UploadedImagePath(), "upload")- if ok {- return upload, nil+ chain := chainState{trace: traceFrom(ctx)}+ upload, uploadOK := resolveLocalFile(ar.UploadedImagePath(), "upload")+ if res, ok := chain.try("upload", upload, uploadOK); ok {+ return res, nil}if upload.localError {// The upload outranks every other source; falling through would persist a lower-priority@@ -191,32 +273,43 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti}}- var chain chainStatefor pattern := range strings.SplitSeq(strings.ToLower(conf.Server.ArtistArtPriority), ",") {pattern = strings.TrimSpace(pattern)+ if pattern == "" {+ continue+ }switch {- case pattern == "external":+ case pattern == externalCandidate:if rd, name, isErr := r.fetchExternalArtist(ctx, *ar); rd != nil {- return resolution{reader: rd, source: "external:" + name}, nil+ return resolution{reader: rd, source: ExternalPrefix + name}, nil} else if isErr {chain.extErr = true}case pattern == "image-folder":- if res, ok := chain.try(resolveArtistImageFolder(ar)); ok {+ res, ok := resolveArtistImageFolder(ar)+ if res, ok = chain.try(pattern, res, ok); ok {return res, nil}case strings.HasPrefix(pattern, "album/"):if lib.FS == nil {+ chain.record(pattern, OutcomeSkipped, "artist has no albums")continue}- if res, ok := chain.try(resolveFolderFile(ctx, lib, imgFiles, strings.TrimPrefix(pattern, "album/"))); ok {+ res, ok := resolveFolderFile(ctx, lib, imgFiles, strings.TrimPrefix(pattern, "album/"))+ if res, ok = chain.try(pattern, res, ok); ok {return res, nil}default:- if lib.FS == nil || artistFolder == "" {+ if lib.FS == nil {+ chain.record(pattern, OutcomeSkipped, "artist has no albums")+ continue+ }+ if artistFolder == "" {+ chain.record(pattern, OutcomeSkipped, "no artist folder")continue}- if res, ok := chain.try(resolveArtistFolderPattern(ctx, lib, artistFolder, pattern)); ok {+ res, ok := resolveArtistFolderPattern(ctx, lib, artistFolder, pattern)+ if res, ok = chain.try(pattern, res, ok); ok {return res, nil}}@@ -224,6 +317,9 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resolutireturn chain.exhausted(), nil}+// PlaylistGridSamples is how many albums resolvePlaylist samples to build the generated grid.+const PlaylistGridSamples = 4+// resolvePlaylist tries the uploaded image, the sidecar and ExternalImageURL, then a generated grid.func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (resolution, error) {pl, err := r.ds.Playlist(ctx).Get(playlistID)@@ -269,7 +365,8 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso}}- albumIDs, err := r.ds.Playlist(ctx).Tracks(pl.ID, false).GetAlbumIDs(model.QueryOptions{Max: 4, Sort: "random()"})+ albumIDs, err := r.ds.Playlist(ctx).Tracks(pl.ID, false).+ GetAlbumIDs(model.QueryOptions{Max: PlaylistGridSamples, Sort: "random()"})if err != nil {return resolution{}, err}@@ -295,7 +392,7 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (resoif decErr == nil {tiles = append(tiles, tile)}- if len(tiles) == 4 {+ if len(tiles) == PlaylistGridSamples {break}}@@ -337,15 +434,35 @@ func (r *resolver) resolveMediaFile(ctx context.Context, id string) (resolution,if err != nil {return resolution{}, err}- if !conf.Server.EnableMediaFileCoverArt || !mf.HasCoverArt {+ chain := chainState{trace: traceFrom(ctx)}+ switch {+ case !conf.Server.EnableMediaFileCoverArt:+ chain.record("embedded", OutcomeSkipped, "EnableMediaFileCoverArt is off")+ return resolution{}, nil+ case !mf.HasCoverArt:+ chain.record("embedded", OutcomeMiss, "the track has no embedded cover art")return resolution{}, nil}lib, err := loadLibraryView(ctx, r.ds, mf.LibraryID)if err != nil {return resolution{}, err}- res, _ := resolveEmbedded(ctx, lib, r.ffmpeg, mf.Path)- return res, nil+ res, ok := resolveEmbedded(ctx, lib, r.ffmpeg, mf.Path)+ if res, ok = chain.try("embedded", res, ok); ok {+ return res, nil+ }+ return chain.exhausted(), nil+}++// resolveDisc walks conf.Server.DiscArtPriority. Disc artwork keeps no state row and is never+// queued: the serving path reads it through on every request, so this only ever explains.+func (r *resolver) resolveDisc(ctx context.Context, id string) (resolution, error) {+ dr, err := newDiscArtworkReader(ctx, r.ds, model.ArtworkID{Kind: model.KindDiscArtwork, ID: id})+ if err != nil {+ return resolution{}, err+ }+ chain := chainState{trace: traceFrom(ctx)}+ return dr.selectImage(ctx, r.ffmpeg, conf.Server.DiscArtPriority, &chain)}// resolveExternalStep runs a single external sourceFunc through the named gate. extErr excludes@@ -353,7 +470,7 @@ func (r *resolver) resolveMediaFile(ctx context.Context, id string) (resolution,func resolveExternalStep(gate gateFunc, name string, sf sourceFunc) (res resolution, ok bool, extErr bool) {r, path, err := gate(name, sf)if r != nil {- return resolution{reader: r, source: "external", sourcePath: path}, true, false+ return resolution{reader: r, source: externalCandidate, sourcePath: path}, true, false}return resolution{}, false, err != nil && !errors.Is(err, model.ErrNotFound)}@@ -394,14 +511,20 @@ func resolveEmbedded(ctx context.Context, lib libraryView, ffm ffmpeg.FFmpeg, emreturn resolution{localError: unreadable}, false}-func resolveFolderFile(ctx context.Context, lib libraryView, imgFiles []string, pattern string) (resolution, bool) {- r, path, err := fromExternalFile(ctx, lib.FS, imgFiles, pattern)()+// resolveFolderSource turns a source that yields a library-relative image path into a folder+// resolution, keeping an existing-but-unopenable file distinct from an absent one.+func resolveFolderSource(lib libraryView, sf sourceFunc) (resolution, bool) {+ r, path, err := sf()if r == nil {return resolution{localError: errors.Is(err, errSourceUnreadable)}, false}return resolution{reader: r, source: "folder", sourcePath: lib.Abs(path), refMtime: mtimeViaFS(lib.FS, path)}, true}+func resolveFolderFile(ctx context.Context, lib libraryView, imgFiles []string, pattern string) (resolution, bool) {+ return resolveFolderSource(lib, fromExternalFile(ctx, lib.FS, imgFiles, pattern))+}+func resolveArtistImageFolder(ar *model.Artist) (resolution, bool) {folder := conf.Server.ArtistImageFolderif folder == "" {diff --git a/core/artwork/resolve_test.go b/core/artwork/resolve_test.goindex 9a0962cf2..25fb727de 100644--- a/core/artwork/resolve_test.go+++ b/core/artwork/resolve_test.go@@ -394,6 +394,28 @@ var _ = Describe("resolveItem", func() {Entry("4 albums -> full grid", []string{"t1", "t2", "t3", "t4"}, tileSize-1),)+ // The grid samples album art through the full album chain, so a playlist reaches the+ // network even with the m3u fetch off.+ It("calls the album image agents for its grid tiles when m3u art is disabled", func() {+ conf.Server.EnableM3UExternalAlbumArt = false+ conf.Server.CoverArtPriority = "external"+ folderRepo.result = nil+ plRepo := tests.CreateMockPlaylistRepo()+ plRepo.SetData(model.Playlists{{ID: "plgrid", Name: "Playlist"}})+ plRepo.TracksRepo = &tests.MockPlaylistTrackRepo{AlbumIDs: []string{"t1", "t2"}}+ ds.MockedPlaylist = plRepo+ imageAgents(&fakeImageAgent{name: "failAgent", err: errors.New("boom")})+ var gatedNames []string+ gate := func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {+ gatedNames = append(gatedNames, name)+ return f()+ }++ _, err := newResolver(ds, ag, ffm, gate).resolve(ctx, model.ArtworkQueueItem{ItemKind: "pl", ItemID: "plgrid"})+ Expect(err).ToNot(HaveOccurred())+ Expect(gatedNames).To(Equal([]string{"failAgent", "failAgent"}), "one lookup per sampled album")+ })+It("resolves the uploaded image before the generated grid", func() {tmpDir := GinkgoT().TempDir()conf.Server.DataFolder = conf.NewDir(tmpDir)@@ -630,3 +652,110 @@ var _ = Describe("decodeTile", func() {Expect(err).To(HaveOccurred())})})++var _ = Describe("Explainable", func() {+ It("is true for the kinds the resolver walks", func() {+ Expect(Explainable(model.KindArtistArtwork)).To(BeTrue())+ Expect(Explainable(model.KindAlbumArtwork)).To(BeTrue())+ Expect(Explainable(model.KindDiscArtwork)).To(BeTrue())+ Expect(Explainable(model.KindMediaFileArtwork)).To(BeTrue())+ })++ It("is false for the kinds resolved from a fixed internal order", func() {+ Expect(Explainable(model.KindPlaylistArtwork)).To(BeFalse())+ Expect(Explainable(model.KindRadioArtwork)).To(BeFalse())+ })+})++var _ = Describe("MayFetchExternal", func() {+ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.CoverArtPriority = "cover.*, embedded"+ conf.Server.ArtistArtPriority = "artist.*"+ conf.Server.EnableM3UExternalAlbumArt = false+ })++ It("is true for the kinds whose chain includes the external candidate", func() {+ conf.Server.CoverArtPriority = "cover.*, external"+ conf.Server.ArtistArtPriority = "artist.*, external"+ Expect(MayFetchExternal(model.KindAlbumArtwork)).To(BeTrue())+ Expect(MayFetchExternal(model.KindArtistArtwork)).To(BeTrue())+ })++ It("is false for a chain with no external candidate", func() {+ Expect(MayFetchExternal(model.KindAlbumArtwork)).To(BeFalse())+ Expect(MayFetchExternal(model.KindArtistArtwork)).To(BeFalse())+ })++ It("is true for playlists when the m3u image fetch is enabled", func() {+ conf.Server.EnableM3UExternalAlbumArt = true+ Expect(MayFetchExternal(model.KindPlaylistArtwork)).To(BeTrue())+ })++ It("is true for playlists whose grid tiles resolve through an external album chain", func() {+ conf.Server.CoverArtPriority = "cover.*, external"+ Expect(MayFetchExternal(model.KindPlaylistArtwork)).To(BeTrue())+ })++ It("is false for playlists with both paths off", func() {+ Expect(MayFetchExternal(model.KindPlaylistArtwork)).To(BeFalse())+ })++ It("is false for the kinds that only read local files", func() {+ conf.Server.CoverArtPriority = "external"+ conf.Server.ArtistArtPriority = "external"+ conf.Server.EnableM3UExternalAlbumArt = true+ Expect(MayFetchExternal(model.KindRadioArtwork)).To(BeFalse())+ Expect(MayFetchExternal(model.KindMediaFileArtwork)).To(BeFalse())+ })+})++var _ = Describe("ExternalLookupsPerItem", func() {+ count := ImageAgentCount{Artist: 3, Album: 2}++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.CoverArtPriority = "cover.*, external"+ conf.Server.ArtistArtPriority = "artist.*, external"+ conf.Server.EnableM3UExternalAlbumArt = false+ })++ It("bills one call per agent, since the walk only stops early on a hit", func() {+ Expect(ExternalLookupsPerItem(model.KindArtistArtwork, count)).To(Equal(int64(3)))+ Expect(ExternalLookupsPerItem(model.KindAlbumArtwork, count)).To(Equal(int64(2)))+ })++ It("bills a playlist for every album its grid samples", func() {+ Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).+ To(Equal(int64(PlaylistGridSamples) * 2))+ })++ It("adds the m3u image fetch on top of the grid", func() {+ conf.Server.EnableM3UExternalAlbumArt = true+ Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).+ To(Equal(int64(PlaylistGridSamples)*2 + 1))+ })++ It("bills only the m3u fetch when the album chain stays local", func() {+ conf.Server.CoverArtPriority = "cover.*"+ conf.Server.EnableM3UExternalAlbumArt = true+ Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).To(Equal(int64(1)))+ })++ It("still bills a call when no agent is visible, which plugins never are offline", func() {+ none := ImageAgentCount{}+ Expect(ExternalLookupsPerItem(model.KindArtistArtwork, none)).To(Equal(int64(1)))+ Expect(ExternalLookupsPerItem(model.KindAlbumArtwork, none)).To(Equal(int64(1)))+ Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, none)).+ To(Equal(int64(PlaylistGridSamples)))+ })++ It("is zero whenever the kind reaches no agent at all", func() {+ conf.Server.CoverArtPriority = "cover.*"+ conf.Server.ArtistArtPriority = "artist.*"+ Expect(ExternalLookupsPerItem(model.KindArtistArtwork, count)).To(BeZero())+ Expect(ExternalLookupsPerItem(model.KindAlbumArtwork, count)).To(BeZero())+ Expect(ExternalLookupsPerItem(model.KindPlaylistArtwork, count)).To(BeZero())+ Expect(ExternalLookupsPerItem(model.KindRadioArtwork, count)).To(BeZero())+ })+})diff --git a/core/artwork/sources.go b/core/artwork/sources.goindex 885ca03cf..78b7dd68d 100644--- a/core/artwork/sources.go+++ b/core/artwork/sources.go@@ -27,23 +27,6 @@ import (// to open it is not evidence the entity has no artwork, so callers must not settle on absent.var errSourceUnreadable = errors.New("artwork source unreadable")-func selectImageReader(ctx context.Context, artID model.ArtworkID, extractFuncs ...sourceFunc) (io.ReadCloser, string, error) {- for _, f := range extractFuncs {- if ctx.Err() != nil {- return nil, "", ctx.Err()- }- start := time.Now()- r, path, err := f()- if r != nil {- msg := fmt.Sprintf("Artwork: Found %s artwork", artID.Kind)- log.Debug(ctx, msg, "artID", artID, "path", path, "source", f, "elapsed", time.Since(start))- return r, path, nil- }- log.Trace(ctx, "Artwork: Failed trying to extract artwork", "artID", artID, "source", f, "elapsed", time.Since(start), err)- }- return nil, "", fmt.Errorf("could not get `%s` cover art for %s: %w", artID.Kind, artID, ErrUnavailable)-}-type sourceFunc func() (r io.ReadCloser, path string, err error)func (f sourceFunc) String() string {diff --git a/core/artwork/trace.go b/core/artwork/trace.gonew file mode 100644index 000000000..5d02fa4ff--- /dev/null+++ b/core/artwork/trace.go@@ -0,0 +1,99 @@+package artwork++import (+ "context"+ "errors"+ "io"+ "slices"+ "sync"+)++// Outcome is what the priority chain observed for one candidate; the CLI renders and branches on these.+type Outcome string++const (+ OutcomeHit Outcome = "hit"+ OutcomeMiss Outcome = "miss"+ OutcomeUnreadable Outcome = "unreadable"+ OutcomeSkipped Outcome = "skipped"+ OutcomeWouldTry Outcome = "would-try"+ OutcomeError Outcome = "error"+)++const (+ // externalCandidate labels the external tier itself, for the cases that never reach an agent.+ externalCandidate = "external"+ // ExternalPrefix qualifies a candidate or a stored source with the agent that produced it.+ ExternalPrefix = externalCandidate + ":"+)++// TraceStep is one candidate the priority chain considered.+type TraceStep struct {+ Candidate string+ Outcome Outcome+ Detail string+}++// ChainTrace collects the walk of a single resolution. The artwork worker never attaches+// one; only the CLI does, so resolution stays allocation-free in the hot path.+type ChainTrace struct {+ mu sync.Mutex+ steps []TraceStep+}++func (t *ChainTrace) add(step TraceStep) {+ if t == nil {+ return+ }+ t.mu.Lock()+ defer t.mu.Unlock()+ t.steps = append(t.steps, step)+}++func (t *ChainTrace) Steps() []TraceStep {+ if t == nil {+ return nil+ }+ t.mu.Lock()+ defer t.mu.Unlock()+ return slices.Clone(t.steps)+}++type traceCtxKey struct{}++func withTrace(ctx context.Context, t *ChainTrace) context.Context {+ return context.WithValue(ctx, traceCtxKey{}, t)+}++func traceFrom(ctx context.Context) *ChainTrace {+ t, _ := ctx.Value(traceCtxKey{}).(*ChainTrace)+ return t+}++var errOfflineSkipped = errors.New("artwork: external lookup skipped (offline)")++// tracingGate records each external agent's outcome without changing what the gate returns.+func tracingGate(t *ChainTrace, inner gateFunc) gateFunc {+ return func(name string, f func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {+ r, path, err := inner(name, f)+ candidate := ExternalPrefix + name+ switch {+ case r != nil:+ t.add(TraceStep{Candidate: candidate, Outcome: OutcomeHit, Detail: path})+ case isTransientExternal(err):+ t.add(TraceStep{Candidate: candidate, Outcome: OutcomeError, Detail: err.Error()})+ default:+ t.add(TraceStep{Candidate: candidate, Outcome: OutcomeMiss})+ }+ return r, path, err+ }+}++// offlineGate reports which agents would be asked without asking them, so a diagnostic+// command cannot add load to a provider that is already rate-limiting us.+func offlineGate(t *ChainTrace) gateFunc {+ return func(name string, _ func() (io.ReadCloser, string, error)) (io.ReadCloser, string, error) {+ t.add(TraceStep{Candidate: ExternalPrefix + name, Outcome: OutcomeWouldTry})+ return nil, "", errOfflineSkipped+ }+}diff --git a/core/artwork/trace_test.go b/core/artwork/trace_test.gonew file mode 100644index 000000000..5a54c9e91--- /dev/null+++ b/core/artwork/trace_test.go@@ -0,0 +1,628 @@+package artwork++import (+ "context"+ "errors"+ "io"+ "os"+ "path/filepath"+ "runtime"+ "strings"++ "github.com/navidrome/navidrome/conf"+ "github.com/navidrome/navidrome/conf/configtest"+ "github.com/navidrome/navidrome/consts"+ "github.com/navidrome/navidrome/core/agents"+ "github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/tests"+ . "github.com/onsi/ginkgo/v2"+ . "github.com/onsi/gomega"+)++var _ = Describe("trace vocabulary", func() {+ // The CLI renders these verbatim and branches on them; a value change is a change to+ // what `artwork explain` tells an operator, so it must be made deliberately.+ It("pins the wire values the CLI reads", func() {+ Expect([]Outcome{+ OutcomeHit, OutcomeMiss, OutcomeUnreadable, OutcomeSkipped, OutcomeWouldTry, OutcomeError,+ }).To(Equal([]Outcome{"hit", "miss", "unreadable", "skipped", "would-try", "error"}))+ Expect(externalCandidate).To(Equal("external"))+ Expect(ExternalPrefix).To(Equal("external:"))+ })+})++var _ = Describe("chainTrace", func() {+ It("returns nil when no trace is attached", func() {+ Expect(traceFrom(context.Background())).To(BeNil())+ })++ It("collects steps in order", func() {+ t := &ChainTrace{}+ ctx := withTrace(context.Background(), t)++ traceFrom(ctx).add(TraceStep{Candidate: "cover.*", Outcome: OutcomeMiss})+ traceFrom(ctx).add(TraceStep{Candidate: "embedded", Outcome: OutcomeHit, Detail: "/music/a.flac"})++ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "cover.*", Outcome: OutcomeMiss},+ {Candidate: "embedded", Outcome: OutcomeHit, Detail: "/music/a.flac"},+ }))++ s := t.Steps()+ s[0].Candidate = "mutated"+ Expect(t.Steps()[0].Candidate).To(Equal("cover.*"))+ })++ It("does not panic when the trace is nil", func() {+ var t *ChainTrace+ Expect(func() { t.add(TraceStep{Candidate: "cover.*", Outcome: OutcomeMiss}) }).ToNot(Panic())+ Expect(t.Steps()).To(BeEmpty(), "a nil trace collects nothing, so reading it must be as safe as writing it")+ })++ It("is safe to use concurrently", func() {+ t := &ChainTrace{}+ done := make(chan struct{})+ for range 10 {+ go func() {+ defer GinkgoRecover()+ t.add(TraceStep{Candidate: "x", Outcome: OutcomeMiss})+ done <- struct{}{}+ }()+ }+ for range 10 {+ <-done+ }+ Expect(t.Steps()).To(HaveLen(10))+ })+})++var _ = Describe("chainState tracing", func() {+ It("records a miss when the candidate was absent", func() {+ t := &ChainTrace{}+ c := chainState{trace: t}++ _, ok := c.try("cover.*", resolution{}, false)++ Expect(ok).To(BeFalse())+ Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "cover.*", Outcome: OutcomeMiss}}))+ })++ It("records unreadable when the candidate existed but could not be read", func() {+ t := &ChainTrace{}+ c := chainState{trace: t}++ _, ok := c.try("cover.*", resolution{localError: true}, false)++ Expect(ok).To(BeFalse())+ Expect(t.Steps()).To(HaveLen(1))+ Expect(t.Steps()[0].Outcome).To(Equal(OutcomeUnreadable),+ "a candidate that existed and failed to decode must be distinguishable from one that was absent")+ })++ It("records a hit with the backing path", func() {+ t := &ChainTrace{}+ c := chainState{trace: t}++ res, ok := c.try("embedded", resolution{reader: nil, source: "embedded", sourcePath: "/music/a.flac"}, true)++ Expect(ok).To(BeTrue())+ Expect(res.source).To(Equal("embedded"))+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "embedded", Outcome: OutcomeHit, Detail: "/music/a.flac"},+ }))+ })+})++var _ = Describe("external gate tracing", func() {+ hit := func() (io.ReadCloser, string, error) {+ return io.NopCloser(strings.NewReader("x")), "http://img", nil+ }+ miss := func() (io.ReadCloser, string, error) { return nil, "", agents.ErrNotFound }+ boom := func() (io.ReadCloser, string, error) { return nil, "", errors.New("returned status 429") }++ It("records a hit with the image path", func() {+ t := &ChainTrace{}+ g := tracingGate(t, passthroughGate)++ r, _, err := g("deezer", hit)++ Expect(err).ToNot(HaveOccurred())+ Expect(r).ToNot(BeNil())+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "external:deezer", Outcome: OutcomeHit, Detail: "http://img"},+ }))+ })++ It("records a miss for a not-found", func() {+ t := &ChainTrace{}+ _, _, _ = tracingGate(t, passthroughGate)("deezer", miss)+ Expect(t.Steps()[0].Outcome).To(Equal(OutcomeMiss))+ })++ It("records a miss for a model not-found", func() {+ t := &ChainTrace{}+ notFound := func() (io.ReadCloser, string, error) { return nil, "", model.ErrNotFound }+ _, _, _ = tracingGate(t, passthroughGate)("deezer", notFound)+ Expect(t.Steps()[0].Outcome).To(Equal(OutcomeMiss),+ "both not-found flavours are definitive answers, not faults")+ })++ It("records an error with its reason", func() {+ t := &ChainTrace{}+ _, _, _ = tracingGate(t, passthroughGate)("apple-music", boom)+ Expect(t.Steps()[0].Outcome).To(Equal(OutcomeError))+ Expect(t.Steps()[0].Detail).To(ContainSubstring("429"))+ })++ It("never calls the agent in offline mode", func() {+ t := &ChainTrace{}+ called := false+ counting := func() (io.ReadCloser, string, error) {+ called = true+ return hit()+ }++ _, _, err := offlineGate(t)("deezer", counting)++ Expect(called).To(BeFalse(), "offline mode must not perform external requests")+ Expect(err).To(MatchError(errOfflineSkipped))+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "external:deezer", Outcome: OutcomeWouldTry},+ }))+ })+})++var _ = Describe("resolveAlbum tracing", func() {+ var (+ ctx context.Context+ ds *tests.MockDataStore+ albumRepo *tests.MockAlbumRepo+ folderRepo *fakeFolderRepo+ ffm *tests.MockFFmpeg+ ag *agents.Agents+ t *ChainTrace+ )++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.CoverArtPriority = "cover.jpg, embedded"+ repoRoot, err := os.Getwd()+ Expect(err).ToNot(HaveOccurred())+ libRepo := &tests.MockLibraryRepo{}+ libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})+ albumRepo = tests.CreateMockAlbumRepo()+ folderRepo = &fakeFolderRepo{}+ ds = &tests.MockDataStore{+ MockedAlbum: albumRepo,+ MockedFolder: folderRepo,+ MockedLibrary: libRepo,+ }+ ffm = tests.NewMockFFmpeg("")+ ag = agents.GetAgents(&tests.MockDataStore{}, nil)+ t = &ChainTrace{}+ ctx = withTrace(context.Background(), t)+ })++ It("records a pattern skipped because the album folder holds no images", func() {+ albumRepo.SetData(model.Albums{+ {ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},+ })++ res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al1"})+ Expect(err).ToNot(HaveOccurred())+ Expect(res.reader).ToNot(BeNil())+ defer res.reader.Close()+ Expect(t.Steps()).To(HaveLen(2), "a configured pattern must appear even when the chain never evaluated it")+ Expect(t.Steps()[0]).To(Equal(TraceStep{+ Candidate: "cover.jpg", Outcome: OutcomeSkipped, Detail: "no images in album folder",+ }))+ Expect(t.Steps()[1].Candidate).To(Equal("embedded"))+ Expect(t.Steps()[1].Outcome).To(Equal(OutcomeHit))+ })++ It("records an evaluated pattern that matched nothing as a miss, not a skip", func() {+ folderRepo.result = []model.Folder{{+ Path: "tests/fixtures/artist/an-album",+ ImageFiles: []string{"artist.png"},+ }}+ albumRepo.SetData(model.Albums{+ {ID: "al3", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"}},+ })++ res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al3"})+ Expect(err).ToNot(HaveOccurred())+ Expect(res.reader).ToNot(BeNil())+ defer res.reader.Close()+ Expect(t.Steps()[0]).To(Equal(TraceStep{Candidate: "cover.jpg", Outcome: OutcomeMiss}),+ "the folder was searched and held no cover.jpg, which is not the same as never looking")+ })++ It("ignores an empty priority token", func() {+ conf.Server.CoverArtPriority = "cover.jpg,"+ albumRepo.SetData(model.Albums{{ID: "al2", Name: "Album", FolderIDs: []string{"f1"}}})++ _, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "al", ItemID: "al2"})+ Expect(err).ToNot(HaveOccurred())+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "cover.jpg", Outcome: OutcomeSkipped, Detail: "no images in album folder"},+ }))+ })+})++var _ = Describe("resolveArtist tracing", func() {+ var (+ ctx context.Context+ ds *tests.MockDataStore+ artistRepo *tests.MockArtistRepo+ albumRepo *tests.MockAlbumRepo+ folderRepo *fakeFolderRepo+ ffm *tests.MockFFmpeg+ ag *agents.Agents+ t *ChainTrace+ repoRoot string+ )++ uploadPath := func(file string) string {+ path := model.UploadedImagePath(consts.EntityArtist, file)+ Expect(os.MkdirAll(filepath.Dir(path), 0o755)).To(Succeed())+ Expect(os.WriteFile(path, []byte("uploaded artist image"), 0o600)).To(Succeed())+ return path+ }++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.DataFolder = conf.NewDir(GinkgoT().TempDir())+ conf.Server.ArtistArtPriority = "album/artist.*"+ var err error+ repoRoot, err = os.Getwd()+ Expect(err).ToNot(HaveOccurred())+ libRepo := &tests.MockLibraryRepo{}+ libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})+ artistRepo = tests.CreateMockArtistRepo()+ albumRepo = tests.CreateMockAlbumRepo()+ folderRepo = &fakeFolderRepo{}+ ds = &tests.MockDataStore{+ MockedArtist: artistRepo,+ MockedAlbum: albumRepo,+ MockedFolder: folderRepo,+ MockedLibrary: libRepo,+ }+ ffm = tests.NewMockFFmpeg("")+ ag = agents.GetAgents(&tests.MockDataStore{}, nil)+ t = &ChainTrace{}+ ctx = withTrace(context.Background(), t)+ })++ It("records the upload short-circuit as a hit", func() {+ path := uploadPath("ar1_test.jpg")+ artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist", UploadedImage: "ar1_test.jpg"}})++ res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar1"})+ Expect(err).ToNot(HaveOccurred())+ Expect(res.reader).ToNot(BeNil())+ defer res.reader.Close()+ Expect(t.Steps()).To(Equal([]TraceStep{{Candidate: "upload", Outcome: OutcomeHit, Detail: path}}))+ })++ It("records an upload miss before walking the chain", func() {+ artistRepo.SetData(model.Artists{{ID: "ar2", Name: "Artist"}})++ _, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar2"})+ Expect(err).ToNot(HaveOccurred())+ Expect(t.Steps()[0]).To(Equal(TraceStep{Candidate: "upload", Outcome: OutcomeMiss}))+ })++ It("labels each step with the configured priority token", func() {+ folderRepo.result = []model.Folder{{+ LibraryPath: testFileLibPath(repoRoot),+ Path: "tests/fixtures/artist/an-album",+ ImageFiles: []string{"artist.png"},+ }}+ artistRepo.SetData(model.Artists{{ID: "ar4", Name: "Artist"}})+ albumRepo.All = model.Albums{{ID: "al9", Name: "Album", LibraryID: 0, FolderIDs: []string{"f1"}}}++ res, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar4"})+ Expect(err).ToNot(HaveOccurred())+ Expect(res.reader).ToNot(BeNil())+ defer res.reader.Close()+ Expect(t.Steps()).To(HaveLen(2))+ Expect(t.Steps()[1].Candidate).To(Equal("album/artist.*"),+ "the step must be labelled with the priority token, not the pattern it was rewritten into")+ Expect(t.Steps()[1].Outcome).To(Equal(OutcomeHit))+ Expect(filepath.ToSlash(t.Steps()[1].Detail)).To(HaveSuffix("tests/fixtures/artist/an-album/artist.png"))+ })++ It("records a configured pattern that could not be evaluated", func() {+ artistRepo.SetData(model.Artists{{ID: "ar5", Name: "Artist"}})++ _, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar5"})+ Expect(err).ToNot(HaveOccurred())+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "upload", Outcome: OutcomeMiss},+ {Candidate: "album/artist.*", Outcome: OutcomeSkipped, Detail: "artist has no albums"},+ }), "a configured pattern that was never evaluated must still appear, and say why")+ })++ It("records why an artist folder pattern was skipped", func() {+ conf.Server.ArtistArtPriority = "artist.*"+ artistRepo.SetData(model.Artists{{ID: "ar6", Name: "Artist"}})+ albumRepo.All = model.Albums{{ID: "al10", Name: "Album", LibraryID: 0, FolderIDs: []string{"f1"}}}++ _, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar6"})+ Expect(err).ToNot(HaveOccurred())+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "upload", Outcome: OutcomeMiss},+ {Candidate: "artist.*", Outcome: OutcomeSkipped, Detail: "no artist folder"},+ }))+ })++ It("records an upload that exists but cannot be read as unreadable", func() {+ if runtime.GOOS == "windows" {+ Skip("chmod does not restrict read access on Windows")+ }+ path := uploadPath("ar3_test.jpg")+ Expect(os.Chmod(path, 0o000)).To(Succeed())+ DeferCleanup(func() { _ = os.Chmod(path, 0o600) })+ artistRepo.SetData(model.Artists{{ID: "ar3", Name: "Artist", UploadedImage: "ar3_test.jpg"}})++ _, err := newResolver(ds, ag, ffm, nil).resolve(ctx, model.ArtworkQueueItem{ItemKind: "ar", ItemID: "ar3"})+ Expect(err).ToNot(HaveOccurred())+ Expect(t.Steps()).To(HaveLen(1))+ Expect(t.Steps()[0].Outcome).To(Equal(OutcomeUnreadable),+ "an upload that exists and will not open must not look like an absent upload")+ })+})++var _ = Describe("NewTracingResolver", func() {+ var (+ ds *tests.MockDataStore+ albumRepo *tests.MockAlbumRepo+ artistRepo *tests.MockArtistRepo+ artworkRepo *tests.MockArtworkRepo+ queueRepo *tests.MockArtworkQueueRepo+ ffm *tests.MockFFmpeg+ t *ChainTrace+ )++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.DataFolder = conf.NewDir(GinkgoT().TempDir())+ conf.Server.CoverArtPriority = "external, embedded"+ conf.Server.ArtistArtPriority = "external"+ repoRoot, err := os.Getwd()+ Expect(err).ToNot(HaveOccurred())+ libRepo := &tests.MockLibraryRepo{}+ libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})+ albumRepo = tests.CreateMockAlbumRepo()+ artistRepo = tests.CreateMockArtistRepo()+ artworkRepo = tests.CreateMockArtworkRepo()+ queueRepo = tests.CreateMockArtworkQueueRepo()+ ds = &tests.MockDataStore{+ MockedAlbum: albumRepo,+ MockedArtist: artistRepo,+ MockedFolder: &fakeFolderRepo{},+ MockedLibrary: libRepo,+ MockedArtwork: artworkRepo,+ MockedArtworkQueue: queueRepo,+ }+ ffm = tests.NewMockFFmpeg("")+ t = &ChainTrace{}+ })++ Context("offline", func() {+ var fake *fakeImageAgent++ BeforeEach(func() {+ fake = &fakeImageAgent{name: "offline-probe"}+ albumRepo.SetData(model.Albums{{+ ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"},+ }})+ artistRepo.SetData(model.Artists{{ID: "ar1", Name: "Artist"}})+ })++ It("reports the external tier without asking any agent", func() {+ source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")++ Expect(err).ToNot(HaveOccurred())+ Expect(source).To(Equal("embedded"))+ Expect(fake.albumCalls).To(BeZero(), "offline mode must not add load to an external provider")+ Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:offline-probe", Outcome: OutcomeWouldTry}))+ })++ It("records the local chain steps too", func() {+ _, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")++ Expect(err).ToNot(HaveOccurred())+ last := t.Steps()[len(t.Steps())-1]+ Expect(last.Candidate).To(Equal("embedded"), "the local chain must be traced, not just the external gate")+ Expect(last.Outcome).To(Equal(OutcomeHit))+ })++ It("never persists artwork state", func() {+ _, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al1")++ Expect(err).ToNot(HaveOccurred())+ Expect(artworkRepo.ItemData).To(BeEmpty(),+ "an offline resolution carries extError, which must never be recorded as a real provider failure")+ Expect(queueRepo.Data).To(BeEmpty())+ })++ It("resolves an artist without persisting anything", func() {+ source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindArtistArtwork, "ar1")++ Expect(err).ToNot(HaveOccurred())+ Expect(source).To(BeEmpty())+ Expect(fake.artistCalls).To(BeZero())+ Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:offline-probe", Outcome: OutcomeWouldTry}))+ Expect(artworkRepo.ItemData).To(BeEmpty())+ Expect(queueRepo.Data).To(BeEmpty())+ })++ It("closes the reader it does not hand back", func() {+ conf.Server.CoverArtPriority = "embedded"+ ffm = tests.NewMockFFmpeg("fake image bytes")+ albumRepo.SetData(model.Albums{{+ ID: "al2", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/no-such-file.mp3", FolderIDs: []string{"f1"},+ }})++ source, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "al2")++ Expect(err).ToNot(HaveOccurred())+ Expect(source).To(Equal("embedded"))+ Expect(ffm.IsClosed()).To(BeTrue(), "nothing downstream closes it, so a leak is one file handle per invocation")+ })++ It("propagates a lookup error", func() {+ _, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, false).Resolve(context.Background(), model.KindAlbumArtwork, "nope")+ Expect(err).To(MatchError(model.ErrNotFound))+ })+ })++ It("asks the agents when live is true", func() {+ fake := &fakeImageAgent{name: "live-probe", err: agents.ErrNotFound}+ albumRepo.SetData(model.Albums{{+ ID: "al1", Name: "Album", EmbedArtPath: "tests/fixtures/artist/an-album/test.mp3", FolderIDs: []string{"f1"},+ }})++ _, err := NewTracingResolver(ds, imageAgents(fake), ffm, t, true).Resolve(context.Background(), model.KindAlbumArtwork, "al1")++ Expect(err).ToNot(HaveOccurred())+ Expect(fake.albumCalls).To(Equal(1))+ Expect(t.Steps()).To(ContainElement(TraceStep{Candidate: "external:live-probe", Outcome: OutcomeMiss}))+ })+})++var _ = Describe("resolveDisc tracing", func() {+ var (+ ctx context.Context+ ds *tests.MockDataStore+ albumRepo *tests.MockAlbumRepo+ folderRepo *fakeFolderRepo+ ffm *tests.MockFFmpeg+ t *ChainTrace+ )++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ repoRoot, err := os.Getwd()+ Expect(err).ToNot(HaveOccurred())+ libRepo := &tests.MockLibraryRepo{}+ libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})+ albumRepo = tests.CreateMockAlbumRepo()+ albumRepo.SetData(model.Albums{{ID: "al1", Name: "Album", FolderIDs: []string{"f1"}}})+ folderRepo = &fakeFolderRepo{}+ mfRepo := tests.CreateMockMediaFileRepo()+ mfRepo.SetData(model.MediaFiles{{ID: "mf1", AlbumID: "al1", DiscNumber: 2, Path: "tests/fixtures/artist/an-album/test.mp3"}})+ ds = &tests.MockDataStore{+ MockedAlbum: albumRepo,+ MockedMediaFile: mfRepo,+ MockedFolder: folderRepo,+ MockedLibrary: libRepo,+ }+ ffm = tests.NewMockFFmpeg("")+ t = &ChainTrace{}+ ctx = withTrace(context.Background(), t)+ })++ It("accounts for every configured entry, including the ones that map to no source", func() {+ conf.Server.DiscArtPriority = "external, discsubtitle, cover.jpg"++ res, err := newResolver(ds, nil, ffm, nil).resolveDisc(ctx, model.DiscArtworkID("al1", 2))++ Expect(err).ToNot(HaveOccurred())+ Expect(res.reader).To(BeNil())+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "external", Outcome: OutcomeSkipped, Detail: "external sources are not supported for disc artwork"},+ {Candidate: "discsubtitle", Outcome: OutcomeSkipped, Detail: "disc has no subtitle"},+ {Candidate: "cover.jpg", Outcome: OutcomeSkipped, Detail: "no images in album folder"},+ }))+ })++ It("records the entry that won and stops there", func() {+ conf.Server.DiscArtPriority = "disc*.*, cover.jpg, embedded"+ folderRepo.result = []model.Folder{{+ Path: "tests/fixtures/artist/an-album",+ ImageFiles: []string{"cover.jpg"},+ }}++ res, err := newResolver(ds, nil, ffm, nil).resolveDisc(ctx, model.DiscArtworkID("al1", 2))++ Expect(err).ToNot(HaveOccurred())+ Expect(res.reader).ToNot(BeNil())+ defer res.reader.Close()+ Expect(res.source).To(Equal("folder"))+ Expect(t.Steps()).To(HaveLen(2), "the walk must stop at the winner, and record nothing below it")+ Expect(t.Steps()[0]).To(Equal(TraceStep{Candidate: "disc*.*", Outcome: OutcomeMiss}))+ Expect(t.Steps()[1].Candidate).To(Equal("cover.jpg"))+ Expect(t.Steps()[1].Outcome).To(Equal(OutcomeHit))+ Expect(t.Steps()[1].Detail).To(HaveSuffix(filepath.FromSlash("tests/fixtures/artist/an-album/cover.jpg")))+ Expect(t.Steps()[1].Detail).ToNot(Equal("tests/fixtures/artist/an-album/cover.jpg"),+ "a library-relative path sends the operator looking in the wrong place")+ })++ It("reports an unparseable disc id rather than explaining another disc", func() {+ conf.Server.DiscArtPriority = "cover.jpg"+ _, err := newResolver(ds, nil, ffm, nil).resolveDisc(ctx, "al1")+ Expect(err).To(HaveOccurred())+ })+})++var _ = Describe("resolveMediaFile tracing", func() {+ var (+ ctx context.Context+ ds *tests.MockDataStore+ mfRepo *tests.MockMediaFileRepo+ ffm *tests.MockFFmpeg+ t *ChainTrace+ )++ BeforeEach(func() {+ DeferCleanup(configtest.SetupConfig())+ conf.Server.EnableMediaFileCoverArt = true+ repoRoot, err := os.Getwd()+ Expect(err).ToNot(HaveOccurred())+ libRepo := &tests.MockLibraryRepo{}+ libRepo.SetData(model.Libraries{{ID: 0, Path: testFileLibPath(repoRoot)}})+ mfRepo = tests.CreateMockMediaFileRepo()+ mfRepo.SetData(model.MediaFiles{{+ ID: "mf1", Title: "Song", HasCoverArt: true, Path: "tests/fixtures/artist/an-album/test.mp3",+ }})+ ds = &tests.MockDataStore{MockedMediaFile: mfRepo, MockedLibrary: libRepo}+ ffm = tests.NewMockFFmpeg("")+ t = &ChainTrace{}+ ctx = withTrace(context.Background(), t)+ })++ It("separates a disabled setting from a track with nothing embedded", func() {+ conf.Server.EnableMediaFileCoverArt = false++ _, err := newResolver(ds, nil, ffm, nil).resolveMediaFile(ctx, "mf1")++ Expect(err).ToNot(HaveOccurred())+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "embedded", Outcome: OutcomeSkipped, Detail: "EnableMediaFileCoverArt is off"},+ }))+ })++ It("records a track with no embedded art as a miss", func() {+ mfRepo.SetData(model.MediaFiles{{ID: "mf2", Title: "Song", HasCoverArt: false}})++ _, err := newResolver(ds, nil, ffm, nil).resolveMediaFile(ctx, "mf2")++ Expect(err).ToNot(HaveOccurred())+ Expect(t.Steps()).To(Equal([]TraceStep{+ {Candidate: "embedded", Outcome: OutcomeMiss, Detail: "the track has no embedded cover art"},+ }))+ })++ It("records the embedded hit", func() {+ res, err := newResolver(ds, nil, ffm, nil).resolveMediaFile(ctx, "mf1")++ Expect(err).ToNot(HaveOccurred())+ Expect(res.reader).ToNot(BeNil())+ defer res.reader.Close()+ Expect(res.source).To(Equal("embedded"))+ Expect(t.Steps()).To(HaveLen(1))+ Expect(t.Steps()[0].Outcome).To(Equal(OutcomeHit))+ })+})diff --git a/core/artwork/worker.go b/core/artwork/worker.goindex 3ded52629..be8495305 100644--- a/core/artwork/worker.go+++ b/core/artwork/worker.go@@ -137,7 +137,7 @@ func (w *Worker) Backfill(ctx context.Context) (bool, error) {return backfill(ctx, w.proc.ds)}-// EnqueueStaleAbsentAll requeues known-absent entries older than staleAbsentAge.+// EnqueueStaleAbsentAll requeues known-absent entries older than StaleAbsentAge.func (w *Worker) EnqueueStaleAbsentAll(ctx context.Context) error {return enqueueStaleAbsentAll(ctx, w.proc.ds)}diff --git a/core/artwork/worker_test.go b/core/artwork/worker_test.goindex 9fad4b503..53b6a43b2 100644--- a/core/artwork/worker_test.go+++ b/core/artwork/worker_test.go@@ -362,7 +362,7 @@ var _ = Describe("Worker", func() {Expect(ia.Hash).To(Equal("cafebabe"), "a persistent outage must not discard served art")})- // Media files are excluded from recheckKinds, so an absent row here would never be+ // Media files are excluded from RecheckKinds, so an absent row here would never be// revisited: a transient read error would look permanent.It("does not settle absent on exhaustion for a kind with no recheck path", func() {conf.Server.EnableMediaFileCoverArt = truediff --git a/model/artwork.go b/model/artwork.goindex 87b424f33..ea724265a 100644--- a/model/artwork.go+++ b/model/artwork.go@@ -119,6 +119,8 @@ type ArtworkRepository interface {}type ArtworkQueueRepository interface {+ // Get returns the pending row for an item, or ErrNotFound when it is not queued.+ Get(kind Kind, id, imageType string) (*ArtworkQueueItem, error)// Enqueue upserts; an existing row keeps the higher priority and has its retry_at reset.Enqueue(items ...ArtworkQueueItem) error// EnqueuePreservingBackoff upserts like Enqueue but preserves an existing row's retry_at, so a@@ -130,6 +132,14 @@ type ArtworkQueueRepository interface {EnqueueAllMissing(kind Kind, priority int) (int64, error)// EnqueueIfMissing inserts only for items with no item_artwork row yet.EnqueueIfMissing(items ...ArtworkQueueItem) error+ // CountBySource reports how many items of a kind currently resolve from the given sources.+ // An empty sources slice means every source; "" matches absent state.+ CountBySource(kind Kind, sources []string) (int64, error)+ // SourcesInUse lists the distinct sources items of a kind currently resolve from, "" included.+ SourcesInUse(kind Kind) ([]string, error)+ // EnqueueBySource inserts queue rows for items of a kind whose current source matches.+ // It does not clear existing artwork state: the current image stays until it is replaced.+ EnqueueBySource(kind Kind, sources []string, priority int) (int64, error)// DequeueBatch returns up to n items with retry_at <= now, priority desc, enqueued_at asc.// Restricted to the given kinds when any are passed, so one kind cannot block another's drain.DequeueBatch(n int, kinds ...string) ([]ArtworkQueueItem, error)@@ -139,6 +149,22 @@ type ArtworkQueueRepository interface {// DeleteIfUnchanged deletes only while retry_at still matches, sparing a concurrent re-enqueue.DeleteIfUnchanged(kind, id, imageType string, retryAt time.Time) errorCount() (int64, error)+ // CountByKindAndPriority reports the pending queue rows grouped by kind and priority.+ CountByKindAndPriority() ([]ArtworkQueueStat, error)+ // CountAbsent reports the absent states of a kind, and how many of those EnqueueStaleAbsent+ // would pick up at the given cutoff.+ CountAbsent(kind Kind, attemptedBefore time.Time) (ArtworkAbsentStat, error)// PurgeDangling removes queue rows whose entity no longer exists.PurgeDangling() (int64, error)}++type ArtworkQueueStat struct {+ ItemKind string+ Priority int+ Count int64+}++type ArtworkAbsentStat struct {+ Total int64+ Stale int64+}diff --git a/persistence/artwork_queue_repository.go b/persistence/artwork_queue_repository.goindex e5469fbea..1ff754dc3 100644--- a/persistence/artwork_queue_repository.go+++ b/persistence/artwork_queue_repository.go@@ -10,6 +10,7 @@ import (. "github.com/Masterminds/squirrel""github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/utils/slice""github.com/pocketbase/dbx")@@ -31,6 +32,16 @@ func NewArtworkQueueRepository(ctx context.Context, db dbx.Builder) model.Artworreturn r}+func (r *artworkQueueRepository) Get(kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {+ var res model.ArtworkQueueItem+ err := r.queryOne(Select("*").From(r.tableName).+ Where(Eq{"item_kind": kind.Prefix(), "item_id": id, "image_type": imageType}), &res)+ if err != nil {+ return nil, err+ }+ return &res, nil+}+// Enqueue also resets enqueued_at, so a fresh request does not inherit an old row's spent retry budget.func (r *artworkQueueRepository) Enqueue(items ...model.ArtworkQueueItem) error {return r.enqueue(`ON CONFLICT (item_kind, item_id, image_type) DO UPDATE SET@@ -87,12 +98,49 @@ func (r *artworkQueueRepository) EnqueueIfMissing(items ...model.ArtworkQueueItereturn nil}-// insertIfNotQueued inserts the rows selected by the given SQL, optionally prefixed by a CTE. DO NOTHING is-// deliberate: a recheck must not bump the priority or retry_at of an already-queued item.+// DO NOTHING is deliberate: a recheck must not bump the priority or retry_at of an already-queued item.+const skipIfQueued = ` ON CONFLICT (item_kind, item_id, image_type) DO NOTHING`++// insertIfNotQueued inserts the rows selected by the given SQL, optionally prefixed by a CTE.func (r *artworkQueueRepository) insertIfNotQueued(with, sql string, args ...any) (int64, error) {return r.executeSQL(Expr(with+`INSERT INTO `+r.tableName+- ` (`+strings.Join(enqueueColumns, ", ")+`) `+sql+- ` ON CONFLICT (item_kind, item_id, image_type) DO NOTHING`, args...))+ ` (`+strings.Join(enqueueColumns, ", ")+`) `+sql+skipIfQueued, args...))+}++// artworkSourceFilter selects item_artwork rows of a kind; no sources means every source, "" the absent state.+func artworkSourceFilter(kind model.Kind, sources []string) Sqlizer {+ f := And{Eq{"item_kind": kind.Prefix()}}+ if len(sources) > 0 {+ f = append(f, Eq{"source": sources})+ }+ return f+}++func (r *artworkQueueRepository) CountBySource(kind model.Kind, sources []string) (int64, error) {+ var res struct{ Count int64 }+ err := r.queryOne(Select("count(*) as count").From(itemArtworkTable).+ Where(artworkSourceFilter(kind, sources)), &res)+ return res.Count, err+}++func (r *artworkQueueRepository) SourcesInUse(kind model.Kind) ([]string, error) {+ var res []struct{ Source string }+ err := r.queryAll(Select("distinct source").From(itemArtworkTable).+ Where(Eq{"item_kind": kind.Prefix()}), &res)+ if err != nil {+ return nil, err+ }+ return slice.Map(res, func(s struct{ Source string }) string { return s.Source }), nil+}++// EnqueueBySource deliberately leaves item_artwork alone: clearing state in bulk would blank the+// library's artwork until every item is resolved again.+func (r *artworkQueueRepository) EnqueueBySource(kind model.Kind, sources []string, priority int) (int64, error) {+ now := time.Now()+ sel := Select("item_kind", "item_id", "image_type").+ Column(Expr("?", priority)).Column("0").Column(Expr("?", now)).Column(Expr("?", now)).+ From(itemArtworkTable).Where(artworkSourceFilter(kind, sources))+ return r.executeSQL(Insert(r.tableName).Columns(enqueueColumns...).Select(sel).Suffix(skipIfQueued))}func (r *artworkQueueRepository) enqueue(conflict string, items []model.ArtworkQueueItem) error {@@ -146,4 +194,20 @@ func (r *artworkQueueRepository) Count() (int64, error) {return res.Count, err}+func (r *artworkQueueRepository) CountByKindAndPriority() ([]model.ArtworkQueueStat, error) {+ var res []model.ArtworkQueueStat+ err := r.queryAll(Select("item_kind", "priority", "count(*) as count").From(r.tableName).+ GroupBy("item_kind", "priority").OrderBy("item_kind", "priority desc"), &res)+ return res, err+}++// CountAbsent matches EnqueueStaleAbsent on hash, so the stale count is what a recheck would queue.+func (r *artworkQueueRepository) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {+ var res model.ArtworkAbsentStat+ err := r.queryOne(Select("count(*) as total").+ Column(Expr("coalesce(sum(attempted_at < ?), 0) as stale", attemptedBefore)).+ From(itemArtworkTable).Where(Eq{"item_kind": kind.Prefix(), "hash": ""}), &res)+ return res, err+}+var _ model.ArtworkQueueRepository = (*artworkQueueRepository)(nil)diff --git a/persistence/artwork_queue_repository_test.go b/persistence/artwork_queue_repository_test.goindex 6638a204e..d11d89a1f 100644--- a/persistence/artwork_queue_repository_test.go+++ b/persistence/artwork_queue_repository_test.go@@ -54,6 +54,22 @@ var _ = Describe("ArtworkQueueRepository", func() {Expect(got[0].ItemID).To(Equal("high"))})+ It("Get returns a queued row, including one still backing off", func() {+ Expect(repo.Enqueue(item("ar", "g1", model.ArtworkPriorityScan))).To(Succeed())+ backOff("ar", "g1", time.Now().Add(time.Hour))++ got, err := repo.Get(model.KindArtistArtwork, "g1", model.ImageTypePrimary)+ Expect(err).ToNot(HaveOccurred())+ Expect(got.Priority).To(Equal(model.ArtworkPriorityScan))+ Expect(got.Attempts).To(Equal(1))+ Expect(got.RetryAt).To(BeTemporally(">", time.Now()))+ })++ It("Get reports ErrNotFound when the item is not queued", func() {+ _, err := repo.Get(model.KindArtistArtwork, "nope", model.ImageTypePrimary)+ Expect(err).To(MatchError(model.ErrNotFound))+ })+It("keeps the higher priority on duplicate enqueue", func() {Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBump))).To(Succeed())Expect(repo.Enqueue(item("al", "a1", model.ArtworkPriorityBackfill))).To(Succeed())@@ -265,6 +281,89 @@ var _ = Describe("ArtworkQueueRepository", func() {Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump), "the existing priority must survive")})+ Describe("EnqueueBySource", func() {+ BeforeEach(func() {+ artRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())+ for _, ia := range []model.ItemArtwork{+ {ItemKind: "ar", ItemID: "ar1", ImageType: model.ImageTypePrimary, Hash: "h1", Source: "external:deezer"},+ {ItemKind: "ar", ItemID: "ar2", ImageType: model.ImageTypePrimary, Hash: "h2", Source: "external:lastfm"},+ {ItemKind: "ar", ItemID: "ar3", ImageType: model.ImageTypePrimary, Hash: "", Source: ""},+ {ItemKind: "al", ItemID: "al1", ImageType: model.ImageTypePrimary, Hash: "h4", Source: "external:deezer"},+ } {+ Expect(artRepo.PutItemArtwork(&ia)).To(Succeed())+ }+ })++ It("enqueues only the matching source within the kind", func() {+ n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)+ Expect(err).ToNot(HaveOccurred())+ Expect(n).To(Equal(int64(1)), "al1 is a different kind and must not be touched")++ got, err := repo.DequeueBatch(10)+ Expect(err).ToNot(HaveOccurred())+ Expect(slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })).To(ConsistOf("ar1"))+ })++ It("treats the empty source as absent", func() {+ n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{""}, model.ArtworkPriorityRecheck)+ Expect(err).ToNot(HaveOccurred())+ Expect(n).To(Equal(int64(1)))++ got, _ := repo.DequeueBatch(10)+ Expect(slice.Map(got, func(it model.ArtworkQueueItem) string { return it.ItemID })).To(ConsistOf("ar3"))+ })++ It("enqueues every source when none is given", func() {+ n, err := repo.EnqueueBySource(model.KindArtistArtwork, nil, model.ArtworkPriorityRecheck)+ Expect(err).ToNot(HaveOccurred())+ Expect(n).To(Equal(int64(3)))+ })++ It("leaves the current artwork state in place", func() {+ _, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)+ Expect(err).ToNot(HaveOccurred())++ artRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())+ ia, err := artRepo.GetItemArtwork(model.KindArtistArtwork, "ar1", model.ImageTypePrimary)+ Expect(err).ToNot(HaveOccurred())+ Expect(ia.Hash).To(Equal("h1"), "the current image must survive until it is replaced")+ Expect(ia.Source).To(Equal("external:deezer"))+ })++ It("does not disturb an already-queued row", func() {+ Expect(repo.Enqueue(item("ar", "ar1", model.ArtworkPriorityBump))).To(Succeed())++ n, err := repo.EnqueueBySource(model.KindArtistArtwork, []string{"external:deezer"}, model.ArtworkPriorityRecheck)+ Expect(err).ToNot(HaveOccurred())+ Expect(n).To(BeZero())++ got, _ := repo.DequeueBatch(10)+ Expect(got).To(HaveLen(1))+ Expect(got[0].Priority).To(Equal(model.ArtworkPriorityBump))+ })++ It("counts without enqueueing", func() {+ n, err := repo.CountBySource(model.KindArtistArtwork, []string{"external:deezer"})+ Expect(err).ToNot(HaveOccurred())+ Expect(n).To(Equal(int64(1)))++ queued, err := repo.Count()+ Expect(err).ToNot(HaveOccurred())+ Expect(queued).To(BeZero(), "CountBySource must not enqueue")+ })++ It("counts the absent source and every source", func() {+ Expect(repo.CountBySource(model.KindArtistArtwork, []string{""})).To(Equal(int64(1)))+ Expect(repo.CountBySource(model.KindArtistArtwork, nil)).To(Equal(int64(3)))+ })++ It("lists the distinct sources in use by a kind", func() {+ Expect(repo.SourcesInUse(model.KindArtistArtwork)).To(ConsistOf("", "external:deezer", "external:lastfm"))+ Expect(repo.SourcesInUse(model.KindAlbumArtwork)).To(ConsistOf("external:deezer"))+ Expect(repo.SourcesInUse(model.KindRadioArtwork)).To(BeEmpty())+ })+ })+It("does not disturb an already-queued entity when enqueueing missing rows", func() {Expect(repo.Enqueue(item("al", albumRadioactivity.ID, model.ArtworkPriorityBump))).To(Succeed())@@ -281,4 +380,43 @@ var _ = Describe("ArtworkQueueRepository", func() {}Expect(count).To(Equal(1), "the already-queued row must not be duplicated")})++ Describe("status counters", func() {+ It("groups queue rows by kind and priority", func() {+ Expect(repo.Enqueue(item("ar", "a1", model.ArtworkPriorityBackfill))).To(Succeed())+ Expect(repo.Enqueue(item("ar", "a2", model.ArtworkPriorityBackfill))).To(Succeed())+ Expect(repo.Enqueue(item("ar", "a3", model.ArtworkPriorityBump))).To(Succeed())+ Expect(repo.Enqueue(item("al", "b1", model.ArtworkPriorityScan))).To(Succeed())++ Expect(repo.CountByKindAndPriority()).To(ConsistOf(+ model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBackfill, Count: 2},+ model.ArtworkQueueStat{ItemKind: "ar", Priority: model.ArtworkPriorityBump, Count: 1},+ model.ArtworkQueueStat{ItemKind: "al", Priority: model.ArtworkPriorityScan, Count: 1},+ ))+ })++ It("reports an empty queue as no rows", func() {+ Expect(repo.CountByKindAndPriority()).To(BeEmpty())+ })++ It("counts absent states and how many are due for recheck", func() {+ awRepo := NewArtworkRepository(context.Background(), GetDBXBuilder())+ old := time.Now().Add(-48 * time.Hour)+ for _, ia := range []model.ItemArtwork{+ {ItemKind: "ar", ItemID: "stale1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old},+ {ItemKind: "ar", ItemID: "fresh1", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: time.Now()},+ {ItemKind: "ar", ItemID: "found1", ImageType: model.ImageTypePrimary, Hash: "hX", AttemptedAt: old},+ {ItemKind: "al", ItemID: "stale2", ImageType: model.ImageTypePrimary, Hash: "", AttemptedAt: old},+ } {+ Expect(awRepo.PutItemArtwork(&ia)).To(Succeed())+ }++ Expect(repo.CountAbsent(model.KindArtistArtwork, time.Now().Add(-24*time.Hour))).+ To(Equal(model.ArtworkAbsentStat{Total: 2, Stale: 1}))+ })++ It("reports a kind with no absent state as zero, not as an error", func() {+ Expect(repo.CountAbsent(model.KindRadioArtwork, time.Now())).To(Equal(model.ArtworkAbsentStat{}))+ })+ })})diff --git a/server/nativeapi/artwork.go b/server/nativeapi/artwork.goindex 3583c2db7..cfd943b1f 100644--- a/server/nativeapi/artwork.go+++ b/server/nativeapi/artwork.go@@ -10,14 +10,6 @@ import ("github.com/navidrome/navidrome/model")-var refreshableArtworkKinds = []model.Kind{- model.KindAlbumArtwork,- model.KindArtistArtwork,- model.KindPlaylistArtwork,- model.KindRadioArtwork,- model.KindMediaFileArtwork,-}-func (api *Router) addArtworkRoute(r chi.Router) {r.Post("/artwork/{kind}/{id}/refresh", api.refreshArtwork())}@@ -28,7 +20,7 @@ func (api *Router) refreshArtwork() http.HandlerFunc {ctx := r.Context()kind, _ := model.ParseKind(chi.URLParam(r, "kind"))id := chi.URLParam(r, "id")- if !slices.Contains(refreshableArtworkKinds, kind) {+ if !slices.Contains(artwork.RefreshableKinds, kind) {http.Error(w, "invalid artwork kind", http.StatusBadRequest)return}diff --git a/tests/mock_artwork_queue_repo.go b/tests/mock_artwork_queue_repo.goindex 1b097ca32..c8e915daa 100644--- a/tests/mock_artwork_queue_repo.go+++ b/tests/mock_artwork_queue_repo.go@@ -7,6 +7,7 @@ import ("time""github.com/navidrome/navidrome/model"+ "github.com/navidrome/navidrome/utils/slice")type MockArtworkQueueRepo struct {@@ -25,6 +26,19 @@ func CreateMockArtworkQueueRepo() *MockArtworkQueueRepo {return &MockArtworkQueueRepo{Data: map[string]model.ArtworkQueueItem{}}}+func (m *MockArtworkQueueRepo) Get(kind model.Kind, id, imageType string) (*model.ArtworkQueueItem, error) {+ m.mu.Lock()+ defer m.mu.Unlock()+ if m.Err != nil {+ return nil, m.Err+ }+ it, ok := m.Data[iaKey(kind.Prefix(), id, imageType)]+ if !ok {+ return nil, model.ErrNotFound+ }+ return &it, nil+}+func (m *MockArtworkQueueRepo) Enqueue(items ...model.ArtworkQueueItem) error {m.mu.Lock()defer m.mu.Unlock()@@ -161,6 +175,49 @@ func (m *MockArtworkQueueRepo) Count() (int64, error) {return int64(len(m.Data)), nil}+func (m *MockArtworkQueueRepo) CountByKindAndPriority() ([]model.ArtworkQueueStat, error) {+ m.mu.Lock()+ defer m.mu.Unlock()+ if m.Err != nil {+ return nil, m.Err+ }+ var res []model.ArtworkQueueStat+ for _, it := range m.Data {+ i := slices.IndexFunc(res, func(s model.ArtworkQueueStat) bool {+ return s.ItemKind == it.ItemKind && s.Priority == it.Priority+ })+ if i < 0 {+ res = append(res, model.ArtworkQueueStat{ItemKind: it.ItemKind, Priority: it.Priority, Count: 1})+ continue+ }+ res[i].Count+++ }+ slices.SortFunc(res, func(a, b model.ArtworkQueueStat) int {+ return cmp.Or(cmp.Compare(a.ItemKind, b.ItemKind), cmp.Compare(b.Priority, a.Priority))+ })+ return res, nil+}++// CountAbsent mirrors the SQL predicate: an absent state is one with no hash.+func (m *MockArtworkQueueRepo) CountAbsent(kind model.Kind, attemptedBefore time.Time) (model.ArtworkAbsentStat, error) {+ m.mu.Lock()+ defer m.mu.Unlock()+ var res model.ArtworkAbsentStat+ if m.Err != nil || m.ItemArtworkSource == nil {+ return res, m.Err+ }+ for _, ia := range m.ItemArtworkSource.ItemData {+ if ia.ItemKind != kind.Prefix() || ia.Hash != "" {+ continue+ }+ res.Total+++ if ia.AttemptedAt.Before(attemptedBefore) {+ res.Stale+++ }+ }+ return res, nil+}+func (m *MockArtworkQueueRepo) EnqueuePreservingBackoff(items ...model.ArtworkQueueItem) error {m.mu.Lock()defer m.mu.Unlock()@@ -216,6 +273,65 @@ func (m *MockArtworkQueueRepo) EnqueueStaleAbsent(kind model.Kind, attemptedBeforeturn inserted, nil}+// matchingSource mirrors the SQL filter: no sources means every source, "" the absent state.+func (m *MockArtworkQueueRepo) matchingSource(kind model.Kind, sources []string) []model.ItemArtwork {+ if m.ItemArtworkSource == nil {+ return nil+ }+ var res []model.ItemArtwork+ for _, ia := range m.ItemArtworkSource.ItemData {+ if ia.ItemKind == kind.Prefix() && (len(sources) == 0 || slices.Contains(sources, ia.Source)) {+ res = append(res, ia)+ }+ }+ return res+}++func (m *MockArtworkQueueRepo) CountBySource(kind model.Kind, sources []string) (int64, error) {+ m.mu.Lock()+ defer m.mu.Unlock()+ if m.Err != nil {+ return 0, m.Err+ }+ return int64(len(m.matchingSource(kind, sources))), nil+}++func (m *MockArtworkQueueRepo) SourcesInUse(kind model.Kind) ([]string, error) {+ m.mu.Lock()+ defer m.mu.Unlock()+ if m.Err != nil {+ return nil, m.Err+ }+ sources := slice.Map(m.matchingSource(kind, nil), func(ia model.ItemArtwork) string { return ia.Source })+ return slice.Unique(sources), nil+}++func (m *MockArtworkQueueRepo) EnqueueBySource(kind model.Kind, sources []string, priority int) (int64, error) {+ m.mu.Lock()+ defer m.mu.Unlock()+ if m.Err != nil {+ return 0, m.Err+ }+ now := time.Now()+ var inserted int64+ for _, ia := range m.matchingSource(kind, sources) {+ k := iaKey(ia.ItemKind, ia.ItemID, ia.ImageType)+ if _, ok := m.Data[k]; ok { // DO NOTHING: never touch existing queue rows+ continue+ }+ m.Data[k] = model.ArtworkQueueItem{+ ItemKind: ia.ItemKind,+ ItemID: ia.ItemID,+ ImageType: ia.ImageType,+ Priority: priority,+ RetryAt: now,+ EnqueuedAt: now,+ }+ inserted+++ }+ return inserted, nil+}+// EnqueueMissing mirrors the SQL set-difference insert: ExistingIDs[kind] minus ItemArtworkSource.func (m *MockArtworkQueueRepo) EnqueueAllMissing(kind model.Kind, priority int) (int64, error) {m.mu.Lock()