feat: Stage 4 — fail2ban connection and server status

backend/app/routers/dashboard.py

@@ -0,0 +1,46 @@
+"""Dashboard router.
+
+Provides the ``GET /api/dashboard/status`` endpoint that returns the cached
+fail2ban server health snapshot.  The snapshot is maintained by the
+background health-check task and refreshed every 30 seconds.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+
+from app.dependencies import AuthDep
+from app.models.server import ServerStatus, ServerStatusResponse
+
+router: APIRouter = APIRouter(prefix="/api/dashboard", tags=["Dashboard"])
+
+
+@router.get(
+    "/status",
+    response_model=ServerStatusResponse,
+    summary="Return the cached fail2ban server status",
+)
+async def get_server_status(
+    request: Request,
+    _auth: AuthDep,
+) -> ServerStatusResponse:
+    """Return the most recent fail2ban health snapshot.
+
+    The snapshot is populated by a background task that runs every 30 seconds.
+    If the task has not yet executed a placeholder ``online=False`` status is
+    returned so the response is always well-formed.
+
+    Args:
+        request: The incoming request (used to access ``app.state``).
+        _auth: Validated session — enforces authentication on this endpoint.
+
+    Returns:
+        :class:`~app.models.server.ServerStatusResponse` containing the
+        current health snapshot.
+    """
+    cached: ServerStatus = getattr(
+        request.app.state,
+        "server_status",
+        ServerStatus(online=False),
+    )
+    return ServerStatusResponse(status=cached)