fix: synchronize bounded Servarr download queues

[constbogdan]

Description

Continues the work originally proposed in #1055, preserving Mavyre's original commit authorship, and incorporates the additional queue synchronization fixes previously submitted in #3473.

This change:

• adds a configurable Download Queue Size for each Sonarr/Radarr server;
• defaults the limit to 10, with an allowed range of 10–1000;
• retrieves Servarr queues using bounded pagination up to the configured total limit;
• waits for the exact RefreshMonitoredDownloads command to complete before reading the queue;
• applies bounded command polling and timeout handling;
• prevents overlapping Download Sync runs from performing duplicate work;
• keeps Radarr and Sonarr server processing parallel;
• handles duplicate server aliases while respecting each configured queue limit;
• catches and logs scheduled Download Sync failures.

The queue limit only controls how many active queue items Seerr retrieves and tracks during Download Sync. It does not affect Sonarr/Radarr download processing.

Mavyre confirmed in #1055 that opening a new PR referencing the original work was welcome.

References #1055.
Supersedes #3473.

How Has This Been Tested?

Automated validation:

• 37/37 focused Servarr queue, command polling, and DownloadTracker tests passed.
• 226/226 complete tests passed.
• pnpm build passed.
• pnpm lint passed with 19 pre-existing warnings in untouched files.
• pnpm format:check passed.
• pnpm i18n:extract passed.
• git diff --check passed.

Live integration testing was also performed using a local Seerr development instance connected to real Sonarr and Radarr services.

Observed queue behavior:

• queue limit 10 → Seerr tracked 10 items;
• queue limit 50 → Seerr tracked all 18 available items;
• when the live queue later increased to 21 items, Seerr refreshed and tracked all 21.

The Radarr and Sonarr settings UI, validation, Advanced tooltip, and queue-size configuration were also tested manually.

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)

AI Assistance Notice

AI assistance was used during implementation, review, and test preparation. All resulting changes were manually reviewed and validated with the automated and live integration tests described above.

Summary by CodeRabbit

• New Features

  • Added an advanced Download Queue Size setting for Radarr and Sonarr, configurable from 10–1,000 items.
  • Download Sync now retrieves queue items according to each server’s configured limit.
  • Queue updates support pagination and wait for refresh commands to complete.

• Bug Fixes

  • Improved handling of concurrent download updates and sync failures.
  • Scheduled download synchronization now logs update errors instead of failing silently.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 2e56c796-e6bf-4de7-a1ed-3d6a941241ec

📥 Commits

Reviewing files that changed from the base of the PR and between 794743a and 3093f86.

📒 Files selected for processing (10)

• seerr-api.yml
• server/api/servarr/base.test.ts
• server/api/servarr/base.ts
• server/job/schedule.ts
• server/lib/downloadtracker.test.ts
• server/lib/downloadtracker.ts
• server/lib/settings/index.ts
• src/components/Settings/RadarrModal/index.tsx
• src/components/Settings/SonarrModal/index.tsx
• src/i18n/locale/en.json

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

---

📝 Walkthrough

Walkthrough

The change adds configurable Radarr and Sonarr download queue limits. Servarr APIs now paginate queue retrieval and poll refresh commands. DownloadTracker coordinates bounded, deduplicated updates and scheduled errors are logged.

Changes

Download queue configuration

Layer / File(s)	Summary
Queue size configuration seerr-api.yml, server/lib/settings/index.ts, src/components/Settings/..., src/i18n/locale/en.json	Radarr and Sonarr settings add downloadQueueSize, defaulting to 10 and accepting integers from 10 through 1000. The setting is exposed in both configuration modals and the API schemas.

Servarr API behavior

Layer / File(s)	Summary
Servarr queue and command handling server/api/servarr/base.ts, server/api/servarr/base.test.ts	getQueue validates limits, retrieves pages, checks response consistency, and caps results. refreshMonitoredDownloads polls command status and handles completion, failure, and timeout states. Tests cover Radarr, Sonarr, pagination, validation, and polling.

Download synchronization

Layer / File(s)	Summary
Download tracker synchronization server/lib/downloadtracker.ts, server/lib/downloadtracker.test.ts, server/job/schedule.ts	DownloadTracker deduplicates concurrent updates, updates Radarr and Sonarr in parallel, applies per-server limits, stores independent snapshots, and filters disabled servers. The scheduled job logs rejected updates. Tests cover these behaviors.

Priority: ➖ Normal

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

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant DownloadSyncJob
  participant DownloadTracker
  participant RadarrAPI
  participant SonarrAPI
  DownloadSyncJob->>DownloadTracker: updateDownloads()
  DownloadTracker->>RadarrAPI: refresh and fetch bounded queue
  DownloadTracker->>SonarrAPI: refresh and fetch bounded queue
  RadarrAPI-->>DownloadTracker: queue data
  SonarrAPI-->>DownloadTracker: queue data
  DownloadTracker-->>DownloadSyncJob: complete or reject

Loading

Suggested reviewers: gauthier-th, fallenbagel

Merge Risk: ⚪ Minimal · up to 3093f

The PR bounds and paginates Servarr queue retrieval, waits for refresh commands, and coordinates deduplicated Radarr/Sonarr synchronization. Supplied evidence covers the changed behavior and failure paths, with no actionable merge-blocking risk remaining.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: bounded synchronization of Servarr download queues. It is concise, specific, and related to the configured queue limits and pagination changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

_{A rabbit sets the queue to ten,
Then gathers pages again and again.
Radarr hops, Sonarr too,
Each snapshot kept fresh and true.
Failed commands leave logs behind.}

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