// Zaparoo Core // Copyright (c) 2026 The Zaparoo Project Contributors. // SPDX-License-Identifier: GPL-3.0-or-later // // This file is part of Zaparoo Core. // // Zaparoo Core is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // Zaparoo Core is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with Zaparoo Core. If not, see . package methods import ( "bytes" "context" "crypto/sha256" "database/sql" "encoding/base64" "encoding/hex" "encoding/json" "errors" "fmt" "image" "image/jpeg" "image/png" "io" "math" "net/http" "os" "path/filepath" "sort" "strings" "sync" "sync/atomic" "time" "github.com/KarpelesLab/gowebp" "github.com/ZaparooProject/zaparoo-core/v2/pkg/api/models" "github.com/ZaparooProject/zaparoo-core/v2/pkg/api/models/requests" "github.com/ZaparooProject/zaparoo-core/v2/pkg/config" "github.com/ZaparooProject/zaparoo-core/v2/pkg/database" "github.com/ZaparooProject/zaparoo-core/v2/pkg/database/tags" "github.com/ZaparooProject/zaparoo-core/v2/pkg/helpers" "github.com/ZaparooProject/zaparoo-core/v2/pkg/helpers/syncutil" "github.com/ZaparooProject/zaparoo-core/v2/pkg/helpers/wuffspng" "github.com/ZaparooProject/zaparoo-core/v2/pkg/platforms" "github.com/ZaparooProject/zaparoo-core/v2/pkg/platforms/ids" "github.com/jonboulle/clockwork" "github.com/rs/zerolog/log" "github.com/spf13/afero" "golang.org/x/image/draw" "golang.org/x/image/webp" ) const ( misterMediaImageMaxBytes = int64(2 * 1024 * 1024) defaultMediaImageMaxBytes = int64(8 * 1024 * 1024) mediaImageNoImageMax = 4096 mediaImageDeliveryInline = "inline" mediaImageDeliveryPath = "localPath" // mediaThumbCacheDirName is the sub-directory of the image folder where // resized thumbnail files are persisted across restarts. Core owns it: // reapStaleVersions removes everything in it but the live version. mediaThumbCacheDirName = config.ImageThumbsDir // mediaThumbCacheVersion identifies the on-disk encode scheme. The live cache // directory is thumbs/v; bumping this constant changes the live directory // so a new build invalidates the cache automatically (the old v dir is // reaped on start and thumbnails regenerate lazily) without users reindexing. // Bump whenever the resized output changes: format, quality, or resize // algorithm. v3 names entries after their source image instead of the media // row and encodes opaque thumbnails as JPEG; v2 grouped entries by system // for targeted invalidation; v1 // introduced lossy WebP output (replacing lossless PNG / JPEG q85). mediaThumbCacheVersion = 3 // mediaThumbWebPQuality and mediaThumbWebPMethod are the lossy VP8 settings // used to re-encode resized thumbnails with transparency. q75/method2 was // selected by benchmarking real covers as the best size/speed point: ~13x // smaller than the previous lossless-PNG output while preserving alpha, and // faster to encode than the higher methods. mediaThumbWebPQuality = 75 mediaThumbWebPMethod = 2 // mediaThumbJPEGQuality is the quality opaque thumbnails are encoded at. mediaThumbJPEGQuality = 80 ) // mediaImageSem limits concurrent image lookups so high-volume image misses do // not saturate SQLite and starve browse/status calls. MediaDB reads use a small // connection pool, so a few lookups may overlap without blocking browse. var mediaImageSem = make(chan struct{}, 3) const ( // mediaImageResizeConcurrency bounds concurrent decode/resize/encode work, // which is CPU and memory heavy and otherwise unbounded once the lookup // semaphore is released. Resource-constrained platforms resize one at a time. mediaImageResizeConcurrency = 2 mediaImageResizeConcurrencyConstrained = 1 ) // defaultMediaImageResizeSem is used when no thumbnail cache was initialised. var defaultMediaImageResizeSem = make(chan struct{}, mediaImageResizeConcurrency) var mediaImageBeforeSemAcquire func() // mediaThumbCachePointer is the process-wide thumbnail disk cache stored as an // atomic pointer so concurrent StartWithReady calls in tests do not race on it. var mediaThumbCachePointer atomic.Pointer[mediaThumbCache] const ( // mediaThumbMemoMax bounds the in-memory resolved-thumbnail memo. mediaThumbMemoMax = 8192 // The cache's size cap ([media] thumb_cache_max_mb, 1 GiB by default) is // soft and counted in allocated blocks (see thumbFileDiskBytes). Past the // cap, the reaper removes the least recently used files until the cache is // back down to mediaThumbCacheTrimPercent of it, but never one used within // mediaThumbCacheMinAge, so a day of heavy browsing can hold it above the // cap. On a MiSTer, where every thumbnail takes a 128 KiB cluster, 1 GiB // holds about 8,000. mediaThumbCacheTrimPercent = 80 // mediaThumbCacheMinAge protects recently used files from the reaper. A // hit refreshes a file's mtime once it is older than this, so a file handed // out as a local path is never reaped while a client may still read it. mediaThumbCacheMinAge = 24 * time.Hour // mediaThumbReapInterval is the least time between two orphan reaps // requested by an index or scrape completing. mediaThumbReapInterval = 24 * time.Hour // mediaThumbCapReapInterval is the least time between two orphan reaps // requested by new thumbnails taking the cache past its cap. A cache held // over the cap by recently used files would otherwise be walked on every // write. mediaThumbCapReapInterval = time.Hour // mediaThumbStartupReapDelay keeps the first orphan reap off startup. mediaThumbStartupReapDelay = 2 * time.Minute // mediaThumbTempMaxAge is the age after which a temporary file that was // never renamed into place is treated as abandoned. mediaThumbTempMaxAge = time.Hour ) // mediaThumbCache persists resized cover images to disk so that the expensive // decode+bilinear-resize+encode is only performed once per source image and // size tier. The cache survives core restarts and reboots. // // A file is named after its source, not after the media row asking for it: a // file-backed image by path, size and modification time, any other image by a // hash of its bytes. A scrape or reindex that leaves an image alone therefore // keeps its thumbnail, a changed image gets a new name and is rebuilt, and a // media DBID reused for different media can never pick up another row's file. // Nothing is wiped; files no longer referenced are left to reapOrphans, which // keeps the cache under a size cap. // // The live directory is thumbs/v — deterministic across // restarts. On start, reapStaleVersions removes any sibling that is not the // current version, so a version bump invalidates the cache and directories left // by older builds are reaped. Files are sharded by the first two hex characters // of their name so no single directory grows large. // // resolved maps an early key (identity+prefs+maxSize) to the file a request // resolved to. It enables a pre-semaphore cache hit that skips the entire // image-load pipeline for warm repeat requests, and is forgotten whenever an // index or scrape completes. type resolvedThumb struct { system string typeTag string path string contentType string } type mediaThumbCache struct { createdAt time.Time clock clockwork.Clock fs afero.Fs reapCtx context.Context resolved map[string]resolvedThumb resizeSem chan struct{} reapDone chan struct{} dir string reapWG sync.WaitGroup // maxBytes is the size cap; a settings change updates it in place. maxBytes atomic.Int64 // clusterBytes rounds file sizes up to the volume's allocation unit // where a stat does not report allocated blocks (Windows). clusterBytes int64 // cacheBytes is the cache's disk use as of the last reap plus every // file written since, so a write can tell when the cap is passed. cacheBytes atomic.Int64 lastReap atomic.Int64 resolvedMu syncutil.RWMutex reapMu syncutil.Mutex reaping atomic.Bool stopped bool } // resizeSemaphore returns the channel bounding concurrent resize work. func (c *mediaThumbCache) resizeSemaphore() chan struct{} { if c == nil || c.resizeSem == nil { return defaultMediaImageResizeSem } return c.resizeSem } // now reads the cache's clock; a cache built without one uses wall time. func (c *mediaThumbCache) now() time.Time { if c.clock == nil { return time.Now() } return c.clock.Now() } // mediaThumbCacheVersionDir is the basename of the live cache directory for the // current encode scheme version. func mediaThumbCacheVersionDir() string { return fmt.Sprintf("v%d", mediaThumbCacheVersion) } // mediaThumbSizeTiers are the standard thumbnail sizes a requested max_size is // snapped onto. Each distinct cached size is a separate cold resize per cover // (read source off slow storage, decode, resize, encode) and a separate entry // competing for the client's image cache, so the number of variants per cover // must stay bounded — but a single hardcoded size throws away the resolution // information clients legitimately have (CRT vs grid vs list vs detail, display // density, grid-size preferences). The ladder is the middle ground: clients // request their true ideal size and it snaps up to the nearest tier. // // Powers of two are the conventional thumbnail-cache ladder. The 32/64 tiers // support cheap low-quality placeholders on software-rendered displays. Steps // are denser at the large end (768 = 512×1.5) because wasted bytes grow with // size, and the ladder tops out near the ~680px native cover dimension — larger // requests would only upscale. 128 ≈ list/CRT, 256 ≈ small grid, 512 ≈ grid @2x // / detail @1x, 768 ≈ detail @2x. Keep ascending. var mediaThumbSizeTiers = []int32{32, 64, 128, 256, 512, 768} // snapThumbMaxSize maps a requested max_size to the smallest standard tier that // is >= the request, capping at the largest tier. This bounds the number of // cached variants per cover and enforces an upper bound on the resize dimension // (a huge request is snapped down before any decode/allocation). A non-positive // request means "full size" and is returned unchanged so no resize is performed. func snapThumbMaxSize(requested int32) int32 { if requested <= 0 { return requested } for _, tier := range mediaThumbSizeTiers { if requested <= tier { return tier } } return mediaThumbSizeTiers[len(mediaThumbSizeTiers)-1] } // mediaImageDir is the configured image folder. A nil config, which only // tests pass, falls back to the default under the data directory. func mediaImageDir(pl platforms.Platform, cfg *config.Instance) string { if pl == nil { return "" } dataDir := helpers.DataDir(pl) if cfg == nil { return config.ResolveImageDir("", dataDir) } return cfg.ImageDir(dataDir) } // requestImageDir is mediaImageDir for a request. func requestImageDir(env *requests.RequestEnv) string { return mediaImageDir(env.Platform, env.Config) } // mediaThumbCacheDir is the live cache directory under the image folder. func mediaThumbCacheDir(pl platforms.Platform, cfg *config.Instance) string { return filepath.Join(mediaImageDir(pl, cfg), mediaThumbCacheDirName, mediaThumbCacheVersionDir()) } // mediaThumbCacheMaxBytes is the configured size cap of the cache. func mediaThumbCacheMaxBytes(cfg *config.Instance) int64 { if cfg == nil { return int64(config.DefaultThumbCacheMaxMB) << 20 } return cfg.ThumbCacheMaxBytes() } func newMediaThumbCacheWithFS(pl platforms.Platform, cfg *config.Instance, fs afero.Fs) *mediaThumbCache { if fs == nil { fs = afero.NewOsFs() } dir := mediaThumbCacheDir(pl, cfg) concurrency := mediaImageResizeConcurrency if pl != nil && pl.Settings().ResourceConstrained { concurrency = mediaImageResizeConcurrencyConstrained } clock := clockwork.NewRealClock() cache := &mediaThumbCache{ fs: fs, clock: clock, dir: dir, resolved: make(map[string]resolvedThumb), resizeSem: make(chan struct{}, concurrency), clusterBytes: thumbCacheClusterBytes(dir), createdAt: clock.Now(), } cache.maxBytes.Store(mediaThumbCacheMaxBytes(cfg)) return cache } // reapStaleVersions ensures the live versioned directory exists and removes // every sibling under thumbs/ that is not the current version. This invalidates // the cache after a mediaThumbCacheVersion bump and reaps directories left by // an older build (earlier versions and their moved-aside wipe directories). // // It runs in the background while requests are served, so it only removes // temporary files older than the cache itself: a temporary file written by a // live request is left to its own rename or cleanup. Temporary files are never // served either way, because lookups only match final hashed names. func (c *mediaThumbCache) reapStaleVersions() { if err := c.fs.MkdirAll(c.dir, 0o750); err != nil { //nolint:gosec // cache dir, 0o750 is intentional log.Debug().Err(err).Str("dir", c.dir).Msg("media.image: thumb cache: failed to create dir") return } parent := filepath.Dir(c.dir) live := filepath.Base(c.dir) // The parent sits in a user-chosen image folder beside scraped images. // Only ever empty Core's own thumbs folder, whatever c.dir was built from. if filepath.Base(parent) != mediaThumbCacheDirName || live != mediaThumbCacheVersionDir() { log.Warn().Str("dir", c.dir).Msg("media.image: thumb cache: not reaping outside the thumbs folder") return } // A thumbs folder that is a link points somewhere Core does not own, so // its other entries are left alone. if lstater, ok := c.fs.(afero.Lstater); ok { info, _, err := lstater.LstatIfPossible(parent) if err != nil || info.Mode()&os.ModeSymlink != 0 { log.Warn().Err(err).Str("dir", parent). Msg("media.image: thumb cache: not reaping a linked thumbs folder") return } } entries, err := afero.ReadDir(c.fs, parent) if err != nil { log.Debug().Err(err).Str("dir", parent).Msg("media.image: thumb cache: failed to read parent for reap") return } for _, entry := range entries { if entry.Name() == live { continue } stale := filepath.Join(parent, entry.Name()) if err := c.fs.RemoveAll(stale); err != nil { log.Warn().Err(err).Str("dir", stale).Msg("media.image: thumb cache: failed to reap stale dir") } else { log.Debug().Str("dir", stale).Msg("media.image: thumb cache: reaped stale dir") } } if err := afero.Walk(c.fs, c.dir, func(path string, info os.FileInfo, walkErr error) error { if walkErr != nil { return walkErr } if info.IsDir() || !isThumbTempFile(info.Name()) { return nil } if !c.createdAt.IsZero() && !info.ModTime().Before(c.createdAt) { return nil } if err := c.fs.Remove(path); err != nil { log.Warn().Err(err).Str("path", path). Msg("media.image: thumb cache: failed to reap temporary file") } return nil }); err != nil { log.Warn().Err(err).Str("dir", c.dir).Msg("media.image: thumb cache: failed to reap temporary files") } } func isThumbTempFile(name string) bool { return strings.HasPrefix(name, ".thumb-") && strings.HasSuffix(name, ".tmp") } // requestReap starts a background orphan reap unless one ran within // interval, one is already running, or the cache was never started with // InitMediaThumbCache. func (c *mediaThumbCache) requestReap(interval time.Duration) { if last := c.lastReap.Load(); last != 0 && c.now().Sub(time.Unix(0, last)) < interval { return } c.reapMu.Lock() defer c.reapMu.Unlock() if c.reapCtx == nil || c.stopped { return } c.reapWG.Add(1) go func() { defer c.reapWG.Done() c.tryReapOrphans(c.reapCtx) }() } // tryReapOrphans runs reapOrphans unless another reap is already running. func (c *mediaThumbCache) tryReapOrphans(ctx context.Context) { if !c.reaping.CompareAndSwap(false, true) { return } defer c.reaping.Store(false) c.reapOrphans(ctx) } // stopReaps cancels background reaps and waits for them to return. func (c *mediaThumbCache) stopReaps(cancel context.CancelFunc) { c.reapMu.Lock() c.stopped = true c.reapMu.Unlock() cancel() c.reapWG.Wait() } type thumbCacheFile struct { modTime time.Time path string size int64 } // reapOrphans keeps the cache under its size cap. Files are never invalidated // directly — a changed source simply stops matching its old file — so this is // what removes thumbnails nothing asks for any more. Under the cap it deletes // nothing. Over it, the least recently used files go first (a hit refreshes a // file's mtime, see touchThumbFile) until the cache is at // mediaThumbCacheTrimPercent of the cap, and nothing used within // mediaThumbCacheMinAge is removed. Abandoned temporary files are removed too. func (c *mediaThumbCache) reapOrphans(ctx context.Context) { now := c.now() c.lastReap.Store(now.UnixNano()) var files []thumbCacheFile var total int64 err := afero.Walk(c.fs, c.dir, func(path string, info os.FileInfo, walkErr error) error { if ctxErr := ctx.Err(); ctxErr != nil { return ctxErr } if walkErr != nil { return walkErr } if !info.Mode().IsRegular() { return nil } if isThumbTempFile(info.Name()) { if now.Sub(info.ModTime()) > mediaThumbTempMaxAge { if err := c.fs.Remove(path); err != nil { log.Debug().Err(err).Str("path", path). Msg("media.image: thumb cache: failed to reap temporary file") } } return nil } size := thumbFileDiskBytes(info, c.clusterBytes) files = append(files, thumbCacheFile{path: path, size: size, modTime: info.ModTime()}) total += size return nil }) if err != nil { if ctx.Err() == nil { log.Warn().Err(err).Str("dir", c.dir).Msg("media.image: thumb cache: failed to walk for reap") } return } defer func() { c.cacheBytes.Store(total) }() maxBytes := c.maxBytes.Load() if total <= maxBytes { log.Debug().Int("files", len(files)).Int64("bytes", total). Msg("media.image: thumb cache: under size cap") return } sort.Slice(files, func(i, j int) bool { return files[i].modTime.Before(files[j].modTime) }) target := maxBytes * mediaThumbCacheTrimPercent / 100 removed := 0 var removedBytes int64 for _, file := range files { if total <= target || ctx.Err() != nil || now.Sub(file.modTime) < mediaThumbCacheMinAge { break } if err := c.fs.Remove(file.path); err != nil { log.Debug().Err(err).Str("path", file.path).Msg("media.image: thumb cache: failed to reap file") continue } total -= file.size removed++ removedBytes += file.size } log.Info().Int("removed", removed).Int64("removedBytes", removedBytes).Int64("bytes", total). Msg("media.image: thumb cache: reaped least recently used thumbnails") } // earlyThumbKey returns a cache key derived only from request-time parameters // (no typeTag needed). Used for the pre-semaphore resolved-thumbnail memo. func earlyThumbKey(ref mediaRefParam, prefs []string, maxSize int) string { var identity string switch { case isDirectoryMediaRef(ref): identity = fmt.Sprintf("dir:%s:%s:id:%d", ref.System, filepath.ToSlash(ref.Path), *ref.MediaID) case ref.MediaID != nil: identity = fmt.Sprintf("id:%d", *ref.MediaID) default: identity = fmt.Sprintf("path:%s:%s", ref.System, filepath.ToSlash(ref.Path)) } return fmt.Sprintf("early:%s:[%s]:%d", identity, strings.Join(prefs, ","), maxSize) } // getResolvedThumb returns the cache file this request resolved to before, or // false when not yet memoized. func (c *mediaThumbCache) getResolvedThumb( ref mediaRefParam, prefs []string, maxSize int, ) (resolvedThumb, bool) { c.resolvedMu.RLock() defer c.resolvedMu.RUnlock() resolved, ok := c.resolved[earlyThumbKey(ref, prefs, maxSize)] return resolved, ok } // setResolvedThumb records the cache file a request resolved to for future // pre-semaphore hits. func (c *mediaThumbCache) setResolvedThumb(ref mediaRefParam, prefs []string, maxSize int, resolved resolvedThumb) { key := earlyThumbKey(ref, prefs, maxSize) c.resolvedMu.Lock() defer c.resolvedMu.Unlock() if _, exists := c.resolved[key]; !exists && len(c.resolved) >= mediaThumbMemoMax { for existing := range c.resolved { delete(c.resolved, existing) break } } c.resolved[key] = resolved } // clearResolved forgets memoized thumbnails for the given systems, or all of // them when systems is nil. func (c *mediaThumbCache) clearResolved(systems map[string]struct{}) { c.resolvedMu.Lock() defer c.resolvedMu.Unlock() if systems == nil { c.resolved = make(map[string]resolvedThumb) return } for key, resolved := range c.resolved { if _, ok := systems[resolved.system]; ok { delete(c.resolved, key) } } } // fileThumbSourceKey identifies a file-backed image by path, size, // modification time and, where the platform has one, status change time, so // a replaced file gets a new key without being read. A replacement that keeps // the size and modification time is only told apart by the change time, which // exFAT and FAT (and Windows) do not provide. // // An images:// path is used as it is, not resolved, so a thumbnail survives // the image folder moving with its modification times intact. func fileThumbSourceKey(path string, info os.FileInfo) string { if !config.IsImagePath(path) { path = filepath.ToSlash(filepath.Clean(path)) } return fmt.Sprintf("f:%d:%d:%d:%s", info.Size(), info.ModTime().UnixNano(), thumbFileChangeNanos(info), path) } // dataThumbSourceKey identifies an image by its content, for sources that // cannot be stat'ed: blobs and files under a source root. The content type is // length-prefixed so the two fields cannot run together. func dataThumbSourceKey(contentType string, data []byte) string { h := sha256.New() _, _ = fmt.Fprintf(h, "%d:%s", len(contentType), contentType) _, _ = h.Write(data) return "d:" + hex.EncodeToString(h.Sum(nil)) } // isFileThumbSourceKey reports whether key came from fileThumbSourceKey. func isFileThumbSourceKey(key string) bool { return strings.HasPrefix(key, "f:") } // thumbFileHash names the cache file for one source at one size tier. func thumbFileHash(sourceKey string, maxSize int) string { h := sha256.Sum256(fmt.Appendf(nil, "%s\x00%d", sourceKey, maxSize)) return hex.EncodeToString(h[:]) } func (c *mediaThumbCache) shardDir(hash string) string { return filepath.Join(c.dir, hash[:2]) } type thumbCacheFormat struct { ext string contentType string } // thumbCacheFormats lists WebP first because it is what the resize writes. var thumbCacheFormats = []thumbCacheFormat{ {ext: ".webp", contentType: "image/webp"}, {ext: ".jpg", contentType: "image/jpeg"}, {ext: ".png", contentType: "image/png"}, {ext: ".gif", contentType: "image/gif"}, } func thumbCacheExtension(contentType string, data []byte) string { ext := extensionFromContentType(contentType) if ext == "" && len(data) > 0 { ext = extensionFromContentType(http.DetectContentType(data)) } for _, format := range thumbCacheFormats { if strings.TrimPrefix(format.ext, ".") == ext { return format.ext } } return "" } func thumbCacheFileInfo(fs afero.Fs, path string) (os.FileInfo, error) { if lstater, ok := fs.(afero.Lstater); ok { info, _, err := lstater.LstatIfPossible(path) if err != nil { return nil, fmt.Errorf("lstat thumbnail cache file: %w", err) } return info, nil } info, err := fs.Stat(path) if err != nil { return nil, fmt.Errorf("stat thumbnail cache file: %w", err) } return info, nil } // touchThumbFile marks a hit file as recently used for reapOrphans. The write // happens at most once per mediaThumbCacheMinAge per file. func (c *mediaThumbCache) touchThumbFile(path string, info os.FileInfo) { now := c.now() if now.Sub(info.ModTime()) < mediaThumbCacheMinAge { return } if err := c.fs.Chtimes(path, now, now); err != nil { log.Debug().Err(err).Str("path", path).Msg("media.image: thumb cache: failed to touch file") } } // lookupPath returns a regular cached thumbnail path without reading its bytes. func (c *mediaThumbCache) lookupPath(sourceKey string, maxSize int) (path, contentType string, found bool) { if sourceKey == "" { return "", "", false } hash := thumbFileHash(sourceKey, maxSize) dir := c.shardDir(hash) for _, format := range thumbCacheFormats { //nolint:gosec // path is constructed from controlled dirs + SHA-256 hash + fixed extension candidate := filepath.Join(dir, hash+format.ext) info, err := thumbCacheFileInfo(c.fs, candidate) if err == nil && info.Mode().IsRegular() { c.touchThumbFile(candidate, info) return candidate, format.contentType, true } } return "", "", false } // read returns cached thumbnail bytes. A deletion between lookup and read is a miss. func (c *mediaThumbCache) read(sourceKey string, maxSize int) (data []byte, contentType string, found bool) { path, contentType, found := c.lookupPath(sourceKey, maxSize) if !found { return nil, "", false } //nolint:gosec // lookupPath only returns controlled cache paths. data, err := afero.ReadFile(c.fs, path) if err != nil { return nil, "", false } return data, contentType, true } // get keeps cache-focused tests concise; production response paths use lookupPath or read explicitly. func (c *mediaThumbCache) get(sourceKey string, maxSize int) (data []byte, contentType string, found bool) { return c.read(sourceKey, maxSize) } // isSafeLocalPath proves a returned cache path is absolute, contained by the // versioned thumbnail cache, and still names a regular non-symlink file. func (c *mediaThumbCache) isSafeLocalPath(path string) bool { cleanDir := filepath.Clean(c.dir) cleanPath := filepath.Clean(path) if !filepath.IsAbs(cleanDir) || !filepath.IsAbs(cleanPath) { return false } rel, err := filepath.Rel(cleanDir, cleanPath) if err != nil || rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) { return false } info, err := thumbCacheFileInfo(c.fs, cleanPath) return err == nil && info.Mode().IsRegular() } // set writes resized image bytes through a same-directory temporary file and // atomic rename. The resulting path is returned only after materialization. func (c *mediaThumbCache) set(sourceKey string, maxSize int, data []byte, contentType string) (string, error) { if sourceKey == "" { return "", errors.New("thumbnail source key is empty") } ext := thumbCacheExtension(contentType, data) if ext == "" { return "", fmt.Errorf("unsupported thumbnail content type %q", contentType) } hash := thumbFileHash(sourceKey, maxSize) dir := c.shardDir(hash) if err := c.fs.MkdirAll(dir, 0o750); err != nil { //nolint:gosec // cache dir, 0o750 is intentional return "", fmt.Errorf("create thumbnail cache directory: %w", err) } path := filepath.Join(dir, hash+ext) tmp, err := afero.TempFile(c.fs, dir, ".thumb-*.tmp") if err != nil { return "", fmt.Errorf("create thumbnail cache temporary file: %w", err) } tmpPath := tmp.Name() defer func() { _ = tmp.Close() _ = c.fs.Remove(tmpPath) }() if err := c.fs.Chmod(tmpPath, 0o600); err != nil { //nolint:gosec // cache file, 0o600 is intentional return "", fmt.Errorf("set thumbnail cache file permissions: %w", err) } if _, err := tmp.Write(data); err != nil { return "", fmt.Errorf("write thumbnail cache temporary file: %w", err) } if err := tmp.Close(); err != nil { return "", fmt.Errorf("close thumbnail cache temporary file: %w", err) } if err := c.fs.Rename(tmpPath, path); err != nil { return "", fmt.Errorf("replace thumbnail cache file: %w", err) } c.noteWritten(path) return path, nil } // noteWritten adds a new file to the cache's running size, and requests a // reap once that passes the cap, so browsing cannot grow the cache past it // for long between index and scrape completions. func (c *mediaThumbCache) noteWritten(path string) { info, err := thumbCacheFileInfo(c.fs, path) if err != nil { return } if c.cacheBytes.Add(thumbFileDiskBytes(info, c.clusterBytes)) > c.maxBytes.Load() { c.requestReap(mediaThumbCapReapInterval) } } // mediaThumbCacheRun owns the caches one InitMediaThumbCache started: the // live one and any a settings change replaced whose reaps are still winding // down, so stopping the service waits for all of them. type mediaThumbCacheRun struct { pl platforms.Platform stop func() retired sync.WaitGroup mu syncutil.Mutex stopped bool } // activeMediaThumbCacheRun is the run ReloadMediaThumbCache moves, the one // the most recent InitMediaThumbCache started. var activeMediaThumbCacheRun atomic.Pointer[mediaThumbCacheRun] // startMediaThumbCache builds a cache from the config, installs it as the // process-wide cache and starts its background reaps. The returned function // cancels them and waits for them to return. func startMediaThumbCache(pl platforms.Platform, cfg *config.Instance) (stop func()) { cache := newMediaThumbCacheWithFS(pl, cfg, nil) if err := cache.fs.MkdirAll(cache.dir, 0o750); err != nil { //nolint:gosec // cache dir, 0o750 is intentional log.Debug().Err(err).Str("dir", cache.dir).Msg("media.image: thumb cache: failed to create dir") } ctx, cancel := context.WithCancel(context.Background()) cache.reapCtx = ctx cache.reapDone = make(chan struct{}) mediaThumbCachePointer.Store(cache) go func() { defer close(cache.reapDone) cache.reapStaleVersions() select { case <-ctx.Done(): return case <-cache.clock.After(mediaThumbStartupReapDelay): } cache.tryReapOrphans(ctx) }() return func() { cache.stopReaps(cancel) <-cache.reapDone } } // InitMediaThumbCache creates or replaces the process-wide thumb cache for the // given platform, in the image folder and with the size cap cfg sets. Must be // called once during service start, before any media.image requests are // handled. The cache is usable as soon as this returns; stale-version // directories and abandoned temporary files are reaped in the background so a // large cache does not delay startup, followed after // mediaThumbStartupReapDelay by the first orphan reap. The returned function // cancels pending reaps and waits for them, including those of a cache that // ReloadMediaThumbCache replaced, so a stopping service does not leave them // writing to the image folder. Uses atomic store so concurrent StartWithReady // calls in tests do not race. func InitMediaThumbCache(pl platforms.Platform, cfg *config.Instance) (stop func()) { run := &mediaThumbCacheRun{pl: pl} run.mu.Lock() run.stop = startMediaThumbCache(pl, cfg) run.mu.Unlock() activeMediaThumbCacheRun.Store(run) return func() { activeMediaThumbCacheRun.CompareAndSwap(run, nil) run.mu.Lock() run.stopped = true stopCache := run.stop run.stop = nil run.mu.Unlock() if stopCache != nil { stopCache() } run.retired.Wait() } } // ReloadMediaThumbCache applies a changed image folder or size cap to the // running cache and reports whether anything changed. A new cap is applied in // place. A new folder gets a new cache there: it replaces the old one at once, // and the old one's reaps are stopped in the background. Files are never // moved or copied; the old folder's thumbnails are simply no longer used. func ReloadMediaThumbCache(cfg *config.Instance) bool { run := activeMediaThumbCacheRun.Load() if run == nil { return false } run.mu.Lock() defer run.mu.Unlock() if run.stopped { return false } current := mediaThumbCachePointer.Load() maxBytes := mediaThumbCacheMaxBytes(cfg) if current != nil && current.dir == mediaThumbCacheDir(run.pl, cfg) { if current.maxBytes.Swap(maxBytes) == maxBytes { return false } log.Info().Int64("maxBytes", maxBytes).Msg("media.image: thumb cache: size cap changed") if current.cacheBytes.Load() > maxBytes { current.requestReap(0) } return true } stopOld := run.stop run.stop = startMediaThumbCache(run.pl, cfg) if next := mediaThumbCachePointer.Load(); next != nil { log.Info().Str("dir", next.dir).Msg("media.image: thumb cache: moved to a new folder") } if stopOld != nil { run.retired.Add(1) go func() { defer run.retired.Done() stopOld() }() } return true } // InvalidateMediaThumbMemo forgets every resolved thumbnail so the next request // for each cover resolves its source again. Called after an index or scrape // completes. Cached files are kept: one whose source is unchanged is still a // hit, and one whose source changed is never matched again and is left to the // orphan reap this also requests. func InvalidateMediaThumbMemo() { if cache := mediaThumbCachePointer.Load(); cache != nil { cache.clearResolved(nil) cache.requestReap(mediaThumbReapInterval) } } // InvalidateMediaThumbMemoSystems is InvalidateMediaThumbMemo for the supplied // systems only. func InvalidateMediaThumbMemoSystems(systemIDs []string) { cache := mediaThumbCachePointer.Load() if cache == nil { return } systems := make(map[string]struct{}, len(systemIDs)) for _, systemID := range systemIDs { if systemID != "" { systems[systemID] = struct{}{} } } if len(systems) == 0 { return } cache.clearResolved(systems) cache.requestReap(mediaThumbReapInterval) } // defaultImageTypes is the preference order used when no imageTypes param is provided. var defaultImageTypes = []string{ "image", "thumbnail", "boxart", "boxart3d", "screenshot", "wheel", "titleshot", "map", "marquee", "fanart", } var imageTypeTags = map[string]string{ "image": tags.PropertyTypeTag(tags.TagPropertyImageImage), "thumbnail": tags.PropertyTypeTag(tags.TagPropertyImageThumbnail), "boxart": tags.PropertyTypeTag(tags.TagPropertyImageBoxart), "boxart3d": tags.PropertyTypeTag(tags.TagPropertyImageBoxart3D), "boxartside": tags.PropertyTypeTag(tags.TagPropertyImageBoxartSide), "boxartback": tags.PropertyTypeTag(tags.TagPropertyImageBoxartBack), "screenshot": tags.PropertyTypeTag(tags.TagPropertyImageScreenshot), "wheel": tags.PropertyTypeTag(tags.TagPropertyImageWheel), "titleshot": tags.PropertyTypeTag(tags.TagPropertyImageTitleshot), "map": tags.PropertyTypeTag(tags.TagPropertyImageMap), "marquee": tags.PropertyTypeTag(tags.TagPropertyImageMarquee), "fanart": tags.PropertyTypeTag(tags.TagPropertyImageFanart), } // rawMediaImage carries raw image bytes and metadata before base64-encoding. // Used to allow the semaphore to be released before CPU-intensive resize/encode. type rawMediaImage struct { contentType string text string // original file path, for extension derivation fallback typeTag string system string sourceKey string // names the image's thumbnails; see mediaThumbCache binary []byte mediaDBID int64 // 0 when the image belongs to a directory, not a media row // cached is true when binary was left unread because a thumbnail for // sourceKey was already cached; see mediaImageCacheProbe. cached bool } // mediaImageCacheProbe reports whether a thumbnail for sourceKey is already // cached at the requested size. A file-backed source whose thumbnail exists is // then never read: a stat names it, and the read is the slow part on SD and // USB storage. nil disables the probe. type mediaImageCacheProbe func(sourceKey string) bool // mediaImageFile is a loaded image file and the key naming its thumbnails. // data is nil when the probe found its thumbnail already cached. type mediaImageFile struct { sourceKey string data []byte } // thumbPassthroughMaxBytes is the largest source that is returned as it is // when it already fits the requested box, instead of being re-encoded as // WebP. On a MiSTer (ARM32) the encode was 300 to 345 ms of a 0.33 to 0.38 s // request for a 320x320 JPEG of 10 to 29 KB, to save 4 to 7 KB: at this size // the format win is a few kilobytes and the encode is nearly the whole cost. const thumbPassthroughMaxBytes = 64 << 10 // resizeImageIfNeeded decodes binary, scales it down to fit within a // maxSize×maxSize bounding box when either dimension exceeds maxSize, and // re-encodes the result as lossy WebP with alpha preserved. // // A source that already fits is not scaled. If it is also no larger than // thumbPassthroughMaxBytes and in a format the thumbnail cache stores (JPEG, // PNG, WebP), the original bytes and content type are returned without an // encode. A larger source that fits is still re-encoded as WebP (keeping // native dimensions) so callers requesting a tier at or above native size get // the format win, unless the WebP would be no smaller, in which case the // original bytes are kept. // // Returns the original bytes unchanged when maxSize <= 0 (full size requested) // or when the source cannot be decoded. func resizeImageIfNeeded(binary []byte, contentType string, maxSize int) (resized []byte, resizedType string) { resized, resizedType, _ = resizeImageWithColor(binary, contentType, maxSize) return resized, resizedType } // resizeImageWithColor is resizeImageIfNeeded that also returns the average // colour of the decoded frame as 0xRRGGBB, or nil when the image was not // decoded or is fully transparent. The colour is computed whether or not the // frame goes on to be encoded. func resizeImageWithColor( binary []byte, contentType string, maxSize int, ) (resized []byte, resizedType string, avgColor *uint32) { if maxSize <= 0 || len(binary) == 0 { return binary, contentType, nil } decodeStart := time.Now() src, err := decodeResizableImage(binary, contentType) if err != nil { return binary, contentType, nil } decodeDur := time.Since(decodeStart) scaleStart := time.Now() bounds := src.Bounds() w, h := bounds.Dx(), bounds.Dy() // Downscale to fit the maxSize box when larger; otherwise keep native // dimensions. A frame that was scaled, or a source too large to pass // through, is re-encoded as WebP below: a request that snaps to a tier at or // above the native size still gets the format win instead of falling back // to the original (often large lossless PNG). frame := src newW, newH := w, h if w > maxSize || h > maxSize { larger := w if h > larger { larger = h } scale := float64(maxSize) / float64(larger) newW = int(math.Round(float64(w) * scale)) newH = int(math.Round(float64(h) * scale)) if newW < 1 { newW = 1 } if newH < 1 { newH = 1 } dst := image.NewRGBA(image.Rect(0, 0, newW, newH)) draw.ApproxBiLinear.Scale(dst, dst.Bounds(), src, bounds, draw.Over, nil) frame = dst } avgColor = averageImageColor(frame) scaleDur := time.Since(scaleStart) // A small source that already fits skips the encode; see // thumbPassthroughMaxBytes. The colour still comes from the decoded frame. // The cache names its files by format, so a source it could not store keeps // going through the encode rather than missing the cache on every request. if newW == w && newH == h && len(binary) <= thumbPassthroughMaxBytes && thumbCacheExtension(contentType, binary) != "" { return binary, contentType, avgColor } encodeStart := time.Now() out, outputType, err := encodeResizedImage(frame) encodeDur := time.Since(encodeStart) if err != nil { return binary, contentType, avgColor } // When no downscale happened, only adopt the WebP if it actually shrank the // payload; some already-compact sources re-encode larger. if newW == w && newH == h && len(out) >= len(binary) { return binary, contentType, avgColor } log.Debug(). Str("contentType", contentType). Str("resizedContentType", outputType). Int("maxSize", maxSize). Int("width", w). Int("height", h). Int("resizedWidth", newW). Int("resizedHeight", newH). Int("inputBytes", len(binary)). Int("resizedBytes", len(out)). Dur("decode", decodeDur). Dur("scale", scaleDur). Dur("encode", encodeDur). Msg("media.image: resized image") return out, outputType, avgColor } // averageColorSampleSide bounds the colour average to about this many samples // per axis, so the cost is independent of the frame size. const averageColorSampleSide = 64 // averageImageColor returns the alpha-weighted average colour of img as // 0xRRGGBB, sampling at most averageColorSampleSide² pixels. It returns nil // for an empty or fully transparent image. func averageImageColor(img image.Image) *uint32 { bounds := img.Bounds() w, h := bounds.Dx(), bounds.Dy() if w <= 0 || h <= 0 { return nil } stepX := max(1, w/averageColorSampleSide) stepY := max(1, h/averageColorSampleSide) var sumR, sumG, sumB, sumA uint64 for y := bounds.Min.Y; y < bounds.Max.Y; y += stepY { for x := bounds.Min.X; x < bounds.Max.X; x += stepX { // RGBA returns alpha-premultiplied 16-bit channels, so the sums are // already weighted by coverage. r, g, b, a := img.At(x, y).RGBA() sumR += uint64(r) sumG += uint64(g) sumB += uint64(b) sumA += uint64(a) } } if sumA == 0 { return nil } channel := func(sum uint64) uint32 { v := sum * 0xff / sumA if v > 0xff { v = 0xff } return uint32(v) //nolint:gosec // clamped to 8 bits above } value := channel(sumR)<<16 | channel(sumG)<<8 | channel(sumB) return &value } // encodeResizedImage encodes a resized frame: an opaque one as JPEG, one with // transparency as lossy WebP so its alpha survives. On a MiSTer the pure-Go // WebP encode was the largest step of a cold cover (a median 142 ms for a // 256 px thumbnail of a 320 px JPEG), and covers are nearly always opaque. // Isolated in one function so the encoder can be swapped without touching the // resize pipeline. func encodeResizedImage(img image.Image) (data []byte, contentType string, err error) { if imageHasTransparency(img) { return encodeWebPImage(img) } var out bytes.Buffer if encErr := jpeg.Encode(&out, img, &jpeg.Options{Quality: mediaThumbJPEGQuality}); encErr != nil { return nil, "", fmt.Errorf("encode resized jpeg: %w", encErr) } return out.Bytes(), "image/jpeg", nil } // encodeWebPImage encodes img as lossy WebP (VP8) with alpha preserved. func encodeWebPImage(img image.Image) (data []byte, contentType string, err error) { var out bytes.Buffer if encErr := gowebp.Encode(&out, img, &gowebp.Options{ Lossy: true, Quality: mediaThumbWebPQuality, Method: mediaThumbWebPMethod, }); encErr != nil { return nil, "", fmt.Errorf("encode resized webp: %w", encErr) } return out.Bytes(), "image/webp", nil } // mediaImageMaxPixels bounds the frame a source image may declare. The byte // caps only limit the compressed file, and every decoder allocates the whole // frame from the header before reading pixels, so a small file declaring a // huge frame could otherwise take hundreds of megabytes. 4096x4096 is far past // any cover art. const mediaImageMaxPixels = 4096 * 4096 // checkImageDimensions reads an image's header and rejects a frame larger // than mediaImageMaxPixels before any decoder allocates it. func checkImageDimensions(format string, binary []byte, decodeConfig func(io.Reader) (image.Config, error)) error { cfg, err := decodeConfig(bytes.NewReader(binary)) if err != nil { return fmt.Errorf("decode %s header for resize: %w", format, err) } if int64(cfg.Width)*int64(cfg.Height) > mediaImageMaxPixels { return fmt.Errorf("%s for resize is %dx%d, past the %d pixel limit", format, cfg.Width, cfg.Height, mediaImageMaxPixels) } return nil } func decodeResizableImage(binary []byte, contentType string) (image.Image, error) { decodeJPEG := func() (image.Image, error) { if err := checkImageDimensions("JPEG", binary, jpeg.DecodeConfig); err != nil { return nil, err } img, err := jpeg.Decode(bytes.NewReader(binary)) if err != nil { return nil, fmt.Errorf("decode JPEG for resize: %w", err) } return img, nil } decodePNG := func() (image.Image, error) { if err := checkImageDimensions("PNG", binary, png.DecodeConfig); err != nil { return nil, err } // Wuffs decodes cover art several times faster than image/png on ARM. // Anything it rejects still gets image/png's verdict. if img, err := wuffspng.Decode(binary); err == nil { return img, nil } else if !errors.Is(err, wuffspng.ErrUnavailable) { log.Debug().Err(err).Msg("media.image: wuffs png decode failed, using image/png") } img, err := png.Decode(bytes.NewReader(binary)) if err != nil { return nil, fmt.Errorf("decode PNG for resize: %w", err) } return img, nil } decodeWebP := func() (image.Image, error) { if err := checkImageDimensions("WebP", binary, webp.DecodeConfig); err != nil { return nil, err } img, err := webp.Decode(bytes.NewReader(binary)) if err != nil { return nil, fmt.Errorf("decode WebP for resize: %w", err) } return img, nil } switch extensionFromContentType(contentType) { case "jpg": return decodeJPEG() case "png": return decodePNG() case "webp": return decodeWebP() } if bytes.HasPrefix(binary, []byte("\x89PNG\r\n\x1a\n")) { return decodePNG() } if len(binary) >= 2 && binary[0] == 0xff && binary[1] == 0xd8 { return decodeJPEG() } if len(binary) >= 12 && bytes.HasPrefix(binary, []byte("RIFF")) && bytes.Equal(binary[8:12], []byte("WEBP")) { return decodeWebP() } return nil, fmt.Errorf("unsupported image type for resize: %s", contentType) } // imageHasTransparency reports whether img contains any non-opaque pixel. // It short-circuits for common opaque types before falling back to a // pixel-by-pixel scan — avoiding O(w×h) work on ARM for JPEG sources. func imageHasTransparency(img image.Image) bool { // Types that are always fully opaque — no alpha channel possible. switch img.(type) { case *image.YCbCr, *image.Gray, *image.Gray16, *image.CMYK: return false } // Types that have an Opaque() helper — use it to avoid a pixel scan when // the image was decoded with a known-opaque palette or alpha mask. type opaque interface{ Opaque() bool } if o, ok := img.(opaque); ok { return !o.Opaque() } // Fallback: per-pixel scan for any remaining type (e.g. *image.Paletted). bounds := img.Bounds() for y := bounds.Min.Y; y < bounds.Max.Y; y++ { for x := bounds.Min.X; x < bounds.Max.X; x++ { _, _, _, alpha := img.At(x, y).RGBA() if alpha != 0xffff { return true } } } return false } type mediaBinaryTooLargeError struct { path string size int64 max int64 } type mediaImageSource struct { propMap map[string]database.MediaProperty isMedia bool } type mediaImageNotFoundError struct { system string path string fileBackedCandidatesChecked bool } type mediaImageNoImageCache struct { entries map[string]error mu syncutil.Mutex } var mediaImageNoImages = &mediaImageNoImageCache{entries: make(map[string]error)} func (e *mediaBinaryTooLargeError) Error() string { return fmt.Sprintf("media binary %q is too large: %d bytes exceeds %d byte limit", e.path, e.size, e.max) } func (e *mediaImageNotFoundError) Error() string { return fmt.Sprintf("no image found for media: system=%q path=%q", e.system, filepath.ToSlash(e.path)) } func mediaImageNoImageMediaIDKey(mediaID int64, prefs []string) string { return fmt.Sprintf("id:%d\x00%s", mediaID, strings.Join(prefs, "\x00")) } func mediaImageNoImagePathKey(system, path string, prefs []string) string { return fmt.Sprintf("path:%s\x00%s\x00%s", system, filepath.ToSlash(path), strings.Join(prefs, "\x00")) } func mediaImageNoImageRequestKey(ref mediaRefParam, prefs []string) string { if isDirectoryMediaRef(ref) { return fmt.Sprintf("dir:%s\x00%s\x00%d\x00%s", ref.System, filepath.ToSlash(ref.Path), *ref.MediaID, strings.Join(prefs, "\x00")) } if ref.MediaID != nil { return mediaImageNoImageMediaIDKey(*ref.MediaID, prefs) } return mediaImageNoImagePathKey(ref.System, ref.Path, prefs) } func (c *mediaImageNoImageCache) get(key string) (bool, error) { c.mu.Lock() defer c.mu.Unlock() err, ok := c.entries[key] return ok, err } func (c *mediaImageNoImageCache) add(key string, err error) { c.mu.Lock() defer c.mu.Unlock() if len(c.entries) >= mediaImageNoImageMax { for existing := range c.entries { delete(c.entries, existing) break } } var noImage *mediaImageNotFoundError if errors.As(err, &noImage) { c.entries[key] = noImage return } c.entries[key] = err } func (c *mediaImageNoImageCache) clear() { c.mu.Lock() defer c.mu.Unlock() c.entries = make(map[string]error) } func mediaImageNoImageError(row *database.MediaFullRow, fileBackedCandidatesChecked bool) error { noImage := &mediaImageNotFoundError{ system: row.System.SystemID, path: row.Path, fileBackedCandidatesChecked: fileBackedCandidatesChecked, } return fmt.Errorf("%w", models.QuietClientErr(noImage)) } func cachedMediaImageNoImageError(err error) error { return fmt.Errorf("%w", models.QuietClientErr(err)) } func isCacheableMediaImageNoImageError(err error) bool { var noImage *mediaImageNotFoundError return errors.As(err, &noImage) && !noImage.fileBackedCandidatesChecked } // mediaImageNotFound reports whether err is a no-image result, and whether // that lookup checked file-backed candidates. func mediaImageNotFound(err error) (notFound, fileBackedCandidatesChecked bool) { var noImage *mediaImageNotFoundError if !errors.As(err, &noImage) { return false, false } return true, noImage.fileBackedCandidatesChecked } // resolveImageTypeTag converts a short image type name to the full property TypeTag. func resolveImageTypeTag(t string) (string, bool) { typeTag, ok := imageTypeTags[t] return typeTag, ok } // buildPropsMap converts a []database.MediaProperty slice into a map keyed by TypeTag. func buildPropsMap(props []database.MediaProperty) map[string]database.MediaProperty { m := make(map[string]database.MediaProperty, len(props)) for _, p := range props { m[p.TypeTag] = p } return m } func imagePropertyTypeTags(props []database.MediaProperty) []string { known := make(map[string]struct{}, len(imageTypeTags)) for _, typeTag := range imageTypeTags { known[typeTag] = struct{}{} } seen := make(map[string]struct{}) for _, p := range props { if _, ok := known[p.TypeTag]; ok { seen[p.TypeTag] = struct{}{} } } result := make([]string, 0, len(seen)) for typeTag := range seen { result = append(result, typeTag) } sort.Strings(result) return result } func inlineMediaImageResponse(data []byte, contentType, sourcePath, typeTag string) models.MediaImageResponse { return models.MediaImageResponse{ Extension: mediaContentExtension(contentType, sourcePath), ContentType: contentType, Data: base64.StdEncoding.EncodeToString(data), Delivery: mediaImageDeliveryInline, TypeTag: typeTag, } } func localMediaImageResponse( cache *mediaThumbCache, path, contentType, typeTag string, ) (models.MediaImageResponse, bool) { if !cache.isSafeLocalPath(path) { return models.MediaImageResponse{}, false } return models.MediaImageResponse{ Extension: mediaContentExtension(contentType, ""), ContentType: contentType, Delivery: mediaImageDeliveryPath, LocalPath: path, TypeTag: typeTag, }, true } // thumbFileResponse serves an existing cache file, as a local path when asked // for one and inline otherwise. It reports false when the file is gone. func thumbFileResponse( cache *mediaThumbCache, path, contentType, typeTag, sourcePath string, localPath bool, ) (models.MediaImageResponse, bool) { info, err := thumbCacheFileInfo(cache.fs, path) if err != nil || !info.Mode().IsRegular() { return models.MediaImageResponse{}, false } cache.touchThumbFile(path, info) if localPath { if response, ok := localMediaImageResponse(cache, path, contentType, typeTag); ok { return response, true } } data, err := afero.ReadFile(cache.fs, path) if err != nil { return models.MediaImageResponse{}, false } return inlineMediaImageResponse(data, contentType, sourcePath, typeTag), true } // cachedMediaImageResponse serves the cached thumbnail for sourceKey, and // returns the file it served so the caller can memoize it. func cachedMediaImageResponse( cache *mediaThumbCache, sourceKey string, typeTag string, maxSize int, sourcePath string, localPath bool, ) (response models.MediaImageResponse, resolved resolvedThumb, found bool) { path, contentType, found := cache.lookupPath(sourceKey, maxSize) if !found { return models.MediaImageResponse{}, resolvedThumb{}, false } response, found = thumbFileResponse(cache, path, contentType, typeTag, sourcePath, localPath) if !found { return models.MediaImageResponse{}, resolvedThumb{}, false } return response, resolvedThumb{typeTag: typeTag, path: path, contentType: contentType}, true } func validateMediaImageDelivery(delivery string, ref mediaRefParam) error { switch delivery { case "", mediaImageDeliveryInline: return nil case mediaImageDeliveryPath: if ref.MaxSize == nil || *ref.MaxSize <= 0 { return models.ClientErrf("media.image: localPath delivery requires a positive maxSize") } return nil default: return models.ClientErrf("media.image: unsupported delivery %q", delivery) } } // HandleMediaImage returns a single best-match image inline or as a transient, // Core-owned cached thumbnail path when explicitly requested. // //nolint:gocritic // RequestEnv is copied once at the API handler boundary. func HandleMediaImage(env requests.RequestEnv) (result any, resultErr error) { started := time.Now() deliveryForLog := "" maxSizeForLog := 0 hasMediaID := false defer func() { log.Debug(). Dur("duration", time.Since(started)). Str("delivery", deliveryForLog). Int("maxSize", maxSizeForLog). Bool("mediaId", hasMediaID). Bool("ok", resultErr == nil). Msg("media.image handler timing") }() ref, delivery, err := parseMediaImageRequest(env.Params) if err != nil { return nil, err } deliveryForLog = delivery hasMediaID = ref.MediaID != nil if deliveryErr := validateMediaImageDelivery(delivery, ref); deliveryErr != nil { return nil, deliveryErr } localPath := delivery == mediaImageDeliveryPath // Snap the requested size onto a standard tier so every view shares one // cached image per cover and the resize dimension is bounded. All downstream // uses (cache keys, resolved-thumbnail memo, resize) see the snapped value. if ref.MaxSize != nil { snapped := snapThumbMaxSize(*ref.MaxSize) ref.MaxSize = &snapped maxSizeForLog = int(snapped) } prefs := imagePrefs(nil, ref.ImageTypes) // cache is nil unless this request resizes and a thumbnail cache exists. var cache *mediaThumbCache maxSize := 0 if ref.MaxSize != nil && *ref.MaxSize > 0 { maxSize = int(*ref.MaxSize) cache = mediaThumbCachePointer.Load() } // Pre-semaphore fast path: if this exact request was served before and the // disk thumbnail is still present, return it without loading the original. if cache != nil { if resolved, ok := cache.getResolvedThumb(ref, prefs, maxSize); ok { if response, found := thumbFileResponse( cache, resolved.path, resolved.contentType, resolved.typeTag, "", localPath, ); found { return response, nil } } } noImageKey := mediaImageNoImageRequestKey(ref, prefs) if ok, cachedErr := mediaImageNoImages.get(noImageKey); ok { return nil, cachedMediaImageNoImageError(cachedErr) } // Recorded fast path: after a restart the in-memory memo is empty, but the // cover's resolved type and source are recorded in MediaDB. Confirm they // still match what a full lookup would pick and serve the disk thumbnail // without reading the original artwork or waiting for the lookup semaphore. if cache != nil { if response, found := recordedThumbResponse(&env, cache, ref, prefs, maxSize, localPath); found { return response, nil } } var probe mediaImageCacheProbe if cache != nil { probe = func(sourceKey string) bool { _, _, found := cache.lookupPath(sourceKey, maxSize) return found } } raw, err := loadRawMediaImageLimited(&env, ref, prefs, noImageKey, probe) if err != nil { return nil, err } if cache != nil { if response, resolved, found := cachedMediaImageResponse( cache, raw.sourceKey, raw.typeTag, maxSize, raw.text, localPath, ); found { resolved.system = raw.system cache.setResolvedThumb(ref, prefs, maxSize, resolved) recordCachedCoverThumb(&env, cache, raw, prefs, maxSize) return response, nil } } if raw.cached { // The probe found a thumbnail that has gone since: read the source. raw, err = loadRawMediaImageLimited(&env, ref, prefs, noImageKey, nil) if err != nil { return nil, err } } binary, contentType := raw.binary, raw.contentType if maxSize > 0 { resizeSem := cache.resizeSemaphore() select { case resizeSem <- struct{}{}: case <-env.Context.Done(): return nil, env.Context.Err() } var avgColor *uint32 binary, contentType, avgColor = resizeImageWithColor(binary, contentType, maxSize) <-resizeSem if cache != nil { writeStart := time.Now() path, cacheErr := cache.set(raw.sourceKey, maxSize, binary, contentType) log.Debug().Dur("duration", time.Since(writeStart)).Int("bytes", len(binary)). Msg("media.image: wrote thumbnail cache file") if cacheErr != nil { log.Debug().Err(cacheErr).Msg("media.image: failed to materialize thumbnail cache file") } else { cache.setResolvedThumb(ref, prefs, maxSize, resolvedThumb{ system: raw.system, typeTag: raw.typeTag, path: path, contentType: contentType, }) recordCoverThumb(&env, raw, prefs, avgColor) } if cacheErr == nil && localPath { if response, ok := localMediaImageResponse(cache, path, contentType, raw.typeTag); ok { return response, nil } log.Debug().Msg("media.image: thumbnail cache path failed local delivery validation") } } } return inlineMediaImageResponse(binary, contentType, raw.text, raw.typeTag), nil } // loadRawMediaImageLimited resolves and loads a request's image under the // lookup semaphore, caching a no-image result for later requests. func loadRawMediaImageLimited( env *requests.RequestEnv, ref mediaRefParam, prefs []string, noImageKey string, probe mediaImageCacheProbe, ) (*rawMediaImage, error) { if mediaImageBeforeSemAcquire != nil { mediaImageBeforeSemAcquire() } select { case mediaImageSem <- struct{}{}: case <-env.Context.Done(): return nil, env.Context.Err() } if ok, cachedErr := mediaImageNoImages.get(noImageKey); ok { <-mediaImageSem return nil, cachedMediaImageNoImageError(cachedErr) } maxBytes := MediaImageMaxBytes(env.Platform) var raw *rawMediaImage var err error switch { case isDirectoryMediaRef(ref): raw, err = loadRawMediaImageDirectoryRef(env, ref, prefs, maxBytes, probe) case ref.MediaID == nil: raw, err = loadRawMediaImageSinglePath(env, ref, prefs, maxBytes, probe) default: raw, err = loadRawMediaImageByID(env, ref, prefs, maxBytes, probe) } // Cache the no-image result while holding the semaphore so concurrent // waiters see it immediately after sem release. if isCacheableMediaImageNoImageError(err) { mediaImageNoImages.add(noImageKey, err) } <-mediaImageSem // release before CPU-intensive decode/resize/encode if err != nil { return nil, err } return raw, nil } // recordedThumbResponse serves a cached thumbnail using the cover recorded in // MediaDB, without loading the original image. It reports false whenever the // record cannot be proven to match what a full lookup would resolve, and the // caller then takes the full path. func recordedThumbResponse( env *requests.RequestEnv, cache *mediaThumbCache, ref mediaRefParam, prefs []string, maxSize int, localPath bool, ) (models.MediaImageResponse, bool) { // A directory's own artwork outranks the cover recorded for its media. if env.Database == nil || env.Database.MediaDB == nil || isDirectoryMediaRef(ref) { return models.MediaImageResponse{}, false } db := env.Database.MediaDB mediaDBID, ok := mediaImageRequestDBID(env, ref) if !ok { return models.MediaImageResponse{}, false } thumb, found, err := db.GetMediaCoverThumb(env.Context, mediaDBID) if err != nil { log.Debug().Err(err).Int64("mediaDBID", mediaDBID).Msg("media.image: cover thumb record lookup failed") return models.MediaImageResponse{}, false } if !found || (ref.MediaID == nil && thumb.SystemID != ref.System) { return models.MediaImageResponse{}, false } if !recordedTypeMatchesPrefs(thumb.TypeTag, thumb.AvailableTypeTags, prefs) { return models.MediaImageResponse{}, false } // Zip container aliases add artwork from equivalent media rows that the // recorded property list does not cover; let the full path decide. if zipContainerAliasesEnabled(env) && (helpers.IsZip(thumb.Path) || helpers.IsZip(strings.TrimSuffix(thumb.ParentDir, "/"))) { return models.MediaImageResponse{}, false } if !recordedSourceCurrent(afero.NewOsFs(), requestImageDir(env), &thumb) { return models.MediaImageResponse{}, false } response, resolved, cached := cachedMediaImageResponse( cache, thumb.SourceKey, thumb.TypeTag, maxSize, "", localPath, ) if !cached { return models.MediaImageResponse{}, false } resolved.system = thumb.SystemID cache.setResolvedThumb(ref, prefs, maxSize, resolved) return response, true } // recordedSourceCurrent reports whether a recorded cover's source is still // the image a full lookup would load. Only file-backed sources qualify: one // stat proves the file the recorded type resolves to now is the one recorded, // with the same size and modification time. Anything else needs the full path. // An images:// source is statted in imageDir but keyed by its images:// path, // as loadMediaImageFile keys it. func recordedSourceCurrent(fs afero.Fs, imageDir string, thumb *database.MediaCoverThumb) bool { if !isFileThumbSourceKey(thumb.SourceKey) || thumb.SourcePath == "" || platforms.IsSourcePath(thumb.SourcePath) { return false } statPath := thumb.SourcePath if config.IsImagePath(statPath) { resolved, ok := config.ResolveImagePath(imageDir, statPath) if !ok { return false } statPath = resolved } info, err := fs.Stat(statPath) if err != nil || !info.Mode().IsRegular() { return false } return fileThumbSourceKey(thumb.SourcePath, info) == thumb.SourceKey } // mediaImageRequestDBID resolves a request to its media row with cheap // indexed lookups. Path requests only match an exact indexed path; relative, // singleton and directory fallbacks are left to the full path. func mediaImageRequestDBID(env *requests.RequestEnv, ref mediaRefParam) (int64, bool) { if ref.MediaID != nil { return *ref.MediaID, *ref.MediaID > 0 } db := env.Database.MediaDB system, err := db.FindSystemBySystemID(ref.System) if err != nil { return 0, false } media, err := db.FindMediaBySystemAndPath(env.Context, system.DBID, ref.Path) if err != nil || media == nil { return 0, false } return media.DBID, true } // recordedTypeMatchesPrefs reports whether typeTag is what the preference // walk would pick: it must be one of prefs and no preference ahead of it may // be available on the media row or its title. func recordedTypeMatchesPrefs(typeTag string, available, prefs []string) bool { availableSet := make(map[string]struct{}, len(available)) for _, tag := range available { availableSet[tag] = struct{}{} } if _, ok := availableSet[typeTag]; !ok { return false } for _, pref := range prefs { prefTag, ok := resolveImageTypeTag(pref) if !ok { continue } if prefTag == typeTag { return true } if _, ok := availableSet[prefTag]; ok { return false } } return false } // coverRecordEligible reports whether a resolved image should be recorded as // the media row's cover. Requests with a single explicit type (a detail view // asking for a screenshot, say) do not define the cover, so they never // replace the record written by cover requests with fallbacks. func coverRecordEligible(env *requests.RequestEnv, raw *rawMediaImage, prefs []string) bool { return raw != nil && raw.mediaDBID > 0 && len(prefs) > 1 && env.Database != nil && env.Database.MediaDB != nil } // recordCoverThumb records the cover's resolved type and average colour. // Failures are logged and ignored: the record is an optimisation. func recordCoverThumb(env *requests.RequestEnv, raw *rawMediaImage, prefs []string, avgColor *uint32) { if !coverRecordEligible(env, raw, prefs) { return } if err := env.Database.MediaDB.PutMediaCoverThumb( context.WithoutCancel(env.Context), raw.mediaDBID, raw.typeTag, raw.sourceKey, avgColor, ); err != nil { log.Debug().Err(err).Int64("mediaDBID", raw.mediaDBID).Msg("media.image: failed to record cover thumb") } } // recordCachedCoverThumb records a cover whose thumbnail was already on disk, // for example one built before cover records existed. The colour is taken // from the small cached thumbnail rather than the original. func recordCachedCoverThumb( env *requests.RequestEnv, cache *mediaThumbCache, raw *rawMediaImage, prefs []string, maxSize int, ) { if !coverRecordEligible(env, raw, prefs) { return } var avgColor *uint32 if data, contentType, found := cache.read(raw.sourceKey, maxSize); found { if img, err := decodeResizableImage(data, contentType); err == nil { avgColor = averageImageColor(img) } } recordCoverThumb(env, raw, prefs, avgColor) } func parseMediaImageRequest(raw json.RawMessage) (mediaRefParam, string, error) { var params models.MediaImageParams decoder := json.NewDecoder(bytes.NewReader(raw)) decoder.DisallowUnknownFields() if err := decoder.Decode(¶ms); err != nil { return mediaRefParam{}, "", models.ClientErrf("invalid params: %w", err) } ref := mediaRefParam{ MediaID: params.MediaID, MaxSize: params.MaxSize, System: params.System, Path: params.Path, ImageTypes: params.ImageTypes, } if err := validateDirectoryMediaRef(ref); err != nil { return mediaRefParam{}, "", models.ClientErrf("invalid params: %w", err) } if err := validateImageTypes(ref.ImageTypes); err != nil { return mediaRefParam{}, "", models.ClientErrf("invalid params: %w", err) } if ref.MaxSize != nil && (*ref.MaxSize <= 0 || *ref.MaxSize > 8192) { return mediaRefParam{}, "", models.ClientErrf("invalid params: maxSize must be between 1 and 8192") } return ref, params.Delivery, nil } func loadRawMediaImageSinglePath( env *requests.RequestEnv, ref mediaRefParam, prefs []string, maxBytes int64, probe mediaImageCacheProbe, ) (*rawMediaImage, error) { db := env.Database.MediaDB system, err := db.FindSystemBySystemID(ref.System) if errors.Is(err, sql.ErrNoRows) { return nil, models.ClientErrf("system not found: %s", ref.System) } if err != nil { return nil, fmt.Errorf("failed to resolve system: %w", err) } // Preserve exact media behavior ahead of directory lookup. Relative and // singleton media fallbacks run only after exact directory properties. media, err := db.FindMediaBySystemAndPath(env.Context, system.DBID, ref.Path) if err != nil { return nil, fmt.Errorf("failed to find media: %w", err) } if media != nil { row, rowErr := getMediaFullRow(env, media.DBID, ref.System, ref.Path) if rowErr != nil { return nil, rowErr } return loadRawMediaImageRow(env, row, prefs, maxBytes, probe) } raw, directoryFileBacked, err := loadRawMediaImageDirectory(env, system, ref.Path, prefs, maxBytes, probe) if raw != nil || err != nil { return raw, err } row, err := resolveMediaBySystemAndPath(env, ref.System, ref.Path) if err != nil { return nil, err } raw, err = loadRawMediaImageRow(env, row, prefs, maxBytes, probe) return raw, markFileBackedCandidatesChecked(err, directoryFileBacked) } // loadRawMediaImageDirectory loads a directory's own artwork. It returns nil // and no error when the directory has none of the requested types, and // reports whether that lookup checked file-backed candidates, so the caller's // final no-image result stays out of the no-image cache. func loadRawMediaImageDirectory( env *requests.RequestEnv, system database.System, path string, prefs []string, maxBytes int64, probe mediaImageCacheProbe, ) (raw *rawMediaImage, fileBackedCandidatesChecked bool, err error) { db := env.Database.MediaDB directoryProps, err := db.GetDirectoryProperties(env.Context, system.DBID, path) if err != nil { return nil, false, fmt.Errorf("failed to get directory properties: %w", err) } if len(directoryProps) == 0 { return nil, false, nil } directoryRow := &database.MediaFullRow{ Path: path, System: database.System{ DBID: system.DBID, SystemID: system.SystemID, Name: system.Name, }, } raw, err = selectRawMediaImageFromSources( env.Context, afero.NewOsFs(), requestImageDir(env), env.Platform, db, directoryRow, nil, directoryProps, prefs, maxBytes, probe, ) if notFound, fileBacked := mediaImageNotFound(err); notFound { return nil, fileBacked, nil } return raw, false, err } // markFileBackedCandidatesChecked marks a no-image result as having checked // file-backed candidates when an earlier lookup for the same request did. func markFileBackedCandidatesChecked(err error, checked bool) error { if !checked { return err } var noImage *mediaImageNotFoundError if errors.As(err, &noImage) { noImage.fileBackedCandidatesChecked = true } return err } // loadRawMediaImageDirectoryRef loads the image for a directory entry and the // media it launches: the directory's own artwork, then that media's, then the // artwork of the media the path alone resolves to. The last keeps a // multi-disc folder's tile from going blank when the disc it launches has no // artwork of its own but the first disc does, which is what media.browse's // hasCover reports. func loadRawMediaImageDirectoryRef( env *requests.RequestEnv, ref mediaRefParam, prefs []string, maxBytes int64, probe mediaImageCacheProbe, ) (*rawMediaImage, error) { resolved, err := resolveMediaRefs(env, []mediaRefParam{ref}) if err != nil { return nil, err } if resolved[0].Err != nil { return nil, resolved[0].Err } row := resolved[0].Row raw, directoryFileBacked, err := loadRawMediaImageDirectory(env, row.System, ref.Path, prefs, maxBytes, probe) if raw != nil || err != nil { return raw, err } raw, err = loadRawMediaImageRow(env, row, prefs, maxBytes, probe) notFound, fileBacked := mediaImageNotFound(err) if !notFound { return raw, err } fileBacked = fileBacked || directoryFileBacked notFoundErr := markFileBackedCandidatesChecked(err, fileBacked) pathRow, pathErr := resolveMediaBySystemAndPath(env, ref.System, ref.Path) if pathErr != nil { var clientErr *models.ClientError if errors.As(pathErr, &clientErr) { return nil, notFoundErr } return nil, pathErr } if pathRow.DBID == row.DBID { return nil, notFoundErr } raw, err = loadRawMediaImageRow(env, pathRow, prefs, maxBytes, probe) if notFound, pathFileBacked := mediaImageNotFound(err); notFound { return nil, mediaImageNoImageError(row, fileBacked || pathFileBacked) } return raw, err } func loadRawMediaImageRow( env *requests.RequestEnv, row *database.MediaFullRow, prefs []string, maxBytes int64, probe mediaImageCacheProbe, ) (*rawMediaImage, error) { db := env.Database.MediaDB mediaPropSources, err := mediaImagePropSources(env, row) if err != nil { return nil, err } titleProps, err := db.GetMediaTitleProperties(env.Context, row.Title.DBID) if err != nil { return nil, fmt.Errorf("failed to get title properties: %w", err) } return selectRawMediaImageFromSources( env.Context, afero.NewOsFs(), requestImageDir(env), env.Platform, db, row, mediaPropSources, titleProps, prefs, maxBytes, probe, ) } func loadRawMediaImageByID( env *requests.RequestEnv, ref mediaRefParam, prefs []string, maxBytes int64, probe mediaImageCacheProbe, ) (*rawMediaImage, error) { resolved, err := resolveMediaRefs(env, []mediaRefParam{ref}) if err != nil { return nil, err } if resolved[0].Err != nil { return nil, resolved[0].Err } db := env.Database.MediaDB row := resolved[0].Row mediaPropSources, err := mediaImagePropSources(env, row) if err != nil { return nil, err } titleProps, err := db.GetMediaTitleProperties(env.Context, row.Title.DBID) if err != nil { return nil, fmt.Errorf("failed to get title properties: %w", err) } return selectRawMediaImageFromSources( env.Context, afero.NewOsFs(), requestImageDir(env), env.Platform, db, row, mediaPropSources, titleProps, prefs, maxBytes, probe, ) } func imagePrefs(topLevel, itemLevel []string) []string { if len(itemLevel) > 0 { return itemLevel } if len(topLevel) > 0 { return topLevel } return defaultImageTypes } func readMediaBinaryFile(fs afero.Fs, path string, maxBytes int64) ([]byte, error) { info, err := fs.Stat(path) if err != nil { return nil, fmt.Errorf("stat media binary file %q: %w", path, err) } if !info.Mode().IsRegular() { return nil, fmt.Errorf("media binary file %q is not a regular file", path) } if info.Size() > maxBytes { return nil, &mediaBinaryTooLargeError{path: path, size: info.Size(), max: maxBytes} } data, err := afero.ReadFile(fs, path) if err != nil { return nil, fmt.Errorf("read media binary file %q: %w", path, err) } if int64(len(data)) > maxBytes { return nil, &mediaBinaryTooLargeError{path: path, size: int64(len(data)), max: maxBytes} } return data, nil } func mediaImageReadError(path string, err error) error { var tooLarge *mediaBinaryTooLargeError if errors.As(err, &tooLarge) { return models.ClientErrf("media.image: image file too large: %s", tooLarge.Error()) } return fmt.Errorf("media.image: read image file %q: %w", path, err) } func mediaImageBlobTooLargeError(prop *database.MediaProperty, maxBytes int64) error { return models.ClientErrf( "media.image: image blob too large for %s: %d bytes exceeds %d byte limit", prop.TypeTag, prop.BlobSize, maxBytes, ) } func mediaImagePropSources(env *requests.RequestEnv, row *database.MediaFullRow) ([][]database.MediaProperty, error) { mediaIDs, err := equivalentMediaIDs(env, row) if err != nil { return nil, err } if len(mediaIDs) == 1 { props, propErr := env.Database.MediaDB.GetMediaProperties(env.Context, row.DBID) if propErr != nil { return nil, fmt.Errorf("failed to get media properties: %w", propErr) } return [][]database.MediaProperty{props}, nil } propsByID, err := env.Database.MediaDB.GetMediaPropertiesByMediaDBIDs(env.Context, mediaIDs) if err != nil { return nil, fmt.Errorf("failed to get media properties: %w", err) } sources := make([][]database.MediaProperty, 0, len(mediaIDs)) for _, id := range mediaIDs { sources = append(sources, propsByID[id]) } return sources, nil } func selectRawMediaImageFromSources( ctx context.Context, fs afero.Fs, imageDir string, platform platforms.Platform, db database.MediaDBI, row *database.MediaFullRow, mediaPropSources [][]database.MediaProperty, titleProps []database.MediaProperty, prefs []string, maxBytes int64, probe mediaImageCacheProbe, ) (*rawMediaImage, error) { sources := make([]mediaImageSource, 0, len(mediaPropSources)+1) for _, props := range mediaPropSources { sources = append(sources, mediaImageSource{buildPropsMap(props), true}) } sources = append(sources, mediaImageSource{buildPropsMap(titleProps), false}) fileBackedCandidatesChecked := false seen := make(map[string]bool, len(prefs)) for _, t := range prefs { typeTag, ok := resolveImageTypeTag(t) if !ok || seen[typeTag] { continue } seen[typeTag] = true for _, src := range sources { prop, ok := src.propMap[typeTag] if !ok { continue } if prop.Text != "" { fileBackedCandidatesChecked = true } raw, stale, err := loadRawMediaImageProperty( ctx, fs, imageDir, platform, db, row, &prop, src, typeTag, maxBytes, probe, ) if stale { delete(src.propMap, typeTag) continue } if err != nil { return nil, err } if raw != nil { return raw, nil } } } mediaImageProps := make([]string, 0) for _, props := range mediaPropSources { mediaImageProps = append(mediaImageProps, imagePropertyTypeTags(props)...) } log.Debug(). Str("system", row.System.SystemID). Str("path", row.Path). Int64("mediaDBID", row.DBID). Int64("titleDBID", row.Title.DBID). Strs("prefs", prefs). Strs("mediaImageProps", mediaImageProps). Strs("titleImageProps", imagePropertyTypeTags(titleProps)). Msg("media.image: no image found") return nil, mediaImageNoImageError(row, fileBackedCandidatesChecked) } func loadRawMediaImageProperty( ctx context.Context, fs afero.Fs, imageDir string, platform platforms.Platform, db database.MediaDBI, row *database.MediaFullRow, prop *database.MediaProperty, src mediaImageSource, typeTag string, maxBytes int64, probe mediaImageCacheProbe, ) (*rawMediaImage, bool, error) { var binary []byte var sourceKey string contentType := mediaContentType(prop.ContentType, prop.Text) switch { case len(prop.Binary) > 0: if int64(len(prop.Binary)) > maxBytes { return nil, false, mediaImageBlobTooLargeError(prop, maxBytes) } binary = prop.Binary sourceKey = dataThumbSourceKey(contentType, binary) case prop.BlobDBID != nil: if prop.BlobSize <= 0 { return nil, false, models.ClientErrf("media.image: image blob has unknown size for %s", prop.TypeTag) } if prop.BlobSize > maxBytes { return nil, false, mediaImageBlobTooLargeError(prop, maxBytes) } var err error binary, contentType, err = db.GetMediaBlobDataCapped(ctx, *prop.BlobDBID, maxBytes) if errors.Is(err, database.ErrMediaBlobTooLarge) { return nil, false, mediaImageBlobTooLargeError(prop, maxBytes) } if err != nil { return nil, false, fmt.Errorf("media.image: read image blob %d: %w", *prop.BlobDBID, err) } if len(binary) == 0 { logStaleMediaImageProperty(row, prop, src.isMedia, typeTag, "empty blob data") return nil, true, nil } sourceKey = dataThumbSourceKey(contentType, binary) case prop.Text != "": file, stale, err := loadMediaImageFile( ctx, fs, imageDir, platform, row, prop, src.isMedia, typeTag, maxBytes, probe, ) if stale || err != nil { return nil, stale, err } binary = file.data sourceKey = file.sourceKey default: return nil, false, nil } return &rawMediaImage{ binary: binary, contentType: contentType, text: prop.Text, typeTag: typeTag, system: row.System.SystemID, sourceKey: sourceKey, mediaDBID: row.DBID, cached: binary == nil, }, false, nil } func loadMediaImageFile( ctx context.Context, fs afero.Fs, imageDir string, platform platforms.Platform, row *database.MediaFullRow, prop *database.MediaProperty, isMedia bool, typeTag string, maxBytes int64, probe mediaImageCacheProbe, ) (file mediaImageFile, stale bool, err error) { if platforms.IsSourcePath(prop.Text) { data, sourceStale, sourceErr := loadSourceMediaImageFile(ctx, platform, row, prop, isMedia, typeTag, maxBytes) if sourceStale || sourceErr != nil { return mediaImageFile{}, sourceStale, sourceErr } return mediaImageFile{ data: data, sourceKey: dataThumbSourceKey(mediaContentType(prop.ContentType, prop.Text), data), }, false, nil } // An images:// path names a file in the image folder. It is read from // there, but keyed and reported by its images:// path. path := prop.Text if config.IsImagePath(path) { resolved, ok := config.ResolveImagePath(imageDir, path) if !ok { logStaleMediaImageProperty(row, prop, isMedia, typeTag, "image path outside the image folder") return mediaImageFile{}, true, nil } path = resolved } info, err := fs.Stat(path) if err != nil { if errors.Is(err, os.ErrNotExist) { logStaleMediaImageProperty(row, prop, isMedia, typeTag, err.Error()) return mediaImageFile{}, true, nil } return mediaImageFile{}, false, mediaImageReadError(path, err) } if !info.Mode().IsRegular() { err := fmt.Errorf("media binary file %q is not a regular file", path) return mediaImageFile{}, false, mediaImageReadError(path, err) } if info.Size() > maxBytes { return mediaImageFile{}, false, mediaImageReadError(path, &mediaBinaryTooLargeError{ path: path, size: info.Size(), max: maxBytes, }) } file.sourceKey = fileThumbSourceKey(prop.Text, info) if probe != nil && probe(file.sourceKey) { return file, false, nil } readStart := time.Now() data, readErr := readMediaBinaryFile(fs, path, maxBytes) if readErr != nil { if errors.Is(readErr, os.ErrNotExist) { logStaleMediaImageProperty(row, prop, isMedia, typeTag, readErr.Error()) return mediaImageFile{}, true, nil } return mediaImageFile{}, false, mediaImageReadError(path, readErr) } log.Debug().Dur("duration", time.Since(readStart)).Int("bytes", len(data)).Str("path", path). Msg("media.image: read source image") file.data = data return file, false, nil } // loadSourceMediaImageFile is loadMediaImageFile's counterpart for a folder // cover or media image stored under a source root: a platform.SourceFileReader // read instead of an afero.Fs one, since those bytes live behind the host // (e.g. SAF on Android), not on a filesystem Core can open directly. A // platform without the capability, or a read failure (the root may no longer // be granted), is treated as a stale property - the same graceful skip a // missing real file already gets - not a hard error. func loadSourceMediaImageFile( ctx context.Context, platform platforms.Platform, row *database.MediaFullRow, prop *database.MediaProperty, isMedia bool, typeTag string, maxBytes int64, ) (data []byte, stale bool, err error) { reader, ok := platform.(platforms.SourceFileReader) if !ok { logStaleMediaImageProperty(row, prop, isMedia, typeTag, "platform cannot read source root files") return nil, true, nil } content, readErr := reader.ReadSourceFile(ctx, prop.Text, maxBytes) if readErr != nil { logStaleMediaImageProperty(row, prop, isMedia, typeTag, readErr.Error()) return nil, true, nil } if int64(len(content)) > maxBytes { return nil, false, mediaImageReadError(prop.Text, &mediaBinaryTooLargeError{ path: prop.Text, size: int64(len(content)), max: maxBytes, }) } return content, false, nil } func logStaleMediaImageProperty( row *database.MediaFullRow, prop *database.MediaProperty, isMedia bool, typeTag string, reason string, ) { level := "title" if isMedia { level = "media" } log.Debug(). Str("system", row.System.SystemID). Str("path", row.Path). Int64("mediaDBID", row.DBID). Int64("titleDBID", row.Title.DBID). Str("typeTag", typeTag). Str("text", prop.Text). Str("source", level). Str("reason", reason). Msg("media.image: stale image property ignored") } // MediaImageMaxBytes is the largest image a media image request reads on pl. func MediaImageMaxBytes(pl platforms.Platform) int64 { if pl != nil && pl.ID() == ids.Mister { return misterMediaImageMaxBytes } return defaultMediaImageMaxBytes }