Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
import type { Node, Edge } from '@xyflow/react'
import type { NodeData, EdgeData, Waypoint } from '@/types'
import { normalizeHandle, clampHandles, handleId, handleCountField, normalizePortLabels, prunePortLabels, type Side } from '@/utils/handleUtils'
import { normalizeMarker } from '@/utils/edgeMarkers'
import { changedFactFields, type FactsBaseline } from '@/utils/deviceFacts'
// ── Types ────────────────────────────────────────────────────────────────────
export interface ApiNode extends Record<string, unknown> {
id: string
type: string
label: string
/** Device Inventory row this node draws; null for canvas furniture. */
device_id?: string | null
pos_x: number
pos_y: number
status: string
services: unknown[]
hostname?: string | null
ip?: string | null
mac?: string | null
os?: string | null
check_method?: string | null
check_target?: string | null
notes?: string | null
description?: string | null
parent_id?: string | null
container_mode?: boolean
custom_colors?: Record<string, unknown> | null
custom_icon?: string | null
cpu_count?: number | null
cpu_model?: string | null
ram_gb?: number | null
disk_gb?: number | null
show_hardware?: boolean
properties?: unknown[] | null
width?: number | null
height?: number | null
top_handles?: number
bottom_handles?: number
left_handles?: number
right_handles?: number
show_port_numbers?: boolean
port_labels?: Record<string, string> | null
}
export interface ApiEdge {
id: string
source: string
target: string
type: string
label?: string | null
vlan_id?: number | null
speed?: string | null
lqi?: number | null
custom_color?: string | null
path_style?: string | null
line_style?: string | null
width_mult?: number | null
animated?: boolean | 'snake' | 'flow' | 'basic' | 'none'
marker_start?: string | boolean | null
marker_end?: string | boolean | null
source_handle?: string | null
target_handle?: string | null
waypoints?: Waypoint[] | null
}
// ── Serialization (RF node → API save payload) ───────────────────────────────
/** Drop the legacy geometry keys from a zone's style blob — its size lives in
* the `width`/`height` columns now, and a stale copy here would be the one an
* older canvas reads back. */
function omitZoneSize(
colors: NodeData['custom_colors'],
): Record<string, unknown> {
if (!colors) return {}
return Object.fromEntries(
Object.entries(colors).filter(([key]) => key !== 'width' && key !== 'height'),
)
}
export function serializeNode(
n: Node<NodeData>,
factsBaseline?: FactsBaseline,
): Record<string, unknown> {
if (n.data.type === 'groupRect') {
return {
id: n.id,
type: 'groupRect',
label: n.data.label,
// A zone is canvas furniture — it never points at an inventory row.
device_id: null,
hostname: null,
ip: null,
mac: null,
os: null,
status: 'unknown',
check_method: null,
check_target: null,
services: [],
notes: null,
// Furniture has no inventory row, so its own text lives on the node.
description: n.data.description ?? null,
parent_id: n.data.parent_id ?? null,
container_mode: false,
custom_icon: null,
pos_x: n.position.x,
pos_y: n.position.y,
// A zone's size goes in the real columns, like every other node type.
// It used to live in the custom_colors blob; `width`/`height` are
// stripped from it below so the two cannot drift apart, and a canvas
// saved before the change is migrated by `_backfill_zone_size`.
width: n.width ?? n.measured?.width ?? 360,
height: n.height ?? n.measured?.height ?? 240,
custom_colors: {
...omitZoneSize(n.data.custom_colors),
// Stash collapse state inside custom_colors so the API/YAML blob does
// not need a new column. Hoisted back to `data.collapsed` on load.
collapsed: n.data.collapsed ?? false,
},
}
}
return {
id: n.id,
type: n.data.type,
label: n.data.label,
// The Device Inventory row this node draws. Round-tripped so a save keeps
// the link; the device fields below are routed to that row server-side.
device_id: n.data.device_id ?? null,
// Which of those fields this canvas actually edited since it loaded them.
// The row is shared, so without this the backend cannot tell an edit from a
// stale copy and a moved node would revert someone else's change.
changed_facts: changedFactFields(n.data, factsBaseline),
hostname: n.data.hostname ?? null,
ip: n.data.ip ?? null,
mac: n.data.mac ?? null,
os: n.data.os ?? null,
status: n.data.status,
check_method: n.data.check_method ?? null,
check_target: n.data.check_target ?? null,
services: n.data.services ?? [],
notes: n.data.notes ?? null,
// Only furniture keeps one; the backend clears it on a node drawing a device.
description: n.data.description ?? null,
parent_id: n.data.parent_id ?? null,
container_mode: n.data.container_mode ?? false,
// Stash collapse state inside the custom_colors blob so the backend's
// dict[str, Any] column carries it without a schema change. Hoisted
// back to `data.collapsed` on load. Applies to every node type — group
// containers, Proxmox hosts, etc. — not just groupRect zones.
custom_colors: n.data.collapsed !== undefined
? { ...(n.data.custom_colors ?? {}), collapsed: n.data.collapsed }
: (n.data.custom_colors ?? null),
custom_icon: n.data.custom_icon ?? null,
cpu_count: n.data.cpu_count ?? null,
cpu_model: n.data.cpu_model ?? null,
ram_gb: n.data.ram_gb ?? null,
disk_gb: n.data.disk_gb ?? null,
show_hardware: n.data.show_hardware ?? false,
properties: n.data.properties ?? [],
// Prefer the explicit (resized) dimension over the DOM-measured one so a
// manual resize persists its exact target instead of drifting to the
// fractional content-fit value.
width: n.width ?? n.measured?.width ?? null,
height: n.height ?? n.measured?.height ?? null,
top_handles: clampHandles('top', n.data.top_handles ?? 1),
bottom_handles: clampHandles('bottom', n.data.bottom_handles ?? 1),
left_handles: clampHandles('left', n.data.left_handles ?? 0),
right_handles: clampHandles('right', n.data.right_handles ?? 0),
show_port_numbers: n.data.show_port_numbers ?? false,
port_labels: prunePortLabels(n.data) ?? null,
pos_x: n.position.x,
pos_y: n.position.y,
}
}
export function serializeEdge(e: Edge<EdgeData>): Record<string, unknown> {
return {
id: e.id,
source: e.source,
target: e.target,
type: e.data?.type ?? 'ethernet',
label: e.data?.label ?? null,
vlan_id: e.data?.vlan_id ?? null,
speed: e.data?.speed ?? null,
// Must be re-sent: `save_canvas` setattrs every field of the payload, so
// omitting it here would overwrite a measured LQI with NULL on every save.
lqi: e.data?.lqi ?? null,
custom_color: e.data?.custom_color ?? null,
path_style: e.data?.path_style ?? null,
line_style: e.data?.line_style ?? null,
width_mult: e.data?.width_mult ?? null,
animated: e.data?.animated ?? false,
marker_start: normalizeMarker(e.data?.marker_start),
marker_end: normalizeMarker(e.data?.marker_end),
source_handle: normalizeHandle(e.sourceHandle),
target_handle: normalizeHandle(e.targetHandle),
waypoints: e.data?.waypoints?.length ? e.data.waypoints : null,
}
}
// ── Deserialization (API response → RF node/edge) ────────────────────────────
export function deserializeApiNode(
n: ApiNode,
proxmoxContainerMap: Map<string, boolean>,
/** Ids of groupRect zones, which parent their contents without clamping them. */
zoneIds?: Set<string>,
): Node<NodeData> {
const normalizedType = n.type === 'docker' ? 'docker_host' : n.type
if (n.type === 'groupRect') {
// Prefer the real columns; fall back to the custom_colors stash for a
// canvas saved before the size moved out of it, and which the backend
// backfill has not reached (a payload from an older server, an import).
const w = n.width ?? (n.custom_colors?.width as number | undefined) ?? 360
const h = n.height ?? (n.custom_colors?.height as number | undefined) ?? 240
const z = (n.custom_colors?.z_order as number | undefined) ?? 1
// Hoist persisted collapse flag from the custom_colors stash to a
// first-class field on NodeData. Tolerates legacy saves that already had
// it there from before the type was promoted.
const collapsed = Boolean(n.custom_colors?.collapsed)
return {
id: n.id,
type: 'groupRect',
position: { x: n.pos_x, y: n.pos_y },
data: { ...(n as unknown as NodeData), collapsed },
width: w,
height: h,
zIndex: z - 10,
...(n.parent_id ? { parentId: n.parent_id, extent: 'parent' as const } : {}),
}
}
const parentIsContainer = n.parent_id ? (proxmoxContainerMap.get(n.parent_id) ?? false) : false
// A node dropped inside a zone is parented (so the zone moves it) but never
// extent-clamped — it must stay draggable back out.
const parentIsZone = n.parent_id ? (zoneIds?.has(n.parent_id) ?? false) : false
return {
id: n.id,
type: normalizedType,
position: { x: n.pos_x, y: n.pos_y },
// Hoist persisted collapse flag from the custom_colors stash (matches
// the symmetric serialize step). Applies to every node type.
data: {
...n,
type: normalizedType,
top_handles: clampHandles('top', n.top_handles ?? 1),
bottom_handles: clampHandles('bottom', n.bottom_handles ?? 1),
left_handles: clampHandles('left', n.left_handles ?? 0),
right_handles: clampHandles('right', n.right_handles ?? 0),
// The API reports NULL for "no labels"; the canvas leaves the field unset.
port_labels: normalizePortLabels(n.port_labels),
collapsed: Boolean(n.custom_colors?.collapsed),
} as unknown as NodeData,
...(n.parent_id && parentIsZone
? { parentId: n.parent_id }
: n.parent_id && parentIsContainer
? { parentId: n.parent_id, extent: 'parent' as const }
: {}),
// Container hosts (Proxmox/VM/LXC/docker in container_mode) get a default
// box if none was saved. Every other node — including LEAF vm/lxc/docker
// nodes nested inside a container — restores its own saved width/height.
// Gating on container_mode (not type) is what keeps a resized nested node
// from snapping back to content-fit on reload.
...(['proxmox', 'vm', 'lxc', 'docker_host'].includes(normalizedType) && n.container_mode !== false
? { width: n.width ?? 300, height: n.height ?? 200 }
: {
...(n.width ? { width: n.width } : {}),
...(n.height ? { height: n.height } : {}),
}),
}
}
export function deserializeApiEdge(e: ApiEdge): Edge<EdgeData> {
return {
id: e.id,
source: e.source,
target: e.target,
type: e.type,
sourceHandle: e.source_handle ?? null,
targetHandle: e.target_handle ?? null,
data: e as unknown as EdgeData,
}
}
// Legacy Proxmox nodes had two always-on cluster handles ('cluster-left' /
// 'cluster-right'). Those are gone — cluster links now use the normal, per-side
// connection points. On load we remap any edge still bound to a cluster handle
// onto the matching left/right slot-0 handle and give that node's side a
// connection point (count → at least 1) so the link survives. The edge's
// 'cluster' type/colour is untouched.
const CLUSTER_HANDLE_SIDE: Record<string, Side> = {
'cluster-left': 'left',
'cluster-right': 'right',
}
export function migrateClusterHandles(
nodes: Node<NodeData>[],
edges: Edge<EdgeData>[],
): { nodes: Node<NodeData>[]; edges: Edge<EdgeData>[] } {
// nodeId → sides that need at least one connection point after remap.
const needed = new Map<string, Set<Side>>()
const mark = (id: string, side: Side) => {
const set = needed.get(id) ?? new Set<Side>()
set.add(side)
needed.set(id, set)
}
const migratedEdges = edges.map((e) => {
const srcSide = e.sourceHandle ? CLUSTER_HANDLE_SIDE[e.sourceHandle] : undefined
const tgtSide = e.targetHandle ? CLUSTER_HANDLE_SIDE[e.targetHandle] : undefined
if (!srcSide && !tgtSide) return e
const next = { ...e }
if (srcSide) { next.sourceHandle = handleId(srcSide, 0); mark(e.source, srcSide) }
if (tgtSide) { next.targetHandle = handleId(tgtSide, 0); mark(e.target, tgtSide) }
return next
})
if (needed.size === 0) return { nodes, edges: migratedEdges }
const migratedNodes = nodes.map((n) => {
const sides = needed.get(n.id)
if (!sides) return n
const data: NodeData = { ...n.data }
for (const side of sides) {
const field = handleCountField(side)
data[field] = Math.max((data[field] as number | undefined) ?? 0, 1)
}
return { ...n, data }
})
return { nodes: migratedNodes, edges: migratedEdges }
}
/**
* Turn a canvas API payload into React Flow nodes/edges. The single entry point
* for every view that renders a saved canvas (editor, live view), so the
* parent maps a node needs to keep its `parentId` — containers and zones —
* cannot drift between them.
*/
export function deserializeApiCanvas(
apiNodes: ApiNode[],
apiEdges: ApiEdge[],
): { nodes: Node<NodeData>[]; edges: Edge<EdgeData>[] } {
const proxmoxContainerMap = new Map<string, boolean>(
apiNodes
.filter((n) => n.type === 'group' || n.container_mode === true)
.map((n) => [n.id, true])
)
const zoneIds = new Set(apiNodes.filter((n) => n.type === 'groupRect').map((n) => n.id))
return migrateClusterHandles(
apiNodes.map((n) => deserializeApiNode(n, proxmoxContainerMap, zoneIds)),
apiEdges.map(deserializeApiEdge),
)
}