Skip to content

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

fix(device-merge): refuse an automatic collapse that would destroy an IEEE

Pouzor16a089e19b3d
diff --git a/backend/app/services/device_merge.py b/backend/app/services/device_merge.py
index cf181f3..a86953b 100644
--- a/backend/app/services/device_merge.py
+++ b/backend/app/services/device_merge.py
@@ -278,6 +278,25 @@ async def _rewrite_links(db: AsyncSession, winner_ieee: str, loser_ieees: list[s
seen.add(key)
+def distinct_ieees(rows: list[InventoryDevice]) -> list[str]:
+ """Every distinct non-blank IEEE carried by ``rows``, first spelling wins.
+
+ ``ieee_address`` is UNIQUE and is what every other writer comes back to —
+ the import matches on it before anything else, the mesh links and the
+ Proxmox host→guest graph are keyed on it. A merge has exactly one row left
+ at the end, so it has room for exactly one of these: any group holding two
+ is a group that cannot be collapsed without destroying an identity. Callers
+ use this to refuse the collapse; :func:`merge_devices` uses it to say what
+ it dropped when the user asked for it anyway.
+ """
+ out: dict[str, str] = {}
+ for row in rows:
+ ieee = row.ieee_address
+ if ieee and not _blank(ieee):
+ out.setdefault(ieee.lower(), ieee)
+ return list(out.values())
+
+
async def merge_devices(
db: AsyncSession,
winner: InventoryDevice,
@@ -303,6 +322,7 @@ async def merge_devices(
"nodes_repointed": 0,
"documents_orphaned": 0,
"views_extended": 0,
+ "ieee_dropped": [],
}
loser_ids = [row.id for row in losers]
@@ -346,6 +366,27 @@ async def merge_devices(
# holding it is gone — assigned after the delete below.
adopted = loser_ieees[0]
+ # One row survives, so it can hold one IEEE. Every other distinct address in
+ # the group goes with the row that carried it, and whatever keys on it — a
+ # Proxmox import, a re-scan, a mesh writer — stops finding this device and
+ # mints a fresh duplicate instead. The automatic passes refuse such a group
+ # outright (`_group_candidates`, the scanner's `_collapse_targets`); reaching
+ # here means the user asked for it by hand, so it is allowed and recorded
+ # rather than vetoed. The mesh links themselves survive: `_rewrite_links`
+ # moves them onto the survivor's address below.
+ kept_ieee = adopted or winner.ieee_address
+ kept_key = kept_ieee.lower() if kept_ieee else None
+ ieee_dropped = [
+ ieee for ieee in distinct_ieees([winner, *losers]) if ieee.lower() != kept_key
+ ]
+ if ieee_dropped:
+ logger.warning(
+ "Inventory merge: %s keeps %s and drops %d other IEEE address(es) — "
+ "anything keying on %s will no longer find this device (%s)",
+ winner.id, kept_ieee or "no IEEE", len(ieee_dropped),
+ ", ".join(ieee_dropped), winner.label or winner.friendly_name or winner.ip,
+ )
+
for loser in losers:
await db.delete(loser)
await db.flush()
@@ -373,6 +414,7 @@ async def merge_devices(
"nodes_repointed": nodes.rowcount or 0,
"documents_orphaned": orphaned,
"views_extended": shown,
+ "ieee_dropped": ieee_dropped,
}
diff --git a/backend/app/services/scanner.py b/backend/app/services/scanner.py
index 60bfe46..7f49ff6 100644
--- a/backend/app/services/scanner.py
+++ b/backend/app/services/scanner.py
@@ -17,7 +17,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
from app.core.config import settings
from app.db.models import InventoryDevice, ScanRun
-from app.services.device_merge import merge_devices, reconcile_duplicates
+from app.services.device_merge import distinct_ieees, merge_devices, reconcile_duplicates
from app.services.discovery_sources import add_source
from app.services.fingerprint import fingerprint_ports, suggest_node_type
from app.services.http_probe import probe_open_ports
@@ -618,9 +618,28 @@ def _collapse_targets(
decide which of them loses its links: every approved row stands, and only
the pending ones are collapsed. The pair then stays visible in the inventory
for the user to sort out.
+
+ A group carrying two distinct IEEE addresses is left alone whole, for the
+ same reason the reconcile pass leaves it alone: the merge has room for one
+ address and would destroy the rest.
"""
approved = [row for row in group if row.status == "approved"]
keep = approved[0] if approved else group[0]
+ if len(distinct_ieees(group)) > 1:
+ # One row survives a merge, so it keeps one IEEE — collapsing this group
+ # would delete the others, and the next import or scan keying on one of
+ # them would no longer find the device and would mint a duplicate. Two
+ # distinct IEEEs sharing an address is not a duplicate anyway: it is two
+ # Proxmox guests behind one host, or two radios. Drop the group whole
+ # rather than guess which member does not belong — the same rule
+ # `_group_candidates` applies in the reconcile pass. The rows stay
+ # visible in the inventory, and the manual merge can still join them.
+ logger.info(
+ "Inventory collapse: leaving %d row(s) sharing an address alone — "
+ "their IEEE says they are different devices (%s)",
+ len(group), ", ".join(row.id for row in group),
+ )
+ return keep, []
if len(approved) > 1:
return keep, [row for row in group if row.status != "approved"]
return keep, [row for row in group if row is not keep]
diff --git a/backend/tests/test_device_merge.py b/backend/tests/test_device_merge.py
index 07d0825..85eb321 100644
--- a/backend/tests/test_device_merge.py
+++ b/backend/tests/test_device_merge.py
@@ -22,7 +22,13 @@ from app.db.models import (
Rack,
RackDevice,
)
-from app.services.device_merge import _naive, _newest, merge_devices, reconcile_duplicates
+from app.services.device_merge import (
+ _naive,
+ _newest,
+ distinct_ieees,
+ merge_devices,
+ reconcile_duplicates,
+)
def _at(day: int) -> datetime:
@@ -286,6 +292,69 @@ async def test_the_survivor_adopts_an_ieee_it_lacks(db_session):
assert winner.ieee_address == "pve-pve1-130"
+async def test_the_survivor_adopts_the_first_ieee_and_reports_the_rest(db_session):
+ """Regression for #453: a merge has room for one IEEE, so say what it drops.
+
+ Two losers carrying distinct addresses collapse onto an IEEE-less survivor.
+ Only the first can be adopted — `ieee_address` is UNIQUE — and the second
+ goes with the row that held it. The automatic passes refuse such a group
+ outright; a hand merge is allowed to do it, but never silently.
+ """
+ winner = await _device(db_session, id="w", ip="192.168.1.62", ieee_address=None)
+ first = await _device(db_session, id="a", ieee_address="0xAABB", discovered_at=_at(1))
+ second = await _device(db_session, id="b", ieee_address="0xCCDD", discovered_at=_at(2))
+
+ result = await merge_devices(db_session, winner, [first, second])
+ await db_session.flush()
+
+ assert winner.ieee_address == "0xAABB"
+ assert result["ieee_dropped"] == ["0xCCDD"]
+
+
+async def test_an_ieee_the_survivor_already_holds_is_not_reported_as_dropped(db_session):
+ winner = await _device(db_session, id="w", ieee_address="0xAABB", ip="192.168.1.62")
+ loser = await _device(db_session, id="l", ieee_address="0xaabb".upper(), ip="192.168.1.62")
+
+ result = await merge_devices(db_session, winner, [loser])
+
+ assert result["ieee_dropped"] == []
+
+
+async def test_a_losers_ieee_is_reported_when_the_survivor_holds_its_own(db_session):
+ """The survivor keeps what it has, so a different address on a loser is lost."""
+ winner = await _device(db_session, id="w", ieee_address="pve-pve1-130", ip="192.168.1.62")
+ loser = await _device(db_session, id="l", ieee_address="0xCCDD", ip="192.168.1.62")
+
+ result = await merge_devices(db_session, winner, [loser])
+
+ assert result["ieee_dropped"] == ["0xCCDD"]
+
+
+async def test_a_merge_that_loses_no_address_reports_nothing(db_session):
+ winner = await _device(db_session, id="w", ip="192.168.1.62", ieee_address=None)
+ loser = await _device(db_session, id="l", ip="192.168.1.62", ieee_address=None)
+
+ result = await merge_devices(db_session, winner, [loser])
+
+ assert result["ieee_dropped"] == []
+
+
+def test_distinct_ieees_folds_case_and_keeps_the_first_spelling():
+ rows = [
+ InventoryDevice(id="a", ieee_address="0xAABB"),
+ InventoryDevice(id="b", ieee_address="0xaabb"),
+ InventoryDevice(id="c", ieee_address=None),
+ InventoryDevice(id="d", ieee_address=""),
+ InventoryDevice(id="e", ieee_address="0xCCDD"),
+ ]
+
+ assert distinct_ieees(rows) == ["0xAABB", "0xCCDD"]
+
+
@pytest.mark.asyncio
async def test_reconcile_merges_rows_sharing_a_mac(db_session):
"""The reported case: a Proxmox row and a canvas row, same NIC."""
diff --git a/backend/tests/test_scanner.py b/backend/tests/test_scanner.py
index ccf2202..8ab0a95 100644
--- a/backend/tests/test_scanner.py
+++ b/backend/tests/test_scanner.py
@@ -1651,6 +1651,99 @@ async def test_dedupe_never_deletes_a_second_approved_row(mem_db):
assert sorted(d.id for d in devices) == ["a", "b"]
+async def test_dedupe_leaves_rows_carrying_two_distinct_ieees_alone(mem_db):
+ """Regression for #453: a collapse has room for one IEEE, so it refuses two.
+
+ Two Proxmox guests behind one host address are not a duplicate. Collapsing
+ them would delete one of the IEEEs, and the next import keying on it would
+ no longer find the device and would mint a fresh row.
+ """
+ from app.services.scanner import _dedupe_pending_by_ip
+
+ async with mem_db() as session:
+ session.add(InventoryDevice(
+ id="keep", ip="10.0.0.1", status="pending", ieee_address=None,
+ discovered_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+ ))
+ session.add(InventoryDevice(
+ id="a", ip="10.0.0.1", status="pending", ieee_address="pve-pve1-130",
+ discovered_at=datetime(2026, 2, 1, tzinfo=timezone.utc),
+ ))
+ session.add(InventoryDevice(
+ id="b", ip="10.0.0.1", status="pending", ieee_address="pve-pve1-131",
+ discovered_at=datetime(2026, 3, 1, tzinfo=timezone.utc),
+ ))
+ await session.commit()
+
+ async with mem_db() as session:
+ deleted = await _dedupe_pending_by_ip(session)
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert deleted == 0
+ assert sorted(d.id for d in devices) == ["a", "b", "keep"]
+ assert sorted(d.ieee_address or "" for d in devices) == ["", "pve-pve1-130", "pve-pve1-131"]
+
+
+async def test_dedupe_still_collapses_a_group_holding_one_ieee(mem_db):
+ """One address across the group is what the survivor has room for."""
+ from app.services.scanner import _dedupe_pending_by_ip
+
+ async with mem_db() as session:
+ session.add(InventoryDevice(
+ id="keep", ip="10.0.0.1", status="pending", ieee_address=None,
+ discovered_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+ ))
+ session.add(InventoryDevice(
+ id="dup", ip="10.0.0.1", status="pending", ieee_address="pve-pve1-130",
+ discovered_at=datetime(2026, 2, 1, tzinfo=timezone.utc),
+ ))
+ await session.commit()
+
+ async with mem_db() as session:
+ deleted = await _dedupe_pending_by_ip(session)
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert deleted == 1
+ assert [d.id for d in devices] == ["keep"]
+ assert devices[0].ieee_address == "pve-pve1-130"
+
+
+def test_collapse_targets_refuses_a_group_with_two_ieees():
+ from app.services.scanner import _collapse_targets
+
+ group = [
+ InventoryDevice(id="keep", ip="10.0.0.1", status="approved"),
+ InventoryDevice(id="a", ip="10.0.0.1", status="pending", ieee_address="0xAABB"),
+ InventoryDevice(id="b", ip="10.0.0.1", status="pending", ieee_address="0xCCDD"),
+ ]
+
+ keep, dups = _collapse_targets(group)
+
+ assert keep.id == "keep"
+ assert dups == []
+
+
+def test_collapse_targets_ignores_case_when_counting_ieees():
+ """The same address spelled two ways is one address, so the group collapses."""
+ from app.services.scanner import _collapse_targets
+
+ group = [
+ InventoryDevice(id="keep", ip="10.0.0.1", status="pending", ieee_address="0xAABB"),
+ InventoryDevice(id="dup", ip="10.0.0.1", status="pending", ieee_address="0xaabb"),
+ ]
+
+ keep, dups = _collapse_targets(group)
+
+ assert keep.id == "keep"
+ assert [d.id for d in dups] == ["dup"]
+
+
@pytest.mark.asyncio
async def test_process_host_never_deletes_a_second_approved_row(mem_db):
"""The same guard on the scan path: the merge target refreshes, no row goes."""