kryten-webqueue 0.15.0__tar.gz → 0.15.2__tar.gz

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/CHANGELOG.md

@@ -6,6 +6,28 @@ 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.15.2] — 2026-06-17
+
+### Fixed
+
+- **Promos were inserted into immutable playlists during a schedule fire.** A scheduled event clears the queue and loads its items over several seconds (throttled adds + 422 retries), but the event lock that suppresses promos was only recorded *after* the entire load finished. Meanwhile the state poller (every ~3s) saw a partially-built queue with no lock and slotted a general promo between the freshly-added immutable items. `PromoDirector` now exposes a re-entrant `suppressed()` guard that `fire_schedule` (and manual playlist import) holds for the whole load — spanning through `set_active_schedule`, so for an immutable event the persistent lock is already live by the time suppression lifts (a clean handoff with no race window). When suppression releases, the next poll re-baselines now-playing instead of treating the bulk load as content advancing, so no promo fires on the wrong boundary. This also satisfies the general rule: never evaluate promos while a bulk queue insert/append is in progress, regardless of playlist type.
+
+[0.15.2]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.15.2
+
+## [0.15.1] — 2026-06-17
+
+### Fixed
+
+- **Application logs were silently dropped.** The app never configured Python logging — `uvicorn.run(log_level="info")` only sets up uvicorn's own loggers, leaving the `kryten_webqueue` hierarchy with no handler, so Python's "last resort" path emitted only `WARNING`+. Every `logger.info(...)` (including all promo-insertion diagnostics) was discarded. A new `logging_config.build_log_config()` installs a `dictConfig` (passed to uvicorn via `log_config`) that attaches a console handler to the application loggers.
+- **Silent failure in the promo poll loop.** `PromoDirector.on_poll()` swallowed every exception from the immutable-event-lock check with a bare `except: return` and no log line, hiding faults. It now logs at `WARNING` with a traceback before skipping the cycle.
+
+### Added
+
+- **Configurable log levels.** New `log_level` (default `INFO`) and `promo_log_level` (default falls back to `log_level`) config fields. Set `promo_log_level` to `DEBUG` for a full per-poll trace of promo decisions without flooding the rest of the app (the `kryten_webqueue.promos` logger is independently tunable).
+- **Deep promo observability.** `PromoDirector` now emits detailed diagnostics across the whole insertion path: now-playing advance + cadence counter, clip selection (order, pool size, sequential index, random no-repeat avoidance), weighted type pick (candidates/weights/skipped), cadence-due reason, idempotency-guard skips, lead-in decisions, and the add/move/uid result. It warns on single-clip pools (which always repeat) and **errors** when an add succeeds but returns no uid (an untracked insertion that would otherwise repeat every poll).
+
+[0.15.1]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.15.1
+
 ## [0.15.0] — 2026-06-14
 
 ### Added

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/PKG-INFO

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

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/config.example.json

@@ -5,6 +5,9 @@
   "secret_key": "CHANGE_ME_long_random_string",
   "session_ttl_hours": 24,
 
+  "log_level": "INFO",
+  "promo_log_level": "DEBUG",
+
   "api_gate_url": "https://www.dropsugar.co:8443/",
   "api_gate_token": "CHANGE_ME",
 

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/kryten_webqueue/__main__.py

@@ -3,13 +3,15 @@ import uvicorn
 
 from .config import Config
 from .app import create_app
+from .logging_config import build_log_config
 
 
 def main():
     config_path = os.environ.get("WQ_CONFIG", "/etc/kryten-webqueue/config.json")
     config = Config.from_file(config_path)
     app = create_app(config)
-    uvicorn.run(app, host=config.host, port=config.port, log_level="info")
+    log_config = build_log_config(config.log_level, config.promo_log_level)
+    uvicorn.run(app, host=config.host, port=config.port, log_config=log_config)
 
 
 if __name__ == "__main__":

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/kryten_webqueue/app.py

@@ -147,6 +147,7 @@ async def lifespan(app: FastAPI):
         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,
+        promo_director=promo_director,
     )
     await scheduler.start()
     app.state.scheduler = scheduler

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/kryten_webqueue/config.py

@@ -104,6 +104,17 @@ class Config(BaseModel):
     secret_key: str
     session_ttl_hours: int = 24
 
+    # Logging
+    # Root application log level for the ``kryten_webqueue`` logger hierarchy.
+    # Without explicit configuration Python only emits WARNING+ via its
+    # "last resort" handler, so INFO diagnostics (e.g. promo insertions) are
+    # silently dropped. ``__main__`` installs a dictConfig using these values.
+    log_level: str = "INFO"
+    # Independent level for the promo subsystem (``kryten_webqueue.promos``).
+    # Set to "DEBUG" for a full per-poll trace of promo decisions without
+    # flooding the rest of the app. Falls back to ``log_level`` when None.
+    promo_log_level: str | None = None
+
     # API Gate
     api_gate_url: str = "http://127.0.0.1:24444"
     api_gate_token: str

kryten_webqueue-0.15.2/kryten_webqueue/logging_config.py

@@ -0,0 +1,81 @@
+"""Centralised logging configuration.
+
+The app previously relied on ``uvicorn.run(log_level="info")`` which only
+configures uvicorn's *own* loggers (``uvicorn``/``uvicorn.access``/
+``uvicorn.error``). Application loggers in the ``kryten_webqueue`` hierarchy had
+no handler, so Python's "last resort" handler emitted only ``WARNING`` and
+above — silently dropping every ``logger.info(...)`` call (e.g. all promo
+insertion diagnostics). This module builds a single ``dictConfig`` that installs
+a console handler for both uvicorn and the application loggers, with an
+independently tunable level for the promo subsystem.
+"""
+
+from __future__ import annotations
+
+
+def _normalize_level(level: str | None, default: str) -> str:
+    if not level:
+        return default
+    candidate = str(level).strip().upper()
+    valid = {"CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "NOTSET"}
+    return candidate if candidate in valid else default
+
+
+def build_log_config(log_level: str = "INFO", promo_log_level: str | None = None) -> dict:
+    """Return a ``logging.config.dictConfig`` dict for uvicorn + the app.
+
+    Args:
+        log_level: Level for the root and ``kryten_webqueue`` loggers.
+        promo_log_level: Level for ``kryten_webqueue.promos`` (the promo
+            director). Falls back to ``log_level`` when not provided. Set to
+            ``DEBUG`` for a full per-poll trace of promo decisions.
+    """
+    app_level = _normalize_level(log_level, "INFO")
+    promo_level = _normalize_level(promo_log_level, app_level)
+
+    return {
+        "version": 1,
+        # Never tear down loggers created at import time (module-level
+        # ``getLogger`` calls); we only attach handlers/levels.
+        "disable_existing_loggers": False,
+        "formatters": {
+            "default": {
+                "format": "%(asctime)s %(levelname)-8s %(name)s: %(message)s",
+                "datefmt": "%Y-%m-%d %H:%M:%S",
+            },
+            "access": {
+                "format": "%(asctime)s %(levelname)-8s %(name)s: %(message)s",
+                "datefmt": "%Y-%m-%d %H:%M:%S",
+            },
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "formatter": "default",
+                "stream": "ext://sys.stderr",
+            },
+            "access": {
+                "class": "logging.StreamHandler",
+                "formatter": "access",
+                "stream": "ext://sys.stdout",
+            },
+        },
+        "root": {"handlers": ["console"], "level": app_level},
+        "loggers": {
+            "kryten_webqueue": {
+                "level": app_level,
+                "handlers": ["console"],
+                "propagate": False,
+            },
+            # Promo subsystem: independently tunable so operators can crank it to
+            # DEBUG for a deep dive without flooding the rest of the app.
+            "kryten_webqueue.promos": {
+                "level": promo_level,
+                "handlers": ["console"],
+                "propagate": False,
+            },
+            "uvicorn": {"level": "INFO", "handlers": ["console"], "propagate": False},
+            "uvicorn.error": {"level": "INFO", "handlers": ["console"], "propagate": False},
+            "uvicorn.access": {"level": "INFO", "handlers": ["access"], "propagate": False},
+        },
+    }

kryten_webqueue-0.15.2/kryten_webqueue/playlists/fire.py

@@ -0,0 +1,136 @@
+import asyncio
+import logging
+from contextlib import nullcontext
+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,
+    add_delay_sec: float = 0.0,
+    add_max_retries: int = 0,
+    promo_director=None,
+):
+    """Fire a scheduled playlist: clear queue, refund displaced pay items, load playlist.
+
+    Promo insertion is suppressed for the whole load (via ``promo_director``):
+    promos must never be slotted between items while the playlist is still being
+    built. Suppression spans through ``set_active_schedule`` so that, for an
+    immutable event, the persistent event lock is already recorded by the time
+    suppression lifts — a clean handoff with no window for a stray insertion.
+    """
+    async with _queue_lock:
+        schedule = await db.get_schedule(schedule_id)
+        if not schedule:
+            logger.error(f"Schedule {schedule_id} not found")
+            return
+
+        playlist_id = schedule["playlist_id"]
+        playlist = await db.get_saved_playlist(playlist_id)
+        if not playlist:
+            logger.error(f"Playlist {playlist_id} not found for schedule {schedule_id}")
+            return
+
+        suppress_ctx = (
+            promo_director.suppressed(f"schedule fire {schedule_id}")
+            if promo_director is not None
+            else nullcontext()
+        )
+        with suppress_ctx:
+            # Refund all pay items currently in queue
+            pay_items = await db.get_pay_items()
+            for item in pay_items:
+                await refund_item(api_gate=api_gate, db=db, uid=item["uid"], reason="schedule_displaced")
+
+            # Clear the CyTube playlist
+            await api_gate.playlist_clear()
+
+            # Load scheduled playlist items
+            items = await db.get_saved_playlist_items(playlist_id)
+            total_duration = 0
+            last_item_uid = None
+            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 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"]
+                    total_duration += item.get("duration_sec", 0) or 0
+                except Exception as e:
+                    logger.warning(f"Schedule fire: failed to add {item['media_id']}: {e}")
+
+            # Append the optional fallback (mutable) playlist AFTER the event items so
+            # the live queue isn't left empty once the event is exhausted. The
+            # fallback items are not part of the "scheduled event", so they do not
+            # change last_item_uid (the event lock still lifts when the last EVENT
+            # item begins) and they remain available for pay-to-play/search.
+            fallback_id = schedule.get("fallback_playlist_id")
+            if fallback_id:
+                fallback_items = await db.get_saved_playlist_items(fallback_id)
+                for index, item in enumerate(fallback_items):
+                    if index and add_delay_sec:
+                        await asyncio.sleep(add_delay_sec)
+                    try:
+                        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}")
+                if fallback_items:
+                    logger.info(
+                        f"Schedule {schedule_id}: appended {len(fallback_items)} fallback item(s) "
+                        f"from playlist {fallback_id}"
+                    )
+
+            # Update active schedule (recorded *inside* the suppression window so
+            # the event lock is live before promos resume).
+            now = datetime.now(UTC)
+            await db.set_active_schedule(
+                schedule_id=schedule_id,
+                playlist_id=playlist_id,
+                is_immutable=playlist.get("is_immutable", False),
+                started_at=now.isoformat(),
+                estimated_end_at=(now + timedelta(seconds=total_duration)).isoformat(),
+                last_item_uid=last_item_uid,
+            )
+
+            # Mark schedule as fired
+            await db.mark_schedule_fired(schedule_id, now.isoformat())
+
+        # Notify WS clients
+        await ws_manager.broadcast({
+            "type": "schedule_fired",
+            "data": {
+                "schedule_id": schedule_id,
+                "playlist_name": playlist["name"],
+                "is_immutable": playlist.get("is_immutable", False),
+            },
+        })
+
+        logger.info(f"Schedule {schedule_id} fired: playlist '{playlist['name']}' ({len(items)} items)")

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/kryten_webqueue/playlists/importer.py

@@ -1,6 +1,7 @@
 import asyncio
 import logging
 import re
+from contextlib import nullcontext
 
 from .bulk_add import add_item_throttled
 
@@ -62,12 +63,14 @@ 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, add_delay_sec: float = 0.0, add_max_retries: int = 0):
+    def __init__(self, *, api_gate, db, shadow, add_delay_sec: float = 0.0, add_max_retries: int = 0,
+                 promo_director=None):
         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
+        self._promo_director = promo_director
 
     async def import_playlist(self, playlist_id: int) -> dict:
         """Import all items from a saved playlist into the live queue."""
@@ -75,29 +78,38 @@ class PlaylistImporter:
         if not items:
             return {"success": False, "error": "Playlist is empty"}
 
+        # Suppress promo insertion for the whole load so promos aren't slotted
+        # between items while the playlist is still being built.
+        suppress_ctx = (
+            self._promo_director.suppressed(f"playlist import {playlist_id}")
+            if self._promo_director is not None
+            else nullcontext()
+        )
+
         added = 0
         errors = 0
-        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 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
-                else:
+        with suppress_ctx:
+            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 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
+                    else:
+                        errors += 1
+                except Exception as e:
+                    logger.warning(f"Failed to add {item['media_id']}: {e}")
                     errors += 1
-            except Exception as e:
-                logger.warning(f"Failed to add {item['media_id']}: {e}")
-                errors += 1
 
         return {"success": True, "added": added, "errors": errors}
 

{kryten_webqueue-0.15.0 → kryten_webqueue-0.15.2}/kryten_webqueue/playlists/scheduler.py

@@ -27,13 +27,15 @@ 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, add_delay_sec: float = 0.0, add_max_retries: int = 0):
+    def __init__(self, *, db, api_gate, shadow, ws_manager, add_delay_sec: float = 0.0, add_max_retries: int = 0,
+                 promo_director=None):
         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._promo_director = promo_director
         self._scheduler = AsyncIOScheduler()
 
     async def start(self):
@@ -100,6 +102,7 @@ class PlaylistScheduler:
             ws_manager=self._ws_manager,
             add_delay_sec=self._add_delay_sec,
             add_max_retries=self._add_max_retries,
+            promo_director=self._promo_director,
         )
         # After an automatic timed fire, advance recurring schedules to their
         # next occurrence and re-arm. (Manual "Fire Now" does NOT advance the