Make error responses more translation/client library friendly

Author: mdegat01

supervisor/addons/addon.py

@@ -67,9 +67,9 @@
 from ..docker.stats import DockerStats
 from ..exceptions import (
     AddonConfigurationError,
+    AddonNotSupportedError,
     AddonsError,
     AddonsJobError,
-    AddonsNotSupportedError,
     ConfigurationFileError,
     DockerError,
     HomeAssistantAPIError,
@@ -1172,7 +1172,7 @@ async def stats(self) -> DockerStats:
     async def write_stdin(self, data) -> None:
         """Write data to add-on stdin."""
         if not self.with_stdin:
-            raise AddonsNotSupportedError(
+            raise AddonNotSupportedError(
                 f"Add-on {self.slug} does not support writing to stdin!", _LOGGER.error
             )
 
@@ -1419,7 +1419,7 @@ def _extract_tarfile() -> tuple[TemporaryDirectory, dict[str, Any]]:
 
             # If available
             if not self._available(data[ATTR_SYSTEM]):
-                raise AddonsNotSupportedError(
+                raise AddonNotSupportedError(
                     f"Add-on {self.slug} is not available for this platform",
                     _LOGGER.error,
                 )

supervisor/addons/manager.py

@@ -14,9 +14,9 @@
 from ..const import AddonBoot, AddonStartup, AddonState
 from ..coresys import CoreSys, CoreSysAttributes
 from ..exceptions import (
+    AddonNotSupportedError,
     AddonsError,
     AddonsJobError,
-    AddonsNotSupportedError,
     CoreDNSError,
     DockerError,
     HassioError,
@@ -307,7 +307,7 @@ async def rebuild(self, slug: str, *, force: bool = False) -> asyncio.Task | Non
                 "Version changed, use Update instead Rebuild", _LOGGER.error
             )
         if not force and not addon.need_build:
-            raise AddonsNotSupportedError(
+            raise AddonNotSupportedError(
                 "Can't rebuild a image based add-on", _LOGGER.error
             )
 

supervisor/addons/model.py

@@ -89,7 +89,12 @@
 )
 from ..coresys import CoreSys
 from ..docker.const import Capabilities
-from ..exceptions import AddonsNotSupportedError
+from ..exceptions import (
+    AddonNotSupportedArchitectureError,
+    AddonNotSupportedError,
+    AddonNotSupportedHomeAssistantVersionError,
+    AddonNotSupportedMachineTypeError,
+)
 from ..jobs.const import JOB_GROUP_ADDON
 from ..jobs.job_group import JobGroup
 from ..utils import version_is_new_enough
@@ -680,19 +685,17 @@ def _validate_availability(
         """Validate if addon is available for current system."""
         # Architecture
         if not self.sys_arch.is_supported(config[ATTR_ARCH]):
-            raise AddonsNotSupportedError(
-                f"Add-on {self.slug} not supported on this platform, supported architectures: {', '.join(config[ATTR_ARCH])}",
-                logger,
+            raise AddonNotSupportedArchitectureError(
+                logger, slug=self.slug, architectures=config[ATTR_ARCH]
             )
 
         # Machine / Hardware
         machine = config.get(ATTR_MACHINE)
         if machine and (
             f"!{self.sys_machine}" in machine or self.sys_machine not in machine
         ):
-            raise AddonsNotSupportedError(
-                f"Add-on {self.slug} not supported on this machine, supported machine types: {', '.join(machine)}",
-                logger,
+            raise AddonNotSupportedMachineTypeError(
+                logger, slug=self.slug, machine_types=machine
             )
 
         # Home Assistant
@@ -701,16 +704,15 @@ def _validate_availability(
             if version and not version_is_new_enough(
                 self.sys_homeassistant.version, version
             ):
-                raise AddonsNotSupportedError(
-                    f"Add-on {self.slug} not supported on this system, requires Home Assistant version {version} or greater",
-                    logger,
+                raise AddonNotSupportedHomeAssistantVersionError(
+                    logger, slug=self.slug, version=str(version)
                 )
 
     def _available(self, config) -> bool:
         """Return True if this add-on is available on this platform."""
         try:
             self._validate_availability(config)
-        except AddonsNotSupportedError:
+        except AddonNotSupportedError:
             return False
 
         return True

supervisor/api/utils.py

@@ -16,8 +16,11 @@
     HEADER_TOKEN,
     HEADER_TOKEN_OLD,
     JSON_DATA,
+    JSON_ERROR_KEY,
+    JSON_EXTRA_FIELDS,
     JSON_JOB_ID,
     JSON_MESSAGE,
+    JSON_MESSAGE_TEMPLATE,
     JSON_RESULT,
     REQUEST_FROM,
     RESULT_ERROR,
@@ -136,10 +139,11 @@ async def wrap_api(
 
 
 def api_return_error(
-    error: Exception | None = None,
+    error: HassioError | None = None,
     message: str | None = None,
     error_type: str | None = None,
     status: int = 400,
+    *,
     job_id: str | None = None,
 ) -> web.Response:
     """Return an API error message."""
@@ -158,12 +162,18 @@ def api_return_error(
                 body=message.encode(), content_type=error_type, status=status
             )
         case _:
-            result = {
+            result: dict[str, Any] = {
                 JSON_RESULT: RESULT_ERROR,
                 JSON_MESSAGE: message,
             }
             if job_id:
                 result[JSON_JOB_ID] = job_id
+            if error and error.error_key:
+                result[JSON_ERROR_KEY] = error.error_key
+            if error and error.message_template:
+                result[JSON_MESSAGE_TEMPLATE] = error.message_template
+            if error and error.extra_fields:
+                result[JSON_EXTRA_FIELDS] = error.extra_fields
 
     return web.json_response(
         result,

supervisor/const.py

@@ -76,6 +76,9 @@
 JSON_MESSAGE = "message"
 JSON_RESULT = "result"
 JSON_JOB_ID = "job_id"
+JSON_ERROR_KEY = "error_key"
+JSON_MESSAGE_TEMPLATE = "message_template"
+JSON_EXTRA_FIELDS = "extra_fields"
 
 RESULT_ERROR = "error"
 RESULT_OK = "ok"

supervisor/exceptions.py

@@ -1,17 +1,32 @@
 """Core Exceptions."""
 
 from collections.abc import Callable
+from typing import Any
 
 
 class HassioError(Exception):
     """Root exception."""
 
+    error_key: str | None = None
+    message_template: str | None = None
+
     def __init__(
         self,
         message: str | None = None,
         logger: Callable[..., None] | None = None,
+        *,
+        extra_fields: dict[str, Any] | None = None,
     ) -> None:
         """Raise & log."""
+        self.extra_fields = extra_fields or {}
+
+        if not message and self.message_template:
+            message = (
+                self.message_template.format(**self.extra_fields)
+                if self.extra_fields
+                else self.message_template
+            )
+
         if logger is not None and message is not None:
             logger(message)
 
@@ -235,8 +250,71 @@ class AddonConfigurationError(AddonsError):
     """Error with add-on configuration."""
 
 
-class AddonsNotSupportedError(HassioNotSupportedError):
-    """Addons don't support a function."""
+class AddonNotSupportedError(HassioNotSupportedError):
+    """Addon doesn't support a function."""
+
+
+class AddonNotSupportedArchitectureError(AddonNotSupportedError):
+    """Addon does not support system due to architecture."""
+
+    error_key = "addon_not_supported_architecture_error"
+    message_template = "Add-on {slug} not supported on this platform, supported architectures: {architectures}"
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        slug: str,
+        architectures: list[str],
+    ) -> None:
+        """Initialize exception."""
+        super().__init__(
+            None,
+            logger,
+            extra_fields={"slug": slug, "architectures": ", ".join(architectures)},
+        )
+
+
+class AddonNotSupportedMachineTypeError(AddonNotSupportedError):
+    """Addon does not support system due to machine type."""
+
+    error_key = "addon_not_supported_machine_type_error"
+    message_template = "Add-on {slug} not supported on this machine, supported machine types: {machine_types}"
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        slug: str,
+        machine_types: list[str],
+    ) -> None:
+        """Initialize exception."""
+        super().__init__(
+            None,
+            logger,
+            extra_fields={"slug": slug, "machine_types": ", ".join(machine_types)},
+        )
+
+
+class AddonNotSupportedHomeAssistantVersionError(AddonNotSupportedError):
+    """Addon does not support system due to Home Assistant version."""
+
+    error_key = "addon_not_supported_home_assistant_version_error"
+    message_template = "Add-on {slug} not supported on this system, requires Home Assistant version {version} or greater"
+
+    def __init__(
+        self,
+        logger: Callable[..., None] | None = None,
+        *,
+        slug: str,
+        version: str,
+    ) -> None:
+        """Initialize exception."""
+        super().__init__(
+            None,
+            logger,
+            extra_fields={"slug": slug, "version": version},
+        )
 
 
 class AddonsJobError(AddonsError, JobException):
@@ -319,10 +397,17 @@ def __init__(
         self,
         message: str | None = None,
         logger: Callable[..., None] | None = None,
+        *,
         job_id: str | None = None,
+        error: HassioError | None = None,
     ) -> None:
         """Raise & log, optionally with job."""
-        super().__init__(message, logger)
+        # Allow these to be set from another error here since APIErrors essentially wrap others to add a status
+        self.error_key = error.error_key if error else None
+        self.message_template = error.message_template if error else None
+        super().__init__(
+            message, logger, extra_fields=error.extra_fields if error else None
+        )
         self.job_id = job_id
 
 

tests/api/test_store.py

@@ -505,8 +505,9 @@ async def test_api_store_addons_addon_availability_success(
     assert resp.status == 200
 
 
+@pytest.mark.parametrize("supported_architectures", [["i386"], ["i386", "aarch64"]])
 async def test_api_store_addons_addon_availability_arch_not_supported(
-    api_client: TestClient, coresys: CoreSys
+    api_client: TestClient, coresys: CoreSys, supported_architectures: list[str]
 ):
     """Test /store/addons/{addon}/availability REST API - architecture not supported."""
     # Create an addon with unsupported architecture
@@ -516,8 +517,8 @@ async def test_api_store_addons_addon_availability_arch_not_supported(
     # Set addon config with unsupported architecture
     addon_config = {
         "advanced": False,
-        "arch": ["i386"],  # Not supported on current system
-        "slug": "test_arch",
+        "arch": supported_architectures,
+        "slug": "test_arch_addon",
         "description": "Test arch add-on",
         "name": "Test Arch Add-on",
         "repository": "test",
@@ -531,10 +532,23 @@ async def test_api_store_addons_addon_availability_arch_not_supported(
         resp = await api_client.get(f"/store/addons/{addon_obj.slug}/availability")
         assert resp.status == 400
         result = await resp.json()
-        assert "not supported on this platform" in result["message"]
+        assert result["error_key"] == "addon_not_supported_architecture_error"
+        assert (
+            result["message_template"]
+            == "Add-on {slug} not supported on this platform, supported architectures: {architectures}"
+        )
+        assert result["extra_fields"] == {
+            "slug": "test_arch_addon",
+            "architectures": ", ".join(supported_architectures),
+        }
+        assert result["message"] == result["message_template"].format(
+            **result["extra_fields"]
+        )
 
 
-@pytest.mark.parametrize("supported_machines", [["odroid-n2"], ["!qemux86-64"]])
+@pytest.mark.parametrize(
+    "supported_machines", [["odroid-n2"], ["!qemux86-64"], ["a", "b"]]
+)
 async def test_api_store_addons_addon_availability_machine_not_supported(
     api_client: TestClient, coresys: CoreSys, supported_machines: list[str]
 ):
@@ -548,7 +562,7 @@ async def test_api_store_addons_addon_availability_machine_not_supported(
         "advanced": False,
         "arch": ["amd64"],
         "machine": supported_machines,
-        "slug": "test_machine",
+        "slug": "test_machine_addon",
         "description": "Test machine add-on",
         "name": "Test Machine Add-on",
         "repository": "test",
@@ -562,7 +576,18 @@ async def test_api_store_addons_addon_availability_machine_not_supported(
         resp = await api_client.get(f"/store/addons/{addon_obj.slug}/availability")
         assert resp.status == 400
         result = await resp.json()
-        assert "not supported on this machine" in result["message"]
+        assert result["error_key"] == "addon_not_supported_machine_type_error"
+        assert (
+            result["message_template"]
+            == "Add-on {slug} not supported on this machine, supported machine types: {machine_types}"
+        )
+        assert result["extra_fields"] == {
+            "slug": "test_machine_addon",
+            "machine_types": ", ".join(supported_machines),
+        }
+        assert result["message"] == result["message_template"].format(
+            **result["extra_fields"]
+        )
 
 
 async def test_api_store_addons_addon_availability_homeassistant_version_too_old(
@@ -578,7 +603,7 @@ async def test_api_store_addons_addon_availability_homeassistant_version_too_old
         "advanced": False,
         "arch": ["amd64"],
         "homeassistant": "2023.1.1",  # Requires newer version than current
-        "slug": "test_version",
+        "slug": "test_version_addon",
         "description": "Test version add-on",
         "name": "Test Version Add-on",
         "repository": "test",
@@ -596,8 +621,17 @@ async def test_api_store_addons_addon_availability_homeassistant_version_too_old
         resp = await api_client.get(f"/store/addons/{addon_obj.slug}/availability")
         assert resp.status == 400
         result = await resp.json()
+        assert result["error_key"] == "addon_not_supported_home_assistant_version_error"
         assert (
-            "requires Home Assistant version 2023.1.1 or greater" in result["message"]
+            result["message_template"]
+            == "Add-on {slug} not supported on this system, requires Home Assistant version {version} or greater"
+        )
+        assert result["extra_fields"] == {
+            "slug": "test_version_addon",
+            "version": "2023.1.1",
+        }
+        assert result["message"] == result["message_template"].format(
+            **result["extra_fields"]
         )