fix(cli): estimate artwork reprocess external lookups per agent, not per item

The reprocess prompt billed one external lookup per externally-capable item.
fetchArtistImage/fetchAlbumImage try every enabled image agent and stop early
only on a hit, and resolvePlaylist can fetch the m3u image and then resolve up
to four sampled albums for the grid, each walking the album agents again. The
number the operator confirmed could understate real provider traffic several
fold, in the prompt whose whole job is to stop a provider flood.

ExternalLookupsPerItem now multiplies by the visible image-agent count and adds
the playlist grid factor. It stays a floor: the CLI never calls Manager.Start(),
so the plugin registry is empty and plugin-provided agents are dropped by
getEnabledAgentNames. On an install with 5 agents of which 3 are plugins the
count is well under the truth, so the wording is now "at least N" rather than
"up to N" — a zero visible count still bills one lookup for the same reason.

Fixing the plugin visibility is out of scope: Manager.Start() needs a Subsonic
router and writes to the DB via syncPlugins, breaking this command group's
read-only guarantee.
This commit is contained in:
Deluan 2026-08-14 16:46:02 -04:00
commit d2aa486d0c
4 changed files with 138 additions and 30 deletions

View file

@ -129,6 +129,33 @@ func MayFetchExternal(kind model.Kind) bool {
}
}
// 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 {
@ -286,6 +313,9 @@ func (r *resolver) resolveArtist(ctx context.Context, artistID string) (resoluti
return 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)
@ -331,7 +361,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
}
@ -357,7 +388,7 @@ func (r *resolver) resolvePlaylist(ctx context.Context, playlistID string) (reso
if decErr == nil {
tiles = append(tiles, tile)
}
if len(tiles) == 4 {
if len(tiles) == PlaylistGridSamples {
break
}
}

View file

@ -707,3 +707,53 @@ var _ = Describe("MayFetchExternal", func() {
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())
})
})