Improve and extend frontend probe after update with WebSocket check (#6811)

agners · claude · web-flow · commit ad1a9115d8f0 · 2026-05-06T10:54:05.000+02:00
* Improve and extend frontend probe after update with WebSocket check The post-update health check introduced in #6311 added HomeAssistantAPI.check_frontend_available, which fetched the frontend through the existing Supervisor-internal API connection to Core. Since #6742 that connection optionally runs over a Unix socket with no authentication, so the request no longer exercises the same transport, auth and routing path that an external HTTP client uses. Move the frontend probe out of HomeAssistantAPI into a small frontend_check module that talks to Core's TCP endpoints via the plain websession with no authentication, mirroring what an external client would see. While doing this, extend the post-update verification to also probe the WebSocket endpoint: open /api/websocket and confirm the first frame is the auth_required text message. This catches the kind of WebSocket breakage seen in #6802, where api/config still listed websocket_api as loaded and GET / still returned HTML, but the WebSocket handshake completed with an immediate close frame and the frontend was unusable. The component check now also requires "http" to be loaded, in addition to "frontend" and "websocket_api", and iterates so every missing component is logged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Address review feedback on WebSocket probe - Wrap ws_connect in asyncio.wait_for so the handshake has an explicit bounded timeout (the global websession's default timeout would otherwise apply). - Validate that the auth_required payload is a JSON object before calling .get("type"); a list/string would otherwise raise AttributeError at runtime. - Add a regression test covering a non-dict JSON payload. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/supervisor/homeassistant/api.py b/supervisor/homeassistant/api.py
@@ -368,32 +368,3 @@ async def check_api_state(self) -> bool:
         if state := await self.get_api_state():
             return state.core_state == "RUNNING" or state.offline_db_migration
         return False
-
-    async def check_frontend_available(self) -> bool:
-        """Check if the frontend is accessible by fetching the root path.
-
-        Caller should make sure that Home Assistant Core is running before
-        calling this method.
-
-        Returns:
-            True if the frontend responds successfully, False otherwise.
-
-        """
-        try:
-            async with self.make_request("get", "", timeout=30) as resp:
-                # Frontend should return HTML content
-                if resp.status == 200:
-                    content_type = resp.headers.get(hdrs.CONTENT_TYPE, "")
-                    if "text/html" in content_type:
-                        _LOGGER.debug("Frontend is accessible and serving HTML")
-                        return True
-                    _LOGGER.warning(
-                        "Frontend responded but with unexpected content type: %s",
-                        content_type,
-                    )
-                    return False
-                _LOGGER.warning("Frontend returned status %s", resp.status)
-                return False
-        except HomeAssistantAPIError as err:
-            _LOGGER.debug("Cannot reach frontend: %s", err)
-            return False
diff --git a/supervisor/homeassistant/core.py b/supervisor/homeassistant/core.py
@@ -45,6 +45,7 @@
     WATCHDOG_THROTTLE_MAX_CALLS,
     WATCHDOG_THROTTLE_PERIOD,
 )
+from .frontend_check import verify_frontend
 
 _LOGGER: logging.Logger = logging.getLogger(__name__)
 
@@ -333,17 +334,19 @@ async def _update(to_version: AwesomeVersion) -> None:
                 # The API stopped responding between the update and now
                 self._error_state = True
             else:
-                # Verify that the frontend is loaded
-                if "frontend" not in data.get("components", []):
-                    _LOGGER.error("API responds but frontend is not loaded")
+                components = data.get("components", [])
+                # Verify that the integrations needed to serve the frontend
+                # are loaded
+                for required in ("http", "frontend", "websocket_api"):
+                    if required not in components:
+                        _LOGGER.error("API responds but %s is not loaded", required)
+                        self._error_state = True
+                # Probe the public HTTP/WS endpoints as an external client
+                # would, to catch cases where integrations are listed as
+                # loaded but the endpoints don't actually function.
+                if not self._error_state and not await verify_frontend(self.coresys):
                     self._error_state = True
-                # Check that the frontend is actually accessible
-                elif not await self.sys_homeassistant.api.check_frontend_available():
-                    _LOGGER.error(
-                        "Frontend component loaded but frontend is not accessible"
-                    )
-                    self._error_state = True
-                else:
+                if not self._error_state:
                     # Health checks passed, clean up old image
                     with suppress(DockerError):
                         await self.instance.cleanup(old_image=old_image)
diff --git a/supervisor/homeassistant/frontend_check.py b/supervisor/homeassistant/frontend_check.py
@@ -0,0 +1,90 @@
+"""External frontend availability probes for Home Assistant Core.
+
+These probes intentionally bypass the Supervisor-internal API layer
+(authentication, Unix socket transport, retries) so they exercise the
+same code paths an external HTTP/WebSocket client would. The goal is
+to detect cases where Core's HTTP API responds but the user-facing
+frontend or WebSocket endpoint is broken (e.g. due to a custom http
+component override masking websocket_api).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+import logging
+
+import aiohttp
+from aiohttp import hdrs
+
+from ..coresys import CoreSys
+
+_LOGGER: logging.Logger = logging.getLogger(__name__)
+
+_PROBE_TIMEOUT = aiohttp.ClientTimeout(total=30)
+_WS_HANDSHAKE_TIMEOUT = 30.0
+_WS_RECEIVE_TIMEOUT = 10.0
+
+
+async def check_frontend(coresys: CoreSys) -> bool:
+    """Verify the frontend serves HTML on the root path."""
+    url = f"{coresys.homeassistant.api_url}/"
+    try:
+        async with coresys.websession.get(
+            url, timeout=_PROBE_TIMEOUT, ssl=False
+        ) as resp:
+            if resp.status != 200:
+                _LOGGER.error("Frontend returned status %s", resp.status)
+                return False
+            content_type = resp.headers.get(hdrs.CONTENT_TYPE, "")
+            if "text/html" not in content_type:
+                _LOGGER.error(
+                    "Frontend responded with unexpected content type: %s",
+                    content_type,
+                )
+                return False
+    except (aiohttp.ClientError, TimeoutError) as err:
+        _LOGGER.error("Cannot reach frontend at %s: %s", url, err)
+        return False
+
+    _LOGGER.debug("Frontend is accessible and serving HTML")
+    return True
+
+
+async def check_websocket(coresys: CoreSys) -> bool:
+    """Verify the WebSocket endpoint accepts a handshake.
+
+    We don't authenticate. A working endpoint sends an `auth_required`
+    text frame immediately after the upgrade; that's enough to confirm
+    websocket_api is wired up and functional.
+    """
+    url = coresys.homeassistant.ws_url
+    ws: aiohttp.ClientWebSocketResponse | None = None
+    try:
+        ws = await asyncio.wait_for(
+            coresys.websession.ws_connect(url, ssl=False),
+            timeout=_WS_HANDSHAKE_TIMEOUT,
+        )
+        msg = await ws.receive(timeout=_WS_RECEIVE_TIMEOUT)
+        if msg.type != aiohttp.WSMsgType.TEXT:
+            _LOGGER.error("WebSocket handshake returned non-text message: %s", msg.type)
+            return False
+        data = msg.json()
+        if not isinstance(data, dict) or data.get("type") != "auth_required":
+            _LOGGER.error("WebSocket did not send auth_required, got: %s", data)
+            return False
+    except (aiohttp.ClientError, TimeoutError, ValueError) as err:
+        _LOGGER.error("WebSocket probe to %s failed: %s", url, err)
+        return False
+    finally:
+        if ws is not None:
+            with suppress(Exception):
+                await ws.close()
+
+    _LOGGER.debug("WebSocket endpoint accepted handshake")
+    return True
+
+
+async def verify_frontend(coresys: CoreSys) -> bool:
+    """Run both frontend probes; return True only if both succeed."""
+    return await check_frontend(coresys) and await check_websocket(coresys)
diff --git a/tests/api/test_homeassistant.py b/tests/api/test_homeassistant.py
@@ -17,6 +17,7 @@
 from supervisor.exceptions import HomeAssistantError
 from supervisor.homeassistant.api import APIState, HomeAssistantAPI
 from supervisor.homeassistant.const import WSEvent
+import supervisor.homeassistant.core as ha_core
 from supervisor.homeassistant.core import HomeAssistantCore
 from supervisor.homeassistant.module import HomeAssistant
 from supervisor.resolution.const import ContextType, IssueType
@@ -315,9 +316,11 @@ async def test_api_progress_updates_home_assistant_update(
             new=PropertyMock(return_value=AwesomeVersion("2025.8.0")),
         ),
         patch.object(
-            HomeAssistantAPI, "get_config", return_value={"components": ["frontend"]}
+            HomeAssistantAPI,
+            "get_config",
+            return_value={"components": ["http", "frontend", "websocket_api"]},
         ),
-        patch.object(HomeAssistantAPI, "check_frontend_available", return_value=True),
+        patch.object(ha_core, "verify_frontend", AsyncMock(return_value=True)),
     ):
         resp = await api_client.post(f"{root}/update", json={"version": "2025.8.3"})
 
@@ -492,9 +495,11 @@ async def test_update_frontend_check_success(
             new=PropertyMock(return_value=AwesomeVersion("2025.8.0")),
         ),
         patch.object(
-            HomeAssistantAPI, "get_config", return_value={"components": ["frontend"]}
+            HomeAssistantAPI,
+            "get_config",
+            return_value={"components": ["http", "frontend", "websocket_api"]},
         ),
-        patch.object(HomeAssistantAPI, "check_frontend_available", return_value=True),
+        patch.object(ha_core, "verify_frontend", AsyncMock(return_value=True)),
         patch.object(DockerInterface, "cleanup") as mock_cleanup,
     ):
         resp = await api_client.post(f"{root}/update", json={"version": "2025.8.3"})
@@ -509,7 +514,7 @@ async def test_update_frontend_check_fails_triggers_rollback(
     caplog: pytest.LogCaptureFixture,
     tmp_supervisor_data: Path,
 ):
-    """Test that update triggers rollback when frontend check fails."""
+    """Test that update triggers rollback when health probes fail."""
     api_client, root = core_api_client_with_root
     coresys.hardware.disk.get_disk_free_space = lambda x: 5000
     coresys.homeassistant.version = AwesomeVersion("2025.8.0")
@@ -535,16 +540,17 @@ async def mock_update(*args, **kwargs):
             new=PropertyMock(return_value=AwesomeVersion("2025.8.0")),
         ),
         patch.object(
-            HomeAssistantAPI, "get_config", return_value={"components": ["frontend"]}
+            HomeAssistantAPI,
+            "get_config",
+            return_value={"components": ["http", "frontend", "websocket_api"]},
         ),
-        patch.object(HomeAssistantAPI, "check_frontend_available", return_value=False),
+        patch.object(ha_core, "verify_frontend", AsyncMock(return_value=False)),
         patch.object(DockerInterface, "cleanup") as mock_cleanup,
     ):
         resp = await api_client.post(f"{root}/update", json={"version": "2025.8.3"})
 
     # Update should trigger rollback, which succeeds and returns 200
     assert resp.status == 200
-    assert "Frontend component loaded but frontend is not accessible" in caplog.text
     assert "HomeAssistant update failed -> rollback!" in caplog.text
     # Should have called update twice (once for update, once for rollback)
     assert update_call_count == 2
@@ -556,6 +562,57 @@ async def mock_update(*args, **kwargs):
     mock_cleanup.assert_not_called()
 
 
+async def test_update_websocket_api_missing_triggers_rollback(
+    core_api_client_with_root: tuple[TestClient, str],
+    coresys: CoreSys,
+    caplog: pytest.LogCaptureFixture,
+    tmp_supervisor_data: Path,
+):
+    """Test that update triggers rollback when websocket_api component is not loaded."""
+    api_client, root = core_api_client_with_root
+    coresys.hardware.disk.get_disk_free_space = lambda x: 5000
+    coresys.homeassistant.version = AwesomeVersion("2025.8.0")
+
+    update_call_count = 0
+
+    async def mock_update(*args, **kwargs):
+        nonlocal update_call_count
+        update_call_count += 1
+        if update_call_count == 1:
+            coresys.homeassistant.version = AwesomeVersion("2025.8.3")
+        elif update_call_count == 2:
+            coresys.homeassistant.version = AwesomeVersion("2025.8.0")
+
+    with (
+        patch.object(DockerInterface, "update", new=mock_update),
+        patch.object(
+            DockerHomeAssistant,
+            "version",
+            new=PropertyMock(return_value=AwesomeVersion("2025.8.0")),
+        ),
+        patch.object(
+            HomeAssistantAPI,
+            "get_config",
+            return_value={"components": ["http", "frontend"]},
+        ),
+        patch.object(
+            ha_core, "verify_frontend", AsyncMock(return_value=True)
+        ) as mock_frontend_check,
+        patch.object(DockerInterface, "cleanup") as mock_cleanup,
+    ):
+        resp = await api_client.post(f"{root}/update", json={"version": "2025.8.3"})
+
+    assert resp.status == 200
+    assert "API responds but websocket_api is not loaded" in caplog.text
+    assert "HomeAssistant update failed -> rollback!" in caplog.text
+    assert update_call_count == 2
+    mock_frontend_check.assert_not_called()
+    assert (
+        Issue(IssueType.UPDATE_ROLLBACK, ContextType.CORE) in coresys.resolution.issues
+    )
+    mock_cleanup.assert_not_called()
+
+
 async def test_update_get_config_error_triggers_rollback(
     core_api_client_with_root: tuple[TestClient, str],
     coresys: CoreSys,
@@ -586,16 +643,16 @@ async def mock_update(*args, **kwargs):
         ),
         patch.object(HomeAssistantAPI, "get_config", side_effect=HomeAssistantError),
         patch.object(
-            HomeAssistantAPI, "check_frontend_available", return_value=True
-        ) as mock_check_frontend,
+            ha_core, "verify_frontend", AsyncMock(return_value=True)
+        ) as mock_frontend_check,
         patch.object(DockerInterface, "cleanup") as mock_cleanup,
     ):
         resp = await api_client.post(f"{root}/update", json={"version": "2025.8.3"})
 
     assert resp.status == 200
     assert "HomeAssistant update failed -> rollback!" in caplog.text
     assert update_call_count == 2
-    mock_check_frontend.assert_not_called()
+    mock_frontend_check.assert_not_called()
     assert (
         Issue(IssueType.UPDATE_ROLLBACK, ContextType.CORE) in coresys.resolution.issues
     )
diff --git a/tests/homeassistant/test_api.py b/tests/homeassistant/test_api.py
@@ -3,7 +3,6 @@
 from contextlib import asynccontextmanager
 from unittest.mock import AsyncMock, MagicMock, patch
 
-from aiohttp import hdrs
 from awesomeversion import AwesomeVersion
 import pytest
 
@@ -17,49 +16,6 @@
 
 from tests.common import MockResponse
 
-# --- check_frontend_available ---
-
-
-@pytest.mark.parametrize(
-    ("status", "content_type", "expected"),
-    [
-        (200, "text/html; charset=utf-8", True),
-        (404, "text/html", False),
-        (200, "application/json", False),
-    ],
-)
-async def test_check_frontend_available(
-    coresys: CoreSys, status: int, content_type: str, expected: bool
-):
-    """Test frontend availability based on HTTP status and content type."""
-    mock_response = MagicMock()
-    mock_response.status = status
-    mock_response.headers = {hdrs.CONTENT_TYPE: content_type}
-
-    @asynccontextmanager
-    async def mock_make_request(*args, **kwargs):
-        yield mock_response
-
-    with patch.object(
-        type(coresys.homeassistant.api), "make_request", new=mock_make_request
-    ):
-        assert await coresys.homeassistant.api.check_frontend_available() is expected
-
-
-async def test_check_frontend_available_api_error(coresys: CoreSys):
-    """Test frontend availability check handles API errors gracefully."""
-
-    @asynccontextmanager
-    async def mock_make_request(*args, **kwargs):
-        raise HomeAssistantAPIError("Connection failed")
-        yield  # pragma: no cover
-
-    with patch.object(
-        type(coresys.homeassistant.api), "make_request", new=mock_make_request
-    ):
-        assert await coresys.homeassistant.api.check_frontend_available() is False
-
-
 # --- get_config / get_core_state ---
 
 
diff --git a/tests/homeassistant/test_frontend_check.py b/tests/homeassistant/test_frontend_check.py
