feat(api): make job timeout configurable via YUBAL_JOB_TIMEOUT_SECONDS

Users with large playlists (400+ tracks) hit the hardcoded 30-minute
timeout. This replaces the class constant with a setting configurable
via environment variable (default: 1800s).

Refs #73

Author: guillevc

.env.example

@@ -27,6 +27,9 @@ YUBAL_DOWNLOAD_UGC=false      # Download user-generated content to _Unofficial/
 # Filenames
 YUBAL_ASCII_FILENAMES=false   # Transliterate unicode to ASCII in filenames (default: false)
 
+# Jobs
+YUBAL_JOB_TIMEOUT_SECONDS=1800  # Job execution timeout in seconds (default: 1800)
+
 # Scheduler
 YUBAL_SCHEDULER_ENABLED=true       # Enable scheduled sync (default: true)
 YUBAL_SCHEDULER_CRON="0 0 * * *"   # Cron schedule (default: daily at midnight)

README.md

@@ -112,16 +112,17 @@ docker compose up -d
 
 ## ⚙️ Configuration
 
-| Variable                  | Description                                       | Default (Docker) |
-| ------------------------- | ------------------------------------------------- | ---------------- |
-| `YUBAL_AUDIO_FORMAT`      | `opus`, `mp3`, or `m4a`                           | `opus`           |
-| `YUBAL_AUDIO_QUALITY`     | Transcode quality (0=best, 10=worst)              | `0`              |
-| `YUBAL_SCHEDULER_ENABLED` | Enable automatic scheduled sync                   | `true`           |
-| `YUBAL_SCHEDULER_CRON`    | Cron schedule for auto-sync                       | `0 0 * * *`      |
-| `YUBAL_FETCH_LYRICS`      | Fetch lyrics from lrclib.net                      | `true`           |
-| `YUBAL_DOWNLOAD_UGC`      | Download user-generated content to `_Unofficial/` | `false`          |
-| `YUBAL_REPLAYGAIN`        | Apply ReplayGain tags to downloads                | `true`           |
-| `YUBAL_TZ`                | Timezone (IANA format)                            | `UTC`            |
+| Variable                    | Description                                       | Default (Docker) |
+| --------------------------- | ------------------------------------------------- | ---------------- |
+| `YUBAL_AUDIO_FORMAT`        | `opus`, `mp3`, or `m4a`                           | `opus`           |
+| `YUBAL_AUDIO_QUALITY`       | Transcode quality (0=best, 10=worst)              | `0`              |
+| `YUBAL_SCHEDULER_ENABLED`   | Enable automatic scheduled sync                   | `true`           |
+| `YUBAL_SCHEDULER_CRON`      | Cron schedule for auto-sync                       | `0 0 * * *`      |
+| `YUBAL_FETCH_LYRICS`        | Fetch lyrics from lrclib.net                      | `true`           |
+| `YUBAL_DOWNLOAD_UGC`        | Download user-generated content to `_Unofficial/` | `false`          |
+| `YUBAL_REPLAYGAIN`          | Apply ReplayGain tags to downloads                | `true`           |
+| `YUBAL_JOB_TIMEOUT_SECONDS` | Job execution timeout in seconds                  | `1800`           |
+| `YUBAL_TZ`                  | Timezone (IANA format)                            | `UTC`            |
 
 <details>
 <summary>All options</summary>

deploy/.env.example

@@ -17,6 +17,9 @@ YUBAL_DOWNLOAD_UGC=false      # Download user-generated content to _Unofficial/
 # Filenames
 YUBAL_ASCII_FILENAMES=false   # Transliterate unicode to ASCII in filenames (default: false)
 
+# Jobs
+YUBAL_JOB_TIMEOUT_SECONDS=1800  # Job execution timeout in seconds (default: 1800)
+
 # Scheduler
 YUBAL_SCHEDULER_ENABLED=true       # Enable scheduled sync (default: true)
 YUBAL_SCHEDULER_CRON="0 0 * * *"   # Cron expression (default: daily at midnight)

packages/api/src/yubal_api/api/app.py

@@ -162,6 +162,7 @@ def create_services(repository: SubscriptionRepository) -> Services:
         download_ugc=settings.download_ugc,
         subscription_service=subscription_service,
         cache_path=settings.cache_path,
+        job_timeout=settings.job_timeout_seconds,
     )
 
     # Create scheduler

packages/api/src/yubal_api/services/job_executor.py

@@ -41,8 +41,6 @@ class JobExecutor:
         - Tasks are tracked in a set to prevent garbage collection
     """
 
-    TIMEOUT_SECONDS: float = 30 * 60  # 30 minutes
-
     def __init__(
         self,
         job_store: JobExecutionStore,
@@ -55,6 +53,7 @@ def __init__(
         download_ugc: bool = False,
         subscription_service: SubscriptionService | None = None,
         cache_path: Path | None = None,
+        job_timeout: float = 1800,
     ) -> None:
         """Initialize the job executor.
 
@@ -69,6 +68,7 @@ def __init__(
             download_ugc: Whether to download UGC tracks to _Unofficial folder.
             subscription_service: Optional service to update subscription metadata.
             cache_path: Optional directory for extraction cache.
+            job_timeout: Maximum execution time per job in seconds.
         """
         self._job_store = job_store
         self._base_path = base_path
@@ -80,6 +80,7 @@ def __init__(
         self._download_ugc = download_ugc
         self._subscription_service = subscription_service
         self._cache_path = cache_path
+        self._job_timeout = job_timeout
 
         # Track background tasks to prevent GC during execution
         self._background_tasks: set[asyncio.Task[Any]] = set()
@@ -184,7 +185,7 @@ async def _run_job(
             if cancel_token.is_cancelled:
                 return
 
-            async with asyncio.timeout(self.TIMEOUT_SECONDS):
+            async with asyncio.timeout(self._job_timeout):
                 self._job_store.transition(
                     job_id,
                     JobStatus.FETCHING_INFO,
@@ -273,7 +274,7 @@ def on_progress(
 
         except TimeoutError:
             logger.warning(
-                "Job %s timed out after %d seconds", job_id[:8], self.TIMEOUT_SECONDS
+                "Job %s timed out after %d seconds", job_id[:8], self._job_timeout
             )
             cancel_token.cancel()
             self._job_store.transition(job_id, JobStatus.FAILED)

packages/api/src/yubal_api/settings.py

@@ -108,6 +108,13 @@ class Settings(BaseSettings):
         description="Cron expression for scheduled sync",
     )
 
+    # Job execution
+    job_timeout_seconds: int = Field(
+        default=1800,
+        ge=60,
+        description="Job execution timeout in seconds",
+    )
+
     # Timezone
     tz: Timezone = Field(default="UTC", description="Timezone for timestamps")
 

packages/api/tests/test_job_executor.py

@@ -53,9 +53,7 @@ def store(self) -> FakeJobStore:
 
     @pytest.fixture
     def executor(self, store: FakeJobStore, tmp_path: Any) -> JobExecutor:
-        ex = JobExecutor(job_store=store, base_path=tmp_path)
-        ex.TIMEOUT_SECONDS = 0.1  # 100ms for fast tests
-        return ex
+        return JobExecutor(job_store=store, base_path=tmp_path, job_timeout=0.1)
 
     @pytest.mark.asyncio
     async def test_timeout_triggers_cancellation_and_fails_job(