Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
import type { Node } from '@xyflow/react'
import type { Design, InventoryEntry, NodeData } from '@/types'
import { ipToInt, parseCidr } from '@/utils/subnet'
import type { DocState, DocumentSummary, GroupBy, TreeGroup, TreeLeaf } from './types'
/**
* The Devices tree, pivoted.
*
* Every grouping the user can pick is derivable from data the app has already
* loaded — the inventory rows, the canvas nodes, the racks — so the tree is
* built here rather than fetched. Re-pivoting is then instant and there is no
* server-side tree to keep in sync with the canvas.
*
* The Library tree is the opposite: real folders the user files by hand, so it
* comes straight from `parent_id` and never re-shapes.
*/
const UNGROUPED = 'Ungrouped'
/** Canvas furniture. A zone or a group is a container, not a device. */
const FURNITURE = new Set(['group', 'groupRect', 'text'])
/** Types that are a guest rather than a box you can touch. */
const VIRTUAL_TYPES = new Set(['vm', 'lxc', 'docker_container'])
/** Types that host guests. Reported separately so the split reads as three. */
const HOST_TYPES = new Set(['proxmox', 'docker_host'])
export type Physicality = 'Physical' | 'Virtual' | 'Host'
/**
* Physical, virtual, or a host running guests.
*
* The type decides it; `container_mode` and having children are the fallback
* for a device typed generically but drawn as a container.
*/
export function physicality(
type: string | null | undefined,
opts: { hasChildren?: boolean; containerMode?: boolean } = {},
): Physicality {
const t = type ?? ''
if (VIRTUAL_TYPES.has(t)) return 'Virtual'
if (HOST_TYPES.has(t)) return 'Host'
if (opts.containerMode || opts.hasChildren) return 'Host'
return 'Physical'
}
/** Every IP a device declares. The column is a comma-separated list. */
export function splitIps(ip: string | null | undefined): string[] {
return (ip ?? '')
.split(',')
.map((token) => token.trim())
.filter(Boolean)
}
/** The /24 an address sits in, for grouping when no CIDR is configured. */
export function slash24(ip: string): string | null {
if (ipToInt(ip) === null) return null
const octets = ip.split('.')
return `${octets[0]}.${octets[1]}.${octets[2]}.0/24`
}
/**
* Which of the configured ranges an address falls in, else its own /24.
* A device declaring several addresses lands under each of their subnets.
*/
export function subnetsOf(device: InventoryEntry, ranges: string[]): string[] {
const found = new Set<string>()
for (const ip of splitIps(device.ip)) {
const value = ipToInt(ip)
if (value === null) continue
const match = ranges.find((cidr) => {
const parsed = parseCidr(cidr)
if (!parsed) return false
const mask = parsed.bits === 0 ? 0 : (-1 << (32 - parsed.bits)) >>> 0
return ((value & mask) >>> 0) === parsed.base
})
const subnet = match ?? slash24(ip)
if (subnet) found.add(subnet)
}
return found.size ? [...found] : [UNGROUPED]
}
export interface DeviceContext {
/**
* Nodes of the canvas that is currently loaded. The app only ever holds one
* canvas at a time, so the "Canvas" pivot answers "on this one or not"
* rather than naming every canvas a device appears on.
*/
nodes: Node<NodeData>[]
designs: Design[]
/** The design those nodes belong to. */
activeDesignId?: string | null
/** deviceId → rack name, from the rack store when a rack canvas is loaded. */
racksByDevice?: Record<string, string>
/** CIDRs from the scan settings; falls back to a per-address /24. */
ranges?: string[]
}
interface NodeFacts {
zone?: string
group?: string
canvas?: string
hasChildren: boolean
containerMode: boolean
type?: string
}
/**
* What the canvas knows about each device: the containers it sits in and the
* canvas it is drawn on. A device drawn twice keeps the first placement per
* grouping, so it appears once under each distinct answer.
*/
export function nodeFactsByDevice(context: DeviceContext): Record<string, NodeFacts> {
const byId = new Map(context.nodes.map((n) => [n.id, n]))
const designName = new Map(context.designs.map((d) => [d.id, d.name]))
const parentOf = new Map<string, string>()
for (const node of context.nodes) {
if (node.data.parent_id) parentOf.set(node.id, node.data.parent_id)
}
const hasChildren = new Set([...parentOf.values()])
const facts: Record<string, NodeFacts> = {}
for (const node of context.nodes) {
const deviceId = node.data.device_id
if (!deviceId || FURNITURE.has(node.data.type)) continue
const entry: NodeFacts = facts[deviceId] ?? {
hasChildren: hasChildren.has(node.id),
containerMode: node.data.container_mode === true,
type: node.data.type,
}
// Walk up to the nearest zone and the nearest group; they are different
// containers and a node can sit in one, the other, or both.
const seen = new Set<string>()
let cursor = node.data.parent_id
while (cursor && !seen.has(cursor)) {
seen.add(cursor)
const parent = byId.get(cursor)
if (!parent) break
if (parent.data.type === 'groupRect' && !entry.zone) entry.zone = parent.data.label
if (parent.data.type === 'group' && !entry.group) entry.group = parent.data.label
cursor = parent.data.parent_id
}
if (!entry.canvas && context.activeDesignId) {
entry.canvas = designName.get(context.activeDesignId)
}
facts[deviceId] = entry
}
return facts
}
/** The buckets one device belongs to under a given pivot. Usually exactly one. */
export function bucketsFor(
device: InventoryEntry,
groupBy: GroupBy,
facts: NodeFacts | undefined,
doc: DocumentSummary | undefined,
context: DeviceContext,
): string[] {
switch (groupBy) {
case 'zone':
return [facts?.zone || 'Unzoned']
case 'group':
return [facts?.group || 'Ungrouped']
case 'type':
return [device.type || device.suggested_type || 'Untyped']
case 'physicality':
return [
physicality(device.type || device.suggested_type || facts?.type, {
hasChildren: facts?.hasChildren,
containerMode: facts?.containerMode,
}),
]
case 'subnet':
return subnetsOf(device, context.ranges ?? [])
case 'canvas':
return [facts?.canvas || 'Not on this canvas']
case 'rack':
return [context.racksByDevice?.[device.id] || 'Not racked']
case 'vendor':
return [device.vendor || 'Unknown vendor']
case 'source': {
const sources = device.discovery_sources?.length
? device.discovery_sources
: [device.discovery_source].filter(Boolean)
return sources.length ? (sources as string[]) : [UNGROUPED]
}
case 'status':
return [device.status_live || 'unknown']
case 'tag':
return doc?.tags?.length ? doc.tags : ['Untagged']
case 'flat':
default:
return ['All devices']
}
}
/** What the badge next to a device says. */
export function docState(
doc: DocumentSummary | undefined,
opts: { drifted?: boolean; overdue?: boolean } = {},
): DocState {
if (!doc) return 'none'
if (opts.drifted) return 'drifted'
if (opts.overdue) return 'overdue'
return doc.edited_at ? 'written' : 'header-only'
}
export function deviceLabel(device: InventoryEntry): string {
return device.label || device.friendly_name || device.hostname || device.ip || 'Unnamed device'
}
const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })
/** Groups last-resort buckets to the bottom, everything else alphabetically. */
function compareGroups(a: TreeGroup, b: TreeGroup): number {
const trailing = new Set(['Unzoned', 'Ungrouped', 'Untyped', 'Untagged', 'Not racked', 'Not on this canvas', 'Unknown vendor', UNGROUPED])
const aLast = trailing.has(a.label)
const bLast = trailing.has(b.label)
if (aLast !== bLast) return aLast ? 1 : -1
return collator.compare(a.label, b.label)
}
export interface DeviceTreeOptions {
groupBy: GroupBy
devices: InventoryEntry[]
docs: DocumentSummary[]
context: DeviceContext
/** Document ids the coverage pass flagged. */
drifted?: Set<string>
overdue?: Set<string>
}
/** The Devices root, grouped as asked. */
export function buildDeviceTree(options: DeviceTreeOptions): TreeGroup[] {
const { groupBy, devices, docs, context } = options
const docByDevice = new Map(docs.filter((d) => d.device_id).map((d) => [d.device_id as string, d]))
const facts = nodeFactsByDevice(context)
const groups = new Map<string, TreeLeaf[]>()
for (const device of devices) {
const doc = docByDevice.get(device.id)
const leaf: TreeLeaf = {
id: doc?.id ?? `device:${device.id}`,
// Once a device is documented the row is that document, so it carries the
// name the document gives itself — the `title:` line the user edits — and
// falls back to the inventory's label only while there is nothing to open.
label: doc?.title?.trim() || deviceLabel(device),
docId: doc?.id,
deviceId: device.id,
kind: doc ? 'device' : 'device-without-doc',
state: docState(doc, {
drifted: doc ? options.drifted?.has(doc.id) : false,
overdue: doc ? options.overdue?.has(doc.id) : false,
}),
}
for (const bucket of bucketsFor(device, groupBy, facts[device.id], doc, context)) {
const items = groups.get(bucket) ?? []
items.push(leaf)
groups.set(bucket, items)
}
}
return [...groups.entries()]
.map(([label, items]) => ({
key: `${groupBy}:${label}`,
label,
items: items.sort((a, b) => collator.compare(a.label, b.label)),
}))
.sort(compareGroups)
}
/** The Library root: real folders, nested by `parent_id`. */
export function buildLibraryTree(docs: DocumentSummary[]): TreeLeaf[] {
const tree = docs.filter((d) => d.kind === 'page' || d.kind === 'folder')
const byParent = new Map<string | null, DocumentSummary[]>()
for (const doc of tree) {
const key = doc.parent_id ?? null
byParent.set(key, [...(byParent.get(key) ?? []), doc])
}
const seen = new Set<string>()
const build = (parentId: string | null): TreeLeaf[] =>
(byParent.get(parentId) ?? [])
.filter((doc) => !seen.has(doc.id))
.sort((a, b) => a.sort_order - b.sort_order || collator.compare(a.title, b.title))
.map((doc): TreeLeaf => {
// A cycle would recurse forever; a folder can only be built once.
seen.add(doc.id)
return {
id: doc.id,
label: doc.title,
docId: doc.id,
kind: doc.kind,
state: docState(doc),
icon: doc.icon,
children: doc.kind === 'folder' ? build(doc.id) : undefined,
}
})
return build(null)
}
/**
* The documents that describe something elsewhere — a device, a canvas node, a
* design — grouped without asking the inventory anything.
*
* `buildDeviceTree` pivots on the inventory rows, the canvas nodes and the
* racks. The public documentation view is handed none of those, and should not
* be: they are full of addresses and hardware. These documents still have to
* appear there, so they are grouped by what they carry themselves — their own
* frontmatter tags, or one flat bucket. The label is the document's own title,
* denormalized onto the row for exactly this reason: it outlives the thing it
* describes.
*/
export function buildLinkedDocTree(
docs: DocumentSummary[],
groupBy: 'tag' | 'flat',
opts: { overdue?: Set<string> } = {},
): TreeGroup[] {
const groups = new Map<string, TreeLeaf[]>()
for (const doc of docs) {
if (doc.kind === 'page' || doc.kind === 'folder') continue
const leaf: TreeLeaf = {
id: doc.id,
label: doc.title,
docId: doc.id,
kind: doc.kind,
// No drift flag: deciding it needs the inventory row this view has no
// access to, so the badge says written / header-only / overdue only.
state: docState(doc, { overdue: opts.overdue?.has(doc.id) }),
icon: doc.icon,
}
const buckets =
groupBy === 'tag' ? (doc.tags?.length ? doc.tags : ['Untagged']) : ['All documents']
for (const bucket of buckets) {
const items = groups.get(bucket) ?? []
items.push(leaf)
groups.set(bucket, items)
}
}
return [...groups.entries()]
.map(([label, items]) => ({
key: `${groupBy}:${label}`,
label,
items: items.sort((a, b) => collator.compare(a.label, b.label)),
}))
.sort(compareGroups)
}
/** Filter a tree by a typed query, keeping the folders that lead to a match. */
export function filterTree(items: TreeLeaf[], query: string): TreeLeaf[] {
const needle = query.trim().toLowerCase()
if (!needle) return items
const walk = (leaves: TreeLeaf[]): TreeLeaf[] =>
leaves
.map((leaf): TreeLeaf | null => {
const children = leaf.children ? walk(leaf.children) : undefined
const hit = leaf.label.toLowerCase().includes(needle)
if (!hit && !children?.length) return null
return { ...leaf, children }
})
.filter((leaf): leaf is TreeLeaf => leaf !== null)
return walk(items)
}
export function filterGroups(groups: TreeGroup[], query: string): TreeGroup[] {
const needle = query.trim().toLowerCase()
if (!needle) return groups
return groups
.map((group) => ({
...group,
items: group.label.toLowerCase().includes(needle)
? group.items
: group.items.filter((item) => item.label.toLowerCase().includes(needle)),
}))
.filter((group) => group.items.length > 0)
}
/** Whether `doc` sits anywhere under `ancestorId`. */
export function isDescendant(
all: DocumentSummary[],
doc: DocumentSummary,
ancestorId: string,
): boolean {
const byId = new Map(all.map((d) => [d.id, d]))
const seen = new Set<string>()
let cursor = doc.parent_id ?? null
while (cursor && !seen.has(cursor)) {
if (cursor === ancestorId) return true
seen.add(cursor)
cursor = byId.get(cursor)?.parent_id ?? null
}
return false
}
/**
* Whether `doc` can be filed under `targetId` — `null` being the Library root.
*
* The server enforces the same four rules; deciding them here too is what lets
* a drag refuse the drop instead of asking, moving, and then failing.
*/
export function canMoveInto(
docs: DocumentSummary[],
doc: DocumentSummary,
targetId: string | null,
): boolean {
if (doc.kind !== 'page' && doc.kind !== 'folder') return false
if ((doc.parent_id ?? null) === targetId) return false
if (targetId === null) return true
if (targetId === doc.id) return false
const target = docs.find((d) => d.id === targetId)
if (!target || target.kind !== 'folder') return false
return !isDescendant(docs, target, doc.id)
}