Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

13.9 KB
Raw Blame
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),
  )
}