Skip to content

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

10.9 KB
Raw Blame
/**
 * Rack canvas — domain types.
 *
 * A rack canvas is a design of `design_type: 'rack'`. These camelCase shapes are
 * what the store and components work with; `@/utils/rackSerializer` maps them to
 * and from the snake_case API payloads.
 */
// Type-only, so the cycle with `./index` (which re-exports this module) is
// erased at compile time. Cables reuse the logical canvas' property records.
import type { NodeProperty } from './index'

/** Horizontal grid inside a rack. 12 columns = full width, 6 = half, 4 = third. */
export const RACK_COLUMNS = 12

export type RackWidthStandard = '19' | '10'

/** 1U is at the bottom (real-world rails) or at the top (some diagram tools). */
export type RackNumbering = 'bottom-up' | 'top-down'

export interface RackStyle {
  /** Frame / chassis colour. */
  frame: string
  /** Rail strip colour. */
  rail: string
  /** Empty slot colour, seen between mounted gear. */
  interior: string
  /** Show the U number strip alongside the rails. */
  showNumbers: boolean
  /** Draw side panels (enclosed cabinet) instead of an open frame. */
  enclosed: boolean
}

export interface Rack {
  id: string
  name: string
  /** Total usable height in U. */
  uHeight: number
  widthStandard: RackWidthStandard
  numbering: RackNumbering
  style: RackStyle
  /** Free-text location label ("garage", "office closet"). */
  location?: string
  /** Position on the canvas. */
  position: { x: number; y: number }
}

// ---------------------------------------------------------------------------
// Ports
// ---------------------------------------------------------------------------

/** Only data ports for now — power cabling is out of v1. */
export type PortType = 'rj45' | 'sfp' | 'sfp+'

export interface Port {
  id: string
  label: string
  type: PortType
  /**
   * Position on the faceplate, expressed in faceplate-local unit coordinates
   * (0..1 on both axes) so a port keeps its spot at any zoom level.
   */
  x: number
  y: number
}

/**
 * The rack modelisation of a device — what it looks like in *any* rack.
 *
 * Owned by the Device Inventory row, not by the mount: a device wears the same
 * front panel, at the same size, with the same ports wherever it is racked.
 * Only its placement (`rackId`, `uStart`, `colStart`), its pinned status and its
 * label stay per canvas. Editing a mount writes this back, silently, for every
 * other rack.
 *
 * Full mode only. Standalone has no inventory to hang it on, so ports there stay
 * per mount (see `standaloneStorage`).
 */
export interface RackModel {
  faceplateId: string
  /** Null when the device was modelled before a size was recorded. */
  uHeight: number | null
  colSpan: number | null
  color: string | null
  ports: Port[]
}

// ---------------------------------------------------------------------------
// Faceplates
// ---------------------------------------------------------------------------

export type FaceplateElement =
  | { kind: 'panel'; fill: string; stroke?: string }
  | { kind: 'vents'; x: number; y: number; w: number; h: number; cols: number; rows: number; fill?: string }
  | { kind: 'bays'; x: number; y: number; w: number; h: number; cols: number; rows: number; fill?: string }
  | { kind: 'strip'; x: number; y: number; w: number; h: number; fill: string }
  /**
   * Power outlets. Artwork only — outlets are drawn but never cabled, since
   * power is out of v1.
   */
  | { kind: 'outlets'; x: number; y: number; w: number; h: number; count: number }

export type FaceplateKind = 'device' | 'accessory'

/** Horizontal band reserved for the device name, in unit coordinates. */
export interface LabelBox {
  x: number
  w: number
  /**
   * Vertical centre of the name band, 0..1, default 0.5.
   *
   * Rack gear wears its name across the middle. Tall desktop boxes do not —
   * their front is drive trays, and the badge sits on a strip at the bottom.
   * The status LED rides the same band.
   */
  y?: number
}

export interface FaceplateTemplate {
  id: string
  label: string
  kind: FaceplateKind
  /** Category used to group the picker list. */
  group: string
  /** Suggested height in U when the template is applied. */
  uHeight: number
  /** Suggested width in rack columns (see RACK_COLUMNS). */
  colSpan: number
  /** Static artwork, drawn in faceplate-local unit coordinates (0..1). */
  elements: FaceplateElement[]
  /** Ports pre-filled on apply. The user can add/remove afterwards. */
  ports: Omit<Port, 'id'>[]
  /**
   * Patch-facing gear (switches, patch panels) always shows its ports; on
   * everything else ports only appear on hover, selection or in patch mode.
   */
  alwaysShowPorts?: boolean
  /** Name band. Ports and artwork must stay clear of it. */
  labelBox: LabelBox
  /** Devices get a status LED; accessories do not. */
  statusLed?: boolean
}

// ---------------------------------------------------------------------------
// Mounted devices
// ---------------------------------------------------------------------------

export type DeviceStatus = 'online' | 'offline' | 'unknown'

/**
 * What a mount's Status field holds: a state the user pinned by hand, or `auto`
 * — "check device", i.e. follow the status check already configured on the
 * matching logical-canvas node (ping / http / ssh…). The rack runs no checker
 * of its own, so `auto` only means anything for a mount whose inventory entry
 * resolves to a node; it renders as `unknown` otherwise.
 */
export type MountStatus = DeviceStatus | 'auto'

export interface RackDevice {
  id: string
  rackId: string
  /**
   * Device Inventory entry this mount represents. Null for accessories (blank
   * panels, shelves) that exist only in the rack view.
   *
   * Unmounting never deletes the inventory entry — the inventory outlives both
   * the rack mount and any canvas node, which is the whole point of keying on it.
   */
  deviceId: string | null
  /**
   * Logical-canvas node for the same hardware, when one exists. Read-only here:
   * resolved by the backend from the inventory entry, used for live status and
   * for seeding cables from the network design's edges.
   */
  nodeId: string | null
  label: string
  /** Lowest U occupied, 1-based, always counted from the bottom rail. */
  uStart: number
  uHeight: number
  /** Left edge on the 12-column grid, 0-based. */
  colStart: number
  colSpan: number
  faceplateId: string
  /** Overrides the faceplate panel fill when set. */
  color?: string
  /** Pinned state, or `auto` to follow the linked node's check. */
  status: MountStatus
  /**
   * Per-mount override of when the plate draws its sockets. Absent means
   * `auto` — see `PortVisibility`.
   */
  portVisibility?: PortVisibility
  ports: Port[]
}

/**
 * When a mount draws its ports.
 *
 * * `auto` — the faceplate decides: patch-facing gear (switches, patch panels,
 *   `FaceplateTemplate.alwaysShowPorts`) always shows them, everything else
 *   only on hover, selection or in patch mode. The default.
 * * `always` — always drawn, whatever the plate.
 * * `hover` — only on hover, selection or in patch mode, even for a switch.
 *
 * A display choice about this mount on this canvas, not a fact about the
 * hardware: it lives on the rack mount, never on the inventory entry.
 */
export type PortVisibility = 'auto' | 'always' | 'hover'

// ---------------------------------------------------------------------------
// Cabling
// ---------------------------------------------------------------------------

export type CableType = 'ethernet' | 'fiber'

/**
 * Extra facts carried by a cable — length, VLAN, patch reference, whatever the
 * user needs. Same record shape as a node's properties (`key`/`value`/`icon`/
 * `visible`), and the same rule: `visible` puts it on the canvas.
 */
export type CableProperty = NodeProperty

export interface Cable {
  id: string
  type: CableType
  color: string
  label?: string
  /** Print the label alongside the run on the canvas. Off by default. */
  labelVisible?: boolean
  /** Free-form key/value facts; the `visible` ones are drawn on the canvas. */
  properties?: CableProperty[]
  from: { deviceId: string; portId: string }
  to: { deviceId: string; portId: string }
}

/** How the cabling overlay behaves. */
export type CableVisibility = 'hover' | 'always' | 'hidden'

// ---------------------------------------------------------------------------
// Inventory
// ---------------------------------------------------------------------------

/** One fingerprinted service, as the mount's info panel prints it. */
export interface InventoryService {
  port: number | null
  name: string | null
}

/**
 * The logical-canvas view of the same hardware, read-only in the rack.
 *
 * Resolved server-side from the inventory entry (IEEE, then IP). Present only
 * once the device has been approved onto a canvas.
 */
export interface LinkedNodeInfo {
  id: string
  label: string | null
  /** `NodeType` on the canvas; free-form here, the rack only prints it. */
  type: string | null
  ip: string | null
  mac: string | null
  hostname: string | null
  os: string | null
  /** Status check the node runs — what `auto` on a mount actually follows. */
  checkMethod: string | null
  /** Canvas the node is drawn on. */
  designId: string | null
  designName: string | null
  /** ISO timestamp of the last successful check, when the node has one. */
  lastSeen: string | null
}

/**
 * A Device Inventory entry offered to the rack tray.
 *
 * Sourced from the backend's `pending_devices` — the same list the Device
 * Inventory panel shows. Entries survive approval and node deletion, so racking
 * and unracking never mutates them.
 */
export interface InventoryDevice {
  id: string
  label: string
  /** `suggested_type` from discovery; free-form, may be unknown to the UI. */
  type: string | null
  /**
   * How the entry got into the inventory: `arp`, `proxmox`, `zigbee`, `manual`,
   * or `rack` for gear the rack canvas created itself.
   *
   * The rack only reads it to know which rows it owns: relinking a mount to
   * another entry discards the placeholder it created, and never a row
   * discovery or the user put there.
   */
  discoverySource?: string | null
  ip?: string | null
  /** MAC, or the IEEE address for a mesh device. */
  mac?: string | null
  hostname?: string | null
  os?: string | null
  /** Services discovery fingerprinted, falling back to the canvas node's. */
  services?: InventoryService[]
  /** Live status of the matching canvas node, `unknown` when there is none. */
  status: DeviceStatus
  /** Matching canvas node, when the device is on a logical canvas. */
  nodeId: string | null
  /** What that node holds. Null when the device is on no canvas. */
  node?: LinkedNodeInfo | null
  /** Already mounted somewhere in this rack design. */
  racked: boolean
  /** Faceplate proposed when the device is dropped into a rack. */
  suggestedFaceplateId: string
  /**
   * Front panel already modelled for this device, reused on every mount. Null
   * for a device never racked — `suggestedFaceplateId` then seeds the plate.
   */
  rackModel?: RackModel | null
}