Skip to content

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb/issues/137. This local document is retained as an engineering spec/evidence record.

ARR-002 - Make Arr automatic search cache-backed and network-friendly

Summary

Improve the Arr-facing Torznab integration so unattended Prowlarr, Radarr, and Sonarr searches can run on a regular cadence without turning every controller poll into fresh eD2K/Kad network work.

The current integration is reactive: Arr-family clients call /indexer/emulebb/api, and eMuleBB starts bounded native searches for concrete Torznab search, movie, and tvsearch requests. This works for manual and controlled automatic search, but the bridge should be more robust before operators enable broad unattended cadence.

Intended Shape

  • Keep concrete Torznab automatic searches supported and bounded.
  • Make empty-query or RSS-like Arr polling return a cache-backed recent feed only; it must not launch a fresh Kad or eD2K search by itself.
  • Coalesce identical in-flight Torznab queries so concurrent Arr calls share one native search instead of receiving avoidable 503 responses.
  • Return useful stale cached results while a refresh is in progress when the cached key matches the request and the cached data is still inside a safe freshness window.
  • Add per-client and global search budgets for the bridge so automatic search cannot monopolize the native search engine.
  • Keep Kad participation conservative: use Kad for media fallback and connected cases already supported by the adapter, but avoid widening fanout or retry cadence just because an Arr app polls often.
  • Expose small diagnostics for the most recent Arr bridge decisions: cache hit, cache miss, coalesced, live search started, stale result served, busy, network methods used, result count, and last error.
  • Update helper defaults and docs so Interactive Search remains on, Automatic Search is explicitly operator-controlled, and RSS remains off unless the cache-backed feed behavior is implemented.

Scope Constraints

  • Do not implement qBittorrent RSS APIs; this item is about the Torznab bridge and native search budgeting.
  • Do not run live native searches for empty-query feed requests.
  • Do not let Arr bridge work bypass native REST search validation, connection checks, or fake/spam result filtering.
  • Do not increase Kad source-search fanout or background cadence as part of this item.
  • Do not make Prowlarr mandatory; direct Radarr/Sonarr Torznab use should keep working where those clients support it.

Acceptance Criteria

  • [ ] Repeated identical Torznab requests coalesce onto one live native search.
  • [ ] Cache hits and non-zero offset pages do not start a new native search.
  • [ ] Empty-query RSS/feed-style Torznab calls return recent cached/feed rows or an empty accepted feed without live network search.
  • [ ] A stale-while-refresh path can serve safe cached results while one refresh is already in flight.
  • [ ] Bridge-level budgets throttle noisy Arr cadence without blocking normal desktop searches.
  • [ ] Diagnostics identify whether a request was served from cache, coalesced, rejected as busy, or dispatched to native search.
  • [ ] Prowlarr/Radarr/Sonarr setup docs state the safe defaults for Interactive Search, Automatic Search, and RSS.
  • [ ] Focused seam tests cover cache/feed policy, coalescing, and budget decisions without requiring live Arr apps.