Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
feat: read-only live view at /view?key=<LIVEVIEW_KEY>
Pouzor210304394e63
diff --git a/.env.example b/.env.exampleindex 11a238b..f9affad 100644--- a/.env.example+++ b/.env.example@@ -22,3 +22,8 @@ STATUS_CHECKER_INTERVAL=60# Generate keys: python3 -c "import secrets; print(secrets.token_hex(32))"MCP_API_KEY=mcp_sk_changemeMCP_SERVICE_KEY=svc_changeme++# Live view — read-only public canvas at /view?key=<value>+# Off by default. Set to a random secret to enable.+# Generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))"+# LIVEVIEW_KEY=diff --git a/backend/app/api/routes/liveview.py b/backend/app/api/routes/liveview.pynew file mode 100644index 0000000..ce6492f--- /dev/null+++ b/backend/app/api/routes/liveview.py@@ -0,0 +1,40 @@+from typing import Any++from fastapi import APIRouter, Depends, HTTPException, Query+from sqlalchemy import select+from sqlalchemy.ext.asyncio import AsyncSession++from app.core.config import settings+from app.db.database import get_db+from app.db.models import CanvasState, Edge, Node+from app.schemas.canvas import CanvasStateResponse+from app.schemas.edges import EdgeResponse+from app.schemas.nodes import NodeResponse++router = APIRouter()++[email protected]("", response_model=CanvasStateResponse)+async def liveview_canvas(+ key: str | None = Query(default=None),+ db: AsyncSession = Depends(get_db),+) -> CanvasStateResponse:+ """Read-only public canvas endpoint.++ Disabled by default — requires LIVEVIEW_KEY to be set in .env.+ Always returns 403 when disabled, regardless of the key provided.+ """+ if not settings.liveview_key:+ raise HTTPException(status_code=403, detail="Live view is disabled")+ if not key or key != settings.liveview_key:+ raise HTTPException(status_code=403, detail="Invalid live view key")++ nodes = (await db.execute(select(Node))).scalars().all()+ edges = (await db.execute(select(Edge))).scalars().all()+ state = await db.get(CanvasState, 1)+ viewport: dict[str, Any] = state.viewport if state else {"x": 0, "y": 0, "zoom": 1}+ return CanvasStateResponse(+ nodes=[NodeResponse.model_validate(n) for n in nodes],+ edges=[EdgeResponse.model_validate(e) for e in edges],+ viewport=viewport,+ )diff --git a/backend/app/core/config.py b/backend/app/core/config.pyindex 80d51a2..7d6a1c6 100644--- a/backend/app/core/config.py+++ b/backend/app/core/config.py@@ -30,6 +30,11 @@ class Settings(BaseSettings):# Leave empty to disable MCP service key auth.mcp_service_key: str = ""+ # Live view — optional read-only public canvas endpoint.+ # Set to a random secret string to enable /api/v1/liveview?key=<value>.+ # Leave unset (or empty) to keep the feature disabled (default).+ liveview_key: str | None = None+def _override_path(self) -> Path:return Path(self.sqlite_path).parent / "scan_config.json"diff --git a/backend/app/main.py b/backend/app/main.pyindex 9767ec6..9cd067d 100644--- a/backend/app/main.py+++ b/backend/app/main.py@@ -5,7 +5,7 @@ from typing import Anyfrom fastapi import FastAPIfrom fastapi.middleware.cors import CORSMiddleware-from app.api.routes import auth, canvas, edges, nodes, scan, status+from app.api.routes import auth, canvas, edges, liveview, nodes, scan, statusfrom app.core.config import settingsfrom app.core.scheduler import start_scheduler, stop_schedulerfrom app.db.database import init_db@@ -40,6 +40,7 @@ app.include_router(edges.router, prefix="/api/v1/edges", tags=["edges"])app.include_router(canvas.router, prefix="/api/v1/canvas", tags=["canvas"])app.include_router(scan.router, prefix="/api/v1/scan", tags=["scan"])app.include_router(status.router, prefix="/api/v1/status", tags=["status"])+app.include_router(liveview.router, prefix="/api/v1/liveview", tags=["liveview"])@app.get("/api/v1/health")diff --git a/backend/tests/test_liveview.py b/backend/tests/test_liveview.pynew file mode 100644index 0000000..bf27b85--- /dev/null+++ b/backend/tests/test_liveview.py@@ -0,0 +1,126 @@+"""+Tests for the /api/v1/liveview read-only canvas endpoint.++The endpoint is:+ - Disabled by default (LIVEVIEW_KEY not set) → 403+ - Returns 403 for missing or wrong key even when enabled+ - Returns canvas data for a valid key (no JWT required)+"""++import pytest+from httpx import AsyncClient++from app.core.config import settings++[email protected](autouse=True)+def reset_liveview_key():+ """Restore liveview_key after each test so tests are isolated."""+ original = settings.liveview_key+ yield+ settings.liveview_key = original+++# ── Disabled (no key configured) ─────────────────────────────────────────────++async def test_liveview_disabled_by_default(client: AsyncClient):+ settings.liveview_key = None+ res = await client.get("/api/v1/liveview?key=anything")+ assert res.status_code == 403+ assert res.json()["detail"] == "Live view is disabled"+++async def test_liveview_disabled_when_key_empty(client: AsyncClient):+ settings.liveview_key = ""+ res = await client.get("/api/v1/liveview?key=anything")+ assert res.status_code == 403+ assert res.json()["detail"] == "Live view is disabled"+++# ── Enabled but wrong / missing key ──────────────────────────────────────────++async def test_liveview_wrong_key(client: AsyncClient):+ settings.liveview_key = "correct-secret"+ res = await client.get("/api/v1/liveview?key=wrong-key")+ assert res.status_code == 403+ assert res.json()["detail"] == "Invalid live view key"+++async def test_liveview_missing_key_param(client: AsyncClient):+ settings.liveview_key = "correct-secret"+ res = await client.get("/api/v1/liveview")+ assert res.status_code == 403+ assert res.json()["detail"] == "Invalid live view key"+++# ── Valid key — no JWT needed ────────────────────────────────────────────────++async def test_liveview_valid_key_returns_canvas(client: AsyncClient):+ settings.liveview_key = "my-secret-key"+ res = await client.get("/api/v1/liveview?key=my-secret-key")+ assert res.status_code == 200+ data = res.json()+ assert "nodes" in data+ assert "edges" in data+ assert "viewport" in data+ assert isinstance(data["nodes"], list)+ assert isinstance(data["edges"], list)+++async def test_liveview_does_not_require_jwt(client: AsyncClient):+ """Accessing without Authorization header must work when key is correct."""+ settings.liveview_key = "open-sesame"+ # client has no auth headers set here+ res = await client.get("/api/v1/liveview?key=open-sesame")+ assert res.status_code == 200+++async def test_liveview_returns_saved_canvas(client: AsyncClient, auth_headers):+ """Canvas saved via POST /canvas/save appears in liveview response."""+ settings.liveview_key = "test-key"+ headers = await auth_headers()++ # Save a canvas with one node+ payload = {+ "nodes": [{+ "id": "lv-node-1",+ "type": "server",+ "label": "Live Node",+ "status": "online",+ "services": [],+ "pos_x": 10,+ "pos_y": 20,+ }],+ "edges": [],+ "viewport": {"x": 0, "y": 0, "zoom": 1},+ }+ await client.post("/api/v1/canvas/save", json=payload, headers=headers)++ # Liveview should return the same node+ res = await client.get("/api/v1/liveview?key=test-key")+ assert res.status_code == 200+ nodes = res.json()["nodes"]+ assert len(nodes) == 1+ assert nodes[0]["id"] == "lv-node-1"+ assert nodes[0]["label"] == "Live Node"+++# ── Re-disable after enabling ─────────────────────────────────────────────────++async def test_liveview_disabled_after_key_cleared(client: AsyncClient):+ settings.liveview_key = "was-enabled"+ res = await client.get("/api/v1/liveview?key=was-enabled")+ assert res.status_code == 200++ settings.liveview_key = None+ res = await client.get("/api/v1/liveview?key=was-enabled")+ assert res.status_code == 403+ assert res.json()["detail"] == "Live view is disabled"diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.tsindex e8d1145..bf4f566 100644--- a/frontend/src/api/client.ts+++ b/frontend/src/api/client.ts@@ -5,6 +5,9 @@ export const api = axios.create({baseURL: '/api/v1',})+// Unauthenticated axios instance — no JWT, no 401 redirect (used for public endpoints)+const publicApi = axios.create({ baseURL: '/api/v1' })+api.interceptors.request.use((config) => {const token = useAuthStore.getState().tokenif (token) config.headers.Authorization = `Bearer ${token}`@@ -44,6 +47,10 @@ export const edgesApi = {delete: (id: string) => api.delete(`/edges/${id}`),}+export const liveviewApi = {+ load: (key: string) => publicApi.get('/liveview', { params: { key } }),+}+export const scanApi = {trigger: () => api.post('/scan/trigger'),pending: () => api.get('/scan/pending'),diff --git a/frontend/src/components/LiveView.tsx b/frontend/src/components/LiveView.tsxnew file mode 100644index 0000000..ac0afa8--- /dev/null+++ b/frontend/src/components/LiveView.tsx@@ -0,0 +1,153 @@+/**+ * LiveView — read-only canvas accessible at /view?key=<LIVEVIEW_KEY>.+ *+ * - Non-standalone: fetches canvas from /api/v1/liveview?key=... (no JWT needed).+ * Returns 403 when the feature is disabled or the key is wrong.+ * - Standalone: loads canvas from localStorage directly (no key required,+ * since there is no backend to validate against).+ *+ * Pan and zoom work. Editing is fully disabled.+ * Clicking a node with an IP opens http://<ip> in a new tab.+ */++import { useCallback, useEffect, useState } from 'react'+import {+ ReactFlowProvider,+ ReactFlow,+ Background,+ BackgroundVariant,+ Controls,+ ConnectionMode,+ type Node,+} from '@xyflow/react'+import '@xyflow/react/dist/style.css'+import { useCanvasStore } from '@/stores/canvasStore'+import { useThemeStore } from '@/stores/themeStore'+import { THEMES } from '@/utils/themes'+import { nodeTypes } from '@/components/canvas/nodes/nodeTypes'+import { edgeTypes } from '@/components/canvas/edges/edgeTypes'+import { deserializeApiNode, deserializeApiEdge, type ApiNode, type ApiEdge } from '@/utils/canvasSerializer'+import { liveviewApi } from '@/api/client'+import type { NodeData } from '@/types'++const STANDALONE = import.meta.env.VITE_STANDALONE === 'true'+const STORAGE_KEY = 'homelable_canvas'++type ViewState = 'loading' | 'disabled' | 'invalid-key' | 'no-key' | 'ready'++function LiveViewCanvas() {+ const { nodes, edges, loadCanvas } = useCanvasStore()+ const activeTheme = useThemeStore((s) => s.activeTheme)+ const theme = THEMES[activeTheme]+ // Derive initial view state synchronously (avoids calling setState inside an effect):+ // - standalone → always ready (localStorage, no key required)+ // - non-standalone, no ?key= → no-key error immediately+ // - non-standalone, key present → loading (API call below)+ const [viewState, setViewState] = useState<ViewState>(() => {+ if (STANDALONE) return 'ready'+ return new URLSearchParams(window.location.search).get('key') ? 'loading' : 'no-key'+ })++ useEffect(() => {+ if (STANDALONE) {+ try {+ const saved = localStorage.getItem(STORAGE_KEY)+ if (saved) {+ const { nodes: savedNodes, edges: savedEdges } = JSON.parse(saved)+ loadCanvas(savedNodes, savedEdges)+ }+ } catch {+ // empty canvas on parse error — show empty canvas+ }+ return+ }++ // Already handled synchronously in useState initializer+ const key = new URLSearchParams(window.location.search).get('key')+ if (!key) return++ liveviewApi.load(key)+ .then((res) => {+ const { nodes: apiNodes, edges: apiEdges } = res.data+ const proxmoxMap = new Map<string, boolean>(+ (apiNodes as ApiNode[])+ .filter((n: ApiNode) => n.type === 'proxmox')+ .map((n: ApiNode) => [n.id, n.container_mode !== false])+ )+ loadCanvas(+ (apiNodes as ApiNode[]).map((n) => deserializeApiNode(n, proxmoxMap)),+ (apiEdges as ApiEdge[]).map(deserializeApiEdge),+ )+ setViewState('ready')+ })+ .catch((err) => {+ const detail: string = err.response?.data?.detail ?? ''+ setViewState(detail === 'Live view is disabled' ? 'disabled' : 'invalid-key')+ })+ }, [loadCanvas])++ const onNodeClick = useCallback((_: React.MouseEvent, node: Node<NodeData>) => {+ const ip = node.data.ip+ if (ip) window.open(`http://${ip}`, '_blank', 'noopener,noreferrer')+ }, [])++ if (viewState === 'loading') {+ return (+ <div className="flex h-screen w-screen items-center justify-center bg-[#0d1117] text-[#8b949e]">+ Loading…+ </div>+ )+ }++ if (viewState !== 'ready') {+ const messages: Record<Exclude<ViewState, 'loading' | 'ready'>, string> = {+ disabled: 'Live view is disabled on this instance.',+ 'invalid-key': 'Invalid or expired live view key.',+ 'no-key': 'Missing key — use ?key=your-secret in the URL.',+ }+ return (+ <div className="flex h-screen w-screen items-center justify-center bg-[#0d1117]">+ <div className="text-center space-y-2">+ <p className="text-[#f85149] text-lg font-medium">Access Denied</p>+ <p className="text-[#8b949e] text-sm">{messages[viewState]}</p>+ </div>+ </div>+ )+ }++ return (+ <div className="w-full h-screen" style={{ background: theme.colors.canvasBackground }}>+ <ReactFlow+ nodes={nodes}+ edges={edges}+ nodeTypes={nodeTypes}+ edgeTypes={edgeTypes}+ nodesDraggable={false}+ nodesConnectable={false}+ elementsSelectable={false}+ panOnDrag+ zoomOnScroll+ fitView+ colorMode={theme.colors.reactFlowColorMode}+ connectionMode={ConnectionMode.Loose}+ onNodeClick={onNodeClick}+ >+ <Background+ variant={BackgroundVariant.Dots}+ gap={24}+ size={1}+ color={theme.colors.canvasDotColor}+ />+ <Controls showInteractive={false} />+ </ReactFlow>+ </div>+ )+}++export default function LiveView() {+ return (+ <ReactFlowProvider>+ <LiveViewCanvas />+ </ReactFlowProvider>+ )+}diff --git a/frontend/src/components/__tests__/LiveView.test.tsx b/frontend/src/components/__tests__/LiveView.test.tsxnew file mode 100644index 0000000..0b63af7--- /dev/null+++ b/frontend/src/components/__tests__/LiveView.test.tsx@@ -0,0 +1,185 @@+import { describe, it, expect, vi, beforeEach } from 'vitest'+import { render, screen, waitFor } from '@testing-library/react'+import { useCanvasStore } from '@/stores/canvasStore'++// ── Mock heavy dependencies ────────────────────────────────────────────────++vi.mock('@xyflow/react', () => ({+ ReactFlowProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,+ ReactFlow: () => <div data-testid="react-flow" />,+ Background: () => null,+ Controls: () => null,+ BackgroundVariant: { Dots: 'dots' },+ ConnectionMode: { Loose: 'loose' },+}))+vi.mock('@xyflow/react/dist/style.css', () => ({}))++vi.mock('@/api/client', () => ({+ liveviewApi: { load: vi.fn() },+}))++import { liveviewApi } from '@/api/client'+import LiveView from '../LiveView'++// ── Helpers ────────────────────────────────────────────────────────────────++function setSearch(params: string) {+ Object.defineProperty(window, 'location', {+ writable: true,+ value: { ...window.location, search: params, pathname: '/view' },+ })+}++const canvasPayload = {+ data: {+ nodes: [{+ id: 'n1', type: 'server', label: 'CI Node', status: 'online',+ services: [], pos_x: 0, pos_y: 0,+ created_at: '2024-01-01T00:00:00Z', updated_at: '2024-01-01T00:00:00Z',+ }],+ edges: [],+ viewport: { x: 0, y: 0, zoom: 1 },+ },+}++// ── Tests ──────────────────────────────────────────────────────────────────++describe('LiveView (non-standalone)', () => {+ beforeEach(() => {+ vi.mocked(liveviewApi.load).mockReset()+ useCanvasStore.setState({ nodes: [], edges: [] })+ })++ // ── No key ────────────────────────────────────────────────────────────────++ it('shows no-key error when ?key= is missing', async () => {+ setSearch('')+ render(<LiveView />)+ await waitFor(() => {+ expect(screen.getByText('Access Denied')).toBeDefined()+ expect(screen.getByText(/Missing key/)).toBeDefined()+ })+ expect(liveviewApi.load).not.toHaveBeenCalled()+ })++ // ── Disabled ──────────────────────────────────────────────────────────────++ it('shows disabled error when backend returns "Live view is disabled"', async () => {+ setSearch('?key=anything')+ vi.mocked(liveviewApi.load).mockRejectedValue({+ response: { data: { detail: 'Live view is disabled' } },+ })+ render(<LiveView />)+ await waitFor(() => {+ expect(screen.getByText(/disabled on this instance/)).toBeDefined()+ })+ })++ // ── Invalid key ───────────────────────────────────────────────────────────++ it('shows invalid-key error when backend returns "Invalid live view key"', async () => {+ setSearch('?key=wrong')+ vi.mocked(liveviewApi.load).mockRejectedValue({+ response: { data: { detail: 'Invalid live view key' } },+ })+ render(<LiveView />)+ await waitFor(() => {+ expect(screen.getByText(/Invalid or expired/)).toBeDefined()+ })+ })++ it('shows invalid-key error for unexpected API errors', async () => {+ setSearch('?key=anything')+ vi.mocked(liveviewApi.load).mockRejectedValue(new Error('network'))+ render(<LiveView />)+ await waitFor(() => {+ expect(screen.getByText(/Invalid or expired/)).toBeDefined()+ })+ })++ // ── Valid key → canvas rendered ───────────────────────────────────────────++ it('renders the canvas on valid key', async () => {+ setSearch('?key=correct-key')+ vi.mocked(liveviewApi.load).mockResolvedValue(canvasPayload as never)+ render(<LiveView />)+ await waitFor(() => {+ expect(screen.getByTestId('react-flow')).toBeDefined()+ })+ expect(liveviewApi.load).toHaveBeenCalledWith('correct-key')+ })++ it('loads nodes into the canvas store on success', async () => {+ setSearch('?key=secret')+ vi.mocked(liveviewApi.load).mockResolvedValue(canvasPayload as never)+ render(<LiveView />)+ await waitFor(() => {+ expect(screen.getByTestId('react-flow')).toBeDefined()+ })+ const { nodes } = useCanvasStore.getState()+ expect(nodes.find((n) => n.id === 'n1')).toBeDefined()+ })++ // ── No editing props passed ───────────────────────────────────────────────++ it('does not show any Access Denied when key is valid', async () => {+ setSearch('?key=valid')+ vi.mocked(liveviewApi.load).mockResolvedValue(canvasPayload as never)+ render(<LiveView />)+ await waitFor(() => expect(screen.getByTestId('react-flow')).toBeDefined())+ expect(screen.queryByText('Access Denied')).toBeNull()+ })+})++// ── Standalone mode ────────────────────────────────────────────────────────++describe('LiveView (standalone — localStorage)', () => {+ beforeEach(() => {+ localStorage.clear()+ useCanvasStore.setState({ nodes: [], edges: [] })+ vi.mocked(liveviewApi.load).mockReset()+ })++ it('loads canvas from localStorage without calling the API', async () => {+ const stored = {+ nodes: [{+ id: 'ls-node', type: 'router',+ position: { x: 10, y: 20 },+ data: { label: 'Router', type: 'router', status: 'unknown', services: [] },+ }],+ edges: [],+ }+ localStorage.setItem('homelable_canvas', JSON.stringify(stored))++ // Stub VITE_STANDALONE before re-importing+ vi.stubEnv('VITE_STANDALONE', 'true')+ vi.resetModules()+ const { default: LiveViewStandalone } = await import('../LiveView')++ setSearch('') // no key needed in standalone+ render(<LiveViewStandalone />)++ await waitFor(() => {+ expect(screen.getByTestId('react-flow')).toBeDefined()+ })+ expect(liveviewApi.load).not.toHaveBeenCalled()++ vi.unstubAllEnvs()+ })++ it('shows canvas (empty) when localStorage has no saved data', async () => {+ vi.stubEnv('VITE_STANDALONE', 'true')+ vi.resetModules()+ const { default: LiveViewStandalone } = await import('../LiveView')++ setSearch('')+ render(<LiveViewStandalone />)++ await waitFor(() => {+ expect(screen.getByTestId('react-flow')).toBeDefined()+ })+ expect(liveviewApi.load).not.toHaveBeenCalled()++ vi.unstubAllEnvs()+ })+})diff --git a/frontend/src/main.tsx b/frontend/src/main.tsxindex bef5202..ad53488 100644--- a/frontend/src/main.tsx+++ b/frontend/src/main.tsx@@ -2,9 +2,12 @@ import { StrictMode } from 'react'import { createRoot } from 'react-dom/client'import './index.css'import App from './App.tsx'+import LiveView from './components/LiveView.tsx'++const isLiveView = window.location.pathname === '/view'createRoot(document.getElementById('root')!).render(<StrictMode>- <App />+ {isLiveView ? <LiveView /> : <App />}</StrictMode>,)