Add release blocklist feature

Introduce a per-request release blocklist to auto-block permanently failing releases and provide admin management. Changes include:

- Database: add BlockedRelease model (blocked_releases) to Prisma schema with unique (requestId, releaseKey) and indexes; documented in backend database docs.
- Service & utils: new blocklist.service, release-key and filter helpers for normalization and matching; processors updated to emit auto-blocks (monitor-download, organize-files, search processors, RSS).
- HTTP API: add admin endpoints GET/DELETE /api/admin/blocklist, DELETE /api/admin/blocklist/[id], and GET /api/admin/blocklist/by-request/[requestId].
- Admin UI: new /admin/blocklist page and numerous React components (toolbar, filters, table, rows, pagination, skeleton, chips, date picker) with URL-driven state hook and per-row unblock UX.
- Tests: add unit/integration tests for service, routes, utils, and updated processor tests.

The blocklist is idempotent (upsert), filters search results before ranking (interactive search shows badges only), and admin-only APIs require auth. This commit wires docs, API, DB, frontend and tests for the new feature.

tests/processors/monitor-download.processor.test.ts

@@ -156,7 +156,7 @@ describe('processMonitorDownload', () => {
     );
   });
 
-  it('marks request failed when download fails', async () => {
+  it('marks request failed when download fails and auto-blocks the release', async () => {
     const qbtClientMock = {
       clientType: 'qbittorrent',
       protocol: 'torrent',
@@ -180,6 +180,20 @@ describe('processMonitorDownload', () => {
       audiobook: { title: 'Book', author: 'Author' },
       user: { plexUsername: 'user' },
     });
+    prismaMock.downloadHistory.findUnique.mockResolvedValue({
+      id: 'dh-3',
+      torrentName: 'Book - Author [M4B]',
+      torrentHash: 'hash-3',
+      nzbId: null,
+      indexerName: 'TestIndexer',
+      indexerId: 4,
+    });
+    prismaMock.blockedRelease.upsert.mockResolvedValue({
+      id: 'block-3',
+      releaseName: 'Book - Author [M4B]',
+      releaseKey: 'book - author [m4b]',
+      createdAt: new Date(),
+    });
 
     const { processMonitorDownload } = await import('@/lib/processors/monitor-download.processor');
     const result = await processMonitorDownload({
@@ -196,6 +210,60 @@ describe('processMonitorDownload', () => {
         data: expect.objectContaining({ status: 'failed' }),
       })
     );
+    expect(prismaMock.blockedRelease.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { requestId_releaseKey: { requestId: 'req-3', releaseKey: 'book - author [m4b]' } },
+        create: expect.objectContaining({
+          requestId: 'req-3',
+          releaseName: 'Book - Author [M4B]',
+          releaseHash: 'hash-3',
+          source: 'download_fail',
+          downloadHistoryId: 'dh-3',
+        }),
+      })
+    );
+  });
+
+  it('does not auto-block when permanent failure is from connection-exhaustion path', async () => {
+    // Simulate the connection-failure-exhausted fallthrough: getDownload rejects
+    // with a transient connection error AND prevConnectionFailureCount is already
+    // at the cap, so the processor enters PATH 3 (permanent error) without the
+    // client ever reporting `failed`. That path must NOT auto-block.
+    const econn = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:8080'), {
+      code: 'ECONNREFUSED',
+    });
+    const qbtClientMock = {
+      clientType: 'qbittorrent',
+      protocol: 'torrent',
+      getDownload: vi.fn().mockRejectedValue(econn),
+    };
+    downloadClientManagerMock.getClientServiceForProtocol.mockResolvedValue(qbtClientMock);
+    prismaMock.request.update.mockResolvedValue({});
+    prismaMock.request.findUnique.mockResolvedValue({
+      id: 'req-conn',
+      audiobook: { title: 'Book', author: 'Author' },
+      user: { plexUsername: 'user' },
+    });
+
+    const { processMonitorDownload } = await import('@/lib/processors/monitor-download.processor');
+    await expect(processMonitorDownload({
+      requestId: 'req-conn',
+      downloadHistoryId: 'dh-conn',
+      downloadClientId: 'hash-conn',
+      downloadClient: 'qbittorrent',
+      jobId: 'job-conn',
+      // Already at the cap — next call enters PATH 3 (permanent), not the
+      // self-rescheduling retry branch.
+      connectionFailureCount: 30,
+    })).rejects.toThrow();
+
+    expect(prismaMock.request.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ status: 'failed' }),
+      })
+    );
+    // CRITICAL: connection exhaustion is transient infra, not a release problem.
+    expect(prismaMock.blockedRelease.upsert).not.toHaveBeenCalled();
   });
 
   it('handles SABnzbd completion and queues organize job', async () => {

tests/processors/monitor-rss-feeds.processor.test.ts

@@ -35,6 +35,8 @@ function futureDate(days = 30): Date {
 describe('processMonitorRssFeeds', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    // Default to empty blocklist so the filter is a no-op unless a test overrides.
+    prismaMock.blockedRelease.findMany.mockResolvedValue([]);
   });
 
   it('matches RSS items and queues search jobs', async () => {
@@ -108,6 +110,42 @@ describe('processMonitorRssFeeds', () => {
     expect(prismaMock.request.update).not.toHaveBeenCalled();
   });
 
+  it('does not queue a search when the matching RSS release is on the request blocklist', async () => {
+    configMock.get.mockImplementation(async (key: string) => {
+      if (key === 'prowlarr_indexers') {
+        return JSON.stringify([{ id: 1, name: 'Indexer', rssEnabled: true }]);
+      }
+      if (key === 'indexer.skip_unreleased') return null;
+      return null;
+    });
+
+    prowlarrMock.getAllRssFeeds.mockResolvedValue([
+      { title: 'Great Book - Author Name' },
+    ]);
+
+    prismaMock.request.findMany.mockResolvedValue([
+      {
+        id: 'req-blocked',
+        type: 'audiobook',
+        status: 'awaiting_search',
+        releaseDate: null,
+        audiobook: { id: 'a1', title: 'Great Book', author: 'Author Name', audibleAsin: 'ASIN1' },
+      },
+    ]);
+
+    // The RSS torrent's normalized name is on the request's blocklist.
+    prismaMock.blockedRelease.findMany.mockResolvedValue([
+      { id: 'b1', releaseKey: 'great book - author name', releaseHash: null },
+    ]);
+
+    const { processMonitorRssFeeds } = await import('@/lib/processors/monitor-rss-feeds.processor');
+    const result = await processMonitorRssFeeds({ jobId: 'job-rss-blocked' });
+
+    expect(result.success).toBe(true);
+    expect(jobQueueMock.addSearchJob).not.toHaveBeenCalled();
+    expect(jobQueueMock.addSearchEbookJob).not.toHaveBeenCalled();
+  });
+
   it('runs RSS search when matched book is unreleased but setting is OFF', async () => {
     configMock.get.mockImplementation(async (key: string) => {
       if (key === 'prowlarr_indexers') {

tests/processors/organize-files.processor.test.ts

@@ -256,9 +256,11 @@ describe('processOrganizeFiles', () => {
         data: expect.objectContaining({ status: 'awaiting_import' }),
       })
     );
+    // Auto-block must NOT fire on a retry — only on the terminal warn transition.
+    expect(prismaMock.blockedRelease.upsert).not.toHaveBeenCalled();
   });
 
-  it('marks request as warn when max retries exceeded and notifies user', async () => {
+  it('marks request as warn when max retries exceeded, auto-blocks the release, and notifies user', async () => {
     prismaMock.request.update.mockResolvedValue({});
     prismaMock.audiobook.findUnique.mockResolvedValue({
       id: 'a6',
@@ -285,6 +287,20 @@ describe('processOrganizeFiles', () => {
       audiobook: { title: 'Book', author: 'Author' },
       user: { plexUsername: 'user' },
     });
+    prismaMock.downloadHistory.findFirst.mockResolvedValue({
+      id: 'dh-6',
+      torrentName: 'Book by Author [M4B]',
+      torrentHash: 'hash-6',
+      nzbId: null,
+      indexerName: 'TestIndexer',
+      indexerId: 7,
+    });
+    prismaMock.blockedRelease.upsert.mockResolvedValue({
+      id: 'block-6',
+      releaseName: 'Book by Author [M4B]',
+      releaseKey: 'book by author [m4b]',
+      createdAt: new Date(),
+    });
     configMock.get.mockResolvedValue(null);
 
     const { processOrganizeFiles } = await import('@/lib/processors/organize-files.processor');
@@ -309,6 +325,23 @@ describe('processOrganizeFiles', () => {
       'user',
       expect.stringContaining('Max retries')
     );
+    // Terminal warn writes a single blocklist row keyed on the selected download.
+    expect(prismaMock.blockedRelease.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { requestId_releaseKey: { requestId: 'req-6', releaseKey: 'book by author [m4b]' } },
+        create: expect.objectContaining({
+          requestId: 'req-6',
+          releaseName: 'Book by Author [M4B]',
+          releaseKey: 'book by author [m4b]',
+          releaseHash: 'hash-6',
+          indexerName: 'TestIndexer',
+          indexerId: 7,
+          source: 'organize_fail',
+          reason: 'No audiobook files found',
+          downloadHistoryId: 'dh-6',
+        }),
+      })
+    );
   });
 
   it('marks request failed for non-retryable errors and notifies user', async () => {
@@ -357,6 +390,8 @@ describe('processOrganizeFiles', () => {
       'user',
       expect.stringContaining('File organization failed')
     );
+    // Non-retryable failures do not auto-block — only terminal warn does.
+    expect(prismaMock.blockedRelease.upsert).not.toHaveBeenCalled();
   });
 
   it('queues retry when organizer returns EPERM copy failure', async () => {

tests/processors/search-indexers.processor.test.ts

@@ -36,6 +36,8 @@ describe('processSearchIndexers', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     configMock.getAudibleRegion.mockResolvedValue('us');
+    // Default to empty blocklist so the filter is a no-op unless a test overrides.
+    prismaMock.blockedRelease.findMany.mockResolvedValue([]);
   });
 
   it('marks request awaiting_search when no results found', async () => {
@@ -124,6 +126,178 @@ describe('processSearchIndexers', () => {
       })
     );
   });
+
+  it('filters out blocklisted releases by name (case-insensitive) before ranking', async () => {
+    configMock.get.mockImplementation(async (key: string) => {
+      if (key === 'prowlarr_indexers') {
+        return JSON.stringify([{ id: 1, name: 'Indexer', protocol: 'torrent', priority: 10, categories: [3030] }]);
+      }
+      if (key === 'indexer_flag_config') return JSON.stringify([]);
+      return null;
+    });
+
+    prowlarrMock.searchWithVariations.mockResolvedValue([
+      {
+        indexer: 'Indexer',
+        indexerId: 1,
+        title: 'BAD Release - Author',
+        size: 50 * 1024 * 1024,
+        seeders: 10,
+        publishDate: new Date(),
+        downloadUrl: 'magnet:?xt=urn:btih:bad',
+        guid: 'guid-bad',
+        format: 'M4B',
+      },
+      {
+        indexer: 'Indexer',
+        indexerId: 1,
+        title: 'Good Release - Author',
+        size: 50 * 1024 * 1024,
+        seeders: 20,
+        publishDate: new Date(),
+        downloadUrl: 'magnet:?xt=urn:btih:good',
+        guid: 'guid-good',
+        format: 'M4B',
+      },
+    ]);
+
+    // Blocklist contains the bad release with lowercased key — must match case-insensitively.
+    prismaMock.blockedRelease.findMany.mockResolvedValue([
+      { id: 'b1', releaseKey: 'bad release - author', releaseHash: null },
+    ]);
+    prismaMock.request.update.mockResolvedValue({});
+
+    const { processSearchIndexers } = await import('@/lib/processors/search-indexers.processor');
+    const result = await processSearchIndexers({
+      requestId: 'req-filter-name',
+      audiobook: { id: 'a-filter', title: 'Good Release', author: 'Author' },
+      jobId: 'job-filter-name',
+    });
+
+    expect(result.success).toBe(true);
+    expect(jobQueueMock.addDownloadJob).toHaveBeenCalledTimes(1);
+    expect(jobQueueMock.addDownloadJob).toHaveBeenCalledWith(
+      'req-filter-name',
+      expect.objectContaining({ id: 'a-filter' }),
+      expect.objectContaining({ title: 'Good Release - Author' })
+    );
+  });
+
+  it('filters out blocklisted releases by infoHash even when title differs', async () => {
+    configMock.get.mockImplementation(async (key: string) => {
+      if (key === 'prowlarr_indexers') {
+        return JSON.stringify([{ id: 1, name: 'Indexer', protocol: 'torrent', priority: 10, categories: [3030] }]);
+      }
+      if (key === 'indexer_flag_config') return JSON.stringify([]);
+      return null;
+    });
+
+    prowlarrMock.searchWithVariations.mockResolvedValue([
+      {
+        indexer: 'Indexer',
+        indexerId: 1,
+        title: 'Some Other Title - Author',
+        size: 50 * 1024 * 1024,
+        seeders: 10,
+        publishDate: new Date(),
+        downloadUrl: 'magnet:?xt=urn:btih:abc',
+        guid: 'guid-hash-bad',
+        infoHash: 'abc123',
+        format: 'M4B',
+      },
+      {
+        indexer: 'Indexer',
+        indexerId: 1,
+        title: 'Good Release - Author',
+        size: 50 * 1024 * 1024,
+        seeders: 20,
+        publishDate: new Date(),
+        downloadUrl: 'magnet:?xt=urn:btih:def',
+        guid: 'guid-hash-good',
+        infoHash: 'def456',
+        format: 'M4B',
+      },
+    ]);
+
+    prismaMock.blockedRelease.findMany.mockResolvedValue([
+      { id: 'b2', releaseKey: 'unrelated key', releaseHash: 'abc123' },
+    ]);
+    prismaMock.request.update.mockResolvedValue({});
+
+    const { processSearchIndexers } = await import('@/lib/processors/search-indexers.processor');
+    const result = await processSearchIndexers({
+      requestId: 'req-filter-hash',
+      audiobook: { id: 'a-filter-hash', title: 'Good Release', author: 'Author' },
+      jobId: 'job-filter-hash',
+    });
+
+    expect(result.success).toBe(true);
+    expect(jobQueueMock.addDownloadJob).toHaveBeenCalledWith(
+      'req-filter-hash',
+      expect.anything(),
+      expect.objectContaining({ title: 'Good Release - Author' })
+    );
+  });
+
+  it('uses blocklist-exhaustion message when every candidate is blocked', async () => {
+    configMock.get.mockImplementation(async (key: string) => {
+      if (key === 'prowlarr_indexers') {
+        return JSON.stringify([{ id: 1, name: 'Indexer', protocol: 'torrent', priority: 10, categories: [3030] }]);
+      }
+      if (key === 'indexer_flag_config') return JSON.stringify([]);
+      return null;
+    });
+
+    prowlarrMock.searchWithVariations.mockResolvedValue([
+      {
+        indexer: 'Indexer',
+        indexerId: 1,
+        title: 'Bad Release One',
+        size: 50 * 1024 * 1024,
+        seeders: 10,
+        publishDate: new Date(),
+        downloadUrl: 'magnet:?xt=urn:btih:1',
+        guid: 'g1',
+        format: 'M4B',
+      },
+      {
+        indexer: 'Indexer',
+        indexerId: 1,
+        title: 'Bad Release Two',
+        size: 50 * 1024 * 1024,
+        seeders: 5,
+        publishDate: new Date(),
+        downloadUrl: 'magnet:?xt=urn:btih:2',
+        guid: 'g2',
+        format: 'M4B',
+      },
+    ]);
+
+    prismaMock.blockedRelease.findMany.mockResolvedValue([
+      { id: 'b1', releaseKey: 'bad release one', releaseHash: null },
+      { id: 'b2', releaseKey: 'bad release two', releaseHash: null },
+    ]);
+    prismaMock.request.update.mockResolvedValue({});
+
+    const { processSearchIndexers } = await import('@/lib/processors/search-indexers.processor');
+    const result = await processSearchIndexers({
+      requestId: 'req-exhausted',
+      audiobook: { id: 'a-exhausted', title: 'Bad Release', author: 'Author' },
+      jobId: 'job-exhausted',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toMatch(/No usable releases — 2 candidates tried, all blocked/);
+    expect(prismaMock.request.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          status: 'awaiting_search',
+          errorMessage: 'No usable releases — 2 candidates tried, all blocked',
+        }),
+      })
+    );
+    expect(jobQueueMock.addDownloadJob).not.toHaveBeenCalled();
+  });
 });