feat: snapshot UX (manual trigger + list + restore + preview) (T99)

chat/web/snapshots.py

@@ -0,0 +1,190 @@
+"""Snapshot UX routes (T99).
+
+Surfaces the existing snapshot service (``chat/services/snapshot.py``)
+through HTML so the user can see, take, restore, and preview snapshots
+without dropping to a shell.
+
+Routes:
+
+* ``GET  /snapshots``                    list all snapshots (both kinds)
+* ``POST /snapshots/take``               take a periodic snapshot now
+* ``POST /snapshots/restore/{id}``       restore (requires matching ``confirm_id``)
+* ``GET  /snapshots/{id}/preview``       show metadata + delta vs current
+
+The ``snapshot_id`` is the filename stem (the UTC timestamp written by
+:func:`chat.services.snapshot.take_snapshot`) — there's no separate UUID,
+and the timestamp filename is already unique per snapshot kind. Both
+periodic and rewind snapshots share the same id space lookup-wise, so
+the restore + preview routes accept ``kind`` as a form/query param to
+disambiguate.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, Form, HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+from fastapi.templating import Jinja2Templates
+
+from chat.services.snapshot import (
+    restore_from_snapshot,
+    take_snapshot,
+)
+from chat.web.bots import get_conn
+
+TEMPLATES = Jinja2Templates(
+    directory=str(Path(__file__).resolve().parent.parent / "templates")
+)
+
+router = APIRouter()
+
+SNAPSHOT_KINDS = ("periodic", "rewind")
+
+
+def _list_all_snapshots(data_dir: Path) -> list[dict]:
+    """Walk ``data/snapshots/{kind}/`` for both kinds and collect metadata.
+
+    Each entry exposes the fields the template needs: ``snapshot_id``
+    (filename stem), ``kind``, ``created_at`` (file mtime as ISO), the
+    on-disk ``file_size_bytes``, and the snapshot's stored
+    ``last_event_id`` (parsed from the JSON body — small enough that
+    listing isn't a performance concern for the handful of files we keep).
+    """
+    from datetime import datetime, timezone
+
+    rows: list[dict] = []
+    for kind in SNAPSHOT_KINDS:
+        snap_dir = data_dir / "snapshots" / kind
+        if not snap_dir.exists():
+            continue
+        for path in sorted(snap_dir.glob("*.json")):
+            try:
+                dump = json.loads(path.read_text())
+                last_event_id = dump.get("last_event_id", 0)
+            except (OSError, json.JSONDecodeError):
+                # Corrupt or unreadable files still get listed so the
+                # user can see and delete them; just don't crash here.
+                last_event_id = None
+            stat = path.stat()
+            rows.append(
+                {
+                    "snapshot_id": path.stem,
+                    "kind": kind,
+                    "created_at": datetime.fromtimestamp(
+                        stat.st_mtime, tz=timezone.utc
+                    ).isoformat(),
+                    "file_size_bytes": stat.st_size,
+                    "last_event_id": last_event_id,
+                    "filename": path.name,
+                }
+            )
+    # Newest first for display.
+    rows.sort(key=lambda r: r["created_at"], reverse=True)
+    return rows
+
+
+def _resolve_snapshot_path(
+    data_dir: Path, snapshot_id: str, kind: str
+) -> Path:
+    """Map an ``(id, kind)`` pair to the on-disk file, or 404."""
+    if kind not in SNAPSHOT_KINDS:
+        raise HTTPException(status_code=400, detail=f"unknown kind: {kind}")
+    path = data_dir / "snapshots" / kind / f"{snapshot_id}.json"
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="snapshot not found")
+    return path
+
+
+@router.get("/snapshots", response_class=HTMLResponse)
+async def snapshots_list(request: Request):
+    settings = request.app.state.settings
+    rows = _list_all_snapshots(settings.data_dir)
+    return TEMPLATES.TemplateResponse(
+        request,
+        "snapshots.html",
+        {"snapshots": rows, "active_nav": "snapshots"},
+    )
+
+
+@router.post("/snapshots/take")
+async def snapshots_take(request: Request, conn=Depends(get_conn)):
+    """Take a periodic snapshot now.
+
+    We use ``kind="periodic"`` for manual snapshots since they're
+    user-initiated checkpoints, not pre-rewind safety dumps. They count
+    against the 5-snapshot retention but that's fine — manual ones are
+    the most recent so they're the last to be pruned.
+    """
+    settings = request.app.state.settings
+    take_snapshot(conn, data_dir=settings.data_dir, kind="periodic")
+    return RedirectResponse(url="/snapshots", status_code=303)
+
+
+@router.post("/snapshots/restore/{snapshot_id}")
+async def snapshots_restore(
+    snapshot_id: str,
+    request: Request,
+    confirm_id: str = Form(""),
+    kind: str = Form("periodic"),
+    conn=Depends(get_conn),
+):
+    """Hard-confirm restore: ``confirm_id`` must equal the path id.
+
+    Mismatched confirm → 400 (without touching the DB). On match, the
+    existing :func:`restore_from_snapshot` clears projected tables and
+    re-loads them from the dump.
+    """
+    if confirm_id != snapshot_id:
+        raise HTTPException(
+            status_code=400,
+            detail="confirm_id does not match snapshot id",
+        )
+    settings = request.app.state.settings
+    path = _resolve_snapshot_path(settings.data_dir, snapshot_id, kind)
+    restore_from_snapshot(conn, path)
+    return RedirectResponse(url="/snapshots", status_code=303)
+
+
+@router.get("/snapshots/{snapshot_id}/preview", response_class=HTMLResponse)
+async def snapshots_preview(
+    snapshot_id: str,
+    request: Request,
+    kind: str = "periodic",
+    conn=Depends(get_conn),
+):
+    """Show snapshot metadata + a basic delta against the current event log.
+
+    Phase 4 keeps this simple: the snapshot's ``last_event_id`` plus the
+    current ``MAX(event_log.id)`` is enough to tell the user how far the
+    log has moved on. A richer per-table diff is a Phase 4.5+ concern.
+    """
+    settings = request.app.state.settings
+    path = _resolve_snapshot_path(settings.data_dir, snapshot_id, kind)
+    dump = json.loads(path.read_text())
+    last_event_id = dump.get("last_event_id", 0)
+
+    cur = conn.execute("SELECT MAX(id) FROM event_log")
+    row = cur.fetchone()
+    current_max_id = row[0] if row[0] is not None else 0
+
+    stat = path.stat()
+    return TEMPLATES.TemplateResponse(
+        request,
+        "snapshots.html",
+        {
+            "snapshots": _list_all_snapshots(settings.data_dir),
+            "active_nav": "snapshots",
+            "preview": {
+                "snapshot_id": snapshot_id,
+                "kind": kind,
+                "filename": path.name,
+                "file_size_bytes": stat.st_size,
+                "last_event_id": last_event_id,
+                "current_event_log_max_id": current_max_id,
+                "event_delta": current_max_id - last_event_id,
+                "event_log_rows_in_snapshot": len(dump.get("event_log", [])),
+            },
+        },
+    )