Skip to content

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

12.9 KB
Raw Blame
"""Unit tests for the Unraid import service (parsing, properties, errors)."""

from __future__ import annotations

import httpx
import pytest

from app.services import unraid_service as svc

HOST_UUID = "AA67F8CB-8DEA-8A1D-AB9C-D8BBC16C6573"
HOST_KEY = HOST_UUID.lower()


def _container(name: str, network: str, ip: str = "", mac: str = "", state: str = "RUNNING", **extra) -> dict:
    return {
        "id": f"server:{name}id",
        "names": [f"/{name}"],
        "image": f"img/{name}:latest",
        "state": state,
        "webUiUrl": None,
        "labels": {},
        "lanIpPorts": None,
        "hostConfig": {"networkMode": network},
        "networkSettings": {"Networks": {network: {"IPAddress": ip, "MacAddress": mac}}},
        **extra,
    }


def _payload(containers: list[dict]) -> dict:
    return {
        "info": {
            "system": {"uuid": HOST_UUID, "manufacturer": "MSI", "model": "MS-7D25"},
            "cpu": {"brand": "Core i5-13600K", "threads": 20},
            "os": {"hostname": "Pearl"},
            "primaryNetwork": {"macAddress": "A0:36:9F:77:F9:44", "ipAddress": "10.1.1.231"},
            "versions": {"core": {"unraid": "7.3.1"}},
        },
        "docker": {
            "networks": [
                {"name": "bridge", "driver": "bridge"},
                {"name": "br0", "driver": "ipvlan"},
                {"name": "mv0", "driver": "macvlan"},
                {"name": "host", "driver": "host"},
            ],
            "containers": containers,
        },
    }


def test_host_node_from_info() -> None:
    nodes, edges = svc._parse_inventory(_payload([]))
    assert edges == []
    host = nodes[0]
    assert host["ieee_address"] == f"unraid-host-{HOST_KEY}"
    assert host["type"] == "docker_host"
    assert host["ip"] == "10.1.1.231"
    assert host["mac"] == "a0:36:9f:77:f9:44"
    assert host["cpu_count"] == 20
    assert host["model"] == "MSI MS-7D25"
    assert host["os_version"] == "Unraid 7.3.1"


def test_host_key_falls_back_to_hostname() -> None:
    data = _payload([])
    data["info"]["system"]["uuid"] = None
    nodes, _ = svc._parse_inventory(data)
    assert nodes[0]["ieee_address"] == "unraid-host-pearl"


def test_server_web_ui_is_the_address_the_import_used() -> None:
    assert svc._server_web_ui("10.1.1.231", 80, False)["host"] == "http://10.1.1.231"
    assert svc._server_web_ui("10.1.1.231", 443, True)["host"] == "https://10.1.1.231"
    custom = svc._server_web_ui("tower.local", 8443, True)
    assert (custom["host"], custom["port"], custom["service_name"]) == ("https://tower.local:8443", 8443, "Web UI")
    assert svc._server_web_ui("fd00::5", 80, False)["host"] == "http://[fd00::5]"


def test_container_identity_is_host_and_name() -> None:
    nodes, edges = svc._parse_inventory(_payload([_container("plex", "host")]))
    plex = nodes[1]
    assert plex["ieee_address"] == f"unraid-{HOST_KEY}-ct-plex"
    assert plex["type"] == "docker_container"
    assert plex["parent_ieee"] == f"unraid-host-{HOST_KEY}"
    assert edges == [{"source": f"unraid-host-{HOST_KEY}", "target": plex["id"]}]


def test_bridge_container_gets_no_address() -> None:
    # The 172.x address is internal to the host and the MAC changes on every
    # recreate - neither may identify the container.
    nodes, _ = svc._parse_inventory(_payload([_container("app", "bridge", "172.17.0.3", "12:64:29:75:17:49")]))
    assert nodes[1]["ip"] is None
    assert nodes[1]["mac"] is None


def test_ipvlan_container_gets_ip_but_never_a_mac() -> None:
    # ipvlan shares the parent interface's MAC with the host.
    nodes, _ = svc._parse_inventory(_payload([_container("netdata", "br0", "10.1.1.198", "a0:36:9f:77:f9:44")]))
    assert nodes[1]["ip"] == "10.1.1.198"
    assert nodes[1]["mac"] is None


def test_macvlan_container_keeps_its_own_mac() -> None:
    nodes, _ = svc._parse_inventory(_payload([_container("pihole", "mv0", "10.1.1.53", "02:42:0A:01:01:35")]))
    assert nodes[1]["ip"] == "10.1.1.53"
    assert nodes[1]["mac"] == "02:42:0a:01:01:35"


def test_container_network_mode_resolves_to_a_name() -> None:
    vpn = _container("vpn", "bridge")
    stash = _container("stash", "container:vpnid")
    stash["networkSettings"] = {"Networks": {}}
    nodes, _ = svc._parse_inventory(_payload([vpn, stash]))
    assert nodes[2]["network"] == "container:vpn"


def test_stopped_container_is_offline() -> None:
    nodes, _ = svc._parse_inventory(_payload([_container("old", "bridge", state="EXITED")]))
    assert nodes[1]["status"] == "offline"


def test_container_properties() -> None:
    ct = _container(
        "jellyfin", "bridge",
        webUiUrl="http://10.1.1.231:8096",
        lanIpPorts=["10.1.1.231:8096", "10.1.1.231:8096", "10.1.1.231:7359"],
        labels={"com.docker.compose.project": "media"},
    )
    nodes, _ = svc._parse_inventory(_payload([ct]))
    props = {p["key"]: p["value"] for p in svc.build_unraid_properties(nodes[1])}
    assert props["Image"] == "img/jellyfin:latest"
    assert props["Ports"] == "10.1.1.231:7359, 10.1.1.231:8096"
    assert "Web UI" not in props
    assert props["Compose Project"] == "media"
    assert props["Source"] == "Unraid"


def test_web_ui_becomes_a_service() -> None:
    ct = _container("jellyfin", "bridge", webUiUrl="http://10.1.1.231:8096")
    nodes, _ = svc._parse_inventory(_payload([ct]))
    assert nodes[1]["services"] == [{
        "port": 8096, "protocol": "tcp", "service_name": "Web UI",
        "host": "http://10.1.1.231:8096", "path": "",
    }]


def test_web_ui_points_at_the_containers_own_lan_ip() -> None:
    # Unraid resolves [IP] to the server, but an ipvlan/macvlan container only
    # answers on its own address.
    ct = _container("netdata", "br0", "10.1.1.198", webUiUrl="http://10.1.1.231:19999")
    nodes, _ = svc._parse_inventory(_payload([ct]))
    assert nodes[1]["services"][0]["host"] == "http://10.1.1.198:19999"


def test_web_ui_service_unescapes_the_template_query() -> None:
    service = svc._web_ui_service(
        "http://10.1.1.231:6080/vnc.html?resize=remote&host=10.1.1.231&port=6080"
    )
    assert service is not None
    assert service["path"] == "/vnc.html?resize=remote&host=10.1.1.231&port=6080"


def test_web_ui_service_drops_credentials() -> None:
    service = svc._web_ui_service("http://admin:[email protected]:8080/app?token=abc&lang=en&api_key=xyz")  # trufflehog:ignore
    assert service is not None
    assert service["host"] == "http://10.1.1.231:8080"
    assert service["path"] == "/app?lang=en"
    assert "hunter2" not in str(service) and "abc" not in str(service) and "xyz" not in str(service)


def test_web_ui_service_keeps_ordinary_params() -> None:
    # Whole-name matching: these merely contain a secret-looking fragment.
    service = svc._web_ui_service("http://10.1.1.231:6080/vnc.html?design=1&autoconnect=1&keyboard=us")
    assert service is not None
    assert service["path"] == "/vnc.html?design=1&autoconnect=1&keyboard=us"


def test_secret_param_names() -> None:
    for name in ("token", "X-Api-Key", "api_key", "access_token", "PASSWORD", "admin_password", "sig"):
        assert svc._is_secret_param(name), name
    for name in ("host", "port", "resize", "design", "autoconnect", "keyboard", "lang"):
        assert not svc._is_secret_param(name), name


def test_web_ui_service_defaults_the_scheme_port() -> None:
    service = svc._web_ui_service("https://10.1.1.231/")
    assert service is not None
    assert service["port"] == 443
    assert service["host"] == "https://10.1.1.231"


def test_no_service_without_a_usable_web_ui() -> None:
    assert svc._web_ui_service(None) is None
    assert svc._web_ui_service("ftp://10.1.1.231:21") is None
    assert svc._web_ui_service("http://10.1.1.231:notaport") is None
    nodes, _ = svc._parse_inventory(_payload([_container("redis", "bridge")]))
    assert nodes[1]["services"] == []


def test_malformed_payload_raises() -> None:
    with pytest.raises(ValueError):
        svc._parse_inventory({"info": None, "docker": {}})


def test_unauthenticated_graphql_error_is_auth_error() -> None:
    payload = {"errors": [{"message": "API key validation failed", "extensions": {"code": "UNAUTHENTICATED"}}]}
    with pytest.raises(svc.UnraidAuthError):
        svc._graphql_errors(payload)


def test_other_graphql_error_is_value_error() -> None:
    with pytest.raises(ValueError, match="boom"):
        svc._graphql_errors({"errors": [{"message": "boom"}]})


def test_client_uses_the_chosen_scheme() -> None:
    assert svc._client("tower", 8080, "k", False, False).base_url.scheme == "http"
    assert svc._client("tower", 8443, "k", False, True).base_url.scheme == "https"


def test_redirect_to_https_says_to_use_https() -> None:
    req = httpx.Request("POST", "http://tower:80/graphql")
    resp = httpx.Response(302, request=req, headers={"location": "https://tower/graphql"})
    exc = httpx.HTTPStatusError("x", request=req, response=resp)
    assert svc._sanitize_unraid_error(exc) == "This server uses HTTPS - tick 'Use HTTPS'"


def test_https_to_a_plain_http_port_says_to_untick() -> None:
    exc = httpx.ConnectError("[SSL: WRONG_VERSION_NUMBER] wrong version number (_ssl.c:1032)")
    assert "untick 'Use HTTPS'" in svc._sanitize_unraid_error(exc)


def test_sanitizer_hides_details() -> None:
    req = httpx.Request("POST", "https://h/graphql", headers={"x-api-key": "secret"})
    exc = httpx.HTTPStatusError("x", request=req, response=httpx.Response(403, request=req))
    msg = svc._sanitize_unraid_error(exc)
    assert "secret" not in msg
    assert "Authentication failed" in msg
    assert "TLS" in svc._sanitize_unraid_error(httpx.ConnectError("certificate verify failed"))


VMS = [
    {"id": "server:AC4A600A-C5F8-C5A5-B82A-5F9B46FC8167", "name": "UbuntuServer", "state": "RUNNING"},
    {"id": "server:bde24b48-b75b-24de-0280-c2aacec154b5", "name": "Mhmmint", "state": "SHUTOFF"},
]


def test_vm_nodes_are_keyed_on_their_uuid() -> None:
    nodes, edges = svc._parse_inventory(_payload([]), VMS)
    ubuntu, mint = nodes[1], nodes[2]
    assert ubuntu["ieee_address"] == f"unraid-{HOST_KEY}-vm-ac4a600a-c5f8-c5a5-b82a-5f9b46fc8167"
    assert ubuntu["type"] == "vm"
    assert ubuntu["status"] == "online"
    assert mint["status"] == "offline"
    # No address of its own in the API: nothing to match a scanned row on.
    assert ubuntu["ip"] is None and ubuntu["mac"] is None
    assert edges[0] == {"source": f"unraid-host-{HOST_KEY}", "target": ubuntu["id"]}
    props = {p["key"]: p["value"] for p in svc.build_unraid_properties(ubuntu)}
    assert props["UUID"] == "ac4a600a-c5f8-c5a5-b82a-5f9b46fc8167"


def _mock_client(monkeypatch: pytest.MonkeyPatch, vm_response: dict) -> None:
    """Answer the inventory query with one container and the VM query with ``vm_response``."""
    def handler(request: httpx.Request) -> httpx.Response:
        assert request.headers["x-api-key"] == "k"
        query = request.read().decode()
        if "vms" in query:
            return httpx.Response(200, json=vm_response)
        if "versions" in query and "docker" not in query:
            return httpx.Response(200, json={"data": {"info": {
                "os": {"hostname": "Pearl"}, "versions": {"core": {"unraid": "7.3.1"}},
            }}})
        return httpx.Response(200, json={"data": _payload([_container("plex", "host")])})

    def fake_client(host: str, port: int, api_key: str, verify_tls: bool, use_https: bool) -> httpx.AsyncClient:
        return httpx.AsyncClient(
            base_url=f"{'https' if use_https else 'http'}://{host}:{port}",
            headers={"x-api-key": api_key},
            transport=httpx.MockTransport(handler),
        )

    monkeypatch.setattr(svc, "_client", fake_client)


FORBIDDEN = {"errors": [{"message": "Forbidden", "extensions": {"code": "FORBIDDEN"}}], "data": None}


@pytest.mark.asyncio
async def test_fetch_inventory_round_trip(monkeypatch: pytest.MonkeyPatch) -> None:
    _mock_client(monkeypatch, {"data": {"vms": {"domains": VMS}}})
    nodes, edges, notice = await svc.fetch_unraid_inventory("h", 443, "k", verify_tls=False, use_https=True)
    assert [n["type"] for n in nodes] == ["docker_host", "docker_container", "vm", "vm"]
    assert nodes[0]["services"] == [svc._server_web_ui("h", 443, True)]
    assert len(edges) == 3
    assert notice is None


@pytest.mark.asyncio
async def test_no_vm_access_keeps_the_containers(monkeypatch: pytest.MonkeyPatch) -> None:
    _mock_client(monkeypatch, FORBIDDEN)
    nodes, _, notice = await svc.fetch_unraid_inventory("h", 443, "k", verify_tls=False)
    assert [n["type"] for n in nodes] == ["docker_host", "docker_container"]
    assert notice is not None and "no read access to VMs" in notice


@pytest.mark.asyncio
async def test_connection_test_mentions_missing_vm_access(monkeypatch: pytest.MonkeyPatch) -> None:
    _mock_client(monkeypatch, FORBIDDEN)
    connected, message = await svc.test_unraid_connection("h", 443, "k", verify_tls=False)
    assert connected is True
    assert message.startswith("Connected to Pearl (Unraid 7.3.1)")
    assert "no read access to VMs" in message