fix(docker): always start the RQ scheduler

The scheduler only started when one of four ENABLE_SCHEDULED_* flags was
true, but nothing else respects that condition. startup.py registers the
netplay, upload-tmp and zip-cache cleanups unconditionally, three more
flags gate periodic tasks that are absent from the list, and the
filesystem watcher defers its rescans through the scheduler as well.

Any of those left jobs sitting in the scheduler registry with no process
to run them. On a default install the three cleanups never fire at all.
Worse, a watcher running with every scheduled task disabled accumulates
delayed scan_platforms entries permanently, and the concurrent scan guard
reads those as a scan already queued, so every manual scan is refused
with "A scan is already in progress" until Redis is cleared. Restarting
does not help, because the entries are persisted state rather than a
running process.

Start the scheduler unconditionally, matching entrypoint.sh, which never
gated it. Also stop counting a scheduler entry whose time passed long ago
as a pending scan: an overdue entry means nothing is draining the
registry, so treating it as queued cannot recover on its own.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: XenuIsWatching

backend/endpoints/sockets/scan.py

@@ -2,6 +2,7 @@
 
 import asyncio
 from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
 from itertools import batched, chain
 from typing import Any, Final
 
@@ -70,6 +71,22 @@
 
 STOP_SCAN_FLAG: Final = "scan:stop"
 
+# How far past its scheduled time a delayed scan can be before it is treated as
+# orphaned rather than pending. Comfortably clear of the scheduler's own polling
+# interval, so a job merely waiting its turn is never discarded.
+SCHEDULED_SCAN_GRACE: Final = timedelta(minutes=15)
+
+
+def _as_utc(value: datetime) -> datetime:
+    """Read a scheduler timestamp as UTC.
+
+    rq-scheduler stores scheduled times as naive UTC, so they cannot be compared
+    against an aware "now" without being localised first.
+    """
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
 
 def _scan_platforms_func_name() -> str:
     """Fully qualified name RQ records for a directly enqueued scan.
@@ -121,12 +138,19 @@ def _get_queued_scan_jobs() -> list[Job]:
     # The scheduler registry also holds the standing cron entry for the
     # scheduled rescan, which is a schedule rather than a pending scan, so only
     # delayed scan_platforms jobs count as queued here.
+    #
+    # An entry whose time passed long ago is not pending either: the scheduler
+    # is not draining the registry, so nothing will ever run it. Counting those
+    # blocks every manual scan for good, which is what a watcher running without
+    # a scheduler used to cause, so treat them as orphaned instead.
     scan_platforms_func_name = _scan_platforms_func_name()
-    for job in tasks_scheduler.get_jobs():
+    overdue_cutoff = datetime.now(timezone.utc) - SCHEDULED_SCAN_GRACE
+    for job, scheduled_for in tasks_scheduler.get_jobs(with_times=True):
         if (
             isinstance(job, Job)
             and get_job_func_name(job) == scan_platforms_func_name
             and job.get_status() in (JobStatus.SCHEDULED, JobStatus.QUEUED)
+            and _as_utc(scheduled_for) > overdue_cutoff
         ):
             jobs[job.id] = job
 

backend/tests/endpoints/sockets/test_scan.py

@@ -1,3 +1,4 @@
+from datetime import datetime, timedelta, timezone
 from itertools import count
 from unittest.mock import AsyncMock, MagicMock, Mock
 
@@ -945,9 +946,20 @@ def make_job(func_name: str, *, status=JobStatus.QUEUED):
 
 
 def patch_scan_jobs(
-    mocker, *, running=None, high_queued=(), low_queued=(), scheduled=()
+    mocker,
+    *,
+    running=None,
+    high_queued=(),
+    low_queued=(),
+    scheduled=(),
+    scheduled_at=None,
 ):
-    """Point every place scan discovery looks at a fixed set of jobs."""
+    """Point every place scan discovery looks at a fixed set of jobs.
+
+    Scheduler entries carry the time they are due, which discovery uses to tell
+    a scan waiting its turn from one nothing is going to run. They default to
+    due shortly, as a naive UTC timestamp, which is what rq-scheduler stores.
+    """
     worker = MagicMock()
     worker.get_current_job.return_value = running
     mocker.patch.object(scan_module.Worker, "all", return_value=[worker])
@@ -957,8 +969,14 @@ def patch_scan_jobs(
     mocker.patch.object(
         scan_module.low_prio_queue, "get_jobs", return_value=list(low_queued)
     )
+    if scheduled_at is None:
+        scheduled_at = datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(
+            minutes=5
+        )
     mocker.patch.object(
-        scan_module.tasks_scheduler, "get_jobs", return_value=list(scheduled)
+        scan_module.tasks_scheduler,
+        "get_jobs",
+        return_value=[(job, scheduled_at) for job in scheduled],
     )
 
 
@@ -1052,6 +1070,36 @@ async def test_standing_rescan_cron_entry_does_not_block(self, mocker, emit):
 
         enqueue.assert_called_once()
 
+    async def test_overdue_scheduled_scan_does_not_block(self, mocker, emit):
+        # A watcher deferring rescans while no scheduler runs leaves them in the
+        # registry with nothing to execute them. Long past due, they are
+        # orphaned, and counting them blocks every manual scan for good.
+        patch_scan_jobs(
+            mocker,
+            scheduled=[make_job(SCAN_PLATFORMS_FUNC, status=JobStatus.SCHEDULED)],
+            scheduled_at=datetime.now(timezone.utc).replace(tzinfo=None)
+            - timedelta(hours=6),
+        )
+        enqueue = mocker.patch.object(scan_module.high_prio_queue, "enqueue")
+
+        await scan_handler("sid", {"type": "quick"})
+
+        enqueue.assert_called_once()
+
+    async def test_aware_scheduler_timestamps_still_block(self, mocker, emit):
+        # rq-scheduler stores naive UTC, but an aware timestamp must compare the
+        # same way rather than raising on the mixed comparison.
+        patch_scan_jobs(
+            mocker,
+            scheduled=[make_job(SCAN_PLATFORMS_FUNC, status=JobStatus.SCHEDULED)],
+            scheduled_at=datetime.now(timezone.utc) + timedelta(minutes=5),
+        )
+        enqueue = mocker.patch.object(scan_module.high_prio_queue, "enqueue")
+
+        await scan_handler("sid", {"type": "quick"})
+
+        enqueue.assert_not_called()
+
     async def test_ignores_unrelated_jobs(self, mocker, emit):
         # Only scans block scans; a cleanup or metadata task must not.
         patch_scan_jobs(

docker/init_scripts/init

@@ -376,10 +376,11 @@ run_startup
 while ! ((exited)); do
 	watchdog_process_pid gunicorn
 
-	# only start the scheduler if enabled
-	if [[ ${ENABLE_SCHEDULED_RESCAN} == "true" || ${ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB} == "true" || ${ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA} == "true" || ${ENABLE_SCHEDULED_CLEANUP_ORPHANED_RESOURCES} == "true" ]]; then
-		watchdog_process_pid rq_scheduler
-	fi
+	# The scheduler always runs. startup.py registers the netplay, upload-tmp and
+	# zip-cache cleanups unconditionally, and the watcher defers its rescans
+	# through the scheduler, so gating it on the ENABLE_SCHEDULED_* flags left
+	# those jobs queued with nothing to execute them.
+	watchdog_process_pid rq_scheduler
 
 	watchdog_process_pid rq_worker