Status: ✅ Implemented | Cache library covers during scans, serve in BookDate
Caches book covers from Plex/Audiobookshelf during library scans. Stores cached files in /app/cache/library/ with SHA-256 hashed filenames. Dramatically improves BookDate user experience by showing real covers instead of placeholders.
- When: During full scans (scan-plex.processor.ts) and recently-added scans (plex-recently-added.processor.ts)
- Where:
/app/cache/library/directory - Filename: SHA-256 hash (first 16 chars) of plexGuid + extension (e.g.,
a3f5e9d2c1b4.jpg) - Smart caching: Checks if file exists before downloading (subsequent scans are fast)
- Field:
PlexLibrary.cachedLibraryCoverPath(nullable TEXT) - Stores: Full path like
/app/cache/library/{hash}.jpg - Migration:
20260120000000_add_cached_library_cover_path
- Plex:
{serverUrl}{thumbUrl}?X-Plex-Token={token} - Audiobookshelf:
{serverUrl}{coverPath}withAuthorization: Bearer {token}header
- Library cached cover (
cachedLibraryCoverPath) →/api/cache/library/{filename} - Audible cache (if book has ASIN) → from
AudibleCache.coverArtUrl - Null (show placeholder 📚)
Serves cached library covers (24-hour browser cache).
Path validation: Prevents directory traversal (rejects .. and /).
Content types: jpg, jpeg, png, gif, webp → image/*, else application/octet-stream
Returns library books with cover URLs.
Response:
{
"books": [
{
"id": "uuid",
"title": "Book Title",
"author": "Author Name",
"coverUrl": "/api/cache/library/a3f5e9d2c1b4.jpg" // or Audible URL, or null
}
]
}Located: src/lib/services/thumbnail-cache.service.ts
Methods:
cacheLibraryThumbnail(plexGuid, coverUrl, backendBaseUrl, authToken, backendMode)→ Returns cached path or nullcleanupLibraryThumbnails(plexGuidToHashMap)→ Returns deleted count
Safeguards:
- 10s timeout per download
- 5MB max file size
- Content-type validation (must be image/*)
- Graceful degradation (logs warning, returns null on failure)
Located: src/lib/services/library/
Both PlexLibraryService and AudiobookshelfLibraryService provide:
getCoverCachingParams()→ Returns{ backendBaseUrl, authToken, backendMode }
- Database: ~30 seconds
- Downloads: ~1-5 minutes (network-dependent)
- Total: ~1.5-5.5 minutes (one-time cost)
- Database: ~30 seconds
- Downloads: ~0 seconds (skipped, files exist)
- Total: ~30 seconds (same as before caching)
- Before: Mostly placeholder covers
- After: Real covers for all books with valid thumbUrl
- Performance: No change (local file serving is fast)
- Download fails → log warning, store null, continue scan
- Invalid content-type → reject, store null
- File system errors → log, store null
- Missing backend config → throw (scan fails early with clear error)
Manual or Scheduled:
- Builds hash-to-plexGuid reverse map from database
- Deletes cached files for plexGuids no longer in library
- Returns count of deleted files
Trigger: Admin endpoint or weekly scheduled job
Volume mount required:
volumes:
- ./cache/library:/app/cache/libraryEnsures cached covers persist across container restarts.
- documentation/backend/database.md (PlexLibrary schema)
- documentation/features/bookdate.md (cover loading logic)
- documentation/integrations/audible.md (Audible thumbnail caching pattern)
- documentation/backend/services/jobs.md (scan processors)