nonebot-plugin-ruok 0.2.0__py3-none-any.whl

nonebot_plugin_ruok/api.py

@@ -0,0 +1,348 @@
+"""FastAPI routes for RUOK — health, session, module management."""
+
+from __future__ import annotations
+
+import time
+import asyncio
+import secrets
+from typing import Any
+from pathlib import Path
+
+from fastapi import Query, Header, Depends, Request, APIRouter, HTTPException
+from fastapi.responses import JSONResponse
+
+from .config import ScopedConfig
+from .protocol import ReporterInfo, ModuleDefinition
+from .collector import (
+    MetricsStore,
+    SessionPluginValidationError,
+    SessionUpdateValidationError,
+    get_module,
+    get_session,
+    list_modules,
+    delete_module,
+    link_sessions,
+    list_sessions,
+    upsert_module,
+    create_session,
+    unlink_session,
+    update_session,
+    get_session_stats,
+    _handle_ruok_error,
+    get_linked_sessions,
+    collect_all_statuses,
+    dispatch_notification,
+    confirm_session_plugins,
+)
+
+# ────────────────────────────────
+# Router factory
+# ────────────────────────────────
+
+
+def create_ruok_router(config: ScopedConfig, data_dir: Path) -> APIRouter:
+    """Build the FastAPI router for all RUOK endpoints."""
+    router = APIRouter(prefix="/ruok/api", tags=["RUOK"])
+
+    # Simple cache
+    _cache: dict[str, Any] = {}
+    _cache_time: dict[str, float] = {}
+
+    def _cached(key: str, factory: Any) -> Any:
+        now = time.time()
+        if key in _cache and now - _cache_time.get(key, 0) < config.cache_ttl:
+            return _cache[key]
+        result = factory()
+        _cache[key] = result
+        _cache_time[key] = now
+        return result
+
+    def _require_api_key(
+        x_ruok_api_key: str | None = Header(None),
+        authorization: str | None = Header(None),
+    ) -> None:
+        if not config.api_key:
+            return
+
+        token = x_ruok_api_key or ""
+        if authorization:
+            scheme, _, value = authorization.partition(" ")
+            if scheme.lower() == "bearer":
+                token = value
+
+        if not secrets.compare_digest(token, config.api_key):
+            raise HTTPException(status_code=401, detail="Invalid API key")
+
+    # ── Health ────────────────────
+
+    @router.get("/status")
+    async def api_status(_: None = Depends(_require_api_key)) -> dict[str, Any]:
+        """Aggregated bot health status."""
+        data = _cached("status", lambda: None)
+        if data is None:
+            data = await collect_all_statuses(config, data_dir)
+            _cache["status"] = data
+            _cache_time["status"] = time.time()
+        return data.model_dump(mode="json")
+
+    @router.get("/health", response_model=None)
+    async def api_health(
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any] | JSONResponse:
+        """Simple health check for K8s / Docker / Uptime."""
+        data = _cached("status", lambda: None)
+        if data is None:
+            try:
+                data = await collect_all_statuses(config, data_dir)
+            except (asyncio.TimeoutError, RuntimeError, OSError):
+                return JSONResponse({"status": "unhealthy"}, status_code=503)
+            except Exception as exc:
+                _handle_ruok_error(exc, "api_health", data_dir)
+                return JSONResponse({"status": "unhealthy"}, status_code=503)
+        if data.overall == "unavailable":
+            return JSONResponse(
+                {"status": "unhealthy", "overall": data.overall}, status_code=503
+            )
+        return {"status": "healthy", "overall": data.overall}
+
+    @router.get("/connections")
+    async def api_connections(
+        _: None = Depends(_require_api_key),
+    ) -> list[dict[str, Any]]:
+        """WS connection status only (lightweight)."""
+        # connections are always fresh, no caching
+        status = await collect_all_statuses(config, data_dir)
+        return [c.model_dump(mode="json") for c in status.connections]
+
+    # ── Sessions ──────────────────
+
+    @router.get("/sessions")
+    async def api_list_sessions(
+        _: None = Depends(_require_api_key),
+        status: str | None = Query(None),
+        module: str | None = Query(None),
+        reporter: str | None = Query(None),
+        search: str | None = Query(None),
+        after: str | None = Query(
+            None, description="ISO datetime, e.g. 2026-07-01T00:00:00"
+        ),
+        before: str | None = Query(None, description="ISO datetime"),
+        plugin: str | None = Query(
+            None, description="Filter by plugin name from ModuleDefinitions"
+        ),
+    ) -> list[dict[str, Any]]:
+        """List sessions with optional filters."""
+        from datetime import datetime as dt
+
+        first_seen_after = dt.fromisoformat(after) if after else None
+        first_seen_before = dt.fromisoformat(before) if before else None
+        sessions = list_sessions(
+            data_dir,
+            status=status,
+            module_name=module,
+            reporter_user_id=reporter,
+            search=search,
+            first_seen_after=first_seen_after,
+            first_seen_before=first_seen_before,
+            plugin_name=plugin,
+        )
+        return [s.model_dump(mode="json") for s in sessions]
+
+    @router.post("/sessions")
+    async def api_create_session(
+        request: Request,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Create a session via API (for WebUI)."""
+        if not config.session_enabled:
+            raise HTTPException(status_code=403, detail="Session system disabled")
+
+        body = await request.json()
+        module_name = body.get("module_name", "")
+        description = body.get("description", "")
+        reporter = ReporterInfo(
+            type=body.get("reporter_type", "user"),
+            user_id=body.get("user_id"),
+            group_id=body.get("group_id"),
+            platform=body.get("platform"),
+        )
+        session = create_session(
+            data_dir,
+            module_name=module_name,
+            description=description,
+            reporter=reporter,
+            source=body.get("source", "manual"),
+        )
+        await dispatch_notification(session, config, data_dir)
+        _cache.pop("status", None)  # invalidate cache
+        return session.model_dump(mode="json")
+
+    @router.get("/sessions/stats")
+    async def api_session_stats(_: None = Depends(_require_api_key)) -> dict[str, Any]:
+        """Return aggregate session statistics."""
+        stats = get_session_stats(data_dir)
+        return stats.model_dump(mode="json")
+
+    @router.get("/sessions/{session_id}")
+    async def api_get_session(
+        session_id: str,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Get a single session with all occurrences."""
+        session = get_session(data_dir, session_id)
+        if session is None:
+            raise HTTPException(status_code=404, detail="Session not found")
+        return session.model_dump(mode="json")
+
+    @router.patch("/sessions/{session_id}")
+    async def api_update_session(
+        session_id: str,
+        request: Request,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Update session status / notes."""
+        if not config.session_enabled:
+            raise HTTPException(status_code=403, detail="Session system disabled")
+
+        body = await request.json()
+        if body.get("status") == "unsolved" and "affected_plugins" in body:
+            try:
+                session = confirm_session_plugins(
+                    data_dir,
+                    config,
+                    session_id,
+                    body.get("affected_plugins", []),
+                )
+            except SessionPluginValidationError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+        else:
+            if "affected_plugins" in body:
+                raise HTTPException(
+                    status_code=400,
+                    detail=(
+                        "affected_plugins can only be set when confirming a session"
+                    ),
+                )
+            updates = {
+                k: v for k, v in body.items() if k in ("status", "developer_notes")
+            }
+            try:
+                session = update_session(data_dir, session_id, updates)
+            except SessionUpdateValidationError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+        if session is None:
+            raise HTTPException(status_code=404, detail="Session not found")
+        _cache.pop("status", None)
+        return session.model_dump(mode="json")
+
+    @router.post("/sessions/{session_id}/link/{other_id}")
+    async def api_link_sessions(
+        session_id: str,
+        other_id: str,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Link two sessions into the same link_group."""
+        if not config.session_enabled:
+            raise HTTPException(status_code=403, detail="Session system disabled")
+
+        ok = link_sessions(data_dir, session_id, other_id)
+        if not ok:
+            raise HTTPException(
+                status_code=404, detail="One or both sessions not found"
+            )
+        s = get_session(data_dir, session_id)
+        return {"linked": True, "link_group": s.link_group if s else None}
+
+    @router.delete("/sessions/{session_id}/link")
+    async def api_unlink_session(
+        session_id: str,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Remove a session from its link_group."""
+        if not config.session_enabled:
+            raise HTTPException(status_code=403, detail="Session system disabled")
+
+        ok = unlink_session(data_dir, session_id)
+        if not ok:
+            raise HTTPException(
+                status_code=404, detail="Session not found or not linked"
+            )
+        return {"unlinked": True}
+
+    @router.get("/sessions/{session_id}/linked")
+    async def api_get_linked_sessions(
+        session_id: str,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Get all sessions in the same link_group."""
+        session = get_session(data_dir, session_id)
+        if session is None:
+            raise HTTPException(status_code=404, detail="Session not found")
+        linked = get_linked_sessions(data_dir, session_id)
+        return {
+            "link_group": session.link_group,
+            "linked": [s.model_dump(mode="json") for s in linked],
+        }
+
+    # ── Modules ───────────────────
+
+    @router.get("/modules")
+    async def api_list_modules(
+        _: None = Depends(_require_api_key),
+    ) -> list[dict[str, Any]]:
+        """List modules with real-time status."""
+        return [m.model_dump(mode="json") for m in list_modules(data_dir, config)]
+
+    @router.get("/modules/{name}")
+    async def api_get_module(
+        name: str,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Get one module."""
+        mod = get_module(data_dir, config, name)
+        if mod is None:
+            raise HTTPException(status_code=404, detail="Module not found")
+        return mod.model_dump(mode="json")
+
+    @router.put("/modules/{name}")
+    async def api_upsert_module(
+        name: str,
+        request: Request,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Create or update a module definition."""
+        body = await request.json()
+        definition = ModuleDefinition(
+            name=name,
+            display_name=body.get("display_name", name),
+            plugins=body.get("plugins", []),
+            description=body.get("description"),
+        )
+        upsert_module(data_dir, definition)
+        _cache.pop("status", None)
+        return definition.model_dump(mode="json")
+
+    @router.delete("/modules/{name}")
+    async def api_delete_module(
+        name: str,
+        _: None = Depends(_require_api_key),
+    ) -> dict[str, Any]:
+        """Delete a module definition."""
+        ok = delete_module(data_dir, name)
+        if not ok:
+            raise HTTPException(status_code=404, detail="Module not found")
+        _cache.pop("status", None)
+        return {"deleted": True}
+
+    # ── Metrics history ───────────
+
+    @router.get("/metrics/history")
+    async def api_metrics_history(
+        _: None = Depends(_require_api_key),
+        hours: float = Query(24.0, ge=0.5, le=168.0),
+    ) -> list[dict[str, Any]]:
+        """Return time-series metrics for the last *hours* hours."""
+        points = MetricsStore.query(data_dir, hours=hours)
+        return [p.model_dump(mode="json") for p in points]
+
+    return router

nonebot_plugin_ruok/chat_render.py

@@ -0,0 +1,154 @@
+"""Image rendering helpers for RUOK chat commands."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from nonebot import logger
+from nonebot.adapters import Bot, Event
+
+from .config import ScopedConfig
+from .protocol import Session, ModuleDefinition
+from .webui.jinja import render_to_string
+
+
+class ChatImageRenderError(RuntimeError):
+    """Raised when a chat command image cannot be rendered or sent."""
+
+
+@dataclass(frozen=True)
+class ChatStatusItem:
+    """Display data for one module in the status image."""
+
+    name: str
+    status: str
+    label: str
+    icon: str
+    reasons: list[str]
+
+
+@dataclass(frozen=True)
+class ChatSessionItem:
+    """Display data for one session in the list image."""
+
+    session_id: str
+    module_name: str
+    status: str
+    label: str
+    icon: str
+    time_text: str
+    description: str
+
+
+def chat_render_enabled(config: ScopedConfig) -> bool:
+    """Return whether chat image rendering is enabled."""
+    return config.chat_render_mode == "image"
+
+
+def build_status_items(modules: list[ModuleDefinition]) -> list[ChatStatusItem]:
+    """Build presentation data for module status rendering."""
+    labels = {
+        "available": "可用",
+        "degraded": "降级",
+        "unavailable": "不可用",
+    }
+    icons = {"available": "🟢", "degraded": "🟡", "unavailable": "🔴"}
+    return [
+        ChatStatusItem(
+            name=module.display_name or module.name,
+            status=module.status,
+            label=labels.get(module.status, module.status),
+            icon=icons.get(module.status, "⚪"),
+            reasons=module.status_reasons[:2],
+        )
+        for module in modules
+    ]
+
+
+def build_session_items(sessions: list[Session]) -> list[ChatSessionItem]:
+    """Build presentation data for session list rendering."""
+    labels = {
+        "pending": "待确认",
+        "unsolved": "未解决",
+        "solved": "已解决",
+        "ignored": "已忽略",
+    }
+    icons = {
+        "pending": "🟡",
+        "unsolved": "🔴",
+        "solved": "🟢",
+        "ignored": "⚪",
+    }
+    return [
+        ChatSessionItem(
+            session_id=session.session_id,
+            module_name=session.module_name,
+            status=session.status,
+            label=labels.get(session.status, session.status),
+            icon=icons.get(session.status, "❓"),
+            time_text=session.last_seen_at.astimezone().strftime("%H:%M"),
+            description=session.description[:120],
+        )
+        for session in sessions
+    ]
+
+
+async def render_status_image(
+    modules: list[ModuleDefinition],
+    config: ScopedConfig,
+) -> bytes:
+    """Render /ruok status output as a PNG image."""
+    html = render_to_string(
+        "chat_status.html.jinja2",
+        items=build_status_items(modules),
+    )
+    return await _render_html(html, config)
+
+
+async def render_session_list_image(
+    *,
+    title: str,
+    sessions: list[Session],
+    total_count: int,
+    hidden_count: int,
+    config: ScopedConfig,
+) -> bytes:
+    """Render /ruok list output as a PNG image."""
+    html = render_to_string(
+        "chat_session_list.html.jinja2",
+        title=title,
+        items=build_session_items(sessions),
+        total_count=total_count,
+        hidden_count=hidden_count,
+    )
+    return await _render_html(html, config)
+
+
+async def send_chat_image(
+    bot: Bot,
+    event: Event,
+    image: bytes,
+) -> None:
+    """Send a rendered image through the current adapter."""
+    if bot.type != "OneBot V11":
+        raise ChatImageRenderError(f"adapter does not support image output: {bot.type}")
+    try:
+        from nonebot.adapters.onebot.v11 import MessageSegment
+
+        await bot.send(event, MessageSegment.image(image))
+    except Exception as exc:
+        raise ChatImageRenderError("send image failed") from exc
+
+
+async def _render_html(html: str, config: ScopedConfig) -> bytes:
+    try:
+        from nonebot_plugin_htmlrender import render_html
+
+        return await asyncio.wait_for(
+            render_html(html, wait=0),
+            timeout=config.chat_render_timeout,
+        )
+    except Exception as exc:
+        logger.warning(f"RUOK: chat image render failed: {exc}")
+        raise ChatImageRenderError("render image failed") from exc

nonebot_plugin_ruok/collector.py

@@ -0,0 +1,197 @@
+"""Core engine: health collection, LogMonitor, session storage, module derivation.
+
+This module is now a thin re-export layer.  The actual implementations live in
+the ``collectors/`` subpackage.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from pathlib import Path
+from datetime import datetime, timezone, timedelta
+
+from .protocol import MetricPoint
+
+# ── Re-export everything from the collectors subpackage ──
+from .collectors import (
+    # monitor
+    LogMonitor,
+    # trackers
+    DiskRateTracker,
+    NetworkRateTracker,
+    SessionPluginValidationError,
+    SessionUpdateValidationError,
+    get_module,
+    get_session,
+    # modules
+    list_modules,
+    _disk_tracker,
+    _startup_time,
+    delete_module,
+    link_sessions,
+    list_sessions,
+    upsert_module,
+    create_session,
+    unlink_session,
+    update_session,
+    # sessions
+    _network_tracker,
+    get_session_stats,
+    _handle_ruok_error,
+    _connection_history,
+    get_linked_sessions,
+    build_plugin_impacts,
+    collect_all_statuses,
+    collect_fast_metrics,
+    derive_module_status,
+    dispatch_notification,
+    rebuild_plugin_impacts,
+    resolve_module_display,
+    confirm_session_plugins,
+    collect_process_snapshot,
+    # metrics (webui/router)
+    _collect_plugin_inventory,
+    list_module_related_sessions,
+    derive_module_status_with_reasons,
+)
+
+__all__ = [
+    "DiskRateTracker",
+    "LogMonitor",
+    "MetricsStore",
+    "NetworkRateTracker",
+    "SessionPluginValidationError",
+    "SessionUpdateValidationError",
+    "_collect_plugin_inventory",
+    "_connection_history",
+    "_disk_tracker",
+    "_network_tracker",
+    "_startup_time",
+    "build_plugin_impacts",
+    "collect_all_statuses",
+    "collect_fast_metrics",
+    "collect_process_snapshot",
+    "confirm_session_plugins",
+    "create_session",
+    "delete_module",
+    "derive_module_status",
+    "derive_module_status_with_reasons",
+    "dispatch_notification",
+    "get_linked_sessions",
+    "get_module",
+    "get_session",
+    "get_session_stats",
+    "link_sessions",
+    "list_module_related_sessions",
+    "list_modules",
+    "list_sessions",
+    "rebuild_plugin_impacts",
+    "resolve_module_display",
+    "unlink_session",
+    "update_session",
+    "upsert_module",
+]
+
+# ────────────────────────────────
+# 11. Time-series Metrics Store
+# ────────────────────────────────
+
+
+class MetricsStore:
+    """Time-series metrics storage backed by daily JSON files.
+
+    File layout::
+
+        {data_dir}/metrics/
+        ├── 2026-07-05.json
+        ├── 2026-07-04.json
+        └── ...
+
+    Each file is a JSON array of MetricPoint dicts.
+    """
+
+    @staticmethod
+    def _metrics_dir(data_dir: Path) -> Path:
+        d = data_dir / "metrics"
+        d.mkdir(parents=True, exist_ok=True)
+        return d
+
+    @staticmethod
+    def _today_file(data_dir: Path) -> Path:
+        return (
+            MetricsStore._metrics_dir(data_dir)
+            / f"{datetime.now(timezone.utc).date().isoformat()}.json"
+        )
+
+    @staticmethod
+    def append(data_dir: Path, point: MetricPoint, retention_days: int = 7) -> None:
+        """Append one MetricPoint to today's file and clean old files."""
+        file_path = MetricsStore._today_file(data_dir)
+        records: list[dict[str, Any]] = []
+        if file_path.exists():
+            try:
+                records = json.loads(file_path.read_text("utf-8"))
+            except (json.JSONDecodeError, OSError):
+                records = []
+        records.append(point.model_dump(mode="json"))
+        file_path.write_text(
+            json.dumps(records, indent=2, ensure_ascii=False), encoding="utf-8"
+        )
+        # Clean old files
+        MetricsStore._cleanup(data_dir, retention_days)
+
+    @staticmethod
+    def query(data_dir: Path, hours: float = 24.0) -> list[MetricPoint]:
+        """Return metrics from the last *hours* hours.
+
+        Loads today's file and yesterday's if needed.
+        """
+        cutoff = datetime.now(timezone.utc) - timedelta(hours=hours)
+        metrics_dir = MetricsStore._metrics_dir(data_dir)
+        points: list[MetricPoint] = []
+
+        today = datetime.now(timezone.utc).date()
+        days = max(1, int(hours // 24) + 2)
+
+        for offset in range(days):
+            date_str = (today - timedelta(days=offset)).isoformat()
+            fpath = metrics_dir / f"{date_str}.json"
+            if not fpath.exists():
+                continue
+            try:
+                records = json.loads(fpath.read_text("utf-8"))
+            except (json.JSONDecodeError, OSError):
+                continue
+            for rec in records:
+                try:
+                    pt = MetricPoint.model_validate(rec)
+                    ts = datetime.fromisoformat(pt.ts)
+                    if ts >= cutoff:
+                        points.append(pt)
+                except (ValueError, KeyError):
+                    continue
+                except Exception as exc:
+                    _handle_ruok_error(exc, "MetricsStore.query 解析记录", data_dir)
+                    continue
+
+        points.sort(key=lambda p: p.ts)
+        return points
+
+    @staticmethod
+    def _cleanup(data_dir: Path, retention_days: int) -> None:
+        """Remove metric files older than *retention_days*."""
+        cutoff_date = (
+            datetime.now(timezone.utc) - timedelta(days=retention_days)
+        ).date()
+        metrics_dir = MetricsStore._metrics_dir(data_dir)
+        for f in metrics_dir.glob("*.json"):
+            try:
+                file_date = datetime.strptime(f.stem, "%Y-%m-%d").date()
+            except ValueError:
+                continue
+            if file_date < cutoff_date:
+                try:
+                    f.unlink()
+                except OSError:
+                    pass