Skip to content

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

fix(unifi): put the imported properties on the NodeProperty contract

Pouzorc8351b01a106
diff --git a/backend/app/api/routes/unifi.py b/backend/app/api/routes/unifi.py
index 33c475a..778a188 100644
--- a/backend/app/api/routes/unifi.py
+++ b/backend/app/api/routes/unifi.py
@@ -26,6 +26,7 @@ from app.services.unifi_service import (
SOURCE_CLIENT,
SOURCE_INFRA,
fetch_unifi_inventory,
+ merge_unifi_properties,
test_unifi_connection,
)
@@ -264,6 +265,14 @@ async def _persist_devices(
existing.ieee_address = existing.ieee_address or ieee
existing.ip = ip or existing.ip
existing.mac = existing.mac or mac
+ # Refresh the values, keep the visibility the user chose and any
+ # property they added by hand. A row merged from another source
+ # gains the controller's facts here rather than staying without
+ # them — they were only ever written when the row was created.
+ existing.properties = merge_unifi_properties(
+ list(existing.properties or []),
+ dev.get("properties", []),
+ )
# A row another source owns keeps its own description: the
# controller knows a client only as a name and a MAC, so letting it
# win would retype a Proxmox LXC as a plain "computer" and replace
diff --git a/backend/app/services/unifi_service.py b/backend/app/services/unifi_service.py
index a9eb5ce..0a45112 100644
--- a/backend/app/services/unifi_service.py
+++ b/backend/app/services/unifi_service.py
@@ -9,8 +9,14 @@ from typing import Any
import httpx
+from app.services.zigbee_service import merge_zigbee_properties
+
logger = logging.getLogger(__name__)
+# Same NodeProperty shape and the same visibility-preservation rules, so the
+# re-sync update path reuses the contract verbatim.
+merge_unifi_properties = merge_zigbee_properties
+
class UnifiApiError(ConnectionError):
"""No UniFi API path answered 200 for a request.
@@ -145,8 +151,8 @@ def _merge(acc: dict[str, dict[str, Any]], dev: dict[str, Any] | None) -> None:
# Same device from a richer source: take its values, keep what it lacks.
for field, value in dev.items():
if field == "properties":
- names = {p["name"] for p in value}
- value = value + [p for p in prev["properties"] if p["name"] not in names]
+ keys = {p["key"] for p in value}
+ value = value + [p for p in prev["properties"] if p["key"] not in keys]
if value:
prev[field] = value
@@ -375,6 +381,15 @@ async def _fetch_known_clients(
)
+def _prop(key: str, value: str, icon: str | None = None) -> dict[str, Any]:
+ """One NodeProperty row: ``{key, value, icon, visible}``.
+
+ ``visible`` is False because the whole inventory convention is opt-in — a
+ device carries more facts than a canvas should print.
+ """
+ return {"key": key, "value": value, "icon": icon, "visible": False}
+
+
def _normalize(d: dict[str, Any]) -> dict[str, Any]:
"""Convert a raw UniFi device record to a homelable-compatible dict."""
raw_type = (d.get("type") or "").lower()
@@ -388,16 +403,19 @@ def _normalize(d: dict[str, Any]) -> dict[str, Any]:
ieee = f"unifi-{mac}" if mac else f"unifi-{name}"
- props: list[dict[str, str]] = []
+ # NodeProperty rows: keyed, with an icon from PROPERTY_ICONS, hidden until
+ # the user opts in from the right panel — as the Proxmox and mesh importers
+ # build theirs.
+ props: list[dict[str, Any]] = []
if raw_type:
- props.append({"name": "UniFi type", "value": raw_type})
+ props.append(_prop("UniFi type", raw_type, "Tag"))
if model:
- props.append({"name": "Model", "value": model})
+ props.append(_prop("Model", model, "Box"))
if version:
- props.append({"name": "Firmware", "value": version})
+ props.append(_prop("Firmware", version, "CircuitBoard"))
uptime = d.get("uptime")
if uptime is not None:
- props.append({"name": "Uptime (s)", "value": str(uptime)})
+ props.append(_prop("Uptime (s)", str(uptime), "Clock"))
return {
"ieee_address": ieee,
@@ -429,20 +447,28 @@ def _normalize_client(d: dict[str, Any]) -> dict[str, Any] | None:
ip = d.get("ip") or d.get("fixed_ip") or None
wired = d.get("is_wired")
- props: list[dict[str, str]] = []
+ props: list[dict[str, Any]] = []
if wired is not None:
- props.append({"name": "Connection", "value": "wired" if wired else "wifi"})
+ props.append(_prop(
+ "Connection",
+ "wired" if wired else "wifi",
+ "EthernetPort" if wired else "Wifi",
+ ))
uplink = d.get("sw_mac") or d.get("ap_mac")
if uplink:
label = "Switch" if d.get("sw_mac") else "Access point"
- props.append({"name": label, "value": str(uplink).lower()})
+ props.append(_prop(label, str(uplink).lower(), "Network"))
port = d.get("sw_port")
if port is not None:
- props.append({"name": "Switch port", "value": str(port)})
- for key, label in (("essid", "SSID"), ("network", "Network"), ("oui", "OUI")):
- value = d.get(key)
+ props.append(_prop("Switch port", str(port), "EthernetPort"))
+ for field, label, icon in (
+ ("essid", "SSID", "Wifi"),
+ ("network", "Network", "Globe"),
+ ("oui", "OUI", "Tag"),
+ ):
+ value = d.get(field)
if value:
- props.append({"name": label, "value": str(value)})
+ props.append(_prop(label, str(value), icon))
return {
"ieee_address": f"unifi-{mac}",
diff --git a/backend/tests/test_unifi_router.py b/backend/tests/test_unifi_router.py
index bb4834e..253106b 100644
--- a/backend/tests/test_unifi_router.py
+++ b/backend/tests/test_unifi_router.py
@@ -401,3 +401,87 @@ async def test_the_oldest_row_wins_when_two_share_a_mac(
found = await _find_existing(db_session, "unifi-bc:24:11:8d:26:ed", "bc:24:11:8d:26:ed")
assert found is not None
assert found.ieee_address == "pve-proxmox-1"
+
+
+# --- properties on re-sync --------------------------------------------------
+
+def _prop(key: str, value: str, visible: bool = False) -> dict:
+ return {"key": key, "value": value, "icon": None, "visible": visible}
+
+
+async def test_resync_refreshes_values_and_keeps_the_users_choices(
+ db_session: AsyncSession,
+) -> None:
+ """Properties were written only when a row was created, so a re-sync left
+ the firmware and uptime frozen at whatever the first import saw."""
+ row = InventoryDevice(
+ ieee_address="unifi-00:27:22:e0:00:01",
+ mac="00:27:22:e0:00:01",
+ status="pending",
+ discovery_source="unifi",
+ discovery_sources=["unifi"],
+ properties=[
+ _prop("Firmware", "8.6.11.18870", visible=True),
+ _prop("Rack unit", "U12"), # added by hand from the right panel
+ ],
+ )
+ db_session.add(row)
+ await db_session.commit()
+
+ await _persist_devices(db_session, [{
+ "ieee_address": "unifi-00:27:22:e0:00:01",
+ "mac": "00:27:22:e0:00:01",
+ "hostname": "U7 Pro",
+ "label": "U7 Pro",
+ "type": "ap",
+ "properties": [
+ _prop("Firmware", "8.7.0.99999"),
+ _prop("Uptime (s)", "4200"),
+ ],
+ "source": "unifi",
+ }])
+
+ updated = (await db_session.execute(select(InventoryDevice))).scalars().first()
+ assert updated is not None
+ by_key = {p["key"]: p for p in updated.properties}
+ assert by_key["Firmware"]["value"] == "8.7.0.99999"
+ # The user turned Firmware on; a re-sync must not turn it back off.
+ assert by_key["Firmware"]["visible"] is True
+ assert by_key["Uptime (s)"]["value"] == "4200"
+ # Their own property survives untouched.
+ assert by_key["Rack unit"]["value"] == "U12"
+
+
+async def test_a_merged_row_gains_the_controller_properties(
+ db_session: AsyncSession,
+) -> None:
+ row = InventoryDevice(
+ ieee_address="pve-proxmox-129",
+ mac="bc:24:11:8d:26:ed",
+ status="approved",
+ discovery_source="proxmox",
+ discovery_sources=["proxmox"],
+ properties=[_prop("VMID", "129"), _prop("Kind", "LXC")],
+ )
+ db_session.add(row)
+ await db_session.commit()
+
+ await _persist_devices(db_session, [{
+ "ieee_address": "unifi-bc:24:11:8d:26:ed",
+ "mac": "bc:24:11:8d:26:ed",
+ "hostname": "Paperless",
+ "label": "Paperless",
+ "type": "computer",
+ "properties": [_prop("Connection", "wired"), _prop("Switch port", "7")],
+ "source": "unifi-client",
+ }])
+
+ merged = (await db_session.execute(select(InventoryDevice))).scalars().first()
+ assert merged is not None
+ by_key = {p["key"]: p["value"] for p in merged.properties}
+ # Proxmox's facts stay, the controller's are added alongside.
+ assert by_key == {
+ "VMID": "129", "Kind": "LXC", "Connection": "wired", "Switch port": "7",
+ }
diff --git a/backend/tests/test_unifi_service.py b/backend/tests/test_unifi_service.py
index e9324cd..a4e8368 100644
--- a/backend/tests/test_unifi_service.py
+++ b/backend/tests/test_unifi_service.py
@@ -199,7 +199,8 @@ async def test_inventory_maps_unifi_types_to_node_types() -> None:
assert ap["ip"] == "192.168.1.100"
assert ap["vendor"] == "Ubiquiti"
assert ap["model"] == "U7PRO"
- assert {"name": "Firmware", "value": "8.6.11.18870"} in ap["properties"]
+ assert {"key": "Firmware", "value": "8.6.11.18870", "icon": "CircuitBoard",
+ "visible": False} in ap["properties"]
# ── import modes ────────────────────────────────────────────────────────────
@@ -291,7 +292,7 @@ async def test_known_clients_can_be_imported_alone() -> None:
async def test_active_clients_carry_the_live_attachment() -> None:
devices, _ = await _fetch(infrastructure=False, active_clients=True)
assert len(devices) == 1
- props = {p["name"]: p["value"] for p in devices[0]["properties"]}
+ props = {p["key"]: p["value"] for p in devices[0]["properties"]}
assert devices[0]["ip"] == "192.168.1.50"
assert props["Switch"] == "00:27:22:e0:00:02"
assert props["Switch port"] == "7"
@@ -309,7 +310,7 @@ async def test_a_client_in_both_sources_is_merged_once() -> None:
# Live data wins for the IP, and the OUI from list/user survives.
assert paperless["ip"] == "192.168.1.50"
assert paperless["vendor"] == "Proxmox Server Solutions GmbH"
- assert {p["name"] for p in paperless["properties"]} >= {"Switch port", "OUI"}
+ assert {p["key"] for p in paperless["properties"]} >= {"Switch port", "OUI"}
@pytest.mark.asyncio
@@ -351,3 +352,51 @@ async def test_test_connection_counts_every_source_when_asked() -> None:
known_clients=True, active_clients=True,
)
assert counts == {"infrastructure": 3, "known_clients": 2, "active_clients": 1}
+
+
+# ── the NodeProperty contract ───────────────────────────────────────────────
+
+async def test_properties_follow_the_node_property_contract() -> None:
+ """key/value/icon/visible — not the {name, value} pairs this used to emit.
+
+ The inventory and the canvas address a property row by its `key`
+ (`_property_view_key`), and PropertyList reads `key`, `icon` and `visible`.
+ A `name` pair collapsed every row onto one keyless entry.
+ """
+ devices, _ = await _fetch(
+ infrastructure=True, known_clients=True, active_clients=True
+ )
+ for dev in devices:
+ for prop in dev["properties"]:
+ assert set(prop) == {"key", "value", "icon", "visible"}
+ assert isinstance(prop["key"], str) and prop["key"]
+ # Opt-in, like the Proxmox and mesh importers build theirs.
+ assert prop["visible"] is False
+
+
+async def test_a_wired_and_a_wifi_client_get_different_icons() -> None:
+ from app.services.unifi_service import _normalize_client
+
+ wired = _normalize_client({"mac": "aa:bb:cc:dd:ee:01", "is_wired": True})
+ wifi = _normalize_client({"mac": "aa:bb:cc:dd:ee:02", "is_wired": False})
+ assert wired is not None and wifi is not None
+ assert wired["properties"][0]["icon"] == "EthernetPort"
+ assert wifi["properties"][0]["icon"] == "Wifi"
+
+
+async def test_every_icon_is_one_the_front_end_can_render() -> None:
+ """PROPERTY_ICONS in frontend/src/utils/propertyIcons.ts is the whole set."""
+ known = {
+ "Battery", "Box", "CircuitBoard", "Clock", "Cpu", "Database",
+ "EthernetPort", "Globe", "Gpu", "HardDrive", "HdmiPort", "Hash", "Key",
+ "Layers", "Link", "MemoryStick", "Monitor", "Network", "Server",
+ "Shield", "Tag", "Thermometer", "Usb", "Wifi", "Zap",
+ }
+ devices, _ = await _fetch(
+ infrastructure=True, known_clients=True, active_clients=True
+ )
+ used = {p["icon"] for d in devices for p in d["properties"] if p["icon"]}
+ assert used and used <= known, f"unknown icon(s): {used - known}"