Skip to content

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

49.7 KB
Raw Blame
import ipaddress
import logging
import uuid
from datetime import datetime, timezone
from typing import Any

from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
from pydantic import BaseModel, field_validator
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from app.api.deps import get_current_user
from app.core.config import settings
from app.db.database import AsyncSessionLocal, get_db
from app.db.models import (
    Design,
    Document,
    Edge,
    InventoryDevice,
    InventoryDeviceLink,
    Node,
    RackDevice,
    ScanRun,
)
from app.schemas.nodes import NodeCreate
from app.schemas.scan import (
    InventoryDeviceCreate,
    InventoryDeviceResponse,
    InventoryDeviceUpdate,
    ScanRunResponse,
)
from app.services.device_merge import merge_devices
from app.services.discovery_sources import add_source
from app.services.doc_links import unlink_documents
from app.services.inventory_sync import find_device_for, merge_properties, merge_services
from app.services.mac_utils import normalize_mac
from app.services.node_dedupe import dedupe_nodes_by_device, find_duplicate_node
from app.services.scanner import (
    DeepScanOptions,
    _valid_port_range,
    _valid_port_spec,
    request_cancel,
    run_device_scan,
    run_scan,
)
from app.services.zigbee_service import (
    build_zigbee_properties,
    merge_zigbee_properties,
)
from app.services.zwave_service import build_zwave_properties

_ZIGBEE_TYPES = {"zigbee_coordinator", "zigbee_router", "zigbee_enddevice"}
_ZWAVE_TYPES = {"zwave_coordinator", "zwave_router", "zwave_enddevice"}


def _ip_tokens(ip: str | None) -> list[str]:
    """Split a Node/device ``ip`` field into individual addresses.

    The canvas stores multiple addresses in one comma-separated string (e.g.
    ``"fe80::1, 192.168.1.5"`` once a user adds an IPv6 address). Matching a
    scanned device against that field must compare per-address, not against the
    whole string, or the device looks absent from the canvas (issue #258).
    """
    return [t.strip() for t in ip.split(",") if t.strip()] if ip else []


def _is_rack_only(device: InventoryDevice) -> bool:
    """True for inventory entries created from a rack canvas.

    They describe a mount — a patch panel, a shelf, a chassis — not a host to
    document on a logical canvas, so they are never approved onto one.
    """
    return device.discovery_source == "rack" or "rack" in (device.discovery_sources or [])


def _is_wireless(node_type: str | None) -> bool:
    """Zigbee + Z-Wave mesh devices share online status / no ICMP check."""
    return node_type in _ZIGBEE_TYPES or node_type in _ZWAVE_TYPES


def _wireless_properties(
    node_type: str | None,
    ieee: str | None,
    vendor: str | None,
    model: str | None,
    lqi: int | None,
) -> list[dict[str, Any]]:
    """Build the right property rows for a mesh device (Z-Wave has no LQI)."""
    if node_type in _ZWAVE_TYPES:
        return build_zwave_properties(ieee, vendor, model)
    return build_zigbee_properties(ieee, vendor, model, lqi)


def build_mac_property(mac: str | None) -> list[dict[str, Any]]:
    """Build a NodeProperty list carrying a device MAC address.

    Shape matches the frontend ``NodeProperty`` type
    (``{key, value, icon, visible}``). Hidden by default — the user opts in to
    showing it on the canvas card from the right panel. Returns an empty list
    when no MAC is known.
    """
    if not mac:
        return []
    return [{"key": "MAC", "value": mac, "icon": None, "visible": False}]


def merge_mac_property(
    props: list[dict[str, Any]] | None, mac: str | None
) -> list[dict[str, Any]]:
    """Append a MAC NodeProperty to ``props`` unless one is already present.

    Preserves any user-supplied properties (and an existing MAC row's
    visibility) untouched. Used on approve so the scanned MAC is not lost.
    """
    out = [dict(p) for p in (props or [])]
    if not mac or any(p.get("key") == "MAC" for p in out):
        return out
    out.append({"key": "MAC", "value": mac, "icon": None, "visible": False})
    return out


class MergeDevicesRequest(BaseModel):
    """Which inventory rows fold into which. ``winner_id`` is the survivor."""

    winner_id: str
    loser_ids: list[str]


class BulkActionRequest(BaseModel):
    device_ids: list[str]
    # Target design for approved nodes. Falls back to the first design when
    # omitted (keeps older clients working), but the UI should send the active
    # design so approved devices land on the canvas the user is looking at.
    design_id: str | None = None


def _check_port_ranges(v: list[str]) -> list[str]:
    for r in v:
        if not _valid_port_range(r.strip()):
            raise ValueError(f"Invalid port range: {r!r}")
    return v


class ScanConfig(BaseModel):
    """Persisted scan defaults (Options page). Deep-scan fields are optional."""

    ranges: list[str]
    http_ranges: list[str] = []
    http_probe_enabled: bool = False
    verify_tls: bool = False

    @field_validator("ranges")
    @classmethod
    def validate_cidr(cls, v: list[str]) -> list[str]:
        for r in v:
            try:
                ipaddress.ip_network(r, strict=False)
            except ValueError as exc:
                raise ValueError(f"Invalid CIDR range: {r!r}") from exc
        return v

    @field_validator("http_ranges")
    @classmethod
    def validate_http_ranges(cls, v: list[str]) -> list[str]:
        return _check_port_ranges(v)


class TriggerScanRequest(BaseModel):
    """Per-scan deep-scan overrides (scan dialog). None → use persisted default."""

    http_ranges: list[str] | None = None
    http_probe_enabled: bool | None = None
    verify_tls: bool | None = None

    @field_validator("http_ranges")
    @classmethod
    def validate_http_ranges(cls, v: list[str] | None) -> list[str] | None:
        return None if v is None else _check_port_ranges(v)


logger = logging.getLogger(__name__)
router = APIRouter()


async def _background_scan(
    run_id: str, ranges: list[str], deep_scan: DeepScanOptions | None = None
) -> None:
    async with AsyncSessionLocal() as db:
        try:
            await run_scan(ranges, db, run_id, deep_scan=deep_scan or DeepScanOptions())
        except Exception:
            logger.exception("Scan run %s failed unexpectedly", run_id)
            await db.rollback()
            run = await db.get(ScanRun, run_id)
            if run and run.status == "running":
                # "error", the same word run_scan / run_device_scan write when
                # they fail themselves — one condition, one name. Scan History
                # filters and colours that one; "failed" showed up unlabelled.
                run.status = "error"
                await db.commit()


async def _background_device_scan(
    run_id: str,
    device_id: str,
    deep_scan: DeepScanOptions | None = None,
    full_ports: bool = True,
    ports: str | None = None,
) -> None:
    async with AsyncSessionLocal() as db:
        try:
            await run_device_scan(
                device_id,
                db,
                run_id,
                deep_scan=deep_scan or DeepScanOptions(),
                full_ports=full_ports,
                ports=ports,
            )
        except Exception:
            logger.exception("Device scan run %s failed unexpectedly", run_id)
            await db.rollback()
            run = await db.get(ScanRun, run_id)
            if run and run.status == "running":
                # "error", the same word run_scan / run_device_scan write when
                # they fail themselves — one condition, one name. Scan History
                # filters and colours that one; "failed" showed up unlabelled.
                run.status = "error"
                await db.commit()


def _resolve_deep_scan(payload: TriggerScanRequest | None) -> DeepScanOptions:
    """Merge per-scan overrides over persisted settings defaults."""
    p = payload or TriggerScanRequest()
    return DeepScanOptions(
        http_ranges=(
            p.http_ranges if p.http_ranges is not None else settings.scanner_http_ranges
        ),
        http_probe_enabled=(
            p.http_probe_enabled
            if p.http_probe_enabled is not None
            else settings.scanner_http_probe_enabled
        ),
        verify_tls=(
            p.verify_tls if p.verify_tls is not None else settings.scanner_http_verify_tls
        ),
    )


@router.post("/trigger", response_model=ScanRunResponse)
async def trigger_scan(
    background_tasks: BackgroundTasks,
    payload: TriggerScanRequest | None = None,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> ScanRun:
    ranges = settings.scanner_ranges
    deep_scan = _resolve_deep_scan(payload)
    run = ScanRun(status="running", ranges=ranges)
    db.add(run)
    await db.commit()
    await db.refresh(run)
    background_tasks.add_task(_background_scan, run.id, ranges, deep_scan)
    return run


class RescanDeviceRequest(BaseModel):
    """Per-device deep rescan. Defaults to every TCP port — that is the point.

    ``ports`` narrows the sweep to what the user typed in the deep-scan dialog
    (``80,443``, ``1-1024``); it wins over ``full_ports``.
    """

    full_ports: bool = True
    ports: str | None = None
    http_probe_enabled: bool | None = None
    verify_tls: bool | None = None

    @field_validator("ports")
    @classmethod
    def _check_ports(cls, v: str | None) -> str | None:
        if v is None or not v.strip():
            return None
        spec = v.strip()
        if not _valid_port_spec(spec):
            raise ValueError("Invalid port range")
        return spec


@router.post("/pending/{device_id}/rescan", response_model=ScanRunResponse)
async def rescan_device(
    device_id: str,
    background_tasks: BackgroundTasks,
    payload: RescanDeviceRequest | None = None,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> ScanRun:
    """Deep-rescan one known device to refresh its services (issue #350).

    Recorded as a ScanRun like any other scan, so progress, stop and history
    work unchanged. One run per device at a time — a second request while the
    first is still scanning is a 409, not a duplicate nmap over 65535 ports.
    """
    device = await db.get(InventoryDevice, device_id)
    if not device:
        raise HTTPException(status_code=404, detail="Device not found")
    if not device.ip:
        raise HTTPException(
            status_code=409, detail="Device has no IP address to scan"
        )
    if device.status == "hidden":
        raise HTTPException(status_code=409, detail="Device is hidden")

    device_ips = []
    for candidate in _ip_tokens(device.ip):
        try:
            device_ips.append(str(ipaddress.ip_address(candidate)))
        except ValueError:
            continue
    if not device_ips:
        raise HTTPException(status_code=409, detail="Device has no valid IP address to scan")
    # A row may retain multiple observed addresses. The deep-rescan operation
    # targets the first valid address, matching the scanner's single-host API.
    target = f"{device_ips[0]}/32"
    running = (await db.execute(
        select(ScanRun).where(ScanRun.status == "running", ScanRun.kind == "device")
    )).scalars().all()
    if any(target in (r.ranges or []) for r in running):
        raise HTTPException(
            status_code=409, detail="A scan is already running for this device"
        )

    p = payload or RescanDeviceRequest()
    deep_scan = _resolve_deep_scan(
        TriggerScanRequest(
            http_probe_enabled=p.http_probe_enabled, verify_tls=p.verify_tls
        )
    )
    run = ScanRun(status="running", kind="device", ranges=[target])
    db.add(run)
    await db.commit()
    await db.refresh(run)
    background_tasks.add_task(
        _background_device_scan, run.id, device_id, deep_scan, p.full_ports, p.ports
    )
    return run


@router.post("/{run_id}/stop", response_model=dict)
async def stop_scan(
    run_id: str,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, bool]:
    try:
        uuid.UUID(run_id)
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid run_id format") from None
    run = await db.get(ScanRun, run_id)
    if not run:
        raise HTTPException(status_code=404, detail="Scan run not found")
    if run.status != "running":
        raise HTTPException(status_code=409, detail="Scan is not running")
    request_cancel(run_id)
    # Flip status eagerly so the UI reflects the stop immediately, instead of
    # waiting for run_scan to reach its next cancellation checkpoint (which may
    # be blocked inside a long nmap call). run_scan converges to the same state.
    run.status = "cancelled"
    run.finished_at = datetime.now(timezone.utc)
    await db.commit()
    return {"stopping": True}


def _agg(values: list[datetime], *, newest: bool) -> datetime | None:
    """Pick the newest (max) or oldest (min) of a list of timestamps, or None."""
    present = [v for v in values if v is not None]
    if not present:
        return None
    return max(present) if newest else min(present)


async def _canvas_correlation(
    db: AsyncSession, devices: list[InventoryDevice]
) -> dict[str, dict[str, Any]]:
    """Correlate each device to the canvas nodes drawing it.

    Returns, per device id: the number of distinct canvases (designs) it appears
    on, plus aggregated node timestamps — created_at (oldest) and updated_at
    (newest). A node names the inventory row it draws, so this is a group-by on
    ``device_id`` rather than the ieee/mac/ip guesswork it used to be.

    ``last_scan`` and ``last_seen`` come off the device row itself now: they are
    observations of the device, not of any one drawing of it.
    """
    if not devices:
        return {}
    rows = (
        await db.execute(
            select(Node.device_id, Node.design_id, Node.created_at, Node.updated_at)
            .where(Node.design_id.isnot(None), Node.device_id.isnot(None))
        )
    ).all()
    by_device: dict[str, list[Any]] = {}
    for row in rows:
        by_device.setdefault(row.device_id, []).append(row)

    info: dict[str, dict[str, Any]] = {}
    for d in devices:
        matched = by_device.get(d.id, [])
        designs = {m.design_id for m in matched}
        info[d.id] = {
            "canvas_count": len(designs),
            "node_created_at": _agg([m.created_at for m in matched], newest=False),
            "node_last_scan": d.last_scan,
            "node_last_modified": _agg([m.updated_at for m in matched], newest=True),
            "node_last_seen": d.last_seen,
        }
    return info


async def _with_canvas_counts(
    db: AsyncSession, devices: list[InventoryDevice]
) -> list[InventoryDevice]:
    """Attach transient canvas count + linked-node timestamps for the response."""
    info = await _canvas_correlation(db, devices)
    for d in devices:
        meta = info.get(d.id, {})
        d.canvas_count = meta.get("canvas_count", 0)
        d.node_created_at = meta.get("node_created_at")
        d.node_last_scan = meta.get("node_last_scan")
        d.node_last_modified = meta.get("node_last_modified")
        d.node_last_seen = meta.get("node_last_seen")
    return devices


@router.get("/pending", response_model=list[InventoryDeviceResponse])
async def list_pending(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[InventoryDevice]:
    # Inventory: every scanned device except the user-hidden ones. Approved devices
    # stay listed so they keep showing with a canvas-presence badge.
    result = await db.execute(select(InventoryDevice).where(InventoryDevice.status != "hidden"))
    return await _with_canvas_counts(db, list(result.scalars().all()))


@router.post("/pending", response_model=InventoryDeviceResponse, status_code=201)
async def create_pending(
    body: InventoryDeviceCreate,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> InventoryDevice:
    """Add an inventory entry by hand, for hardware no scan can discover.

    Lands as ``status="pending"`` like a discovery would, so the existing approve
    / hide / restore flows apply unchanged.
    """
    # One device is one row. If this host is already known — by ieee, ip or mac —
    # the user is documenting the device they already have, so fill in what the
    # row is missing rather than splitting it in two.
    mac = normalize_mac(body.mac)
    existing = await find_device_for(db, ip=body.ip, mac=mac, ieee=None)
    if existing is not None:
        for field in (
            "hostname", "ip", "os", "suggested_type", "model", "vendor", "label", "type",
            "notes", "cpu_count", "cpu_model", "ram_gb", "disk_gb", "check_method",
            "check_target", "friendly_name", "device_subtype",
        ):
            value = getattr(body, field, None)
            if value not in (None, "") and getattr(existing, field, None) in (None, ""):
                setattr(existing, field, value)
        existing.mac = existing.mac or mac
        existing.properties = merge_properties(existing.properties, body.properties)
        existing.services = merge_services(existing.services, body.services)
        existing.discovery_sources = add_source(existing.discovery_sources, body.discovery_source)
        # A hidden row is still that device, so it is the one to fill in — but
        # adding a device by hand is asking for it, and returning it still hidden
        # would leave the user with a 201 and nothing in the inventory. The
        # explicit add outranks the earlier hide, exactly like restore.
        if existing.status == "hidden":
            existing.status = "pending"
        await db.commit()
        await db.refresh(existing)
        return (await _with_canvas_counts(db, [existing]))[0]

    device = InventoryDevice(
        hostname=body.hostname,
        ip=body.ip,
        # Canonical form, like every other write path: dedup compares MACs by
        # equality, so a hand-typed "AA-BB-CC-11-22-33" would never match the
        # scanned "aa:bb:cc:11:22:33" and approve would build a duplicate node.
        mac=mac,
        suggested_type=body.suggested_type,
        model=body.model,
        vendor=body.vendor,
        properties=body.properties,
        status="pending",
        discovery_source=body.discovery_source,
        discovery_sources=[body.discovery_source],
        os=body.os,
        services=body.services,
        friendly_name=body.friendly_name,
        device_subtype=body.device_subtype,
        label=body.label,
        type=body.type,
        notes=body.notes,
        cpu_count=body.cpu_count,
        cpu_model=body.cpu_model,
        ram_gb=body.ram_gb,
        disk_gb=body.disk_gb,
        show_hardware=body.show_hardware,
        check_method=body.check_method,
        check_target=body.check_target,
    )
    db.add(device)
    await db.commit()
    await db.refresh(device)
    return (await _with_canvas_counts(db, [device]))[0]


@router.patch("/pending/{device_id}", response_model=InventoryDeviceResponse)
async def update_pending(
    device_id: str,
    body: InventoryDeviceUpdate,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> InventoryDevice:
    """Edit an inventory row — the device facts, not its lifecycle.

    The inventory row owns what a device *is*; a canvas node only owns how it is
    drawn. This is the write path behind the device detail modal, and applies
    only the fields the client actually sent.
    """
    device = (
        await db.execute(select(InventoryDevice).where(InventoryDevice.id == device_id))
    ).scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not found")

    data = body.model_dump(exclude_unset=True)
    if "mac" in data:
        # Same reason as create_pending: dedup matches MACs by equality.
        data["mac"] = normalize_mac(data["mac"])
    for field, value in data.items():
        setattr(device, field, value)

    await db.commit()
    await db.refresh(device)
    return (await _with_canvas_counts(db, [device]))[0]


# What a copy inherits: the facts two identical units share. Addresses, the
# check target, services and the hostname describe one physical box, so they
# stay behind — copied, they would make create_pending's dedup and every
# importer treat the twin as the same device (issue #481).
_DUPLICATED_FIELDS = (
    "os", "suggested_type", "type", "model", "vendor", "friendly_name",
    "device_subtype", "notes", "cpu_count", "cpu_model", "ram_gb", "disk_gb",
    "show_hardware", "check_method", "rack_faceplate_id", "rack_u_height",
    "rack_col_span", "rack_color",
)


@router.post("/pending/{device_id}/duplicate", response_model=InventoryDeviceResponse, status_code=201)
async def duplicate_pending(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> InventoryDevice:
    """Copy an inventory row into a new, hand-made one — the second unit of a
    redundant pair, with the same specs and front panel but no identity yet."""
    source = (
        await db.execute(select(InventoryDevice).where(InventoryDevice.id == device_id))
    ).scalar_one_or_none()
    if not source:
        raise HTTPException(status_code=404, detail="Device not found")

    name = source.label or source.friendly_name or source.hostname or source.ip or source.ieee_address
    discovery_source = "rack" if _is_rack_only(source) else "manual"
    copy = InventoryDevice(
        **{field: getattr(source, field) for field in _DUPLICATED_FIELDS},
        label=f"{name} (copy)" if name else "Device (copy)",
        properties=[dict(p) for p in source.properties or []],
        services=[],
        status="pending",
        discovery_source=discovery_source,
        discovery_sources=[discovery_source],
        # Fresh port ids: a cable names a port by id, so the twin's ports must
        # never be mistaken for the source's.
        rack_ports=(
            [{**p, "id": str(uuid.uuid4())} for p in source.rack_ports]
            if source.rack_ports is not None
            else None
        ),
    )
    db.add(copy)
    await db.commit()
    await db.refresh(copy)
    return (await _with_canvas_counts(db, [copy]))[0]


@router.delete("/pending", response_model=dict)
async def clear_pending(
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, int]:
    from sqlalchemy import delete as sa_delete
    from sqlalchemy import update as sa_update

    # Unlink by subquery, not by a list of ids read beforehand: a device approved
    # between that read and the delete would lose its documents without being
    # deleted. The UPDATE takes SQLite's write lock, so the set it unlinks is the
    # set the DELETE removes. (#444)
    pending = select(InventoryDevice.id).where(InventoryDevice.status == "pending")
    await db.execute(
        sa_update(Document).where(Document.device_id.in_(pending)).values(device_id=None)
    )
    result = await db.execute(sa_delete(InventoryDevice).where(InventoryDevice.status == "pending"))
    await db.commit()
    return {"deleted": result.rowcount}


@router.delete("/pending/{device_id}", response_model=dict)
async def delete_pending(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, bool]:
    """Remove one inventory entry.

    Used by the rack canvas to drop the placeholder it created for a plate once
    that plate is pointed at a real inventory row. Refuses while a rack still
    mounts the device: SQLite runs with foreign keys off here, so the mount's
    ``device_id`` would be left naming a row that no longer exists rather than
    being cleared by the ``ON DELETE SET NULL`` the schema declares.
    """
    device = (
        await db.execute(select(InventoryDevice).where(InventoryDevice.id == device_id))
    ).scalar_one_or_none()
    if not device:
        raise HTTPException(status_code=404, detail="Device not found")

    mounted = (
        await db.execute(select(RackDevice.id).where(RackDevice.device_id == device_id).limit(1))
    ).scalar_one_or_none()
    if mounted:
        raise HTTPException(status_code=409, detail="Device is mounted in a rack")

    await unlink_documents(db, device_ids=[device.id])
    await db.delete(device)
    await db.commit()
    return {"deleted": True}


@router.get("/hidden", response_model=list[InventoryDeviceResponse])
async def list_hidden(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[InventoryDevice]:
    result = await db.execute(select(InventoryDevice).where(InventoryDevice.status == "hidden"))
    return await _with_canvas_counts(db, list(result.scalars().all()))


@router.get("/pending/{device_id}/proxmox-children", response_model=list[InventoryDeviceResponse])
async def list_proxmox_children(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> list[InventoryDevice]:
    """Inventory rows for the guests a Proxmox host (or Unraid server) runs.

    The Proxmox and Unraid imports record host -> guest/container as a
    ``device_inventory_links`` row with ``discovery_source`` "proxmox" or
    "unraid", keyed by IEEE. This resolves those targets back to inventory rows
    so the UI can offer "add the children too" when a host is placed on a
    canvas. Empty for anything that is not a host.
    """
    device = await db.get(InventoryDevice, device_id)
    if device is None:
        raise HTTPException(status_code=404, detail="Device not found")
    if not device.ieee_address:
        return []
    ieees = list(
        (
            await db.execute(
                select(InventoryDeviceLink.target_ieee).where(
                    InventoryDeviceLink.source_ieee == device.ieee_address,
                    InventoryDeviceLink.discovery_source.in_(("proxmox", "unraid")),
                )
            )
        )
        .scalars()
        .all()
    )
    if not ieees:
        return []
    result = await db.execute(
        select(InventoryDevice).where(
            InventoryDevice.ieee_address.in_(ieees),
            InventoryDevice.status != "hidden",
        )
    )
    return await _with_canvas_counts(db, list(result.scalars().all()))


@router.post("/pending/merge", response_model=InventoryDeviceResponse)
async def merge_inventory_devices(
    payload: MergeDevicesRequest,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> InventoryDevice:
    """Fold several inventory rows into one, keeping ``winner_id``.

    The manual half of the duplicate repair. Identity matching only runs when a
    row is created, so two rows describing one host — minted before either
    carried the address that would have matched them — stay separate forever.
    Where they share no address at all, no automatic rule can join them safely
    (a name is not an identity), and this is the only way to say "these are the
    same machine".

    Non-destructive: facts are unioned onto the survivor and every canvas node,
    rack mount and document is re-pointed at it before the extras go.
    """
    winner = await db.get(InventoryDevice, payload.winner_id)
    if winner is None:
        raise HTTPException(status_code=404, detail="Device not found")

    loser_ids = [i for i in dict.fromkeys(payload.loser_ids) if i != winner.id]
    if not loser_ids:
        raise HTTPException(status_code=400, detail="Select at least two devices to merge")

    losers = (
        await db.execute(select(InventoryDevice).where(InventoryDevice.id.in_(loser_ids)))
    ).scalars().all()
    missing = set(loser_ids) - {row.id for row in losers}
    if missing:
        raise HTTPException(status_code=404, detail="Device not found")

    await merge_devices(db, winner, list(losers))
    await db.commit()
    await db.refresh(winner)
    return (await _with_canvas_counts(db, [winner]))[0]


@router.post("/pending/bulk-approve", response_model=dict)
async def bulk_approve_devices(
    payload: BulkActionRequest,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, Any]:
    # Repair any legacy same-canvas duplicate nodes before placing more.
    await dedupe_nodes_by_device(db)

    # Target the design the user is on; fall back to the first design.
    default_design_id = payload.design_id
    if default_design_id is None:
        first_design = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
        default_design_id = first_design.id if first_design else None

    # Accept every selected device that isn't user-hidden. We intentionally do NOT
    # filter on status == "pending": a device's status is global, but canvas
    # membership is per-design. A device approved onto another canvas (or whose
    # node was later deleted) must still be placeable on THIS design. Duplicates
    # are guarded per-design below, not by the global status flag.
    result = await db.execute(
        select(InventoryDevice).where(
            InventoryDevice.id.in_(payload.device_ids),
            InventoryDevice.status != "hidden",
        )
    )
    devices = result.scalars().all()

    # What already sits on the target canvas. A node names the inventory row it
    # draws, so "already placed" is now a device-id lookup rather than a guess
    # across ip/mac/ieee. The value may be a Node still pending flush (in-batch
    # duplicate) — resolved to its id after the flush below.
    existing = (
        await db.execute(
            select(Node.id, Node.device_id).where(
                Node.design_id == default_design_id, Node.device_id.isnot(None)
            )
        )
    ).all()
    placed: dict[str, Any] = {device_id: nid for nid, device_id in existing}

    created_nodes: list[Node] = []
    approved_devices: list[InventoryDevice] = []
    skipped_devices: list[dict[str, Any]] = []
    for device in devices:
        # Rack-only gear belongs to a rack canvas, never to a logical one.
        if _is_rack_only(device):
            skipped_devices.append({
                "device_id": device.id,
                "label": device.hostname or device.friendly_name or "device",
                "match": "rack", "value": "rack device", "_ref": None,
            })
            continue
        # Report which identifier names the device, so the caller can explain
        # the skip and link to the node already drawing it.
        if device.id in placed:
            match, value = (
                ("ip", device.ip) if device.ip
                else ("ieee", device.ieee_address) if device.ieee_address
                else ("mac", device.mac)
            )
            skipped_devices.append({
                "device_id": device.id,
                "label": device.hostname or device.friendly_name or value or "device",
                "match": match, "value": value, "_ref": placed[device.id],
            })
            continue
        device.status = "approved"
        node_type = device.suggested_type or "generic"
        is_wireless = _is_wireless(node_type)
        cluster_host = await _is_proxmox_cluster_member(db, device.ieee_address)
        # Enrich the row, not the node: a mesh device's radio properties and the
        # default check method describe the device itself.
        device.type = device.type or node_type
        device.label = device.label or device.hostname or device.friendly_name or device.ip or "device"
        device.properties = (
            _wireless_properties(node_type, device.ieee_address, device.vendor, device.model, device.lqi)
            if is_wireless
            else merge_mac_property(list(device.properties or []), device.mac)
        )
        if is_wireless:
            # A mesh device answers no ICMP; being in the mesh is the liveness.
            device.check_method = "none"
            device.status_live = "online"
        elif not device.check_method:
            # Default to ping so the status checker actually polls it. Without
            # this the scheduler skips it (check_method NULL -> no check).
            # With the checker switched off there is nothing to poll for: keep
            # it NULL rather than store a probe that would start the moment the
            # switch is flipped back.
            device.check_method = "ping" if device.ip and settings.status_checker_enabled else None
        node = Node(
            label=device.label,
            type=device.type,
            # Cluster hosts get side handles for their host<->host cluster edge.
            left_handles=1 if cluster_host else 0,
            right_handles=1 if cluster_host else 0,
            design_id=default_design_id,
            # The node draws this inventory row; the row owns the facts.
            device_id=device.id,
        )
        db.add(node)
        created_nodes.append(node)
        approved_devices.append(device)
        # Track within this batch so a duplicate selection is not placed twice
        # on the same canvas. Stores the Node so a later in-batch skip can
        # resolve to its id after flush.
        placed[device.id] = node
    await db.flush()  # populates node.id from Python-side default before reading
    # node_ids and approved_device_ids stay index-aligned for the client's mapping.
    node_ids = [n.id for n in created_nodes]
    approved_device_ids = [d.id for d in approved_devices]

    # Resolve each skip's existing-node reference to a concrete id now that any
    # in-batch nodes have been flushed, and expose it under a clean key.
    for entry in skipped_devices:
        ref = entry.pop("_ref")
        entry["existing_node_id"] = ref.id if isinstance(ref, Node) else ref

    all_edges: list[dict[str, Any]] = []
    for device, node in zip(approved_devices, created_nodes, strict=True):
        all_edges.extend(
            await _resolve_pending_links_for_ieee(
                db, device.ieee_address, default_design_id, self_node=node
            )
        )

    await db.commit()
    return {
        "approved": len(node_ids),
        "node_ids": node_ids,
        "device_ids": approved_device_ids,
        "edges_created": len(all_edges),
        "edges": all_edges,
        "skipped": len(payload.device_ids) - len(node_ids),
        "skipped_devices": skipped_devices,
    }


@router.post("/pending/bulk-hide", response_model=dict)
async def bulk_hide_devices(
    payload: BulkActionRequest,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, Any]:
    result = await db.execute(
        select(InventoryDevice).where(
            InventoryDevice.id.in_(payload.device_ids),
            InventoryDevice.status == "pending",
        )
    )
    devices = result.scalars().all()
    for device in devices:
        device.status = "hidden"
    await db.commit()
    return {"hidden": len(devices), "skipped": len(payload.device_ids) - len(devices)}


@router.post("/pending/{device_id}/restore", response_model=dict)
async def restore_device(
    device_id: str,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, Any]:
    device = await db.get(InventoryDevice, device_id)
    if not device:
        raise HTTPException(status_code=404, detail="Device not found")
    if device.status != "hidden":
        raise HTTPException(status_code=409, detail="Device is not hidden")
    device.status = "pending"
    await db.commit()
    return {"restored": True, "device_id": device_id}


@router.post("/pending/bulk-restore", response_model=dict)
async def bulk_restore_devices(
    payload: BulkActionRequest,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, Any]:
    result = await db.execute(
        select(InventoryDevice).where(
            InventoryDevice.id.in_(payload.device_ids),
            InventoryDevice.status == "hidden",
        )
    )
    devices = result.scalars().all()
    for device in devices:
        device.status = "pending"
    await db.commit()
    return {"restored": len(devices), "skipped": len(payload.device_ids) - len(devices)}


@router.post("/pending/{device_id}/approve", response_model=dict)
async def approve_device(
    device_id: str,
    node_data: NodeCreate,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> dict[str, Any]:
    # Determine target design
    node_design_id = node_data.design_id
    if node_design_id is None:
        first = (await db.execute(select(Design).order_by(Design.created_at).limit(1))).scalar()
        node_design_id = first.id if first else None

    device = await db.get(InventoryDevice, device_id)
    if not device:
        raise HTTPException(status_code=404, detail="Device not found")
    # A device's status is GLOBAL — it flips to "approved" the moment it lands on
    # ANY canvas — but canvas membership is per-design. Approving onto a NEW
    # design must therefore work even when the device already sits on another
    # one (mirroring bulk_approve_devices, which deliberately does not filter on
    # status == "pending"). Same-design duplicates are caught by the per-design
    # IEEE/ip/mac guards below, not by this global flag. Only a user-hidden
    # device is off-limits here.
    if device.status == "hidden":
        raise HTTPException(status_code=409, detail="Device is hidden")
    if _is_rack_only(device):
        raise HTTPException(
            status_code=409,
            detail="Rack devices cannot be placed on a logical canvas",
        )
    wireless = _is_wireless(node_data.type)

    # A device already on THIS design (matched by ieee, ip OR mac) is NOT placed
    # again automatically: the user might genuinely want a second card, or might
    # be re-approving by mistake. Reject with 409 + the existing node so the UI
    # can ask — identical handling for IEEE (Zigbee/Z-Wave) and plain IP/ARP
    # hosts. force=True (set after the user confirms) skips this and creates it.
    # The same device on a *different* design is valid (one Node per canvas), so
    # this is scoped to node_design_id.
    if not node_data.force:
        conflict = await find_duplicate_node(
            db, node_design_id,
            node_data.ip or device.ip,
            node_data.mac or device.mac,
            ieee=device.ieee_address,
        )
        if conflict is not None:
            raise HTTPException(status_code=409, detail=conflict)

    device.status = "approved"
    # Prefer the MAC discovered during the scan (stored on the inventory row);
    # fall back to whatever the approve payload carried.
    _mac = device.mac or node_data.mac
    cluster_host = await _is_proxmox_cluster_member(db, device.ieee_address)

    # The approve dialog is an edit of the device, so its values land on the row
    # — the node that follows only says where it is drawn. A blank field in the
    # payload never clears what discovery already found.
    device.label = node_data.label or device.label
    device.type = node_data.type or device.type
    device.ip = node_data.ip or device.ip
    device.mac = _mac
    device.hostname = node_data.hostname or device.hostname
    device.services = merge_services(device.services, node_data.services)
    device.properties = (
        _wireless_properties(
            node_data.type, device.ieee_address, device.vendor, device.model, device.lqi
        )
        if wireless
        else merge_mac_property(
            merge_zigbee_properties(list(device.properties or []), node_data.properties or []),
            _mac,
        )
    )
    if wireless:
        # A mesh device answers no ICMP; being in the mesh is the liveness.
        device.check_method = "none"
        device.check_target = None
        device.status_live = "online"
    else:
        device.check_method = node_data.check_method or device.check_method or (
            "ping" if device.ip and settings.status_checker_enabled else None
        )
        device.check_target = node_data.check_target or device.check_target
        if node_data.status:
            device.status_live = node_data.status

    node = Node(
        label=device.label or node_data.label,
        type=device.type or node_data.type,
        # Cluster hosts get side handles for their host<->host cluster edge.
        left_handles=1 if cluster_host else 0,
        right_handles=1 if cluster_host else 0,
        design_id=node_design_id,
        # The node draws this inventory row; the row owns the facts.
        device_id=device.id,
    )
    db.add(node)
    await db.flush()
    node_id = node.id

    edges = await _resolve_pending_links_for_ieee(
        db, device.ieee_address, node_design_id, self_node=node
    )

    await db.commit()
    return {
        "approved": True,
        "node_id": node_id,
        "edges_created": len(edges),
        "edges": edges,
    }


async def _is_proxmox_cluster_member(db: AsyncSession, ieee: str | None) -> bool:
    """True if ``ieee`` participates in a proxmox_cluster link (host↔host).

    Such a host needs one left + one right handle for the cluster edge endpoints
    (both default to 0). Checked at approve time, before the link is consumed by
    ``_resolve_pending_links_for_ieee``.
    """
    if not ieee:
        return False
    found = (
        await db.execute(
            select(InventoryDeviceLink.id)
            .where(
                InventoryDeviceLink.discovery_source == "proxmox_cluster",
                (InventoryDeviceLink.source_ieee == ieee) | (InventoryDeviceLink.target_ieee == ieee),
            )
            .limit(1)
        )
    ).scalar()
    return found is not None


async def _resolve_pending_links_for_ieee(
    db: AsyncSession,
    ieee: str | None,
    design_id: str | None,
    self_node: Node | None = None,
) -> list[dict[str, Any]]:
    """Materialize edges for any device_inventory_links involving ``ieee`` on the
    canvas identified by ``design_id``.

    For each link where the other endpoint already exists as a Node *on this
    design* (matched by ``Node.ieee_address`` + ``Node.design_id``), create the
    Edge. Links are **never** deleted here: they describe the discovered mesh /
    cluster topology and are wiped+reinserted wholesale on the next import
    (zigbee/zwave/proxmox). Keeping them lets the same devices be re-approved
    onto a second canvas with their edges intact.

    ``self_node`` is the node just placed for ``ieee``. Pass it whenever the
    caller has it: a device drawn twice on one design has two nodes for the same
    ieee, and looking it up again could land on the older card — whose edges
    already exist — leaving the new one unlinked.
    """
    if not ieee:
        return []

    links_q = await db.execute(
        select(InventoryDeviceLink).where(
            (InventoryDeviceLink.source_ieee == ieee)
            | (InventoryDeviceLink.target_ieee == ieee)
        )
    )
    links = list(links_q.scalars().all())
    if not links:
        return []

    # Map every relevant ieee → Node *on the target design* (single query).
    # Scoping by design is what makes a re-approve onto a second canvas link the
    # nodes of THAT canvas, not stale nodes left on another one.
    other_ieees = {
        link.target_ieee if link.source_ieee == ieee else link.source_ieee
        for link in links
    }
    other_ieees.add(ieee)
    # A node reaches its ieee through the inventory row it draws.
    nodes_q = await db.execute(
        select(InventoryDevice.ieee_address, Node)
        .join(Node, Node.device_id == InventoryDevice.id)
        .where(
            InventoryDevice.ieee_address.in_(other_ieees),
            Node.design_id == design_id,
        )
    )
    by_ieee = {row_ieee: node for row_ieee, node in nodes_q.all() if row_ieee}

    if self_node is not None:
        by_ieee[ieee] = self_node
    self_node = by_ieee.get(ieee)
    if self_node is None:
        return []

    # Pre-fetch existing edges between these node ids so we don't create dups
    # if the user re-approves a device or had drawn the link manually.
    candidate_node_ids = [n.id for n in by_ieee.values()]
    existing_q = await db.execute(
        select(Edge).where(
            Edge.source.in_(candidate_node_ids),
            Edge.target.in_(candidate_node_ids),
        )
    )
    existing_pairs = {(e.source, e.target) for e in existing_q.scalars().all()}

    created: list[dict[str, Any]] = []
    for link in links:
        other_ieee = (
            link.target_ieee if link.source_ieee == ieee else link.source_ieee
        )
        other_node = by_ieee.get(other_ieee)
        if other_node is None:
            continue
        if link.source_ieee == ieee:
            src_id, tgt_id = self_node.id, other_node.id
        else:
            src_id, tgt_id = other_node.id, self_node.id
        # Skip if either direction already exists on this design (re-approve or
        # a manually drawn link). The link row is kept for other designs.
        if (src_id, tgt_id) in existing_pairs or (tgt_id, src_id) in existing_pairs:
            continue
        # Edge lands on the design we're approving into (the nodes above are
        # already scoped to it).
        edge_design_id = design_id or (self_node.design_id if self_node else None)
        # Edge shape by link source. Handle IDs are the *bare* slot-0 side names
        # (the canonical stored form — the save path normalizes '<side>-t' → the
        # bare source id, and React Flow resolves the bare id to that side). A
        # '-t' target id does not resolve here and RF falls back to the top
        # handle, so never emit one.
        #   proxmox         → 'virtual' host→guest, vertical (bottom → top)
        #   unraid          -> 'virtual' host->container, same shape
        #   proxmox_cluster → 'cluster' host↔host, horizontal (right → left)
        #   anything else   → 'iot' mesh link, vertical
        if link.discovery_source in ("proxmox", "unraid"):
            edge_type, src_handle, tgt_handle = "virtual", "bottom", "top"
        elif link.discovery_source == "proxmox_cluster":
            edge_type, src_handle, tgt_handle = "cluster", "right", "left"
        elif link.discovery_source == "zigbee_mesh":
            # Neighbour link, not a parent attachment: sideways, like the
            # cluster edges, so it reads apart from the tree.
            edge_type, src_handle, tgt_handle = "zigbee_mesh", "right", "left"
        else:
            edge_type, src_handle, tgt_handle = "iot", "bottom", "top"
        edge = Edge(
            source=src_id,
            target=tgt_id,
            type=edge_type,
            source_handle=src_handle,
            target_handle=tgt_handle,
            design_id=edge_design_id,
            # Measured link quality, carried from the import. A mesh link has no
            # node-property fallback, so losing it here loses it for good.
            lqi=link.lqi,
        )
        db.add(edge)
        await db.flush()
        existing_pairs.add((src_id, tgt_id))
        # Return the edge's type + handles so the client injects it faithfully
        # (a cluster edge must keep its right→left handles, not the iot default).
        created.append({
            "id": edge.id,
            "source": src_id,
            "target": tgt_id,
            "type": edge_type,
            "source_handle": src_handle,
            "target_handle": tgt_handle,
            "lqi": link.lqi,
        })

    return created


@router.post("/pending/{device_id}/hide")
async def hide_device(
    device_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
) -> dict[str, bool]:
    device = await db.get(InventoryDevice, device_id)
    if not device:
        raise HTTPException(status_code=404, detail="Device not found")
    device.status = "hidden"
    await db.commit()
    return {"hidden": True}


@router.post("/pending/{device_id}/ignore")
async def ignore_device(
    device_id: str, db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)
) -> dict[str, bool]:
    device = await db.get(InventoryDevice, device_id)
    if not device:
        raise HTTPException(status_code=404, detail="Device not found")
    await unlink_documents(db, device_ids=[device.id])
    await db.delete(device)
    await db.commit()
    return {"ignored": True}


@router.get("/runs", response_model=list[ScanRunResponse])
async def list_runs(db: AsyncSession = Depends(get_db), _: str = Depends(get_current_user)) -> list[ScanRun]:
    result = await db.execute(select(ScanRun).order_by(ScanRun.started_at.desc()).limit(20))
    return list(result.scalars().all())


@router.get("/runs/{run_id}", response_model=ScanRunResponse)
async def get_run(
    run_id: str,
    db: AsyncSession = Depends(get_db),
    _: str = Depends(get_current_user),
) -> ScanRun:
    """One run, for a caller waiting on a scan it started (the device rescan)."""
    run = await db.get(ScanRun, run_id)
    if not run:
        raise HTTPException(status_code=404, detail="Scan run not found")
    return run


@router.get("/config", response_model=ScanConfig)
async def get_scan_config(_: str = Depends(get_current_user)) -> ScanConfig:
    return ScanConfig(
        ranges=settings.scanner_ranges,
        http_ranges=settings.scanner_http_ranges,
        http_probe_enabled=settings.scanner_http_probe_enabled,
        verify_tls=settings.scanner_http_verify_tls,
    )


@router.post("/config", response_model=ScanConfig)
async def update_scan_config(payload: ScanConfig, _: str = Depends(get_current_user)) -> ScanConfig:
    previous = (
        settings.scanner_ranges,
        settings.scanner_http_ranges,
        settings.scanner_http_probe_enabled,
        settings.scanner_http_verify_tls,
    )
    settings.scanner_ranges = payload.ranges
    settings.scanner_http_ranges = payload.http_ranges
    settings.scanner_http_probe_enabled = payload.http_probe_enabled
    settings.scanner_http_verify_tls = payload.verify_tls
    try:
        settings.save_overrides()
        return payload
    except Exception as exc:
        (
            settings.scanner_ranges,
            settings.scanner_http_ranges,
            settings.scanner_http_probe_enabled,
            settings.scanner_http_verify_tls,
        ) = previous
        logger.error("Failed to save scan config: %s", exc)
        raise HTTPException(status_code=500, detail="Failed to save scan config") from exc