Add modelable ingress APIs to client library (#290)

* Add modelable ingress APIs to client library

* Fixes from feedback

Author: mdegat01

aiohasupervisor/ingress.py

@@ -0,0 +1,33 @@
+"""Ingress client for supervisor."""
+
+from .client import _SupervisorComponentClient
+from .const import ResponseType
+from .models.ingress import CreateSessionOptions, IngressPanel, IngressPanels, Session
+
+
+class IngressClient(_SupervisorComponentClient):
+    """Handles ingress access in Supervisor.
+
+    This includes only the APIs with fixed paths and models from Supervisor's Ingress
+    API. The wildcard proxy endpoints that allow the UI to talk to addons through Core
+    and Supervisor are intentionally omitted as they can't be modeled.
+    """
+
+    async def panels(self) -> dict[str, IngressPanel]:
+        """Get ingress panels, returns a map of addon slug to panel info."""
+        result = await self._client.get("ingress/panels")
+        return IngressPanels.from_dict(result.data).panels
+
+    async def create_session(self, options: CreateSessionOptions | None = None) -> str:
+        """Create a new ingress session."""
+        result = await self._client.post(
+            "ingress/session",
+            json=options.to_dict() if options else None,
+            response_type=ResponseType.JSON,
+        )
+        return Session.from_dict(result.data).session
+
+    async def validate_session(self, session: str) -> None:
+        """Validate an existing ingress session."""
+        body = Session(session=session).to_dict()
+        await self._client.post("ingress/validate_session", json=body)

aiohasupervisor/models/__init__.py

@@ -72,6 +72,7 @@
     ServiceState,
     ShutdownOptions,
 )
+from aiohasupervisor.models.ingress import CreateSessionOptions, IngressPanel
 from aiohasupervisor.models.jobs import (
     Job,
     JobCondition,
@@ -195,6 +196,7 @@
     "CheckType",
     "ContextType",
     "CpuArch",
+    "CreateSessionOptions",
     "DataDisk",
     "DetectBlockingIO",
     "Discovery",
@@ -221,11 +223,12 @@
     "IPv4Config",
     "IPv6",
     "IPv6Config",
+    "IngressPanel",
     "InstalledAddon",
     "InstalledAddonComplete",
-    "InterfaceMethod",
     "InterfaceAddrGenMode",
     "InterfaceIp6Privacy",
+    "InterfaceMethod",
     "InterfaceType",
     "Issue",
     "IssueType",

aiohasupervisor/models/ingress.py

@@ -0,0 +1,36 @@
+"""Models for ingress APIs."""
+
+from dataclasses import dataclass
+
+from .base import Request, ResponseData
+
+
+@dataclass(frozen=True, slots=True)
+class IngressPanel(ResponseData):
+    """IngressPanel model."""
+
+    title: str
+    icon: str
+    admin: bool
+    enable: bool | None
+
+
+@dataclass(frozen=True, slots=True)
+class IngressPanels(ResponseData):
+    """IngressPanels model."""
+
+    panels: dict[str, IngressPanel]
+
+
+@dataclass(frozen=True, slots=True)
+class CreateSessionOptions(Request):
+    """CreateSessionOptions model."""
+
+    user_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class Session(ResponseData):
+    """Session model."""
+
+    session: str

aiohasupervisor/root.py

@@ -10,6 +10,7 @@
 from .discovery import DiscoveryClient
 from .homeassistant import HomeAssistantClient
 from .host import HostClient
+from .ingress import IngressClient
 from .jobs import JobsClient
 from .models.root import AvailableUpdate, AvailableUpdates, RootInfo
 from .mounts import MountsClient
@@ -43,6 +44,7 @@ def __init__(
         self._store = StoreClient(self._client)
         self._supervisor = SupervisorManagementClient(self._client)
         self._homeassistant = HomeAssistantClient(self._client)
+        self._ingress = IngressClient(self._client)
 
     @property
     def addons(self) -> AddonsClient:
@@ -104,6 +106,11 @@ def supervisor(self) -> SupervisorManagementClient:
         """Get supervisor component client."""
         return self._supervisor
 
+    @property
+    def ingress(self) -> IngressClient:
+        """Get ingress component client."""
+        return self._ingress
+
     async def info(self) -> RootInfo:
         """Get root info."""
         result = await self._client.get("info")

tests/fixtures/create_session.json

@@ -0,0 +1,6 @@
+{
+  "result": "ok",
+  "data": {
+    "session": "abc123"
+  }
+}

tests/fixtures/ingress_panels.json

@@ -0,0 +1,19 @@
+{
+  "result": "ok",
+  "data": {
+    "panels": {
+      "core_ssh": {
+        "title": "Terminal",
+        "icon": "mdi:console",
+        "admin": true,
+        "enable": false
+      },
+      "a0d7b954_vscode": {
+        "title": "Studio Code Server",
+        "icon": "mdi:microsoft-visual-studio-code",
+        "admin": true,
+        "enable": true
+      }
+    }
+  }
+}

tests/test_ingress.py

@@ -0,0 +1,69 @@
+"""Test ingress component client."""
+
+from aioresponses import aioresponses
+import pytest
+from yarl import URL
+
+from aiohasupervisor import SupervisorClient
+from aiohasupervisor.models import CreateSessionOptions
+
+from . import load_fixture
+from .const import SUPERVISOR_URL
+
+
+async def test_panels(
+    responses: aioresponses, supervisor_client: SupervisorClient
+) -> None:
+    """Test panels API."""
+    responses.get(
+        f"{SUPERVISOR_URL}/ingress/panels",
+        status=200,
+        body=load_fixture("ingress_panels.json"),
+    )
+    result = await supervisor_client.ingress.panels()
+    assert "core_ssh" in result
+    assert result["core_ssh"].title == "Terminal"
+    assert result["core_ssh"].icon == "mdi:console"
+    assert result["core_ssh"].admin is True
+    assert result["core_ssh"].enable is False
+    assert "a0d7b954_vscode" in result
+    assert result["a0d7b954_vscode"].title == "Studio Code Server"
+    assert result["a0d7b954_vscode"].icon == "mdi:microsoft-visual-studio-code"
+    assert result["a0d7b954_vscode"].admin is True
+    assert result["a0d7b954_vscode"].enable is True
+
+
+@pytest.mark.parametrize(
+    ("options", "expected_body"),
+    [(None, None), (CreateSessionOptions(user_id="test"), {"user_id": "test"})],
+)
+async def test_create_session(
+    responses: aioresponses,
+    supervisor_client: SupervisorClient,
+    options: CreateSessionOptions | None,
+    expected_body: dict[str, str] | None,
+) -> None:
+    """Test create session API."""
+    session_url = f"{SUPERVISOR_URL}/ingress/session"
+    responses.post(session_url, status=200, body=load_fixture("create_session.json"))
+    result = await supervisor_client.ingress.create_session(options)
+    assert result == "abc123"
+
+    assert responses.requests.keys() == {("POST", URL(session_url))}
+    session_calls = responses.requests[("POST", URL(session_url))]
+    assert len(session_calls) == 1
+    assert session_calls[0].kwargs["json"] == expected_body
+
+
+async def test_validate_session(
+    responses: aioresponses, supervisor_client: SupervisorClient
+) -> None:
+    """Test validate session API."""
+    validate_url = f"{SUPERVISOR_URL}/ingress/validate_session"
+    responses.post(validate_url, status=200)
+    assert await supervisor_client.ingress.validate_session("abc123") is None
+
+    assert responses.requests.keys() == {("POST", URL(validate_url))}
+    validate_calls = responses.requests[("POST", URL(validate_url))]
+    assert len(validate_calls) == 1
+    assert validate_calls[0].kwargs["json"] == {"session": "abc123"}