kryten-webqueue 0.24.0__tar.gz → 0.25.0__tar.gz

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [0.25.0] — 2026-06-22
+
+### Added
+
+- **Live web race view at `/race`.** The economy's racing game play-by-play moved off public chat (which flooded the channel) and onto a visual web view anyone can watch — no login required. A new public page animates the race in real time: each racer glides along its lane toward the finish, with live positions, odds, the betting countdown, per-colour bet totals, and a winner banner + payouts when it ends. A background `RacePoller` polls api-gate's `GET /economy/race` adaptively (fast while a race is live, backing off when idle) and pushes frames to spectators over a dedicated public `/ws/race` WebSocket; a newly-opened view is immediately shown a race already in progress. The race WebSocket carries only race frames (no user or queue data), and a “Race” link was added to the nav.
+
+[0.25.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.25.0
+
 ## [0.24.0] — 2026-06-21
 
 ### Added

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/PKG-INFO

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

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/kryten_webqueue/api_gate/client.py

@@ -47,6 +47,16 @@ class ApiGateClient:
     async def get_user(self, username: str) -> dict:
         return await self.get(f"/state/user/{username}")
 
+    # --- Economy: race view ---
+
+    async def get_race_state(self) -> dict:
+        """Live race snapshot for the web race view.
+
+        Returns ``{"active": bool, "frame": {...}|None}`` from api-gate's
+        ``GET /economy/race`` (which proxies the economy ``race.state`` command).
+        """
+        return await self.get("/economy/race")
+
     # --- Playlist CRUD ---
 
     async def playlist_add(self, media_type: str, media_id: str, *, position: str = "end", temp: bool = True) -> dict:

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/kryten_webqueue/app.py

@@ -16,6 +16,7 @@ from .jobs import JobManager
 from .catalog.images import CoverArtResolver
 from .queue.shadow import QueueShadow
 from .queue.poller import StatePoller
+from .queue.race_poller import RacePoller
 from .queue.presence import PresenceRefundMonitor
 from .promos.director import PromoDirector
 from .ws.manager import WebSocketManager
@@ -114,6 +115,13 @@ async def lifespan(app: FastAPI):
     ws_manager = WebSocketManager()
     app.state.ws_manager = ws_manager
 
+    # Public race-view WebSocket manager (anonymous spectators) + poller.
+    race_ws_manager = WebSocketManager()
+    app.state.race_ws_manager = race_ws_manager
+    race_poller = RacePoller(api_gate=api_gate, ws_manager=race_ws_manager)
+    await race_poller.start()
+    app.state.race_poller = race_poller
+
     # Queue shadow
     shadow = QueueShadow(db)
     await shadow.load_from_db()
@@ -218,6 +226,7 @@ async def lifespan(app: FastAPI):
     for task in bg_tasks:
         task.cancel()
     await poller.stop()
+    await race_poller.stop()
     await scheduler.stop()
     await presence_monitor.stop()
     await catalog_sync.close()

kryten_webqueue-0.25.0/kryten_webqueue/queue/race_poller.py

@@ -0,0 +1,91 @@
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class RacePoller:
+    """Polls api-gate's race view and pushes frames to race spectators.
+
+    Adaptive cadence: while a race is live it polls quickly (``active_interval``)
+    so the web view animates smoothly; when idle it backs off
+    (``idle_interval``). The latest frame is cached so a newly-connected
+    spectator can be shown the race already in progress.
+
+    Broadcast messages (to the public race WebSocket manager):
+    - ``{"type": "race_frame", "data": <frame>}`` each poll while a race is live.
+    - ``{"type": "race_clear"}`` once, when a race ends and the view goes idle.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_gate,
+        ws_manager,
+        active_interval: float = 1.5,
+        idle_interval: float = 4.0,
+    ):
+        self._api_gate = api_gate
+        self._ws_manager = ws_manager
+        self._active_interval = active_interval
+        self._idle_interval = idle_interval
+        self._task: asyncio.Task | None = None
+        self._last_frame: dict | None = None
+
+    @property
+    def last_frame(self) -> dict | None:
+        """The most recent live frame, or None when no race is active."""
+        return self._last_frame
+
+    async def start(self):
+        self._task = asyncio.create_task(self._loop())
+        logger.info(
+            "RacePoller started (active=%.1fs idle=%.1fs)",
+            self._active_interval, self._idle_interval,
+        )
+
+    async def stop(self):
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            logger.info("RacePoller stopped")
+
+    async def _poll_once(self) -> float:
+        """Run one poll; broadcast as needed. Returns the next sleep interval."""
+        try:
+            result = await self._api_gate.get_race_state()
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.debug("Race poll error: %s", e)
+            # Treat an error like "idle" but don't spuriously clear an active
+            # view — just back off and retry.
+            return self._idle_interval
+
+        active = bool(result.get("active")) and result.get("frame") is not None
+        if active:
+            self._last_frame = result["frame"]
+            await self._ws_manager.broadcast(
+                {"type": "race_frame", "data": self._last_frame}
+            )
+            return self._active_interval
+
+        # Not active. If we were showing a race, tell spectators to clear once.
+        if self._last_frame is not None:
+            self._last_frame = None
+            await self._ws_manager.broadcast({"type": "race_clear"})
+        return self._idle_interval
+
+    async def _loop(self):
+        while True:
+            try:
+                delay = await self._poll_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                logger.warning("RacePoller loop error: %s", e)
+                delay = self._idle_interval
+            await asyncio.sleep(delay)

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/kryten_webqueue/routes/pages.py

@@ -71,6 +71,13 @@ async def login_page(request: Request):
     return templates.TemplateResponse(request, "auth/login.html", {"user": None})
 
 
+@router.get("/race", response_class=HTMLResponse)
+async def race_view(request: Request):
+    """Public race spectator view — no auth. Streams frames over /ws/race."""
+    user = _get_user_or_none(request)
+    return templates.TemplateResponse(request, "race.html", {"user": user})
+
+
 @router.get("/catalog/browse", response_class=HTMLResponse)
 async def catalog_browse_page(request: Request, category: str | None = None,
                               tag: str | None = None, page: int = 1,

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/kryten_webqueue/templates/base.html

@@ -34,6 +34,7 @@
         <div class="nav-links">
             <a href="/catalog/browse">Browse</a>
             <a href="/queue">Queue</a>
+            <a href="/race">Race</a>
             {% if user %}
                 <a href="/user/dashboard">{{ user.username }}</a>
                 {% if user.rank >= 3 %}

kryten_webqueue-0.25.0/kryten_webqueue/templates/race.html

@@ -0,0 +1,223 @@
+{% extends "base.html" %}
+{% block title %}Live Race{% endblock %}
+{% block body_class %}race-page{% endblock %}
+
+{% block head %}
+<style>
+  .race-wrap { max-width: 900px; margin: 0 auto; }
+  .race-head { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; flex-wrap: wrap; }
+  .race-head h1 { font-family: 'Sora', sans-serif; margin: 0; }
+  .race-status { font-weight: 600; opacity: 0.85; }
+  .race-status .pill { padding: 0.15rem 0.6rem; border-radius: 999px; font-size: 0.8rem; }
+  .pill-betting { background: #1f6feb33; color: #79c0ff; }
+  .pill-racing  { background: #2ea04333; color: #7ee787; }
+  .pill-finished{ background: #d2992233; color: #f0c674; }
+  .pill-idle    { background: #6e768166; color: #c9d1d9; }
+
+  .race-track { margin: 1.25rem 0; display: flex; flex-direction: column; gap: 0.55rem; }
+  .lane {
+    position: relative; display: grid; grid-template-columns: 2.4rem 1fr auto;
+    align-items: center; gap: 0.6rem; padding: 0.35rem 0.5rem; border-radius: 10px;
+    background: #11141a; border: 1px solid #232a33;
+  }
+  .lane.win { border-color: #f0c674; box-shadow: 0 0 0 1px #f0c67455, 0 0 18px #f0c67433; }
+  .lane-pos { font-weight: 700; text-align: center; opacity: 0.8; font-variant-numeric: tabular-nums; }
+  .lane-rail { position: relative; height: 26px; background: #0c0e12; border-radius: 6px; overflow: hidden; }
+  .lane-fill {
+    position: absolute; inset: 0 auto 0 0; width: 0%;
+    background: linear-gradient(90deg, #1f6feb44, #1f6feb22);
+    transition: width 1.4s linear; border-right: 2px solid #ffffff22;
+  }
+  .lane-runner {
+    position: absolute; top: 50%; left: 0; transform: translate(-50%, -50%);
+    font-size: 1.15rem; transition: left 1.4s linear; will-change: left;
+    text-shadow: 0 1px 2px #000a;
+  }
+  .lane-meta { display: flex; align-items: baseline; gap: 0.5rem; }
+  .lane-name { font-weight: 600; }
+  .lane-odds { font-size: 0.8rem; opacity: 0.7; font-variant-numeric: tabular-nums; }
+  .lane-trait { font-size: 0.72rem; opacity: 0.6; }
+  .lane-amt { font-size: 0.75rem; opacity: 0.7; font-variant-numeric: tabular-nums; }
+
+  .race-side { display: flex; gap: 1.5rem; flex-wrap: wrap; font-variant-numeric: tabular-nums; }
+  .race-side .stat b { font-size: 1.1rem; }
+  .race-winner { margin: 1rem 0; padding: 0.75rem 1rem; border-radius: 10px;
+    background: #d2992218; border: 1px solid #f0c67455; }
+  .race-winner h2 { margin: 0 0 0.35rem; font-family: 'Sora', sans-serif; }
+  .race-payouts { margin: 0.25rem 0 0; padding-left: 1.1rem; }
+  .race-idle { text-align: center; opacity: 0.7; padding: 3rem 1rem; }
+  .race-finish-flag { position: absolute; right: 4px; top: 50%; transform: translateY(-50%);
+    font-size: 0.95rem; opacity: 0.5; }
+</style>
+{% endblock %}
+
+{% block content %}
+<div class="race-wrap">
+  <div class="race-head">
+    <h1>🏁 Live Race</h1>
+    <div class="race-status" id="race-status"><span class="pill pill-idle">Connecting…</span></div>
+  </div>
+
+  <div id="race-body">
+    <div class="race-idle" id="race-idle">Waiting for the next race…</div>
+    <div class="race-track" id="race-track" hidden></div>
+    <div class="race-side" id="race-side" hidden></div>
+    <div class="race-winner" id="race-winner" hidden></div>
+  </div>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+(function () {
+  const statusEl = document.getElementById('race-status');
+  const idleEl   = document.getElementById('race-idle');
+  const trackEl  = document.getElementById('race-track');
+  const sideEl   = document.getElementById('race-side');
+  const winnerEl = document.getElementById('race-winner');
+
+  const lanes = new Map();   // color -> { row, fill, runner, pos, amt }
+  let laneSig = '';          // signature of the current racer set (to detect changes)
+
+  function esc(s) {
+    return String(s).replace(/[&<>"']/g, c => (
+      { '&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;' }[c]
+    ));
+  }
+
+  function setStatus(kind, text) {
+    statusEl.innerHTML = '<span class="pill pill-' + kind + '">' + esc(text) + '</span>';
+  }
+
+  function buildLanes(racers) {
+    trackEl.innerHTML = '';
+    lanes.clear();
+    for (const r of racers) {
+      const row = document.createElement('div');
+      row.className = 'lane';
+      row.innerHTML =
+        '<div class="lane-pos"></div>' +
+        '<div class="lane-rail">' +
+          '<div class="lane-fill"></div>' +
+          '<span class="lane-runner">' + esc(r.emoji || '🏃') + '</span>' +
+          '<span class="race-finish-flag">🏁</span>' +
+        '</div>' +
+        '<div class="lane-meta">' +
+          '<span class="lane-name">' + esc(r.color) + '</span>' +
+          '<span class="lane-odds">' + esc(r.odds || '') + '</span>' +
+          (r.trait ? '<span class="lane-trait">' + esc(r.trait) + '</span>' : '') +
+          '<span class="lane-amt"></span>' +
+        '</div>';
+      trackEl.appendChild(row);
+      lanes.set(r.color, {
+        row,
+        fill: row.querySelector('.lane-fill'),
+        runner: row.querySelector('.lane-runner'),
+        pos: row.querySelector('.lane-pos'),
+        amt: row.querySelector('.lane-amt'),
+      });
+    }
+  }
+
+  function render(frame) {
+    idleEl.hidden = true;
+    trackEl.hidden = false;
+    sideEl.hidden = false;
+
+    // Rebuild lanes only when the racer set changes (keeps CSS transitions smooth).
+    const sig = frame.racers.map(r => r.color).join('|');
+    if (sig !== laneSig) { buildLanes(frame.racers); laneSig = sig; }
+
+    const finished = frame.phase === 'finished';
+    const winnerColor = frame.winner && frame.winner.color;
+    const betsByColor = frame.bets_by_color || {};
+
+    for (const r of frame.racers) {
+      const lane = lanes.get(r.color);
+      if (!lane) continue;
+      const pct = Math.max(0, Math.min(100, r.pct || 0));
+      lane.fill.style.width = pct + '%';
+      lane.runner.style.left = pct + '%';
+      lane.pos.textContent = r.position ? ('#' + r.position) : '';
+      const bet = betsByColor[r.color];
+      lane.amt.textContent = bet ? ('💰 ' + bet.amount.toLocaleString()) : '';
+      lane.row.classList.toggle('win', finished && r.color === winnerColor);
+    }
+
+    // Status line
+    if (frame.phase === 'betting') {
+      setStatus('betting', 'Betting open — ' + (frame.betting_closes_in || 0) + 's left');
+    } else if (frame.phase === 'racing') {
+      setStatus('racing', 'Racing! Leader: ' + (frame.leader || '—'));
+    } else if (finished) {
+      setStatus('finished', 'Finished');
+    }
+
+    // Side stats
+    const sym = frame.symbol || '';
+    sideEl.innerHTML =
+      '<div class="stat">Pool <b>' + (frame.pool || 0).toLocaleString() + ' ' + esc(sym) + '</b></div>' +
+      '<div class="stat">Bettors <b>' + (frame.bettor_count || 0) + '</b></div>' +
+      (frame.phase === 'betting'
+        ? '<div class="stat">Min bet <b>' + (frame.min_bet || 0).toLocaleString() + ' ' + esc(sym) + '</b></div>'
+        : '');
+
+    // Winner banner + payouts
+    if (finished && frame.winner) {
+      const payouts = (frame.payouts || []).slice(0, 5)
+        .map(p => '<li>' + esc(p.username) + ' <b>+' + (p.net || 0).toLocaleString() + ' ' + esc(sym) + '</b></li>')
+        .join('');
+      winnerEl.hidden = false;
+      winnerEl.innerHTML =
+        '<h2>' + esc(frame.winner.emoji || '🏆') + ' ' + esc(frame.winner.color) + ' wins!</h2>' +
+        (payouts ? '<ul class="race-payouts">' + payouts + '</ul>'
+                 : '<div>No winning bets this race.</div>');
+    } else {
+      winnerEl.hidden = true;
+    }
+  }
+
+  function showIdle() {
+    laneSig = '';
+    lanes.clear();
+    trackEl.hidden = true;
+    sideEl.hidden = true;
+    winnerEl.hidden = true;
+    idleEl.hidden = false;
+    setStatus('idle', 'No race running');
+  }
+
+  // ── WebSocket with auto-reconnect ──────────────────────────
+  let ws = null, retry = 0, pingTimer = null;
+
+  function connect() {
+    const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+    ws = new WebSocket(proto + '://' + location.host + '/ws/race');
+
+    ws.onopen = () => {
+      retry = 0;
+      setStatus('idle', 'Connected');
+      clearInterval(pingTimer);
+      pingTimer = setInterval(() => {
+        try { ws.send(JSON.stringify({ type: 'ping' })); } catch (e) {}
+      }, 25000);
+    };
+    ws.onmessage = (ev) => {
+      let m; try { m = JSON.parse(ev.data); } catch (e) { return; }
+      if (m.type === 'race_frame') render(m.data);
+      else if (m.type === 'race_clear') showIdle();
+    };
+    ws.onclose = () => {
+      clearInterval(pingTimer);
+      setStatus('idle', 'Reconnecting…');
+      retry = Math.min(retry + 1, 6);
+      setTimeout(connect, 500 * retry);
+    };
+    ws.onerror = () => { try { ws.close(); } catch (e) {} };
+  }
+
+  showIdle();
+  connect();
+})();
+</script>
+{% endblock %}

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/kryten_webqueue/ws/handler.py

@@ -1,5 +1,6 @@
 import json
 import logging
+import uuid
 from fastapi import APIRouter, WebSocket, WebSocketDisconnect
 import jwt
 
@@ -57,3 +58,47 @@ async def websocket_endpoint(ws: WebSocket):
         logger.warning(f"WS error for {username}: {e}")
     finally:
         await manager.disconnect(username)
+
+
+@router.websocket("/ws/race")
+async def race_websocket_endpoint(ws: WebSocket):
+    """Public race-view WebSocket. No authentication — streams only race frames.
+
+    Anyone watching the channel can open the race view without logging into the
+    queue dashboard. Connections are anonymous (keyed by a random id) and only
+    ever receive race frames (no user/queue data), so this is safe to expose.
+    """
+    await ws.accept()
+    manager = ws.app.state.race_ws_manager
+    poller = getattr(ws.app.state, "race_poller", None)
+    conn_id = uuid.uuid4().hex
+
+    await manager.connect(conn_id, ws)
+
+    # Show a race that's already in progress to a late-joining spectator.
+    try:
+        if poller is not None and poller.last_frame is not None:
+            await ws.send_text(
+                json.dumps({"type": "race_frame", "data": poller.last_frame})
+            )
+    except Exception:
+        await manager.disconnect(conn_id)
+        return
+
+    # Keep the socket open; ignore inbound except ping/pong.
+    try:
+        while True:
+            text = await ws.receive_text()
+            try:
+                msg = json.loads(text)
+            except json.JSONDecodeError:
+                continue
+            if msg.get("type") == "ping":
+                await ws.send_text(json.dumps({"type": "pong"}))
+    except WebSocketDisconnect:
+        pass
+    except Exception as e:
+        logger.debug(f"Race WS error: {e}")
+    finally:
+        await manager.disconnect(conn_id)
+

{kryten_webqueue-0.24.0 → kryten_webqueue-0.25.0}/pyproject.toml

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

kryten_webqueue-0.25.0/tests/test_race_poller.py

@@ -0,0 +1,102 @@
+"""RacePoller — adaptive race-frame polling + WebSocket broadcast.
+
+Drives ``_poll_once()`` directly (the loop is just sleep + retry) to assert the
+broadcast/cache/back-off behaviour without real timers or sockets.
+"""
+
+from kryten_webqueue.queue.race_poller import RacePoller
+
+
+class _FakeApiGate:
+    def __init__(self, results):
+        # results: list of dicts to return, or Exception instances to raise.
+        self._results = list(results)
+        self.calls = 0
+
+    async def get_race_state(self):
+        self.calls += 1
+        val = self._results[min(self.calls - 1, len(self._results) - 1)]
+        if isinstance(val, Exception):
+            raise val
+        return val
+
+
+class _FakeWs:
+    def __init__(self):
+        self.messages = []
+
+    async def broadcast(self, message):
+        self.messages.append(message)
+
+
+async def test_active_frame_broadcasts_and_caches():
+    ws = _FakeWs()
+    frame = {"phase": "racing", "tick": 1}
+    poller = RacePoller(
+        api_gate=_FakeApiGate([{"active": True, "frame": frame}]),
+        ws_manager=ws, active_interval=1.5, idle_interval=4.0,
+    )
+    delay = await poller._poll_once()
+    assert delay == 1.5
+    assert poller.last_frame == frame
+    assert ws.messages == [{"type": "race_frame", "data": frame}]
+
+
+async def test_idle_without_prior_does_not_broadcast():
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([{"active": False, "frame": None}]),
+        ws_manager=ws,
+    )
+    delay = await poller._poll_once()
+    assert delay == poller._idle_interval
+    assert ws.messages == []
+    assert poller.last_frame is None
+
+
+async def test_clear_broadcast_once_after_active():
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([
+            {"active": True, "frame": {"phase": "racing"}},
+            {"active": False, "frame": None},
+            {"active": False, "frame": None},
+        ]),
+        ws_manager=ws,
+    )
+    await poller._poll_once()   # active
+    await poller._poll_once()   # transitions to idle → one clear
+    await poller._poll_once()   # still idle → no repeat
+    assert [m["type"] for m in ws.messages] == ["race_frame", "race_clear"]
+    assert poller.last_frame is None
+
+
+async def test_active_false_with_stale_frame_is_idle():
+    """``active: true`` but a null frame is treated as no race (defensive)."""
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([{"active": True, "frame": None}]),
+        ws_manager=ws,
+    )
+    delay = await poller._poll_once()
+    assert delay == poller._idle_interval
+    assert ws.messages == []
+    assert poller.last_frame is None
+
+
+async def test_error_backs_off_without_clearing():
+    ws = _FakeWs()
+    poller = RacePoller(
+        api_gate=_FakeApiGate([
+            {"active": True, "frame": {"phase": "racing"}},
+            RuntimeError("nats hiccup"),
+        ]),
+        ws_manager=ws,
+    )
+    await poller._poll_once()            # active → caches frame
+    delay = await poller._poll_once()    # error
+    assert delay == poller._idle_interval
+    # No spurious clear; the cached frame is retained so a reconnecting
+    # spectator still sees the race in progress.
+    assert poller.last_frame == {"phase": "racing"}
+    assert [m["type"] for m in ws.messages] == ["race_frame"]