sofarr/docs/ADDING-A-DOWNLOAD-CLIENT.md

Adding a New Download Client to Sofarr

This guide explains how to add support for a new download client to Sofarr using the Pluggable Download Client Architecture (PDCA).

Overview

The PDCA makes adding new download clients straightforward by providing a standardized interface. You only need to implement the DownloadClient abstract base class and register your client in the configuration system.

Prerequisites

• Familiarity with JavaScript/Node.js
• Understanding of your target client's API
• Basic knowledge of Sofarr's architecture (see ARCHITECTURE.md)

Step 1: Create the Client Class

Create a new file in server/clients/ named after your client (e.g., DelugeClient.js).

// server/clients/DelugeClient.js
const DownloadClient = require('./DownloadClient');
const { logToFile } = require('../utils/logger');

class DelugeClient extends DownloadClient {
  constructor(instance) {
    super(instance);
    // Add any client-specific initialization here
    this.sessionId = null;
    this.rpcUrl = `${this.url}/json`;
  }

  getClientType() {
    return 'deluge';
  }

  async testConnection() {
    try {
      // Implement connection test logic
      const response = await this.makeRequest('auth.check_session');
      logToFile(`[Deluge:${this.name}] Connection test successful`);
      return true;
    } catch (error) {
      logToFile(`[Deluge:${this.name}] Connection test failed: ${error.message}`);
      return false;
    }
  }

  async makeRequest(method, params = []) {
    // Implement RPC call logic
    const payload = {
      method: method,
      params: params,
      id: Date.now()
    };

    // Add authentication if needed
    if (this.sessionId) {
      payload.params.unshift(this.sessionId);
    }

    // Make HTTP request to your client's API
    // Handle authentication, errors, etc.
  }

  async getActiveDownloads() {
    try {
      // Fetch downloads from your client
      const torrents = await this.makeRequest('core.get_torrents_status', 
        [{}, ['name', 'state', 'progress', 'total_size', 'download_payload_rate']]
      );

      // Normalize each download using the standard schema
      return Object.entries(torrents).map(([id, torrent]) => 
        this.normalizeDownload({ ...torrent, id })
      );
    } catch (error) {
      logToFile(`[Deluge:${this.name}] Error fetching downloads: ${error.message}`);
      return [];
    }
  }

  async getClientStatus() {
    try {
      // Optional: Return client status information
      const status = await this.makeRequest('core.get_session_status');
      return status;
    } catch (error) {
      logToFile(`[Deluge:${this.name}] Error getting client status: ${error.message}`);
      return null;
    }
  }

  normalizeDownload(torrent) {
    // Convert client-specific data to the normalized schema
    return {
      id: torrent.id,
      title: torrent.name,
      type: 'torrent',
      client: 'deluge',
      instanceId: this.id,
      instanceName: this.name,
      status: this.mapStatus(torrent.state),
      progress: Math.round(torrent.progress * 100),
      size: torrent.total_size,
      downloaded: Math.round(torrent.total_size * torrent.progress),
      speed: torrent.download_payload_rate,
      eta: torrent.eta > 0 ? torrent.eta : null,
      category: torrent.label || undefined,
      tags: torrent.tracker ? [torrent.tracker] : [],
      savePath: torrent.save_path,
      addedOn: torrent.added_time ? new Date(torrent.added_time * 1000).toISOString() : undefined,
      raw: torrent // Include original data for advanced use cases
    };
  }

  mapStatus(state) {
    // Map client-specific states to normalized statuses
    const statusMap = {
      'Downloading': 'Downloading',
      'Seeding': 'Seeding',
      'Paused': 'Paused',
      'Checking': 'Checking',
      'Error': 'Error',
      'Queued': 'Queued'
    };
    
    return statusMap[state] || state;
  }
}

module.exports = DelugeClient;

Step 2: Add Configuration Support

Update server/utils/config.js to add support for your client's environment variables:

function getDelugeInstances() {
  return parseInstances(
    process.env.DELUGE_INSTANCES,
    process.env.DELUGE_URL,
    null, // no apiKey for Deluge
    process.env.DELUGE_USERNAME,
    process.env.DELUGE_PASSWORD
  );
}

// Add to module.exports
module.exports = {
  // ... existing exports
  getDelugeInstances,
  // ... other exports
};

Step 3: Register the Client

Update server/utils/downloadClients.js to include your client:

const DelugeClient = require('../clients/DelugeClient');

// Add to clientClasses mapping
const clientClasses = {
  sabnzbd: SABnzbdClient,
  qbittorrent: QBittorrentClient,
  transmission: TransmissionClient,
  deluge: DelugeClient // Add your client here
};

// Update instance configuration
const instanceConfigs = [
  ...sabnzbdInstances.map(inst => ({ ...inst, type: 'sabnzbd' })),
  ...qbittorrentInstances.map(inst => ({ ...inst, type: 'qbittorrent' })),
  ...transmissionInstances.map(inst => ({ ...inst, type: 'transmission' })),
  ...delugeInstances.map(inst => ({ ...inst, type: 'deluge' })) // Add this line
];

Step 4: Update Poller Integration

The poller automatically uses the registry, so no changes are needed there. However, if you want to maintain backward compatibility with existing cache keys, you may need to update the poller's transformation logic.

Step 5: Add Tests

Create comprehensive tests for your client:

// tests/unit/clients/DelugeClient.test.js
const DelugeClient = require('../../../server/clients/DelugeClient');

describe('DelugeClient', () => {
  let client;
  let mockConfig;

  beforeEach(() => {
    mockConfig = {
      id: 'test-deluge',
      name: 'Test Deluge',
      url: 'http://localhost:8112',
      username: 'admin',
      password: 'deluge'
    };
    
    client = new DelugeClient(mockConfig);
  });

  describe('Constructor', () => {
    it('should initialize with correct properties', () => {
      expect(client.getClientType()).toBe('deluge');
      expect(client.getInstanceId()).toBe('test-deluge');
      expect(client.name).toBe('Test Deluge');
    });
  });

  describe('Connection Test', () => {
    it('should test connection successfully', async () => {
      // Mock successful connection
      client.makeRequest = jest.fn().mockResolvedValue({ result: true });
      
      const result = await client.testConnection();
      
      expect(result).toBe(true);
      expect(client.makeRequest).toHaveBeenCalledWith('auth.check_session');
    });
  });

  describe('Download Normalization', () => {
    it('should normalize download data correctly', () => {
      const torrent = {
        id: 'abc123',
        name: 'Test Torrent',
        state: 'Downloading',
        progress: 0.75,
        total_size: 1000000000,
        download_payload_rate: 1048576,
        eta: 3600,
        label: 'movies',
        save_path: '/downloads/test'
      };

      const normalized = client.normalizeDownload(torrent);

      expect(normalized).toEqual({
        id: 'abc123',
        title: 'Test Torrent',
        type: 'torrent',
        client: 'deluge',
        instanceId: 'test-deluge',
        instanceName: 'Test Deluge',
        status: 'Downloading',
        progress: 75,
        size: 1000000000,
        downloaded: 750000000,
        speed: 1048576,
        eta: 3600,
        category: 'movies',
        tags: [],
        savePath: '/downloads/test',
        raw: torrent
      });
    });
  });

  // Add more tests for error handling, edge cases, etc.
});

Step 6: Configuration Examples

Add documentation for your client's configuration in .env.sample:

# Deluge Configuration
# Single instance (legacy format)
# DELUGE_URL=http://localhost:8112
# DELUGE_USERNAME=admin
# DELUGE_PASSWORD=deluge

# Multiple instances (JSON format)
DELUGE_INSTANCES='[
  {
    "name": "Main Deluge",
    "url": "http://localhost:8112",
    "username": "admin",
    "password": "deluge"
  },
  {
    "name": "Backup Deluge",
    "url": "http://localhost:8113",
    "username": "admin",
    "password": "deluge"
  }
]'

Step 7: Update Documentation

Update relevant documentation files:

1. ARCHITECTURE.md: Add your client to the download clients section
2. README.md: Add configuration instructions for your client
3. CHANGELOG.md: Document the new client support

Best Practices

Error Handling

• Always wrap API calls in try-catch blocks
• Return empty arrays for download fetch failures
• Log errors with appropriate context
• Implement retry logic where appropriate

Authentication

• Store credentials securely (don't log them)
• Handle session expiration gracefully
• Implement automatic re-authentication when possible

Performance

• Use efficient API calls (batch requests when available)
• Implement caching for expensive operations
• Consider pagination for large download lists
• Use connection pooling for HTTP clients

Normalization

• Always return the complete normalized schema
• Handle missing or null values gracefully
• Preserve original data in the raw field
• Map client-specific statuses to standard ones

Testing

• Test both success and failure scenarios
• Mock external API calls
• Test normalization edge cases
• Include integration tests

Example: Complete Implementation

For a complete example, refer to the existing client implementations:

• SABnzbdClient.js: Simple REST API client
• QBittorrentClient.js: Complex client with sync API and fallback
• TransmissionClient.js: JSON-RPC client with session management
• RTorrentClient.js: XML-RPC client with HTTP Basic Auth

rTorrent Specific Notes

rTorrent uses XML-RPC over HTTP with the following specifics:

• Endpoint: ${url}/RPC2 (most common)
• Authentication: HTTP Basic Auth (handled by reverse proxy or web server)
• Primary Method: d.multicall2 for efficient bulk torrent data retrieval
• Library: Uses the xmlrpc package (v1.3.2)
• Status Mapping: Combines d.state, d.is_active, and d.is_hash_checking to determine status
• ETA Calculation: Computed from download speed and remaining bytes when actively downloading

Troubleshooting

Common Issues

1. Authentication failures: Check credentials and URL format
2. API changes: Ensure your client matches the API version
3. Network issues: Implement proper timeout and retry logic
4. Data normalization: Verify all required fields are populated

Debugging

• Enable debug logging in your client
• Check the server logs for error messages
• Use the test connection endpoint to verify configuration
• Test API calls manually before implementing

Contributing

When contributing a new client:

1. Follow the existing code style and patterns
2. Include comprehensive tests
3. Update all relevant documentation
4. Test with multiple instances if supported
5. Consider edge cases and error scenarios

Support

If you need help implementing a new client:

1. Review existing client implementations
2. Check the architecture documentation
3. Look at the test examples
4. Ask questions in the project discussions

---

This guide covers the basics of adding a new download client. For more advanced scenarios, refer to the source code and existing implementations.