fix: add 15s timeout to HTTP thumbnail download to prevent long hangs (#405)

- Add 15-second timeout to downloadChannelThumbnailFromUrl() so the
  HTTP request fails fast instead of waiting for OS-level TCP timeout
  (~17 min) when direct connections to YouTube CDN appear to hang
- On timeout, destroy the request, clean up partial files, and let the
  existing yt-dlp fallback handle the download (which respects proxy config)
- Add tests for timeout, error handling, and partial file cleanup
- Document expected proxy fallback behavior in CONFIG.md and TROUBLESHOOTING.md

Author: dialmaster

docs/CONFIG.md

@@ -406,6 +406,7 @@ The old `discordWebhookUrl` and `notificationService` fields are automatically r
 - **Default**: `""` (empty)
 - **Description**: HTTP/HTTPS proxy for downloads
 - **Format**: `"http://proxy:port"` or `"socks5://proxy:port"`
+- **Note**: The proxy is used by yt-dlp for all YouTube requests (downloads, metadata, thumbnails). Some operations like thumbnail downloads and RSS feed checks first attempt a direct HTTP request with a 15-second timeout before falling back to yt-dlp. SOCKS5 proxy users may notice brief delays (~15 seconds) during these fallbacks when adding or refreshing channels, but the operations will complete successfully via yt-dlp.
 
 ### Use External Temporary Directory
 - **Config Key**: `useTmpForDownloads`

docs/TROUBLESHOOTING.md

@@ -439,6 +439,18 @@ YouTube is blocking your downloads.
 **NOTE**: In some cases YouTube may temporarily blacklist your IP address if too many requests were happening from your IP. You may just need to wait in order to download again. You can manually test downloading a video from YouTube to rule out Youtarr-specific issues by downloading yt-dlp and attempting to manually download a single video.
 
 
+## Slow Channel Operations with Proxy
+
+### Adding or Refreshing Channels Takes ~15 Seconds
+
+**Problem**: Adding a new channel or refreshing channel metadata takes around 15 seconds longer than expected.
+
+**Cause**: Youtarr first attempts direct HTTP requests for thumbnails and RSS feeds. When you're using a SOCKS5 or HTTP proxy, these direct requests cannot reach YouTube and must wait for a 15-second timeout before falling back to yt-dlp, which correctly uses your configured proxy.
+
+**Solution**: This is expected behavior and no action is needed. The operations will complete successfully after the brief timeout. If operations are taking significantly longer than 15-20 seconds, verify your proxy is correctly configured in **Configuration > Advanced Settings**.
+
+---
+
 ## Plex Integration Issues
 
 ### Videos Not Showing in Plex

server/modules/__tests__/channelModule.test.js

@@ -1,6 +1,7 @@
 /* eslint-env jest */
 
 const { Op } = require('sequelize');
+const realHttps = require('https');
 
 jest.mock('fs');
 jest.mock('child_process');
@@ -3004,4 +3005,95 @@ describe('ChannelModule', () => {
       expect(ChannelModule.resizeChannelThumbnail).toHaveBeenCalledWith(channelId);
     });
   });
+
+  describe('downloadChannelThumbnailFromUrl', () => {
+    let fsExtra;
+    let mockWriteStream;
+    let mockRequest;
+    let mockResponse;
+    let originalGet;
+    let originalCreateWriteStream;
+
+    beforeEach(() => {
+      originalGet = realHttps.get;
+      fsExtra = require('fs-extra');
+      originalCreateWriteStream = fsExtra.createWriteStream;
+
+      mockWriteStream = {
+        on: jest.fn(),
+        close: jest.fn(),
+      };
+      fsExtra.createWriteStream = jest.fn().mockReturnValue(mockWriteStream);
+
+      mockRequest = {
+        on: jest.fn().mockReturnThis(),
+        destroy: jest.fn(),
+      };
+
+      mockResponse = {
+        statusCode: 200,
+        pipe: jest.fn(),
+        headers: {},
+      };
+    });
+
+    afterEach(() => {
+      realHttps.get = originalGet;
+      fsExtra.createWriteStream = originalCreateWriteStream;
+    });
+
+    test('should pass timeout option to protocol.get', async () => {
+      realHttps.get = jest.fn((url, opts, cb) => {
+        cb(mockResponse);
+        const finishCb = mockWriteStream.on.mock.calls.find(c => c[0] === 'finish')[1];
+        finishCb();
+        return mockRequest;
+      });
+
+      await ChannelModule.downloadChannelThumbnailFromUrl('https://example.com/thumb.jpg', 'UC123');
+
+      expect(realHttps.get).toHaveBeenCalledWith(
+        'https://example.com/thumb.jpg',
+        expect.objectContaining({ timeout: 15000 }),
+        expect.any(Function)
+      );
+    });
+
+    test('should reject and clean up partial file on timeout', async () => {
+      fsExtra.existsSync = jest.fn().mockReturnValue(true);
+      fsExtra.unlinkSync = jest.fn();
+
+      realHttps.get = jest.fn(() => {
+        return mockRequest;
+      });
+
+      const promise = ChannelModule.downloadChannelThumbnailFromUrl('https://example.com/thumb.jpg', 'UC123');
+
+      const timeoutHandler = mockRequest.on.mock.calls.find(c => c[0] === 'timeout')[1];
+      timeoutHandler();
+
+      await expect(promise).rejects.toThrow('Thumbnail download timed out');
+      expect(mockRequest.destroy).toHaveBeenCalled();
+      expect(mockWriteStream.close).toHaveBeenCalled();
+      expect(fsExtra.unlinkSync).toHaveBeenCalled();
+    });
+
+    test('should reject on network error and clean up', async () => {
+      fsExtra.existsSync = jest.fn().mockReturnValue(true);
+      fsExtra.unlinkSync = jest.fn();
+
+      realHttps.get = jest.fn(() => {
+        return mockRequest;
+      });
+
+      const promise = ChannelModule.downloadChannelThumbnailFromUrl('https://example.com/thumb.jpg', 'UC123');
+
+      const errorHandler = mockRequest.on.mock.calls.find(c => c[0] === 'error')[1];
+      errorHandler(new Error('ECONNREFUSED'));
+
+      await expect(promise).rejects.toThrow('ECONNREFUSED');
+      expect(mockWriteStream.close).toHaveBeenCalled();
+      expect(fsExtra.unlinkSync).toHaveBeenCalled();
+    });
+  });
 });

server/modules/channelModule.js

@@ -641,7 +641,7 @@ class ChannelModule {
       const protocol = thumbnailUrl.startsWith('https') ? https : http;
       const file = fs.createWriteStream(imagePath);
 
-      protocol.get(thumbnailUrl, (response) => {
+      const req = protocol.get(thumbnailUrl, { timeout: 15000 }, (response) => {
         // Handle redirects
         if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
           file.close();
@@ -663,7 +663,18 @@ class ChannelModule {
           logger.debug({ channelId, imagePath }, 'Channel thumbnail downloaded via HTTP');
           resolve();
         });
-      }).on('error', (err) => {
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        file.close();
+        if (fs.existsSync(imagePath)) {
+          fs.unlinkSync(imagePath);
+        }
+        reject(new Error('Thumbnail download timed out'));
+      });
+
+      req.on('error', (err) => {
         file.close();
         if (fs.existsSync(imagePath)) {
           fs.unlinkSync(imagePath);