baqueue 0.1.0__py3-none-any.whl

baqueue/dashboard/api.py

@@ -0,0 +1,193 @@
+"""REST API endpoints for the BaQueue dashboard."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from baqueue.drivers.base import BaseDriver
+from baqueue.serializer import _now_ts
+
+
+class DashboardAPI:
+    """Provides data for the dashboard REST endpoints."""
+
+    def __init__(self, driver: BaseDriver):
+        self.driver = driver
+        self._supervisor_stats: list[dict[str, Any]] = []
+
+    def set_supervisor_stats(self, stats: list[dict[str, Any]]) -> None:
+        self._supervisor_stats = stats
+
+    async def overview(self) -> dict[str, Any]:
+        queues = await self.driver.queues()
+        metrics = await self.driver.get_metrics()
+        now = _now_ts()
+        rate_window_from = now - 60
+
+        total_pending = 0
+        total_processing = 0
+        total_completed = 0
+        total_failed = 0
+        queue_details = []
+
+        for q in queues:
+            m = metrics.get(q, {})
+            pending = m.get("pending", 0)
+            processing = m.get("processing", 0)
+            completed = m.get("completed", 0)
+            failed = m.get("failed", 0)
+
+            total_pending += pending
+            total_processing += processing
+            total_completed += completed
+            total_failed += failed
+
+            q_pending_rate = await self.driver.count_jobs(queue=q, created_from=rate_window_from)
+            q_throughput = await self.driver.recent_throughput(seconds=60, queue=q)
+
+            queue_details.append({
+                "name": q,
+                "pending": pending,
+                "processing": processing,
+                "completed": completed,
+                "failed": failed,
+                "rates": {
+                    "pending_per_min": q_pending_rate,
+                    "processing_per_min": q_throughput.get("processing", 0),
+                    "completed_per_min": q_throughput.get("completed", 0),
+                    "failed_per_min": q_throughput.get("failed", 0),
+                },
+            })
+
+        dispatch_rate = await self.driver.count_jobs(created_from=rate_window_from)
+        throughput = await self.driver.recent_throughput(seconds=60)
+        supervisors = await self.driver.get_supervisor_stats()
+        if not supervisors:
+            supervisors = self._supervisor_stats
+
+        return {
+            "totals": {
+                "pending": total_pending,
+                "processing": total_processing,
+                "completed": total_completed,
+                "failed": total_failed,
+                "queues": len(queues),
+                "total": total_pending + total_processing + total_completed + total_failed,
+            },
+            "rates": {
+                "pending_per_min": dispatch_rate,
+                "processing_per_min": throughput.get("processing", 0),
+                "completed_per_min": throughput.get("completed", 0),
+                "failed_per_min": throughput.get("failed", 0),
+            },
+            "queues": queue_details,
+            "supervisors": supervisors,
+            "timestamp": now,
+        }
+
+    async def queue_detail(self, queue: str) -> dict[str, Any]:
+        metrics = await self.driver.get_metrics(queue)
+        size = await self.driver.size(queue)
+        m = metrics.get(queue, {})
+        return {
+            "name": queue,
+            "size": size,
+            "metrics": m,
+        }
+
+    async def jobs_list(
+        self,
+        queue: str | None = None,
+        status: str | None = None,
+        tag: str | None = None,
+        batch_id: str | None = None,
+        page: int = 1,
+        per_page: int = 25,
+        created_from: float | None = None,
+        created_to: float | None = None,
+    ) -> dict[str, Any]:
+        offset = (page - 1) * per_page
+        jobs = await self.driver.get_jobs(
+            queue=queue, status=status, tag=tag, batch_id=batch_id,
+            offset=offset, limit=per_page,
+            created_from=created_from, created_to=created_to,
+        )
+        total = await self.driver.count_jobs(
+            queue=queue, status=status,
+            created_from=created_from, created_to=created_to,
+        )
+        return {
+            "jobs": [j.to_dict() for j in jobs],
+            "page": page,
+            "per_page": per_page,
+            "count": len(jobs),
+            "total": total,
+        }
+
+    async def job_detail(self, job_id: str) -> dict[str, Any] | None:
+        job = await self.driver.get_job(job_id)
+        return job.to_dict() if job else None
+
+    async def retry_job(self, job_id: str) -> bool:
+        job = await self.driver.get_job(job_id)
+        if not job or job.status != "failed":
+            return False
+        await self.driver.release(job, delay=0)
+        return True
+
+    async def retry_failed_jobs(
+        self,
+        queue: str | None = None,
+        tag: str | None = None,
+        created_from: float | None = None,
+        created_to: float | None = None,
+    ) -> int:
+        """Retry all failed jobs matching the optional filters. Returns count."""
+        from baqueue.queue import Queue
+        return await Queue.retry_failed(
+            queue=queue, tag=tag,
+            created_from=created_from, created_to=created_to,
+        )
+
+    async def delete_job(self, job_id: str) -> bool:
+        await self.driver.delete(job_id)
+        return True
+
+    async def batch_detail(self, batch_id: str) -> dict[str, Any] | None:
+        return await self.driver.get_batch(batch_id)
+
+    async def prune_jobs(
+        self,
+        status: str | None = None,
+        tag: str | None = None,
+        hours: float | None = None,
+    ) -> int:
+        older_than = hours * 3600 if hours else None
+        return await self.driver.prune(status=status, tag=tag, older_than_seconds=older_than)
+
+    async def metrics_snapshot(self) -> dict[str, Any]:
+        return await self.driver.get_metrics()
+
+    async def supervisors_snapshot(self) -> list[dict[str, Any]]:
+        data = await self.driver.get_supervisor_stats()
+        if data:
+            return data
+        return self._supervisor_stats
+
+    async def stats(self, created_from: float | None = None, created_to: float | None = None) -> dict[str, Any]:
+        """Aggregate statistics for the stats panel."""
+        queues = await self.driver.queues()
+        result: dict[str, Any] = {"queues": {}, "statuses": {}}
+
+        for st in ("pending", "processing", "completed", "failed"):
+            result["statuses"][st] = await self.driver.count_jobs(status=st, created_from=created_from, created_to=created_to)
+
+        for q in queues:
+            q_stats: dict[str, int] = {}
+            for st in ("pending", "processing", "completed", "failed"):
+                q_stats[st] = await self.driver.count_jobs(queue=q, status=st, created_from=created_from, created_to=created_to)
+            q_stats["total"] = sum(q_stats.values())
+            result["queues"][q] = q_stats
+
+        result["total"] = sum(result["statuses"].values())
+        return result

baqueue/dashboard/server.py

@@ -0,0 +1,263 @@
+"""FastAPI server for the BaQueue monitoring dashboard.
+
+NOTE: Do NOT use `from __future__ import annotations` in this module.
+FastAPI relies on runtime type inspection for WebSocket parameter resolution,
+which breaks with PEP 563 deferred annotations.
+"""
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Optional
+
+from baqueue.config import BaQueueConfig
+from baqueue.dashboard.api import DashboardAPI
+from baqueue.drivers.base import BaseDriver
+
+logger = logging.getLogger("baqueue.dashboard")
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+OVERVIEW_BROADCAST_INTERVAL = 2.0
+JOBS_PUSH_INTERVAL = 1.5
+
+
+def create_app(driver: BaseDriver, config: Optional[BaQueueConfig] = None) -> Any:
+    """Create and return a FastAPI application for the dashboard."""
+    from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Query
+    from fastapi.responses import JSONResponse, FileResponse
+
+    api = DashboardAPI(driver)
+    connected_ws: list[WebSocket] = []
+
+    async def _broadcast_loop() -> None:
+        """One overview() per interval, fanned out to every connected WS.
+        Replaces N independent driver queries when N tabs are open."""
+        while True:
+            try:
+                await asyncio.sleep(OVERVIEW_BROADCAST_INTERVAL)
+                if not connected_ws:
+                    continue
+                data = await api.overview()
+                stale: list[WebSocket] = []
+                for ws in list(connected_ws):
+                    try:
+                        await ws.send_json(data)
+                    except Exception:
+                        stale.append(ws)
+                for ws in stale:
+                    if ws in connected_ws:
+                        connected_ws.remove(ws)
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("Error in overview broadcast loop")
+
+    @asynccontextmanager
+    async def lifespan(_app):
+        task = asyncio.create_task(_broadcast_loop())
+        try:
+            yield
+        finally:
+            task.cancel()
+            try:
+                await task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+    app = FastAPI(title="BaQueue Dashboard", version="0.2.0", lifespan=lifespan)
+
+    # ── Static files ────────────────────────────────────────────
+
+    @app.get("/")
+    async def index():
+        return FileResponse(STATIC_DIR / "index.html")
+
+    @app.get("/app.js")
+    async def app_js():
+        return FileResponse(STATIC_DIR / "app.js", media_type="application/javascript")
+
+    @app.get("/style.css")
+    async def app_css():
+        return FileResponse(STATIC_DIR / "style.css", media_type="text/css")
+
+    # ── REST API ────────────────────────────────────────────────
+
+    @app.get("/api/overview")
+    async def get_overview():
+        data = await api.overview()
+        return JSONResponse(data)
+
+    @app.get("/api/stats")
+    async def get_stats(
+        created_from: Optional[float] = Query(None),
+        created_to: Optional[float] = Query(None),
+    ):
+        data = await api.stats(created_from=created_from, created_to=created_to)
+        return JSONResponse(data)
+
+    @app.get("/api/queues")
+    async def get_queues():
+        queues = await driver.queues()
+        return JSONResponse({"queues": queues})
+
+    @app.get("/api/queues/{queue}")
+    async def get_queue(queue: str):
+        data = await api.queue_detail(queue)
+        return JSONResponse(data)
+
+    @app.get("/api/jobs")
+    async def get_jobs(
+        queue: Optional[str] = Query(None),
+        status: Optional[str] = Query(None),
+        tag: Optional[str] = Query(None),
+        batch_id: Optional[str] = Query(None),
+        page: int = Query(1),
+        per_page: int = Query(25),
+        created_from: Optional[float] = Query(None),
+        created_to: Optional[float] = Query(None),
+    ):
+        data = await api.jobs_list(
+            queue=queue, status=status, tag=tag,
+            batch_id=batch_id, page=page, per_page=per_page,
+            created_from=created_from, created_to=created_to,
+        )
+        return JSONResponse(data)
+
+    @app.get("/api/jobs/{job_id}")
+    async def get_job(job_id: str):
+        data = await api.job_detail(job_id)
+        if data is None:
+            return JSONResponse({"error": "Job not found"}, status_code=404)
+        return JSONResponse(data)
+
+    @app.post("/api/jobs/retry-failed")
+    async def retry_failed(
+        queue: Optional[str] = Query(None),
+        tag: Optional[str] = Query(None),
+        created_from: Optional[float] = Query(None),
+        created_to: Optional[float] = Query(None),
+    ):
+        count = await api.retry_failed_jobs(
+            queue=queue, tag=tag,
+            created_from=created_from, created_to=created_to,
+        )
+        return JSONResponse({"retried": count})
+
+    @app.post("/api/jobs/{job_id}/retry")
+    async def retry_job(job_id: str):
+        ok = await api.retry_job(job_id)
+        return JSONResponse({"success": ok})
+
+    @app.delete("/api/jobs/{job_id}")
+    async def delete_job(job_id: str):
+        ok = await api.delete_job(job_id)
+        return JSONResponse({"success": ok})
+
+    @app.get("/api/batches/{batch_id}")
+    async def get_batch(batch_id: str):
+        data = await api.batch_detail(batch_id)
+        if data is None:
+            return JSONResponse({"error": "Batch not found"}, status_code=404)
+        return JSONResponse(data)
+
+    @app.post("/api/prune")
+    async def prune_jobs(
+        status: Optional[str] = Query(None),
+        tag: Optional[str] = Query(None),
+        hours: Optional[float] = Query(None),
+    ):
+        count = await api.prune_jobs(status=status, tag=tag, hours=hours)
+        return JSONResponse({"pruned": count})
+
+    @app.get("/api/metrics")
+    async def get_metrics():
+        data = await api.metrics_snapshot()
+        return JSONResponse(data)
+
+    @app.get("/api/supervisors")
+    async def get_supervisors():
+        data = await api.supervisors_snapshot()
+        return JSONResponse({"supervisors": data})
+
+    # ── WebSocket ───────────────────────────────────────────────
+
+    @app.websocket("/ws")
+    async def websocket_endpoint(ws: WebSocket):
+        await ws.accept()
+        connected_ws.append(ws)
+        try:
+            data = await api.overview()
+            await ws.send_json(data)
+            while True:
+                # Keep the connection alive; the broadcaster pushes updates.
+                await ws.receive_text()
+        except WebSocketDisconnect:
+            pass
+        except Exception:
+            pass
+        finally:
+            if ws in connected_ws:
+                connected_ws.remove(ws)
+
+    @app.websocket("/ws/jobs")
+    async def jobs_websocket(ws: WebSocket):
+        """Per-connection jobs feed. Subscriber sends a {"type":"subscribe","filters":{...}}
+        message; server pushes filtered jobs_list snapshots on a tick until disconnect."""
+        await ws.accept()
+        filters: dict[str, Any] = {
+            "queue": None, "status": None, "tag": None, "batch_id": None,
+            "page": 1, "per_page": 25,
+            "created_from": None, "created_to": None,
+        }
+        push_lock = asyncio.Lock()
+
+        async def push_snapshot() -> bool:
+            async with push_lock:
+                try:
+                    data = await api.jobs_list(**filters)
+                    await ws.send_json(data)
+                    return True
+                except WebSocketDisconnect:
+                    return False
+                except Exception:
+                    logger.exception("ws/jobs push failed")
+                    return True
+
+        async def push_loop() -> None:
+            while True:
+                await asyncio.sleep(JOBS_PUSH_INTERVAL)
+                if not await push_snapshot():
+                    return
+
+        push_task = asyncio.create_task(push_loop())
+        try:
+            await push_snapshot()
+            while True:
+                msg = await ws.receive_json()
+                if msg.get("type") == "subscribe":
+                    incoming = msg.get("filters") or {}
+                    for k in filters:
+                        if k not in incoming:
+                            continue
+                        v = incoming[k]
+                        if k in ("page", "per_page"):
+                            filters[k] = int(v) if v is not None else filters[k]
+                        elif k in ("created_from", "created_to"):
+                            filters[k] = float(v) if v not in (None, "") else None
+                        else:
+                            filters[k] = v if v not in (None, "") else None
+                    await push_snapshot()
+        except WebSocketDisconnect:
+            pass
+        except Exception:
+            pass
+        finally:
+            push_task.cancel()
+            try:
+                await push_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+    return app