kryten-webqueue 0.9.12__tar.gz → 0.9.13__tar.gz

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
+## [0.9.13] — 2026-06-12
+
+### Fixed
+
+- **Bulk playlist loads no longer fail with spurious `422 Unprocessable Entity`.** When importing a saved playlist into the live queue or firing a scheduled playlist, items were added back-to-back with no pacing. CyTube validates each queued item server-side (fetching the custom MediaCMS manifest), and adding faster than it can validate triggers a transient `queueFail` — surfaced by api-gate as HTTP 422 — even for perfectly valid URLs. The importer and scheduled-fire loops now throttle consecutive adds and retry the transient 422 with a short backoff.
+
+### Added
+
+- Config: `playlist_bulk_add_delay_sec` (default `0.5`) — pause between consecutive CyTube adds during bulk loads — and `playlist_bulk_add_max_retries` (default `2`) — retries on a transient 422.
+
 ## [0.9.12] — 2026-06-12
 
 ### Fixed

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kryten-webqueue
-Version: 0.9.12
+Version: 0.9.13
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/config.example.json

@@ -32,5 +32,8 @@
   "pre_fire_lock_minutes_default": 15,
   "state_poll_interval_sec": 3.0,
 
+  "playlist_bulk_add_delay_sec": 0.5,
+  "playlist_bulk_add_max_retries": 2,
+
   "prometheus_port": 28292
 }

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/kryten_webqueue/app.py

@@ -131,7 +131,11 @@ async def lifespan(app: FastAPI):
     app.state.rate_limiter = RateLimiter()
 
     # Playlist scheduler
-    scheduler = PlaylistScheduler(db=db, api_gate=api_gate, shadow=shadow, ws_manager=ws_manager)
+    scheduler = PlaylistScheduler(
+        db=db, api_gate=api_gate, shadow=shadow, ws_manager=ws_manager,
+        add_delay_sec=config.playlist_bulk_add_delay_sec,
+        add_max_retries=config.playlist_bulk_add_max_retries,
+    )
     await scheduler.start()
     app.state.scheduler = scheduler
 

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/kryten_webqueue/config.py

@@ -60,6 +60,13 @@ class Config(BaseModel):
     pre_fire_lock_minutes_default: int = 15
     state_poll_interval_sec: float = 3.0
 
+    # Bulk playlist loading (manual import + scheduled fire). CyTube validates
+    # each queued item server-side (fetching custom manifests); adding faster
+    # than it can validate triggers a transient queueFail (surfaced by api-gate
+    # as HTTP 422). Throttle consecutive adds and retry the transient 422.
+    playlist_bulk_add_delay_sec: float = 0.5   # pause between consecutive adds
+    playlist_bulk_add_max_retries: int = 2     # retries on transient 422
+
     # Monitoring
     prometheus_port: int = 28292
 

kryten_webqueue-0.9.13/kryten_webqueue/playlists/bulk_add.py

@@ -0,0 +1,52 @@
+"""Throttled, retrying single-item add used by bulk playlist loaders.
+
+CyTube validates each queued item server-side (e.g. fetching a custom MediaCMS
+manifest). Adding items faster than CyTube can validate them produces a
+transient ``queueFail`` — which api-gate surfaces as HTTP 422 on
+``/playlist/add``. These rejections are not about a bad URL; spacing the calls
+out (and retrying the 422 a couple of times) lets the queue settle.
+"""
+
+import asyncio
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+async def add_item_throttled(
+    api_gate,
+    *,
+    media_type: str,
+    media_id: str,
+    position: str = "end",
+    max_retries: int = 0,
+    retry_delay_sec: float = 0.5,
+) -> dict:
+    """Add one item to the live queue, retrying transient CyTube rejections.
+
+    A 422 (CyTube ``queueFail``) is retried up to ``max_retries`` times with a
+    linear backoff (``retry_delay_sec`` × attempt). Any other HTTP error is not
+    retried. Returns the api-gate result dict; re-raises the final exception
+    when retries are exhausted so callers can count/log the failure.
+    """
+    attempt = 0
+    while True:
+        try:
+            return await api_gate.playlist_add(
+                media_type=media_type,
+                media_id=media_id,
+                position=position,
+            )
+        except httpx.HTTPStatusError as e:
+            is_transient = e.response is not None and e.response.status_code == 422
+            if not is_transient or attempt >= max_retries:
+                raise
+            attempt += 1
+            backoff = retry_delay_sec * attempt
+            logger.info(
+                "CyTube rejected %s (422 queueFail); retry %d/%d after %.1fs",
+                media_id, attempt, max_retries, backoff,
+            )
+            await asyncio.sleep(backoff)

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/kryten_webqueue/playlists/fire.py

@@ -3,13 +3,23 @@ import logging
 from datetime import datetime, timedelta, UTC
 
 from ..queue.ordering import refund_item
+from .bulk_add import add_item_throttled
 
 logger = logging.getLogger(__name__)
 
 _queue_lock = asyncio.Lock()
 
 
-async def fire_schedule(*, schedule_id: int, api_gate, db, shadow, ws_manager):
+async def fire_schedule(
+    *,
+    schedule_id: int,
+    api_gate,
+    db,
+    shadow,
+    ws_manager,
+    add_delay_sec: float = 0.0,
+    add_max_retries: int = 0,
+):
     """Fire a scheduled playlist: clear queue, refund displaced pay items, load playlist."""
     async with _queue_lock:
         schedule = await db.get_schedule(schedule_id)
@@ -35,12 +45,19 @@ async def fire_schedule(*, schedule_id: int, api_gate, db, shadow, ws_manager):
         items = await db.get_saved_playlist_items(playlist_id)
         total_duration = 0
         last_item_uid = None
-        for item in items:
+        for index, item in enumerate(items):
+            # Throttle consecutive adds so CyTube can validate each item before
+            # the next arrives (avoids transient queueFail/422 under load).
+            if index and add_delay_sec:
+                await asyncio.sleep(add_delay_sec)
             try:
-                add_result = await api_gate.playlist_add(
+                add_result = await add_item_throttled(
+                    api_gate,
                     media_type=item["media_type"],
                     media_id=item["media_id"],
                     position="end",
+                    max_retries=add_max_retries,
+                    retry_delay_sec=add_delay_sec or 0.5,
                 )
                 if isinstance(add_result, dict) and add_result.get("uid") is not None:
                     last_item_uid = add_result["uid"]
@@ -56,12 +73,17 @@ async def fire_schedule(*, schedule_id: int, api_gate, db, shadow, ws_manager):
         fallback_id = schedule.get("fallback_playlist_id")
         if fallback_id:
             fallback_items = await db.get_saved_playlist_items(fallback_id)
-            for item in fallback_items:
+            for index, item in enumerate(fallback_items):
+                if index and add_delay_sec:
+                    await asyncio.sleep(add_delay_sec)
                 try:
-                    await api_gate.playlist_add(
+                    await add_item_throttled(
+                        api_gate,
                         media_type=item["media_type"],
                         media_id=item["media_id"],
                         position="end",
+                        max_retries=add_max_retries,
+                        retry_delay_sec=add_delay_sec or 0.5,
                     )
                 except Exception as e:
                     logger.warning(f"Schedule fire: failed to add fallback {item['media_id']}: {e}")

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/kryten_webqueue/playlists/importer.py

@@ -1,6 +1,9 @@
+import asyncio
 import logging
 import re
 
+from .bulk_add import add_item_throttled
+
 logger = logging.getLogger(__name__)
 
 
@@ -59,10 +62,12 @@ def _manifest_url_for_token(token: str, mediacms_url: str | None) -> str | None:
 class PlaylistImporter:
     """Imports items from a saved playlist into the live CyTube queue."""
 
-    def __init__(self, *, api_gate, db, shadow):
+    def __init__(self, *, api_gate, db, shadow, add_delay_sec: float = 0.0, add_max_retries: int = 0):
         self._api_gate = api_gate
         self._db = db
         self._shadow = shadow
+        self._add_delay_sec = add_delay_sec
+        self._add_max_retries = add_max_retries
 
     async def import_playlist(self, playlist_id: int) -> dict:
         """Import all items from a saved playlist into the live queue."""
@@ -72,12 +77,19 @@ class PlaylistImporter:
 
         added = 0
         errors = 0
-        for item in items:
+        for index, item in enumerate(items):
+            # Throttle consecutive adds so CyTube can validate each item before
+            # the next arrives (avoids transient queueFail/422 under load).
+            if index and self._add_delay_sec:
+                await asyncio.sleep(self._add_delay_sec)
             try:
-                result = await self._api_gate.playlist_add(
+                result = await add_item_throttled(
+                    self._api_gate,
                     media_type=item["media_type"],
                     media_id=item["media_id"],
                     position="end",
+                    max_retries=self._add_max_retries,
+                    retry_delay_sec=self._add_delay_sec or 0.5,
                 )
                 if result.get("success"):
                     added += 1

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/kryten_webqueue/playlists/scheduler.py

@@ -27,11 +27,13 @@ def _next_occurrence(rrule_str: str, dtstart: datetime, after: datetime) -> date
 class PlaylistScheduler:
     """APScheduler-based scheduler for playlist fire events."""
 
-    def __init__(self, *, db, api_gate, shadow, ws_manager):
+    def __init__(self, *, db, api_gate, shadow, ws_manager, add_delay_sec: float = 0.0, add_max_retries: int = 0):
         self._db = db
         self._api_gate = api_gate
         self._shadow = shadow
         self._ws_manager = ws_manager
+        self._add_delay_sec = add_delay_sec
+        self._add_max_retries = add_max_retries
         self._scheduler = AsyncIOScheduler()
 
     async def start(self):
@@ -96,6 +98,8 @@ class PlaylistScheduler:
             db=self._db,
             shadow=self._shadow,
             ws_manager=self._ws_manager,
+            add_delay_sec=self._add_delay_sec,
+            add_max_retries=self._add_max_retries,
         )
         # After an automatic timed fire, advance recurring schedules to their
         # next occurrence and re-arm. (Manual "Fire Now" does NOT advance the

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/kryten_webqueue/routes/admin_playlists.py

@@ -89,10 +89,13 @@ async def import_to_live(request: Request, playlist_id: int, user: dict = Depend
     if not playlist:
         raise HTTPException(404, "Playlist not found")
 
+    config = request.app.state.config
     importer = PlaylistImporter(
         api_gate=request.app.state.api_gate,
         db=db,
         shadow=request.app.state.shadow,
+        add_delay_sec=config.playlist_bulk_add_delay_sec,
+        add_max_retries=config.playlist_bulk_add_max_retries,
     )
     result = await importer.import_playlist(playlist_id)
     return result

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/kryten_webqueue/routes/admin_schedules.py

@@ -112,12 +112,15 @@ async def fire_now(request: Request, schedule_id: int, user: dict = Depends(requ
     if not sched:
         raise HTTPException(404, "Schedule not found")
 
+    config = request.app.state.config
     await fire_schedule(
         schedule_id=schedule_id,
         api_gate=request.app.state.api_gate,
         db=db,
         shadow=request.app.state.shadow,
         ws_manager=request.app.state.ws_manager,
+        add_delay_sec=config.playlist_bulk_add_delay_sec,
+        add_max_retries=config.playlist_bulk_add_max_retries,
     )
     return {"success": True}
 

{kryten_webqueue-0.9.12 → kryten_webqueue-0.9.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kryten-webqueue"
-version = "0.9.12"
+version = "0.9.13"
 description = "Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube"
 readme = "README.md"
 license = "MIT"