[fallenbagel]

Description

Library scans and availability sync fetched the full /tv/:id payload including aggregate_credits and cached it for 12 hours in the same unbounded cache the interactive TV detail page uses, so a full scan left most of a library resident until the TTL expired. Scanners and availability sync now request only keywords and external_ids, which is everything they read, and write to a separate LRU-bounded cache with a 15 minute TTL, so scan lookups age out on their own instead of evicting manual browsing traffic. The interactive cache gains a key-count backstop against unbounded growth, and aggregate_credits.crew and credits.cast are stripped before caching since nothing in the codebase reads either.

Both tiers are capped by key count rather than bytes. There is no per-entry ceiling to derive for the interactive tier because TMDB doesn't cap the credit rosters, and for the scan tier the TTL is what actually bounds occupancy: a larger library takes proportionally longer to walk rather than holding proportionally more at once.

Separately, the recently added scan asked Plex for items without includeGuids=1, unlike the full scan, so every newly added movie fell back to a per-item /library/metadata request on each pass while it sat inside the scan's ten minute overlap window. That flag is now set on the movie query only as the show query is left alone because it returns episodes, whose guids the scanner never reads. The plexguid cache is removed along with it as it was keyed by rating key, its cache-hit branch never actually skipped anything since the metadata fetch below it ran unconditionally and overwrote the cached ids, and with guids arriving inline the only thing it still did, reusing an external-id resolve, is already handled by the scan cache tier. Every scan, full or recently added, now derives ids from what Plex reports at that moment, so a corrected match in Plex is picked up on the next scan exactly as before.

In addition, node-cache was entirely dropped in favour of lru-cache.

• Fixes Library scans blow out the V8 heap and kill the process (still happens at mem_limit 1g) #3307

How Has This Been Tested?

Tested on two instances: mine (with just my tv library enabled), and the reporter of #3307, where the crash in in that issue was reproducible nightly.

On my instance, heap snapshots over Chrome DevTools Protocol with the same library both pre- and post- fix:

	before	after
idle	110 MB	107 MB
post-sync	270 MB	124 MB
+30 min, forced GC	269 MB	121 MB

Cache counters were identical across both runs (33 hits, 482 misses, 482 keys), so both pre- and post- fix resolved the same set of shows. The scan tier drained from 482 keys to 11 over the 30 minutes so TTL is also working as intended.

The reporter ran the same sequence from a fresh container on each pre- and post- fix, used_heap_size after two forced collections:

	develop	this branch
idle after restart	99.68 MiB	98.83 MiB
after availability sync	451.22 MiB	128.47 MiB
+30 min, forced GC	452.63 MiB	116.01 MiB
Sonarr scan from that state	died at 2m28s	completed in 4m46s

The sync took 810s on develop and 840s on the branch, so both pre- and post- fix did the same work. Afterwards the tmdb cache on develop held 175.03 MiB of JSON against 7.29 MiB in tmdbscan on the branch, and the scan tier had drained to zero keys by the 30 minute probe.

They have since been running it without restarts and without heap aborts, sitting at 129.89 MiB after an unattended job block, on the same box that aborted five nights running.

Screenshots / Logs (if applicable)

Checklist:

• I have read and followed the contribution guidelines.
• Disclosed any use of AI (see our policy)
• I have updated the documentation accordingly.
• All new and existing tests passed.
• Successful build pnpm build
• Translation keys pnpm i18n:extract
• Database migration (if required)

Summary by CodeRabbit

Performance

• Improved TV metadata lookup speed with bounded caching and automatic expiration.
• Reduced unnecessary metadata processing during library scans.

Bug Fixes

• Improved TV show identification across Jellyfin, Plex, and Sonarr scans.
• Added more reliable TVDB, IMDb, and AniDB resolution during scanning.
• Improved matching accuracy when resolving external identifiers.
• Improved handling of missing or incomplete TV metadata during scans.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b753b6d2-2317-4f63-ada6-08e0b4fc8937

📥 Commits

Reviewing files that changed from the base of the PR and between c9825ab and b30cfd7.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (5)

• package.json
• server/api/plexapi.ts
• server/lib/cache.ts
• server/lib/scanners/plex/index.ts
• src/components/Settings/SettingsJobsCache/index.tsx

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

TMDB TV lookups now support reduced scan responses with dedicated bounded LRU caching. Shared cache handling supports per-call stores and transformations. Availability synchronization and Jellyfin, Plex, and Sonarr scanners use scan-specific methods.

Changes

TMDB scan caching and integrations

Layer / File(s)	Summary
Bounded cache storage package.json, server/lib/cache.ts	Replaced node-cache with bounded LRU storage. Added CacheStore, cache statistics, cloning, size tracking, explicit key limits, and the tmdbscan cache.
Configurable TMDB TV requests server/api/externalapi.ts, server/api/themoviedb/index.ts, server/api/themoviedb/interfaces.ts	Added configurable cache and transformation handling. Added reduced TV scan responses, dedicated TTLs, scan cache access, external-ID validation, and shared TVDB resolution.
Availability season enrichment server/lib/availabilitySync.ts, server/lib/availabilitySync.test.ts	Availability synchronization now uses scan-specific TMDB lookups and supports scan or full TV details. Tests use scan-specific method mocks.
Media scanner lookups server/lib/scanners/jellyfin/*, server/lib/scanners/plex/index.ts, server/lib/scanners/sonarr/*	Jellyfin, Plex, and Sonarr resolution paths now use scan-specific TMDB methods and types. Plex no longer stores GUID results in the removed GUID cache. Test mocks support the new methods.
API and cache settings integration server/api/plexapi.ts, src/components/Settings/SettingsJobsCache/index.tsx	Plex requests GUIDs only for movie queries. The cache settings table now displays all API caches.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: ⚪ Minimal · up to b30cf

The change bounds cache growth and separates short-lived scan lookups from interactive browsing data, with reported tests showing substantially lower memory use and completed scans; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Scanner
  participant TheMovieDb
  participant ExternalAPI
  participant CacheStore
  Scanner->>TheMovieDb: Request scan TV details
  TheMovieDb->>ExternalAPI: Send reduced TV detail request
  ExternalAPI->>CacheStore: Read or write transformed response
  CacheStore-->>ExternalAPI: Return cached scan response
  ExternalAPI-->>TheMovieDb: Return scan details
  TheMovieDb-->>Scanner: Return TmdbTvScanDetails

Loading

Suggested reviewers: 0xsysr3ll, danshilm

Poem

A rabbit caches shows with care,
LRU shelves hold details there.
Scan responses stay small and bright,
TTLs retire them at the right time,
Scanners hop through every show.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address issue #3307 by bounding cache growth, using a separate 15-minute scan cache, limiting scan response fields, removing unused credit data, and preventing repeated scans from retainin…
Out of Scope Changes check	✅ Passed	The changes are related to the stated memory-reduction objective. Dependency replacement, scanner updates, cache UI updates, and movie-only GUID requests support the bounded cache and scan-tier design…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: bounding the TMDB cache and separating scan lookups into a dedicated tier.

Full details: Linked Issues check

Explanation

The changes address issue #3307 by bounding cache growth, using a separate 15-minute scan cache, limiting scan response fields, removing unused credit data, and preventing repeated scans from retaining unbounded TMDB responses.

Full details: Out of Scope Changes check

Explanation

The changes are related to the stated memory-reduction objective. Dependency replacement, scanner updates, cache UI updates, and movie-only GUID requests support the bounded cache and scan-tier design.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Bounds TMDB caching and separates lightweight scan traffic from interactive TV-detail traffic to reduce memory pressure.

Changes:

• Adds bounded LRU caches for interactive and scan workloads.
• Introduces lightweight TMDB TV scan responses.
• Migrates scanners and availability sync to scan-specific lookups.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
server/lib/cache.ts	Adds bounded LRU cache tiers.
server/api/externalapi.ts	Supports per-request caches and transforms.
server/api/themoviedb/index.ts	Adds lightweight scan lookups and strips unused credits.
server/api/themoviedb/interfaces.ts	Defines scan response shape.
server/lib/scanners/sonarr/index.ts	Uses scan-tier TV lookups.
server/lib/scanners/plex/index.ts	Uses scan-tier TV lookups.
server/lib/scanners/jellyfin/index.ts	Uses scan-tier TV lookups.
server/lib/availabilitySync.ts	Uses scan-tier TV lookups.
package.json	Adds lru-cache.
pnpm-lock.yaml	Locks the dependency.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cypress]

seerr    Run #3648

Run Properties:   Failed #3648  •  59ad5f1916: perf: bound tmdb cache & split scan lookups into their own tier (#3367)

Project	seerr
Branch Review	develop
Run status	Failed #3648
Run duration	02m 37s
Commit	59ad5f1916: perf: bound tmdb cache & split scan lookups into their own tier (#3367)
Committer	fallenbagel
View all properties for this run ↗︎

---

Test results
Failures	1
Flaky	0
Pending	0
Skipped	0
Passing	32
View all changes introduced in this branch ↗︎

---

Tests for review

  cypress/e2e/settings/general-settings.cy.ts • 1 failed test

View Output Video

Test		Artifacts
General Settings > modifies setting that requires restart		Test Replay Screenshots Video

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (1)

server/api/themoviedb/index.ts:983

• Scan /find lookups still expire after 5 minutes: passing undefined here makes ExternalAPI.get() write with its 300-second default, overriding the scan cache's configured 900-second TTL. This makes TVDB/IMDb mappings age out earlier than the rest of the scan tier and can cause repeated TMDB requests during longer scans. Preserve the existing 5-minute behavior for the interactive cache, but pass SCAN_TTL when the scan cache is supplied.

        undefined,
        { cache }

[fallenbagel]

Ignore the failing cypress tests. That's unrelated to this PR and not relevant to users and is fixed by
#3368 anyways.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[0xSysR3ll]

LGTM

[fallenbagel]

Ignore the failing cypress test. It will be fixed on:
#3432

[gauthier-th]

LGTM