Unify Core user handling with HomeAssistantUser model (#6558)

* Unify Core user listing with HomeAssistantUser model

Replace the ingress-specific IngressSessionDataUser with a general
HomeAssistantUser dataclass that models the Core config/auth/list WS
response. This deduplicates the WS call (previously in both auth.py
and module.py) into a single HomeAssistant.list_users() method.

- Add HomeAssistantUser dataclass with fields matching Core's user API
- Remove get_users() and its unnecessary 5-minute Job throttle
- Auth and ingress consumers both use HomeAssistant.list_users()
- Auth API endpoint uses typed attribute access instead of dict keys
- Migrate session serialization from legacy "displayname" to "name"
- Accept both keys in schema/deserialization for backwards compat
- Add test for loading persisted sessions with legacy displayname key

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Tighten list_users() to trust Core's auth/list contract

Core's config/auth/list WS command always returns a list, never None.
Replace the silent `if not raw: return []` (which also swallowed empty
lists) with an assert, remove the dead AuthListUsersNoneResponseError
exception class, and document the HomeAssistantWSError contract in the
docstring.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Remove | None from async_send_command return type

The WebSocket result is always set from data["result"] in _receive_json,
never explicitly to None. Remove the misleading | None from the return
type of both WSClient and HomeAssistantWebSocket async_send_command, and
drop the now-unnecessary assert in list_users.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Use HomeAssistantWSConnectionError in _ensure_connected

_ensure_connected and connect_with_auth raise on connection-level
failures, so use the more specific HomeAssistantWSConnectionError
instead of the broad HomeAssistantWSError. This allows callers to
distinguish connection errors from Core API errors (e.g. unsuccessful
WebSocket command responses). Also document that _ensure_connected can
propagate HomeAssistantAuthError from ensure_access_token.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Remove user list cache from _find_user_by_id

Drop the _list_of_users cache to avoid stale auth data in ingress
session creation. The method now fetches users fresh each time and
returns None on any API error instead of serving potentially outdated
cached results.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

tests/api/test_auth.py

@@ -1,7 +1,6 @@
 """Test auth API."""
 
 from datetime import UTC, datetime, timedelta
-from typing import Any
 from unittest.mock import AsyncMock, MagicMock, patch
 
 from aiohttp.hdrs import WWW_AUTHENTICATE
@@ -169,46 +168,25 @@ async def test_list_users(
     ]
 
 
-@pytest.mark.parametrize(
-    ("send_command_mock", "error_response", "expected_log"),
-    [
-        (
-            AsyncMock(return_value=None),
-            {
-                "result": "error",
-                "message": "Home Assistant returned invalid response of `None` instead of a list of users. Check Home Assistant logs for details (check with `ha core logs`)",
-                "error_key": "auth_list_users_none_response_error",
-                "extra_fields": {"none": "None", "logs_command": "ha core logs"},
-            },
-            "Home Assistant returned invalid response of `None` instead of a list of users. Check Home Assistant logs for details (check with `ha core logs`)",
-        ),
-        (
-            AsyncMock(side_effect=HomeAssistantWSError("fail")),
-            {
-                "result": "error",
-                "message": "Can't request listing users on Home Assistant. Check supervisor logs for details (check with 'ha supervisor logs')",
-                "error_key": "auth_list_users_error",
-                "extra_fields": {"logs_command": "ha supervisor logs"},
-            },
-            "Can't request listing users on Home Assistant: fail",
-        ),
-    ],
-)
-async def test_list_users_failure(
+async def test_list_users_ws_error(
     api_client: TestClient,
     ha_ws_client: AsyncMock,
     caplog: pytest.LogCaptureFixture,
-    send_command_mock: AsyncMock,
-    error_response: dict[str, Any],
-    expected_log: str,
 ):
-    """Test failure listing users via API."""
-    ha_ws_client.async_send_command = send_command_mock
+    """Test WS error when listing users via API."""
+    ha_ws_client.async_send_command = AsyncMock(
+        side_effect=HomeAssistantWSError("fail")
+    )
     resp = await api_client.get("/auth/list")
     assert resp.status == 500
     result = await resp.json()
-    assert result == error_response
-    assert expected_log in caplog.text
+    assert result == {
+        "result": "error",
+        "message": "Can't request listing users on Home Assistant. Check supervisor logs for details (check with 'ha supervisor logs')",
+        "error_key": "auth_list_users_error",
+        "extra_fields": {"logs_command": "ha supervisor logs"},
+    }
+    assert "Can't request listing users on Home Assistant: fail" in caplog.text
 
 
 @pytest.mark.parametrize(

tests/api/test_ingress.py

@@ -99,9 +99,7 @@ async def test_validate_session_with_user_id(
         assert session in coresys.ingress.sessions_data
         assert coresys.ingress.get_session_data(session).user.id == "some-id"
         assert coresys.ingress.get_session_data(session).user.username == "sn"
-        assert (
-            coresys.ingress.get_session_data(session).user.display_name == "Some Name"
-        )
+        assert coresys.ingress.get_session_data(session).user.name == "Some Name"
 
 
 async def test_ingress_proxy_no_content_type_for_empty_body_responses(

tests/homeassistant/test_module.py

@@ -58,12 +58,11 @@ async def test_load(
     assert ha_ws_client.async_send_command.call_args_list[0][0][0] == {"lorem": "ipsum"}
 
 
-async def test_get_users_none(coresys: CoreSys, ha_ws_client: AsyncMock):
-    """Test get users returning none does not fail."""
+async def test_list_users_none(coresys: CoreSys, ha_ws_client: AsyncMock):
+    """Test list users raises on unexpected None response from Core."""
     ha_ws_client.async_send_command.return_value = None
-    assert (
-        await coresys.homeassistant.get_users.__wrapped__(coresys.homeassistant) == []
-    )
+    with pytest.raises(TypeError):
+        await coresys.homeassistant.list_users()
 
 
 async def test_write_pulse_error(coresys: CoreSys, caplog: pytest.LogCaptureFixture):

tests/homeassistant/test_websocket.py

@@ -8,7 +8,7 @@ import pytest
 
 from supervisor.const import CoreState
 from supervisor.coresys import CoreSys
-from supervisor.exceptions import HomeAssistantWSError
+from supervisor.exceptions import HomeAssistantWSConnectionError
 from supervisor.homeassistant.const import WSEvent, WSType
 
 
@@ -81,7 +81,7 @@ async def test_send_command_core_not_reachable(
     ha_ws_client.connected = False
     with (
         patch.object(coresys.homeassistant.api, "check_api_state", return_value=False),
-        pytest.raises(HomeAssistantWSError, match="not reachable"),
+        pytest.raises(HomeAssistantWSConnectionError, match="not reachable"),
     ):
         await coresys.homeassistant.websocket.async_send_command({"type": "test"})
 
@@ -102,7 +102,7 @@ async def test_fire_and_forget_core_not_reachable(
 async def test_send_command_during_shutdown(coresys: CoreSys, ha_ws_client: AsyncMock):
     """Test async_send_command raises during shutdown."""
     await coresys.core.set_state(CoreState.SHUTDOWN)
-    with pytest.raises(HomeAssistantWSError, match="shutting down"):
+    with pytest.raises(HomeAssistantWSConnectionError, match="shutting down"):
         await coresys.homeassistant.websocket.async_send_command({"type": "test"})
 
     ha_ws_client.async_send_command.assert_not_called()

tests/test_ingress.py

@@ -1,10 +1,11 @@
 """Test ingress."""
 
 from datetime import timedelta
+import json
 from pathlib import Path
 from unittest.mock import ANY, patch
 
-from supervisor.const import IngressSessionData, IngressSessionDataUser
+from supervisor.const import HomeAssistantUser, IngressSessionData
 from supervisor.coresys import CoreSys
 from supervisor.ingress import Ingress
 from supervisor.utils.dt import utc_from_timestamp
@@ -34,7 +35,7 @@ def test_session_handling(coresys: CoreSys):
 def test_session_handling_with_session_data(coresys: CoreSys):
     """Create and test session."""
     session = coresys.ingress.create_session(
-        IngressSessionData(IngressSessionDataUser("some-id"))
+        IngressSessionData(HomeAssistantUser("some-id"))
     )
 
     assert session
@@ -76,7 +77,7 @@ async def test_ingress_save_data(coresys: CoreSys, tmp_supervisor_data: Path):
     with patch("supervisor.ingress.FILE_HASSIO_INGRESS", new=config_file):
         ingress = await Ingress(coresys).load_config()
         session = ingress.create_session(
-            IngressSessionData(IngressSessionDataUser("123", "Test", "test"))
+            IngressSessionData(HomeAssistantUser("123", name="Test", username="test"))
         )
         await ingress.save_data()
 
@@ -87,12 +88,47 @@ async def test_ingress_save_data(coresys: CoreSys, tmp_supervisor_data: Path):
     assert await coresys.run_in_executor(get_config) == {
         "session": {session: ANY},
         "session_data": {
-            session: {"user": {"id": "123", "displayname": "Test", "username": "test"}}
+            session: {"user": {"id": "123", "name": "Test", "username": "test"}}
         },
         "ports": {},
     }
 
 
+async def test_ingress_load_legacy_displayname(
+    coresys: CoreSys, tmp_supervisor_data: Path
+):
+    """Test loading session data with legacy 'displayname' key."""
+    config_file = tmp_supervisor_data / "ingress.json"
+    session_token = "a" * 128
+
+    config_file.write_text(
+        json.dumps(
+            {
+                "session": {session_token: 9999999999.0},
+                "session_data": {
+                    session_token: {
+                        "user": {
+                            "id": "456",
+                            "displayname": "Legacy Name",
+                            "username": "legacy",
+                        }
+                    }
+                },
+                "ports": {},
+            }
+        )
+    )
+
+    with patch("supervisor.ingress.FILE_HASSIO_INGRESS", new=config_file):
+        ingress = await Ingress(coresys).load_config()
+
+    session_data = ingress.get_session_data(session_token)
+    assert session_data is not None
+    assert session_data.user.id == "456"
+    assert session_data.user.name == "Legacy Name"
+    assert session_data.user.username == "legacy"
+
+
 async def test_ingress_reload_ignore_none_data(coresys: CoreSys):
     """Test reloading ingress does not add None for session data and create errors."""
     session = coresys.ingress.create_session()