Gandalf/sofarr
Public Access
0
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases 59 Wiki Activity

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

New Issue
Closed
opened 2026-05-19 14:18:44 +01:00 by Gandalf · 1 comment
Gandalf commented 2026-05-19 14:18:44 +01:00
Owner
Copy Link
Copy Source

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 commented 2026-05-22 17:11:02 +01:00
Author
Owner
Copy Link
Copy Source

This issue has been fully implemented. The pluggable *arr retrieval architecture (PALDRA) is now complete and in production.

Implementation Summary:

  • Created abstract base class defining the interface for all retrievers
  • Implemented and with polling-based data retrieval
  • Created singleton factory modeled after PDCA pattern
  • Updated to use the registry generically, significantly simplifying the code
  • Added comprehensive unit tests for the registry and retriever implementations
  • Updated ARCHITECTURE.md to document PALDRA (Pluggable *Arr Library Data Retrieval Architecture)

Key Commits:

  • 627329d - feat: implement Pluggable Abstraction Layer for Data Retrieval (PALDRA) - #19
  • 6e19992 - refactor: make PALDRA match PDCA style exactly
  • 5159a83 - fix(retrievers): Use unique key to prevent Sonarr/Radarr collision
  • ed4237d - feat(ombi): Add Ombi PALDRA integration for request management
  • 4aa3590 - test: comprehensive test coverage for PALDRA

The architecture is now ready for future retrieval strategies (e.g., webhook listeners) to push normalized data directly into the existing cache and SSE system without touching the poller logic, as originally specified.

This issue has been fully implemented. The pluggable *arr retrieval architecture (PALDRA) is now complete and in production. **Implementation Summary:** - Created abstract base class defining the interface for all retrievers - Implemented and with polling-based data retrieval - Created singleton factory modeled after PDCA pattern - Updated to use the registry generically, significantly simplifying the code - Added comprehensive unit tests for the registry and retriever implementations - Updated ARCHITECTURE.md to document PALDRA (Pluggable *Arr Library Data Retrieval Architecture) **Key Commits:** - 627329d - feat: implement Pluggable Abstraction Layer for Data Retrieval (PALDRA) - #19 - 6e19992 - refactor: make PALDRA match PDCA style exactly - 5159a83 - fix(retrievers): Use unique key to prevent Sonarr/Radarr collision - ed4237d - feat(ombi): Add Ombi PALDRA integration for request management - 4aa3590 - test: comprehensive test coverage for PALDRA The architecture is now ready for future retrieval strategies (e.g., webhook listeners) to push normalized data directly into the existing cache and SSE system without touching the poller logic, as originally specified.
Gandalf added the Area/Matching label 2026-05-28 11:58:41 +01:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Area/Docker
Docker image and container packaging
 Area/Download Clients
Download client integrations
 Area/Frontend
Client-side UI and build tooling
 Area/History
History and completed downloads views
 Area/Logging
Log streaming, file handling, and debug infrastructure
 Area/Matching
Matching and correlation logic
 Area/Proxy
Upstream service proxy routes
 Area/SSE
Server-Sent Events and real-time streaming
 Area/Webhooks
Webhook processing and reliability
 Compat/Breaking
Breaking change that won't be backward compatible
 Compat/Non-Breaking
Non-breaking compatibility change
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Area/Matching Kind/Enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Gandalf
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Gandalf/sofarr#19
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?