Make *arr retrieval process pluggable to support future enhancements #19

New Issue

Gandalf · 2026-05-19T14:18:44+01:00

Gandalf commented

2026-05-19 14:18:44 +01:00

Problem Statement

While the Pluggable Download Client Architecture (PDCA) has successfully unified download-client handling (see #18), Sonarr and Radarr data retrieval remains hardcoded with direct Axios calls inside poller.js (and historyFetcher.js).

This tight coupling makes it difficult to introduce alternative retrieval strategies (such as event-driven listeners) without duplicating logic, risking regressions, or bloating the poller.

Goal

Introduce a clean, pluggable abstraction layer for all Sonarr and Radarr data retrieval that mirrors the PDCA pattern already used for download clients.

This refactor must:

Keep current polling behavior, caching, SSE broadcasting, error handling, timing logs, and public APIs 100% unchanged.
Significantly simplify poller.js.
Lay the architectural groundwork so a future webhook listener (or any other retrieval strategy) can push normalized data directly into the existing cache and SSE system without touching the poller.

Scope

Define an ArrRetriever abstract base class / interface (in server/clients/) with core methods:
- getTags(instance)
- getQueue(instance)
- getHistory(instance, options?)
Create a central registry/factory (server/utils/arrRetrievers.js) modeled exactly after DownloadClientRegistry.
Implement default polling-based retrievers:
- PollingSonarrRetriever
- PollingRadarrRetriever
Move all existing Axios logic from poller.js (and affected parts of historyFetcher.js) into these new classes.
Update poller.js to use the registry generically (in the same style as download clients).
Ensure the design remains open for future implementations that feed the same normalized data and cache keys.
Comprehensive unit + integration tests for the new abstraction.
Minimal updates to documentation (e.g., ARCHITECTURE.md or README if present).

Normalized Data Requirements

All retrievers must return data in exactly the same shape and cache-key format currently used by the poller (no changes to existing cache keys, TTLs, or downstream consumers).

Success Metrics

100% of existing functionality and performance characteristics are preserved (no regressions in dashboard updates, multi-instance support, or polling).
poller.js becomes noticeably smaller and focused only on orchestration.
The architecture is immediately ready for a follow-up webhook listener with zero further refactoring of the core retrieval layer.
All existing tests continue to pass.

Notes

This is a foundational, non-breaking refactor only.
The change must follow the exact style, error-isolation patterns, and naming conventions established in the PDCA (#18).

**Problem Statement** While the Pluggable Download Client Architecture (PDCA) has successfully unified download-client handling (see #18), Sonarr and Radarr data retrieval remains hardcoded with direct Axios calls inside `poller.js` (and `historyFetcher.js`). This tight coupling makes it difficult to introduce alternative retrieval strategies (such as event-driven listeners) without duplicating logic, risking regressions, or bloating the poller. **Goal** Introduce a clean, pluggable abstraction layer for all Sonarr and Radarr data retrieval that mirrors the PDCA pattern already used for download clients. This refactor must: - Keep **current polling behavior, caching, SSE broadcasting, error handling, timing logs, and public APIs 100% unchanged**. - Significantly simplify `poller.js`. - Lay the architectural groundwork so a future webhook listener (or any other retrieval strategy) can push normalized data directly into the existing cache and SSE system **without touching the poller**. **Scope** - Define an `ArrRetriever` abstract base class / interface (in `server/clients/`) with core methods: - `getTags(instance)` - `getQueue(instance)` - `getHistory(instance, options?)` - Create a central registry/factory (`server/utils/arrRetrievers.js`) modeled exactly after `DownloadClientRegistry`. - Implement default polling-based retrievers: - `PollingSonarrRetriever` - `PollingRadarrRetriever` - Move all existing Axios logic from `poller.js` (and affected parts of `historyFetcher.js`) into these new classes. - Update `poller.js` to use the registry generically (in the same style as download clients). - Ensure the design remains open for future implementations that feed the same normalized data and cache keys. - Comprehensive unit + integration tests for the new abstraction. - Minimal updates to documentation (e.g., ARCHITECTURE.md or README if present). **Normalized Data Requirements** All retrievers must return data in exactly the same shape and cache-key format currently used by the poller (no changes to existing cache keys, TTLs, or downstream consumers). **Success Metrics** - 100% of existing functionality and performance characteristics are preserved (no regressions in dashboard updates, multi-instance support, or polling). - `poller.js` becomes noticeably smaller and focused only on orchestration. - The architecture is immediately ready for a follow-up webhook listener with zero further refactoring of the core retrieval layer. - All existing tests continue to pass. **Notes** - This is a **foundational, non-breaking refactor** only. - The change must follow the exact style, error-isolation patterns, and naming conventions established in the PDCA (#18).

Gandalf added the Kind/Enhancement label 2026-05-19 14:23:01 +01:00

Gandalf referenced this issue from a commit

2026-05-19 14:43:43 +01:00

feat: implement Pluggable Abstraction Layer for Data Retrieval (PALDRA) - #19

Gandalf referenced this issue from a commit

2026-05-19 15:10:33 +01:00

Merge branch 'develop-paldra' into develop

Sign in to join this conversation.