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

Pluggable Download Client Architecture (PDCA) – Unified Interface + Expanded Client Support #18

New Issue
Closed
opened 2026-05-19 11:01:12 +01:00 by Gandalf · 0 comments
Gandalf commented 2026-05-19 11:01:12 +01:00
Owner
Copy Link
Copy Source

Problem Statement

Sofarr currently handles download clients in a semi-coupled way:

SABnzbd logic lives mostly inside the poller.
qBittorrent has its own dedicated client class (recently enhanced with the Sync API).

This makes adding new clients (rtorrent, uTorrent, Transmission, Deluge) expensive and risks inconsistent data shapes in the cache and dashboard. Every new client duplicates authentication, error handling, normalization, and caching logic.

Goal

Introduce a clean, pluggable abstraction layer for all download clients (Usenet + BitTorrent) so that:

The poller and cache become client-agnostic.
Adding a new client is a matter of implementing a small, well-defined interface.
All clients produce a normalized download object that the rest of the application can consume without knowing the underlying client.

Scope

  • Define a DownloadClient abstract base class / interface with these core methods:

    • getActiveDownloads() → normalized array
    • getClientStatus() (optional but recommended)
    • testConnection() / health check

  • Refactor existing clients to implement the interface:

    • SABnzbdClient
    • QBittorrentClient (preserve the Sync API work already done)

  • Create a DownloadClientFactory + registry (config-driven).

  • Update the poller to iterate over registered clients generically.

  • Normalize all download objects to a common schema (see below).

  • Comprehensive unit + integration tests for the new abstraction.

  • Update ARCHITECTURE.md and add a small “Adding a New Download Client” guide.

Normalized Download Object (Proposed Schema)
All clients must return objects matching this shape (extensible via raw or clientSpecific):

interface NormalizedDownload {
  id: string;                    // client-specific unique id
  title: string;
  type: 'usenet' | 'torrent';
  client: string;                // 'sabnzbd' | 'qbittorrent' | 'transmission' ...
  instanceId: string;
  instanceName: string;
  status: string;                // normalized (Downloading, Seeding, Paused, etc.)
  progress: number;              // 0-100
  size: number;                  // bytes
  downloaded: number;            // bytes
  speed: number;                 // bytes/sec
  eta: number | null;            // seconds
  category?: string;
  tags?: string[];
  savePath?: string;
  addedOn?: string;
  // For matching to Sonarr/Radarr
  arrQueueId?: number;
  arrType?: 'series' | 'movie';
  // Escape hatch
  raw?: any;                     // original client response (for advanced use)
}

Success Metrics

  • 100% of existing functionality preserved (no regressions in SABnzbd or qBittorrent).
  • Poller becomes ~30-40% smaller and easier to reason about.
  • Passes all existing integration tests.
**Problem Statement** Sofarr currently handles download clients in a semi-coupled way: SABnzbd logic lives mostly inside the poller. qBittorrent has its own dedicated client class (recently enhanced with the Sync API). This makes adding new clients (rtorrent, uTorrent, Transmission, Deluge) expensive and risks inconsistent data shapes in the cache and dashboard. Every new client duplicates authentication, error handling, normalization, and caching logic. **Goal** Introduce a clean, pluggable abstraction layer for all download clients (Usenet + BitTorrent) so that: The poller and cache become client-agnostic. Adding a new client is a matter of implementing a small, well-defined interface. All clients produce a normalized download object that the rest of the application can consume without knowing the underlying client. **Scope** - Define a DownloadClient abstract base class / interface with these core methods: - getActiveDownloads() → normalized array - getClientStatus() (optional but recommended) - testConnection() / health check - Refactor existing clients to implement the interface: - SABnzbdClient - QBittorrentClient (preserve the Sync API work already done) - Create a DownloadClientFactory + registry (config-driven). - Update the poller to iterate over registered clients generically. - Normalize all download objects to a common schema (see below). - Comprehensive unit + integration tests for the new abstraction. - Update ARCHITECTURE.md and add a small “Adding a New Download Client” guide. **Normalized Download Object (Proposed Schema)** All clients must return objects matching this shape (extensible via raw or clientSpecific): ```ts interface NormalizedDownload { id: string; // client-specific unique id title: string; type: 'usenet' | 'torrent'; client: string; // 'sabnzbd' | 'qbittorrent' | 'transmission' ... instanceId: string; instanceName: string; status: string; // normalized (Downloading, Seeding, Paused, etc.) progress: number; // 0-100 size: number; // bytes downloaded: number; // bytes speed: number; // bytes/sec eta: number | null; // seconds category?: string; tags?: string[]; savePath?: string; addedOn?: string; // For matching to Sonarr/Radarr arrQueueId?: number; arrType?: 'series' | 'movie'; // Escape hatch raw?: any; // original client response (for advanced use) } ``` **Success Metrics** - 100% of existing functionality preserved (no regressions in SABnzbd or qBittorrent). - Poller becomes ~30-40% smaller and easier to reason about. - Passes all existing integration tests.
Gandalf added the Kind/Enhancement label 2026-05-19 11:01:12 +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 labels Kind/Enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
Gandalf
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Gandalf/sofarr#18