Merge pull request #364 from alexis-morain/feat/metadata-missing-client-agnostic

[NEEDS CODE REVIEWER] feat(remove_metadata_missing): detect stuck metadata for non-qBittorrent clients (opt-in)

Author: ManiMatter

README.md

@@ -561,11 +561,13 @@ This is the interesting section. It defines which job you want decluttarr to run
 -   Steers whether downloads stuck obtaining metadata are removed from the queue
 -   Blocklisted: Yes
 -   Type: Boolean or Dict
--   Permissible Values: True, False or max_strikes (int)
+-   Permissible Values: True, False or max_strikes (int), detect_via_missing_size (bool)
 -   Is Mandatory: No (Defaults to False)
 -   Note:
       - With max_strikes you can define how many times this torrent can be caught before being removed
       - Instead of configuring it here, you may also configure it as a default across all jobs or use the built-in defaults (see further above under "max_strikes")
+      - By default, this check relies on the "qBittorrent is downloading metadata" message that qBittorrent surfaces in the \*arr queue. Other download clients (e.g. Transmission, Deluge) do not surface such a message, so a torrent stuck fetching metadata stays undetected (see [#57](https://github.com/ManiMatter/decluttarr/issues/57)).
+      - Set `detect_via_missing_size: true` to additionally flag, regardless of download client, queued items whose size is not yet known (size 0), which is the client-agnostic signature of "no metadata yet". This is debounced by max_strikes. Defaults to False to keep existing (qBittorrent) behavior unchanged.
 
 #### REMOVE_MISSING_FILES
 

src/jobs/remove_metadata_missing.py

@@ -6,5 +6,20 @@ class RemoveMetadataMissing(RemovalJob):
     blocklist = True
 
     async def _find_affected_items(self):
+        # qBittorrent surfaces a dedicated *arr error message while fetching metadata.
         conditions = [("queued", "qBittorrent is downloading metadata")]
-        return self.queue_manager.filter_queue(self.queue, conditions)
+        affected_items = self.queue_manager.filter_queue(self.queue, conditions)
+
+        # Other clients (e.g. Transmission, Deluge) do not surface such a message, so a
+        # torrent stuck fetching metadata is invisible to the message-based check above
+        # (see #57). Opt-in fallback: also flag queued items whose size is not yet known
+        # (size == 0), which is the client-agnostic signature of "no metadata yet".
+        # Debounced by max_strikes like the rest of this job.
+        if getattr(self.job, "detect_via_missing_size", False):
+            seen = {id(item) for item in affected_items}
+            for item in self.queue_manager.filter_missing_size(self.queue):
+                if id(item) not in seen:
+                    affected_items.append(item)
+                    seen.add(id(item))
+
+        return affected_items

src/settings/_jobs.py

@@ -14,6 +14,7 @@ class JobParams:
     max_concurrent_searches: int
     min_days_between_searches: int
     target_tags: list
+    detect_via_missing_size: bool = False
 
     def __init__(
         self,
@@ -25,6 +26,7 @@ def __init__(
         max_concurrent_searches=None,
         min_days_between_searches=None,
         target_tags=None,
+        detect_via_missing_size=None,
     ):
         self.enabled = enabled
         self.keep_archives = keep_archives
@@ -34,6 +36,7 @@ def __init__(
         self.max_concurrent_searches = max_concurrent_searches
         self.min_days_between_searches = min_days_between_searches
         self.target_tags = target_tags
+        self.detect_via_missing_size = detect_via_missing_size
 
         # Remove attributes that are None to keep the object clean
         self._remove_none_attributes()
@@ -90,6 +93,7 @@ def _set_job_defaults(self):
         )
         self.remove_metadata_missing = JobParams(
             max_strikes=self.job_defaults.max_strikes,
+            detect_via_missing_size=False,
         )
         self.remove_missing_files = JobParams()
         self.remove_orphans = JobParams()

src/utils/queue_manager.py

@@ -243,3 +243,21 @@ def filter_queue(
                     filtered_items.append(item)
                     break
         return filtered_items
+
+    @staticmethod
+    def filter_missing_size(queue: list[dict]) -> list[dict]:
+        """
+        Return queued items whose size is not yet known (no metadata fetched).
+
+        Unlike qBittorrent, clients such as Transmission or Deluge do not surface a
+        "downloading metadata" message in the *arr queue, so a torrent stuck fetching
+        metadata cannot be matched by message. Such items are reported by the *arr as
+        status "queued" with size 0. This client-agnostic check catches them (see #57).
+
+        The "size" key must be present so that incomplete items are not matched.
+        """
+        return [
+            item
+            for item in queue
+            if item.get("status") == "queued" and "size" in item and not item["size"]
+        ]

tests/jobs/test_remove_metadata_missing.py

@@ -1,3 +1,5 @@
+from unittest.mock import MagicMock
+
 import pytest
 
 from src.jobs.remove_metadata_missing import RemoveMetadataMissing
@@ -91,3 +93,100 @@ async def test_find_affected_items(queue_data, expected_download_ids):
 
     # Act and Assert
     await shared_test_affected_items(removal_job, expected_download_ids)
+
+
+# Tests the opt-in, client-agnostic detection of items stuck without metadata
+# (status "queued" + size 0), e.g. on Transmission/Deluge which do not surface the
+# qBittorrent "downloading metadata" message in the *arr queue (see issue #57).
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("detect_via_missing_size", "queue_data", "expected_download_ids"),
+    [
+        # Disabled (default): a queued size-0 item is NOT flagged; only the qBit message is.
+        (
+            False,
+            [
+                {
+                    "id": 1,
+                    "downloadId": "a",
+                    "status": "queued",
+                    "size": 0,
+                    "errorMessage": None,
+                },
+                {
+                    "id": 2,
+                    "downloadId": "b",
+                    "status": "queued",
+                    "errorMessage": "qBittorrent is downloading metadata",
+                },
+            ],
+            ["b"],
+        ),
+        # Enabled: queued + size 0 is flagged; size > 0 and non-queued are left alone.
+        (
+            True,
+            [
+                {
+                    "id": 1,
+                    "downloadId": "a",
+                    "status": "queued",
+                    "size": 0,
+                    "errorMessage": None,
+                },
+                {
+                    "id": 2,
+                    "downloadId": "b",
+                    "status": "queued",
+                    "size": 1234,
+                    "errorMessage": None,
+                },
+                {
+                    "id": 3,
+                    "downloadId": "c",
+                    "status": "downloading",
+                    "size": 0,
+                    "errorMessage": None,
+                },
+            ],
+            ["a"],
+        ),
+        # Enabled: an item matching BOTH the qBit message and size 0 is not duplicated.
+        (
+            True,
+            [
+                {
+                    "id": 1,
+                    "downloadId": "a",
+                    "status": "queued",
+                    "size": 0,
+                    "errorMessage": "qBittorrent is downloading metadata",
+                },
+                {
+                    "id": 2,
+                    "downloadId": "b",
+                    "status": "queued",
+                    "size": 0,
+                    "errorMessage": None,
+                },
+            ],
+            ["a", "b"],
+        ),
+        # Enabled but no size key present (e.g. partial item): not matched.
+        (
+            True,
+            [
+                {"id": 1, "downloadId": "a", "status": "queued", "errorMessage": None},
+            ],
+            [],
+        ),
+    ],
+)
+async def test_find_affected_items_via_missing_size(
+    detect_via_missing_size, queue_data, expected_download_ids
+):
+    # Arrange
+    removal_job = shared_fix_affected_items(RemoveMetadataMissing, queue_data)
+    removal_job.job = MagicMock(detect_via_missing_size=detect_via_missing_size)
+
+    # Act and Assert
+    await shared_test_affected_items(removal_job, expected_download_ids)