kryten-webqueue 0.42.0__tar.gz → 0.43.0__tar.gz

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.43.0] - 2026-08-24
+
+### Added
+
+- **Fetch-queue drain cooldown (anti-bot pacing).** The **Fetch Queue — Process**
+  job now waits a randomized cooldown *between* items instead of downloading
+  back-to-back, so it stops tripping the source's bot detection (the MediaCMS
+  encoder is the real bottleneck anyway). The wait is drawn uniformly from
+  `cooldown_mean_minutes ± cooldown_jitter_minutes` (default **42 ± 8 min**).
+  New optional `fetch_queue` config block: `cooldown_mean_minutes`,
+  `cooldown_jitter_minutes`, `cooldown_enabled`. Settings are **re-read from the
+  config file before every wait**, so editing the config retunes a *running*
+  drain — no restart needed. A `cooldown` progress heartbeat exposes the
+  remaining wait to the admin UI.
+
+### Changed
+
+- **Interrupted fetch-queue downloads now resume.** On startup any item left
+  `running` by a crash/restart is reset to `pending`, and the drain auto-starts
+  if anything is pending — so a download cut off mid-flight is re-attempted
+  without an admin re-triggering it. A drain cancelled by shutdown re-queues its
+  in-flight item (rather than marking it `failed`) for the same reason. Retries
+  re-download the whole file; a leftover yt-dlp `.part` file may let yt-dlp
+  resume where it left off.
+
 ## [0.42.0] - 2026-08-24
 
 ### Added

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kryten-webqueue
-Version: 0.42.0
+Version: 0.43.0
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT
@@ -122,6 +122,16 @@ sudo nginx -t && sudo systemctl reload nginx
 ### WebSocket
 - `ws://host/ws` — Real-time queue updates (auth via session cookie)
 
+### Public API (third-party clients)
+- `POST /api/public/v1/link` — Exchange a one-time device code for an API key
+- `GET /api/public/v1/current` — Now playing
+- `GET /api/public/v1/queue` — Live queue with predicted start times
+- `GET /api/public/v1/events` — Upcoming scheduled events
+
+Key-authenticated (`Authorization: Bearer <key>`) endpoints for Smart TV /
+tablet apps. Users link a device at `/link`. Full contract, JSON schemas, and a
+developer's guide: [docs/PUBLIC_API.md](docs/PUBLIC_API.md).
+
 ## Dependencies
 
 - Python ≥ 3.12

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/README.md

@@ -89,6 +89,16 @@ sudo nginx -t && sudo systemctl reload nginx
 ### WebSocket
 - `ws://host/ws` — Real-time queue updates (auth via session cookie)
 
+### Public API (third-party clients)
+- `POST /api/public/v1/link` — Exchange a one-time device code for an API key
+- `GET /api/public/v1/current` — Now playing
+- `GET /api/public/v1/queue` — Live queue with predicted start times
+- `GET /api/public/v1/events` — Upcoming scheduled events
+
+Key-authenticated (`Authorization: Bearer <key>`) endpoints for Smart TV /
+tablet apps. Users link a device at `/link`. Full contract, JSON schemas, and a
+developer's guide: [docs/PUBLIC_API.md](docs/PUBLIC_API.md).
+
 ## Dependencies
 
 - Python ≥ 3.12

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/config.example.json

@@ -30,6 +30,12 @@
     "token_cache_path": "/var/lib/kryten-webqueue/.fetchurls_tokens.bin"
   },
 
+  "fetch_queue": {
+    "cooldown_mean_minutes": 42.0,
+    "cooldown_jitter_minutes": 8.0,
+    "cooldown_enabled": true
+  },
+
   "presence_refund": {
     "enabled": true,
     "on_leave": true,

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/docs/PUBLIC_API.md

@@ -21,7 +21,7 @@ Keys are minted through a short, user-driven pairing flow so a device never
 handles the user's credentials.
 
 ```
-┌────────────┐   1. names device, gets code    ┌──────────────────┐
+┌────────────┐   1. names device, gets code     ┌──────────────────┐
 │  Browser   │ ───────────────────────────────▶│  queue.dropsugar │
 │ (logged in)│   GET /link  →  "AB2CD"          │      .co         │
 └────────────┘                                  └──────────────────┘
@@ -275,10 +275,12 @@ Errors use FastAPI's standard shape:
 ## 5. Client implementation notes
 
 - **Polling:** these endpoints return point-in-time snapshots. Poll `/current`
-  and `/queue` every ~10–15s; `/events` changes rarely (every few minutes is
-  plenty).
+  and `/queue` no more often than once per minute, it is advised that you
+  locally calculate time remaining and poll even less, if an item is in progress
+  the only thing that will change about it's API data is the time elapsed and
+  time remaining values; `/events` changes rarely (every 15m-1h is plenty).
 - **Countdowns:** compute live countdowns on-device from `remaining_sec` /
-  `estimated_start_in_sec` rather than re-polling every second.
+  `estimated_start_in_sec` rather than re-polling every minute.
 - **Cover art:** `cover_art_url` is absolute and ready to load. It may be
   `null`; show a placeholder.
 - **Key loss / revocation:** if requests start returning 401, the key was

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/kryten_webqueue/app.py

@@ -189,6 +189,26 @@ async def lifespan(app: FastAPI):
     )
     app.state.job_manager = job_manager
 
+    # Recover interrupted fetch-queue downloads. Any item left 'running' was cut
+    # off by a crash/restart (the running flag isn't durable); flip it back to
+    # 'pending' so the drain re-attempts it, then auto-start the drain if
+    # anything is pending so downloads resume without an admin re-triggering it.
+    requeued = await db.reset_running_fetch_items()
+    if requeued:
+        logger.warning(
+            "Re-queued %d interrupted fetch-queue item(s) after restart", requeued
+        )
+    if await db.count_fetch_queue_pending() > 0 and not job_manager.is_running(
+        "fetch_queue_drain"
+    ):
+        try:
+            await job_manager.run("fetch_queue_drain", triggered_by="startup-recovery")
+            logger.info("Auto-started fetch_queue_drain to resume pending downloads")
+        except Exception:  # noqa: BLE001 - best-effort; admin can re-trigger
+            logger.debug(
+                "Could not auto-start fetch_queue_drain at startup", exc_info=True
+            )
+
     # Cron-based job scheduler (persists schedules to job_schedules table)
     job_scheduler = JobScheduler(db, job_manager)
     # Seed a default schedule for the security-sensitive ban-reconcile job so it

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/kryten_webqueue/catalog/db/_fetch_queue.py

@@ -57,6 +57,36 @@ class _FetchQueueMixin:
         )
         await self._db.commit()
 
+    async def requeue_fetch_item(self, item_id: int) -> None:
+        """Return a single item to 'pending' (e.g. interrupted by shutdown).
+
+        Clears the run timestamps and any prior error so the drain re-attempts it
+        cleanly on the next pass.
+        """
+        await self._db.execute(
+            "UPDATE fetch_queue"
+            " SET status = 'pending', started_at = NULL, finished_at = NULL, error = NULL"
+            " WHERE id = ?",
+            [item_id],
+        )
+        await self._db.commit()
+
+    async def reset_running_fetch_items(self) -> int:
+        """Reset any 'running' items to 'pending'; return how many were reset.
+
+        Called at startup to recover from a crash or hard kill that left the
+        in-flight item marked 'running' forever (the running flag is process
+        state, not durable). Flipping it back to 'pending' lets the drain
+        re-attempt it — a fresh download, though a yt-dlp ``.part`` file left in
+        the work dir may let yt-dlp resume where it left off.
+        """
+        cursor = await self._db.execute(
+            "UPDATE fetch_queue SET status = 'pending', started_at = NULL"
+            " WHERE status = 'running'"
+        )
+        await self._db.commit()
+        return cursor.rowcount or 0
+
     async def get_fetch_queue(
         self, *, limit: int = 100, status: str | None = None
     ) -> list[dict]:

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/kryten_webqueue/config.py

@@ -51,6 +51,26 @@ class FetchUrlsConfig(BaseModel):
     token_cache_path: str = ""  # MSAL cache file, pre-seeded out-of-band
 
 
+class FetchQueueConfig(BaseModel):
+    """Settings for the persistent fetch-queue drain job.
+
+    The drain processes queued downloads one at a time and waits a randomized
+    cooldown *between* items so it doesn't hammer the source and trip bot
+    detection (the MediaCMS encoder is the real bottleneck anyway, so a long
+    gap costs little). Each wait is drawn uniformly from
+    ``cooldown_mean_minutes ± cooldown_jitter_minutes`` (clamped at >= 0).
+
+    These are re-read from the config file before every wait, so editing the
+    config and reloading retunes a *running* drain without a restart.
+    """
+
+    # Randomized inter-item cooldown, centered on ~42 min with jitter.
+    cooldown_mean_minutes: float = 42.0
+    cooldown_jitter_minutes: float = 8.0
+    # Set false to drain back-to-back (e.g. for a one-off bulk import).
+    cooldown_enabled: bool = True
+
+
 class PresenceRefundConfig(BaseModel):
     """Settings for presence-based cancel/refund of pending paid items.
 
@@ -168,9 +188,9 @@ class Config(BaseModel):
     # Jobs (optional; jobs whose config/deps are absent fail fast at run time)
     fetch_cookies_path: str = ""  # optional yt-dlp cookies for gated sources
     fetchurls: FetchUrlsConfig = FetchUrlsConfig()
+    fetch_queue: FetchQueueConfig = FetchQueueConfig()
     emote_rehost: EmoteRehostConfig = EmoteRehostConfig()
     motd: MOTDConfig = MOTDConfig()
-
     # Presence-based cancel/refund of pending paid items
     presence_refund: PresenceRefundConfig = PresenceRefundConfig()
 
@@ -213,6 +233,23 @@ class Config(BaseModel):
         cfg._source_path = Path(path)
         return cfg
 
+    def reload_fetch_queue(self) -> "FetchQueueConfig":
+        """Re-read just the ``fetch_queue`` section from the source file.
+
+        Enables live cooldown tuning: edit the config file and the running drain
+        picks up new pacing before its next wait — no restart needed. On any
+        error (no known source path, unreadable or invalid file) falls back to
+        the section loaded at startup so the drain never breaks on a bad edit.
+        """
+        if self._source_path is None:
+            return self.fetch_queue
+        try:
+            with open(self._source_path, encoding="utf-8") as f:
+                raw = json.load(f)
+            return FetchQueueConfig(**(raw.get("fetch_queue") or {}))
+        except Exception:  # noqa: BLE001 - never let a bad edit break the drain
+            return self.fetch_queue
+
     def save(self) -> None:
         """Persist the current config back to the file it was loaded from.
 

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/kryten_webqueue/jobs/tasks.py

@@ -15,6 +15,8 @@ import functools
 import importlib
 import json
 import logging
+import random
+import time
 
 from .manager import JobError
 
@@ -840,6 +842,41 @@ FETCH_QUEUE_ADD_SCHEMA = [
 FETCH_QUEUE_DRAIN_SCHEMA: list[dict] = []
 
 
+async def _fetch_queue_cooldown(ctx, *, processed: int, failed: int) -> None:
+    """Wait a randomized cooldown between fetch-queue downloads.
+
+    The wait is drawn uniformly from ``mean ± jitter`` minutes (clamped at >= 0)
+    so the drain doesn't hammer the source and trip bot detection. Settings are
+    re-read from the config file each call, so editing the config file (and
+    reloading) retunes a running drain without a restart. ``asyncio.sleep``
+    stays cancellable, so shutdown interrupts the wait cleanly.
+    """
+    fq = ctx.config.reload_fetch_queue()
+    if not fq.cooldown_enabled:
+        return
+    low = max(0.0, fq.cooldown_mean_minutes - fq.cooldown_jitter_minutes)
+    high = max(low, fq.cooldown_mean_minutes + fq.cooldown_jitter_minutes)
+    seconds = max(0.0, random.uniform(low, high) * 60.0)
+    if seconds <= 0:
+        return
+    await ctx.progress(
+        {
+            "status": "cooldown",
+            "processed": processed,
+            "failed": failed,
+            "cooldown_seconds": round(seconds),
+            "resume_epoch": round(time.time() + seconds),
+        }
+    )
+    logger.info(
+        "fetch_queue_drain: cooldown %.1f min before next item (processed=%d failed=%d)",
+        seconds / 60.0,
+        processed,
+        failed,
+    )
+    await asyncio.sleep(seconds)
+
+
 async def fetch_queue_add_job(params: dict, ctx) -> dict:
     """Add one or more URLs to the fetch queue and auto-start the drain if idle."""
     raw = (params.get("urls") or "").strip()
@@ -883,7 +920,17 @@ async def fetch_queue_add_job(params: dict, ctx) -> dict:
 
 
 async def fetch_queue_drain_job(params: dict, ctx) -> dict:
-    """Process all pending fetch-queue items one at a time."""
+    """Process all pending fetch-queue items one at a time.
+
+    Between items the drain waits a randomized cooldown (configurable via
+    ``fetch_queue`` in the config, centered on ~42 min with jitter) so downloads
+    don't hammer the source and trip bot detection — the MediaCMS encoder is the
+    real bottleneck anyway. Cooldown settings are re-read live before each wait.
+
+    An item interrupted by shutdown is re-queued (not failed) so it retries on
+    the next start; combined with the startup reset of orphaned 'running' items,
+    an interrupted download is always re-attempted from the top.
+    """
     processed = 0
     failed = 0
 
@@ -918,8 +965,11 @@ async def fetch_queue_drain_job(params: dict, ctx) -> dict:
             processed += 1
             logger.info("fetch_queue_drain: id=%d done", item["id"])
         except asyncio.CancelledError:
-            await ctx.db.finish_fetch_item(
-                item["id"], status="failed", error="cancelled"
+            # Interrupted by shutdown/cancel: re-queue so it retries on the next
+            # start rather than being lost as a permanent failure.
+            await ctx.db.requeue_fetch_item(item["id"])
+            logger.info(
+                "fetch_queue_drain: id=%d interrupted — re-queued for retry", item["id"]
             )
             raise
         except Exception as exc:  # noqa: BLE001
@@ -929,5 +979,9 @@ async def fetch_queue_drain_job(params: dict, ctx) -> dict:
             await ctx.db.finish_fetch_item(item["id"], status="failed", error=str(exc))
             failed += 1
 
+        # Space out downloads: cooldown before the next item, unless none remain.
+        if await ctx.db.count_fetch_queue_pending() > 0:
+            await _fetch_queue_cooldown(ctx, processed=processed, failed=failed)
+
     logger.info("fetch_queue_drain: done — processed=%d failed=%d", processed, failed)
     return {"processed": processed, "failed": failed}

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/kryten_webqueue/static/js/admin.js

@@ -438,6 +438,13 @@ async function showRunDetail(runId) {
         bodyHtml = `<p style="color:var(--warning)">\u23f3 Download in progress</p>
             <p>Current URL: <code style="word-break:break-all">${escapeHtml(d.url || '')}</code></p>
             <p>Done: <strong>${d.processed || 0}</strong> &nbsp; Failed: <strong>${d.failed || 0}</strong></p>`;
+    } else if (d && d.status === 'cooldown') {
+        // fetch_queue_drain anti-bot cooldown between items
+        const mins = d.cooldown_seconds ? Math.round(d.cooldown_seconds / 60) : 0;
+        const resume = d.resume_epoch ? new Date(d.resume_epoch * 1000).toLocaleTimeString() : '';
+        bodyHtml = `<p style="color:var(--warning)">\u23f8\ufe0f Cooling down before the next download</p>
+            <p>Waiting <strong>~${mins} min</strong>${resume ? ` (resumes ~${escapeHtml(resume)})` : ''}.</p>
+            <p>Done: <strong>${d.processed || 0}</strong> &nbsp; Failed: <strong>${d.failed || 0}</strong></p>`;
     } else {
         // Generic / legacy format
         const raw = typeof run.detail === 'string' ? run.detail : JSON.stringify(run.detail, null, 2);
@@ -597,6 +604,11 @@ function summarizeRunDetail(detail) {
             const host = (() => { try { return new URL(d.url).hostname; } catch (e) { return d.url.slice(0, 40); } })();
             return `\u23f3 ${host} (${d.processed || 0} done)`;
         }
+        // fetch_queue_drain cooldown between items
+        if (d.status === 'cooldown') {
+            const mins = d.cooldown_seconds ? Math.round(d.cooldown_seconds / 60) : 0;
+            return `\u23f8\ufe0f cooldown ~${mins} min (${d.processed || 0} done)`;
+        }
         if (parts.length) return parts.join(' · ');
     }
     return '';

{kryten_webqueue-0.42.0 → kryten_webqueue-0.43.0}/pyproject.toml

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

kryten_webqueue-0.43.0/tests/test_fetch_queue_pacing.py

@@ -0,0 +1,159 @@
+"""Fetch-queue drain pacing + interrupted-download recovery.
+
+Covers the anti-bot cooldown between drain items (config-driven, jittered,
+live-reloadable) and the crash/shutdown recovery paths that re-queue an
+interrupted download so it retries instead of being lost.
+"""
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from kryten_webqueue.catalog.db import Database
+from kryten_webqueue.config import Config, FetchQueueConfig
+from kryten_webqueue.jobs import tasks
+from kryten_webqueue.jobs.manager import JobContext
+
+
+@pytest.fixture
+async def db(tmp_path):
+    database = Database(str(tmp_path / "fetch_queue.db"))
+    await database.connect()
+    await database.run_migrations()
+    yield database
+    await database.close()
+
+
+def _ctx(db, config):
+    return JobContext(
+        db=db, api_gate=None, config=config, run_id=1, triggered_by="admin"
+    )
+
+
+# --- DB recovery helpers -------------------------------------------------------
+
+
+async def test_reset_running_fetch_items_requeues_orphans(db):
+    a = await db.enqueue_fetch(url="https://x/1")
+    b = await db.enqueue_fetch(url="https://x/2")
+    # Simulate a crash mid-download: one item stuck at 'running'.
+    await db.claim_next_fetch_item()  # claims oldest (a) → running
+
+    reset = await db.reset_running_fetch_items()
+    assert reset == 1
+    assert await db.count_fetch_queue_pending() == 2  # both pending again
+
+    # The reset item can be claimed again (fresh re-attempt).
+    claimed = await db.claim_next_fetch_item()
+    assert claimed["id"] == a
+    _ = b  # second item remains pending
+
+
+async def test_requeue_fetch_item_clears_error_and_timestamps(db):
+    item_id = await db.enqueue_fetch(url="https://x/1")
+    await db.claim_next_fetch_item()
+    await db.finish_fetch_item(item_id, status="failed", error="boom")
+
+    await db.requeue_fetch_item(item_id)
+    rows = await db.get_fetch_queue(limit=10)
+    row = next(r for r in rows if r["id"] == item_id)
+    assert row["status"] == "pending"
+    assert row["started_at"] is None
+    assert row["finished_at"] is None
+    assert row["error"] is None
+
+
+# --- live config reload --------------------------------------------------------
+
+
+def test_reload_fetch_queue_reads_current_file(tmp_path):
+    path = tmp_path / "config.json"
+    base = {
+        "secret_key": "x" * 16,
+        "api_gate_token": "t",
+        "mediacms_token": "t",
+        "fetch_queue": {"cooldown_mean_minutes": 10.0},
+    }
+    path.write_text(json.dumps(base), encoding="utf-8")
+    config = Config.from_file(path)
+    assert config.reload_fetch_queue().cooldown_mean_minutes == 10.0
+
+    # Edit the file on disk: a running drain must pick up the new value.
+    base["fetch_queue"]["cooldown_mean_minutes"] = 55.0
+    path.write_text(json.dumps(base), encoding="utf-8")
+    assert config.reload_fetch_queue().cooldown_mean_minutes == 55.0
+
+
+def test_reload_fetch_queue_falls_back_on_bad_file(tmp_path):
+    path = tmp_path / "config.json"
+    path.write_text(
+        json.dumps(
+            {"secret_key": "x" * 16, "api_gate_token": "t", "mediacms_token": "t"}
+        ),
+        encoding="utf-8",
+    )
+    config = Config.from_file(path)
+    # Corrupt the file; reload must fall back to the in-memory section, not raise.
+    path.write_text("{ not valid json", encoding="utf-8")
+    fq = config.reload_fetch_queue()
+    assert fq.cooldown_mean_minutes == config.fetch_queue.cooldown_mean_minutes
+
+
+# --- cooldown behaviour --------------------------------------------------------
+
+
+async def test_cooldown_disabled_does_not_sleep(db, monkeypatch):
+    slept: list[float] = []
+
+    async def _fake_sleep(seconds):
+        slept.append(seconds)
+
+    monkeypatch.setattr(tasks.asyncio, "sleep", _fake_sleep)
+    config = SimpleNamespace(
+        reload_fetch_queue=lambda: FetchQueueConfig(cooldown_enabled=False)
+    )
+    ctx = _ctx(db, config)
+    await tasks._fetch_queue_cooldown(ctx, processed=1, failed=0)
+    assert slept == []
+
+
+async def test_cooldown_sleeps_within_jitter_band(db, monkeypatch):
+    slept: list[float] = []
+
+    async def _fake_sleep(seconds):
+        slept.append(seconds)
+
+    monkeypatch.setattr(tasks.asyncio, "sleep", _fake_sleep)
+    fq = FetchQueueConfig(cooldown_mean_minutes=42.0, cooldown_jitter_minutes=8.0)
+    config = SimpleNamespace(reload_fetch_queue=lambda: fq)
+    ctx = _ctx(db, config)
+    await tasks._fetch_queue_cooldown(ctx, processed=2, failed=1)
+    assert len(slept) == 1
+    # Within [34, 50] minutes, expressed in seconds.
+    assert 34 * 60 <= slept[0] <= 50 * 60
+
+
+async def test_drain_cooldown_runs_between_items_only(db, monkeypatch):
+    await db.enqueue_fetch(url="https://x/1")
+    await db.enqueue_fetch(url="https://x/2")
+
+    cooldowns: list[int] = []
+
+    async def _fake_cooldown(ctx, *, processed, failed):
+        cooldowns.append(processed)
+
+    async def _fake_single_fetch(params, ctx):
+        return {"ok": True}
+
+    monkeypatch.setattr(tasks, "_fetch_queue_cooldown", _fake_cooldown)
+    monkeypatch.setattr(tasks, "_run_single_fetch", _fake_single_fetch)
+
+    fq = FetchQueueConfig()
+    ctx = _ctx(db, SimpleNamespace(reload_fetch_queue=lambda: fq))
+    result = await tasks.fetch_queue_drain_job({}, ctx)
+
+    assert result == {"processed": 2, "failed": 0}
+    # Two items → exactly one inter-item cooldown (after the first, before the
+    # second); none after the last item.
+    assert cooldowns == [1]