chore: bump version to 1.7.38 and update CHANGELOG and docs

CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.38] - 2026-05-29
+
+### Fixed
+
+- **SABnzbd History Legacy Slot Name Compatibility (Issue #74)** — Hardened SABnzbd active-download and history slot title matching in `DownloadMatcher.js` to support all slot name property variations (`filename`, `nzbname`, `name`, `nzb_name`). This ensures history matching succeeds against cached/legacy data schemas where the name is stored solely under the `filename` property, preventing completed downloads awaiting import from incorrectly displaying as `"Unknown"` client cards. Added unit tests for legacy `filename` slot matching compatibility.
+
+## [1.7.37] - 2026-05-29
+
+### Fixed
+
+- **SABnzbd History Matching Symmetry (Issue #74)** — Consolidated SABnzbd active-download matching algorithms in `DownloadMatcher.js` by introducing a unified, type-safe internal helper `findSabMatch(sabDownloadId, nzbName, context, caller)`. Refactored `matchSabSlots` and `matchSabHistory` to route entirely through `findSabMatch`. This resolves a bug where completed SABnzbd downloads awaiting manual import in Sonarr or Radarr queues were incorrectly flagged as "unknown" client/"Orphaned (unconfigured client)". Added detailed unit tests to safeguard this behavior.
+
+## [1.7.36] - 2026-05-29
+
+### Fixed
+
+- **Test Timeout & Cross-Suite Background Event Pollution (V8 Coverage)** — Configured `fileParallelism: false` and `testTimeout: 15000` in `vitest.config.js`. This guarantees that slow code compilation/instrumentation under V8 coverage doesn't cause transient 5-second timeouts, and prevents asynchronous fire-and-forget background event loops (like Ombi webhook retry loops) in one test suite from running concurrently and overwriting cache singletons in other test suites.
+
+## [1.7.35] - 2026-05-29
+
+### Added
+
+- **Orphaned *arr Queue Item Support (Issue #73)** — Added support for active Sonarr/Radarr queue items from unconfigured download clients ("orphaned" downloads). Added a new synthetic client (`'orphaned'`) with a custom viewBox vector graphics asset at `/images/clients/orphaned.svg` to represent unconfigured clients, and updated filter dropdown lists and active downloads grids to cleanly display them with a dimmed logo, custom dashed border styling, and informative hover tooltips. Resolves Gitea Issue [#73](https://git.i3omb.com/Gandalf/sofarr/issues/73).
+
+### Enhanced
+
+- **Download Matching & JSDoc Hygiene (Issue #73)** — Refactored core active-download matching algorithms into unified, deduplicated helper functions (`normalizeTitle`, `titleMatches`, `buildArrDownload`) in `DownloadMatcher.js`, preventing hundreds of lines of duplicate code. Handled case-insensitive and type-safe `downloadId` lookup in `matchSabHistory` across both history and active queue records. Added safe progress arithmetic bounds checking to prevent division-by-zero or `NaN`.
+
+### Fixed
+
+- **Security Metadata Isolation in buildArrDownload (Issue #73)** — Restricted access control for sensitive properties like `arrInstanceKey` (the raw instance API key) to ensure they are strictly stripped out of download objects for non-administrator users, preserving system security boundaries.
+
 ## [1.7.34] - 2026-05-28
 
 ### Fixed

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "sofarr",
-  "version": "1.7.34",
+  "version": "1.7.38",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "sofarr",
-      "version": "1.7.34",
+      "version": "1.7.38",
       "license": "MIT",
       "dependencies": {
         "axios": "^1.6.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sofarr",
-  "version": "1.7.34",
+  "version": "1.7.38",
   "description": "A personal media download dashboard that shows your downloads 'so far' while you relax on the sofa waiting for your *arr services to finish",
   "main": "server/index.js",
   "scripts": {

server/app.js

@@ -133,7 +133,7 @@ function createApp({ skipRateLimits = false } = {}) {
    *                 version:
    *                   type: string
    *                   description: sofarr version
-   *                   example: "1.7.34"
+   *                   example: "1.7.38"
    *     x-code-samples:
    *       - lang: curl
    *         label: cURL

server/openapi.yaml

@@ -22,7 +22,7 @@ info:
 
     ## SSE Streaming
     Real-time updates are available via Server-Sent Events at GET /api/dashboard/stream.
-  version: 1.7.34
+  version: 1.7.38
   contact:
     name: sofarr
   license:

server/services/DownloadMatcher.js

@@ -35,7 +35,7 @@ function normalizeTitle(str) {
  * and normalized (dots/dashes/underscores to spaces) forms bidirectionally.
  * Only logs on title fallback matches (when isFallback=true) to keep logs clean.
  */
-function titleMatches(clientName, arrTitle, { isFallback = true } = {}) {
+function titleMatches(clientName, arrTitle, { isFallback = true, caller = 'DownloadMatcher' } = {}) {
   if (!clientName || !arrTitle) return false;
   const a = clientName.toLowerCase();
   const b = arrTitle.toLowerCase();
@@ -48,14 +48,76 @@ function titleMatches(clientName, arrTitle, { isFallback = true } = {}) {
                   a.includes(bNorm) || bNorm.includes(a);
 
   if (matched && isFallback) {
-    logger.debug(`[DownloadMatcher] Title fallback match after normalization: "${clientName}" <-> "${arrTitle}"`);
+    logger.debug(`[DownloadMatcher] Title fallback match in ${caller} after normalization: "${clientName}" <-> "${arrTitle}"`);
   }
   return matched;
 }
 
+/**
+ * Internal helper: Finds the best matching Sonarr or Radarr record for a SABnzbd slot.
+ * Performs robust case-insensitive downloadId matching (queue → history),
+ * then bidirectional title fallback (queue → history).
+ * This eliminates all duplication and asymmetry between matchSabSlots and matchSabHistory.
+ *
+ * @param {string|null} sabDownloadId
+ * @param {string} nzbName
+ * @param {Object} context
+ * @param {string} caller - e.g. 'matchSabHistory' or 'matchSabSlots'
+ * @returns {{ sonarrMatch: Object|null, radarrMatch: Object|null }}
+ */
+function findSabMatch(sabDownloadId, nzbName, context, caller = 'DownloadMatcher') {
+  const {
+    sonarrQueueRecords = [],
+    sonarrHistoryRecords = [],
+    radarrQueueRecords = [],
+    radarrHistoryRecords = []
+  } = context;
+
+  const findBest = (queueRecords, historyRecords) => {
+    // 1. Robust ID match (queue first)
+    let match = sabDownloadId
+      ? queueRecords.find(r => {
+          const dl = r && r.downloadId;
+          return dl && String(dl).toLowerCase() === String(sabDownloadId).toLowerCase();
+        })
+      : null;
+
+    if (!match && sabDownloadId) {
+      match = historyRecords.find(r => {
+        const dl = r && r.downloadId;
+        return dl && String(dl).toLowerCase() === String(sabDownloadId).toLowerCase();
+      });
+    }
+
+    // 2. Title fallback (queue first, then history)
+    if (!match && nzbName) {
+      match = queueRecords.find(r => {
+        const rTitle = r && (r.title || r.sourceTitle);
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller });
+      });
+    }
+    if (!match && nzbName) {
+      match = historyRecords.find(r => {
+        const rTitle = r && (r.title || r.sourceTitle);
+        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true, caller });
+      });
+    }
+
+    return match || null;
+  };
+
+  return {
+    sonarrMatch: findBest(sonarrQueueRecords, sonarrHistoryRecords),
+    radarrMatch: findBest(radarrQueueRecords, radarrHistoryRecords)
+  };
+}
+
 /**
  * All callers (matchers + orphan path) must supply client, instanceId, and instanceName via options.
  * Defaults exist only as a last-resort safety net.
+ *
+ * @example
+ * buildArrDownload(sonarrMatch, context, { client: 'sabnzbd', instanceId: 'sabnzbd-default', instanceName: 'SABnzbd' })
  */
 function buildArrDownload(record, context, options = {}) {
   const {
@@ -119,7 +181,6 @@ function buildArrDownload(record, context, options = {}) {
   dlObj.arrQueueId = record.id;
   dlObj.arrType = isSeries ? 'sonarr' : 'radarr';
   dlObj.arrInstanceUrl = record._instanceUrl || null;
-  dlObj.arrInstanceKey = record._instanceKey || null;
   dlObj.arrContentId = record.episodeId || record.movieId || null;
   dlObj.arrContentIds = record.episodeIds || null;
   dlObj.arrSeriesId = record.seriesId || null;
@@ -131,6 +192,7 @@ function buildArrDownload(record, context, options = {}) {
   if (isAdmin) {
     dlObj.downloadPath = options.downloadPath || null;
     dlObj.targetPath = media.path || null;
+    dlObj.arrInstanceKey = record._instanceKey || null;
     dlObj.arrLink = isSeries 
       ? DownloadAssembler.getSonarrLink(media)
       : DownloadAssembler.getRadarrLink(media);
@@ -228,52 +290,14 @@ async function matchSabSlots(slots, context) {
 
   const matched = [];
   for (const slot of slots) {
-    const nzbName = slot.filename || slot.nzbname;
+    const nzbName = slot.filename || slot.nzbname || slot.name || slot.nzb_name;
     if (!nzbName) continue;
 
     const slotState = getSlotStatusAndSpeed(slot, queueStatus, queueSpeed, queueKbpersec);
     const nzbNameLower = nzbName.toLowerCase();
 
-    // Try to match by downloadId first (most reliable)
     const sabDownloadId = slot.nzo_id || slot.id;
-    let sonarrMatch = sabDownloadId ? sonarrQueueRecords.find(r => r.downloadId === sabDownloadId) : null;
+    const { sonarrMatch, radarrMatch } = findSabMatch(sabDownloadId, nzbName, context, 'matchSabSlots');
-    let radarrMatch = sabDownloadId ? radarrQueueRecords.find(r => r.downloadId === sabDownloadId) : null;
-
-    // Also check HISTORY by downloadId
-    if (!sonarrMatch && sabDownloadId) {
-      sonarrMatch = sonarrHistoryRecords.find(r => r.downloadId === sabDownloadId);
-    }
-    if (!radarrMatch && sabDownloadId) {
-      radarrMatch = radarrHistoryRecords.find(r => r.downloadId === sabDownloadId);
-    }
-
-    // Fallback: Check by title matching
-    if (!sonarrMatch) {
-      sonarrMatch = sonarrQueueRecords.find(r => {
-        const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
-      });
-    }
-    if (!radarrMatch) {
-      radarrMatch = radarrQueueRecords.find(r => {
-        const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
-      });
-    }
-
-    // Also check HISTORY (completed downloads) if no queue match
-    if (!sonarrMatch) {
-      sonarrMatch = sonarrHistoryRecords.find(r => {
-        const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
-      });
-    }
-    if (!radarrMatch) {
-      radarrMatch = radarrHistoryRecords.find(r => {
-        const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
-      });
-    }
 
     // Progress calculation
     const mbValue = slot.mb !== undefined && slot.mb !== null ? parseFloat(slot.mb) : 0;
@@ -319,63 +343,20 @@ async function matchSabSlots(slots, context) {
   return matched;
 }
 
-/**
- * Matches SABnzbd history slots to Sonarr/Radarr activity using title matching.
- * @param {Array} slots - SABnzbd history slots
- * @param {Object} context - Matching context with records, maps, and user info
- * @returns {Array} Array of matched download objects
- */
 async function matchSabHistory(slots, context) {
-  const {
-    sonarrQueueRecords,
-    sonarrHistoryRecords,
-    radarrQueueRecords,
-    radarrHistoryRecords
-  } = context;
-
   const matched = [];
+
   for (const slot of slots) {
-    const nzbName = slot.name || slot.nzb_name || slot.nzbname;
+    const nzbName = slot.filename || slot.nzbname || slot.name || slot.nzb_name;
     if (!nzbName) continue;
-    const nzbNameLower = nzbName.toLowerCase();
 
-    // Try to match by downloadId (nzo_id or slot ID) first (most reliable)
     const sabDownloadId = slot.nzo_id || slot.id;
-    const matchesSabId = (r) => {
+    const { sonarrMatch, radarrMatch } = findSabMatch(sabDownloadId, nzbName, context, 'matchSabHistory');
-      const dl = r && r.downloadId;
-      if (!dl || !sabDownloadId) return false;
-      return String(dl).toLowerCase() === String(sabDownloadId).toLowerCase();
-    };
-
-    let sonarrMatch = sabDownloadId ? sonarrHistoryRecords.find(matchesSabId) : null;
-    let radarrMatch = sabDownloadId ? radarrHistoryRecords.find(matchesSabId) : null;
-
-    // Dual-lookup: also try against active queue records (history slot may still be in *arr queue)
-    if (!sonarrMatch && sabDownloadId) {
-      sonarrMatch = sonarrQueueRecords.find(matchesSabId);
-    }
-    if (!radarrMatch && sabDownloadId) {
-      radarrMatch = radarrQueueRecords.find(matchesSabId);
-    }
-
-    // Fallback: Check by title matching
-    if (!sonarrMatch) {
-      sonarrMatch = sonarrHistoryRecords.find(r => {
-        const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
-      });
-    }
-    if (!radarrMatch) {
-      radarrMatch = radarrHistoryRecords.find(r => {
-        const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(nzbName, rTitle, { isFallback: true });
-      });
-    }
 
     const commonOptions = {
       title: nzbName,
       status: slot.status || 'Completed',
-      progress: 100, // History items are completed
+      progress: 100,
       mb: slot.mb,
       size: Math.round((slot.mb || 0) * 1024 * 1024),
       completedAt: slot.completed_time,
@@ -389,7 +370,7 @@ async function matchSabHistory(slots, context) {
       const dlObj = buildArrDownload(sonarrMatch, context, {
         ...commonOptions,
         arrType: 'sonarr',
-        episodes: DownloadAssembler.gatherEpisodes(nzbNameLower, sonarrHistoryRecords)
+        episodes: DownloadAssembler.gatherEpisodes(nzbName.toLowerCase(), context.sonarrHistoryRecords || [])
       });
       if (dlObj) matched.push(dlObj);
     }
@@ -402,6 +383,7 @@ async function matchSabHistory(slots, context) {
       if (dlObj) matched.push(dlObj);
     }
   }
+
   return matched;
 }
 
@@ -441,13 +423,13 @@ async function matchTorrents(torrents, context) {
     if (!sonarrMatch) {
       sonarrMatch = sonarrQueueRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }
     if (!radarrMatch) {
       radarrMatch = radarrQueueRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }
 
@@ -458,13 +440,13 @@ async function matchTorrents(torrents, context) {
     if (!sonarrHistoryMatch) {
       sonarrHistoryMatch = sonarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }
     if (!radarrHistoryMatch) {
       radarrHistoryMatch = radarrHistoryRecords.find(r => {
         const rTitle = r.title || r.sourceTitle;
-        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true });
+        return rTitle && titleMatches(torrentName, rTitle, { isFallback: true, caller: 'matchTorrents' });
       });
     }
 

tests/unit/services/DownloadMatcher.test.js

@@ -226,6 +226,61 @@ describe('DownloadMatcher', () => {
       expect(result).toHaveLength(1);
       expect(result[0].arrQueueId).toBe(101);
     });
+
+    it('falls back to title matching against Sonarr queue records when downloadId is absent/unmatched', async () => {
+      const testContext = {
+        ...context,
+        sonarrHistoryRecords: [],
+        sonarrQueueRecords: [
+          { id: 201, seriesId: 1, title: 'My.Cool.Show.S01E01.720p-Group' }
+        ],
+        seriesMap: new Map([[1, { id: 1, title: 'My Cool Show', tags: [1] }]])
+      };
+
+      const slots = [{ id: null, name: 'My_Cool_Show_S01E01_720p-Group.nzb', status: 'Completed', mb: 1000 }];
+      const result = await DownloadMatcher.matchSabHistory(slots, testContext);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].arrQueueId).toBe(201);
+      expect(result[0].arrType).toBe('sonarr');
+    });
+
+    it('falls back to title matching against Radarr queue records when downloadId is absent/unmatched', async () => {
+      const testContext = {
+        ...context,
+        radarrHistoryRecords: [],
+        radarrQueueRecords: [
+          { id: 301, movieId: 2, title: 'Awesome Movie 2026 1080p' }
+        ],
+        moviesMap: new Map([[2, { id: 2, title: 'Awesome Movie', tags: [1] }]]),
+        radarrTagMap: new Map([[1, 'alice']])
+      };
+
+      const slots = [{ id: null, name: 'Awesome.Movie.2026.1080p.nzb', status: 'Completed', mb: 1000 }];
+      const result = await DownloadMatcher.matchSabHistory(slots, testContext);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].arrQueueId).toBe(301);
+      expect(result[0].arrType).toBe('radarr');
+    });
+
+    it('matches when history slots only have the filename field (cached legacy format)', async () => {
+      const testContext = {
+        ...context,
+        sonarrHistoryRecords: [],
+        sonarrQueueRecords: [
+          { id: 201, seriesId: 1, title: 'My.Cool.Show.S01E01.720p-Group' }
+        ],
+        seriesMap: new Map([[1, { id: 1, title: 'My Cool Show', tags: [1] }]])
+      };
+
+      const slots = [{ id: null, filename: 'My_Cool_Show_S01E01_720p-Group.nzb', status: 'Completed', mb: 1000 }];
+      const result = await DownloadMatcher.matchSabHistory(slots, testContext);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].arrQueueId).toBe(201);
+      expect(result[0].arrType).toBe('sonarr');
+    });
   });
 
   describe('titleMatches helper', () => {

vitest.config.js

@@ -5,6 +5,10 @@ export default defineConfig({
   test: {
     // Global test helpers (describe, it, expect, vi) without per-file imports
     globals: true,
+    // Increase test timeout to avoid transient timeouts under coverage/heavy loads
+    testTimeout: 15000,
+    // Run test files sequentially to avoid cross-test background event pollution
+    fileParallelism: false,
     // Run each test file in an isolated module registry so module-level state
     // (tokenStore cache, config singletons) doesn't leak between files
     isolate: true,