From 0177cd95281337f541eb51d8e830a6ead48c98ef Mon Sep 17 00:00:00 2001
From: Mike Degatano <michael.degatano@gmail.com>
Date: Tue, 27 Aug 2024 11:59:52 -0400
Subject: [PATCH] Add `manual_only` option to addon boot config (#5272)

* Add manual_forced option to addon boot config

* Include client library in pull request template

* Add boot_config to api output so frontend can use it

* `manual_forced` to `manual_only`
---
 .github/PULL_REQUEST_TEMPLATE.md              |  7 ++++++-
 supervisor/addons/addon.py                    |  5 ++++-
 supervisor/addons/model.py                    | 10 ++++++++--
 supervisor/addons/validate.py                 |  5 ++++-
 supervisor/api/addons.py                      |  8 +++++++-
 supervisor/api/const.py                       |  1 +
 supervisor/const.py                           | 15 ++++++++++++++
 tests/addons/test_addon.py                    | 12 +++++++++++
 tests/api/test_addons.py                      | 20 +++++++++++++++++++
 .../fixtures/addons/local/example/config.yaml |  1 +
 10 files changed, 78 insertions(+), 6 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 0a3480a4c84..27f17d8ddaa 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -38,6 +38,7 @@
 - This PR is related to issue:
 - Link to documentation pull request:
 - Link to cli pull request:
+- Link to client library pull request:
 
 ## Checklist
 
@@ -55,9 +56,11 @@
 - [ ] The code has been formatted using Ruff (`ruff format supervisor tests`)
 - [ ] Tests have been added to verify that the new code works.
 
-If API endpoints of add-on configuration are added/changed:
+If API endpoints or add-on configuration are added/changed:
 
 - [ ] Documentation added/updated for [developers.home-assistant.io][docs-repository]
+- [ ] [CLI][cli-repository] updated (if necessary)
+- [ ] [Client library][client-library-repository] updated (if necessary)
 
 <!--
   Thank you for contributing <3
@@ -67,3 +70,5 @@ If API endpoints of add-on configuration are added/changed:
 
 [dev-checklist]: https://developers.home-assistant.io/docs/en/development_checklist.html
 [docs-repository]: https://github.com/home-assistant/developers.home-assistant
+[cli-repository]: https://github.com/home-assistant/cli
+[client-library-repository]: https://github.com/home-assistant-libs/python-supervisor-client/
diff --git a/supervisor/addons/addon.py b/supervisor/addons/addon.py
index 8ac72e56538..f1680bf81b3 100644
--- a/supervisor/addons/addon.py
+++ b/supervisor/addons/addon.py
@@ -57,6 +57,7 @@
     ATTR_WATCHDOG,
     DNS_SUFFIX,
     AddonBoot,
+    AddonBootConfig,
     AddonStartup,
     AddonState,
     BusEvent,
@@ -311,7 +312,9 @@ def options(self, value: dict[str, Any] | None) -> None:
 
     @property
     def boot(self) -> AddonBoot:
-        """Return boot config with prio local settings."""
+        """Return boot config with prio local settings unless config is forced."""
+        if self.boot_config == AddonBootConfig.MANUAL_ONLY:
+            return super().boot
         return self.persist.get(ATTR_BOOT, super().boot)
 
     @boot.setter
diff --git a/supervisor/addons/model.py b/supervisor/addons/model.py
index 2d400c00c29..8a53224ca19 100644
--- a/supervisor/addons/model.py
+++ b/supervisor/addons/model.py
@@ -83,6 +83,7 @@
     SECURITY_DISABLE,
     SECURITY_PROFILE,
     AddonBoot,
+    AddonBootConfig,
     AddonStage,
     AddonStartup,
 )
@@ -150,10 +151,15 @@ def options(self) -> dict[str, Any]:
         return self.data[ATTR_OPTIONS]
 
     @property
-    def boot(self) -> AddonBoot:
-        """Return boot config with prio local settings."""
+    def boot_config(self) -> AddonBootConfig:
+        """Return boot config."""
         return self.data[ATTR_BOOT]
 
+    @property
+    def boot(self) -> AddonBoot:
+        """Return boot config with prio local settings unless config is forced."""
+        return AddonBoot(self.data[ATTR_BOOT])
+
     @property
     def auto_update(self) -> bool | None:
         """Return if auto update is enable."""
diff --git a/supervisor/addons/validate.py b/supervisor/addons/validate.py
index c096860e8bf..a177ac9d215 100644
--- a/supervisor/addons/validate.py
+++ b/supervisor/addons/validate.py
@@ -98,6 +98,7 @@
     ROLE_ALL,
     ROLE_DEFAULT,
     AddonBoot,
+    AddonBootConfig,
     AddonStage,
     AddonStartup,
     AddonState,
@@ -321,7 +322,9 @@ def _migrate(config: dict[str, Any]):
         vol.Optional(ATTR_STARTUP, default=AddonStartup.APPLICATION): vol.Coerce(
             AddonStartup
         ),
-        vol.Optional(ATTR_BOOT, default=AddonBoot.AUTO): vol.Coerce(AddonBoot),
+        vol.Optional(ATTR_BOOT, default=AddonBootConfig.AUTO): vol.Coerce(
+            AddonBootConfig
+        ),
         vol.Optional(ATTR_INIT, default=True): vol.Boolean(),
         vol.Optional(ATTR_ADVANCED, default=False): vol.Boolean(),
         vol.Optional(ATTR_STAGE, default=AddonStage.STABLE): vol.Coerce(AddonStage),
diff --git a/supervisor/api/addons.py b/supervisor/api/addons.py
index 83b6ad42c2e..6c9cad1cce6 100644
--- a/supervisor/api/addons.py
+++ b/supervisor/api/addons.py
@@ -98,6 +98,7 @@
     ATTR_WEBUI,
     REQUEST_FROM,
     AddonBoot,
+    AddonBootConfig,
 )
 from ..coresys import CoreSysAttributes
 from ..docker.stats import DockerStats
@@ -109,7 +110,7 @@
     PwnedSecret,
 )
 from ..validate import docker_ports
-from .const import ATTR_REMOVE_CONFIG, ATTR_SIGNED
+from .const import ATTR_BOOT_CONFIG, ATTR_REMOVE_CONFIG, ATTR_SIGNED
 from .utils import api_process, api_validate, json_loads
 
 _LOGGER: logging.Logger = logging.getLogger(__name__)
@@ -217,6 +218,7 @@ async def info(self, request: web.Request) -> dict[str, Any]:
             ATTR_VERSION_LATEST: addon.latest_version,
             ATTR_PROTECTED: addon.protected,
             ATTR_RATING: rating_security(addon),
+            ATTR_BOOT_CONFIG: addon.boot_config,
             ATTR_BOOT: addon.boot,
             ATTR_OPTIONS: addon.options,
             ATTR_SCHEMA: addon.schema_ui,
@@ -300,6 +302,10 @@ async def options(self, request: web.Request) -> None:
         if ATTR_OPTIONS in body:
             addon.options = body[ATTR_OPTIONS]
         if ATTR_BOOT in body:
+            if addon.boot_config == AddonBootConfig.MANUAL_ONLY:
+                raise APIError(
+                    f"Addon {addon.slug} boot option is set to {addon.boot_config} so it cannot be changed"
+                )
             addon.boot = body[ATTR_BOOT]
         if ATTR_AUTO_UPDATE in body:
             addon.auto_update = body[ATTR_AUTO_UPDATE]
diff --git a/supervisor/api/const.py b/supervisor/api/const.py
index be0356d31b6..e34998a3963 100644
--- a/supervisor/api/const.py
+++ b/supervisor/api/const.py
@@ -17,6 +17,7 @@
 ATTR_ATTRIBUTES = "attributes"
 ATTR_AVAILABLE_UPDATES = "available_updates"
 ATTR_BACKGROUND = "background"
+ATTR_BOOT_CONFIG = "boot_config"
 ATTR_BOOT_SLOT = "boot_slot"
 ATTR_BOOT_SLOTS = "boot_slots"
 ATTR_BOOT_TIMESTAMP = "boot_timestamp"
diff --git a/supervisor/const.py b/supervisor/const.py
index b1181af2af8..6f4ffb219ad 100644
--- a/supervisor/const.py
+++ b/supervisor/const.py
@@ -382,12 +382,27 @@
 ROLE_ALL = [ROLE_DEFAULT, ROLE_HOMEASSISTANT, ROLE_BACKUP, ROLE_MANAGER, ROLE_ADMIN]
 
 
+class AddonBootConfig(StrEnum):
+    """Boot mode config for the add-on."""
+
+    AUTO = "auto"
+    MANUAL = "manual"
+    MANUAL_ONLY = "manual_only"
+
+
 class AddonBoot(StrEnum):
     """Boot mode for the add-on."""
 
     AUTO = "auto"
     MANUAL = "manual"
 
+    @classmethod
+    def _missing_(cls, value: str) -> Self | None:
+        """Convert 'forced' config values to their counterpart."""
+        if value == AddonBootConfig.MANUAL_ONLY:
+            return AddonBoot.MANUAL
+        return None
+
 
 class AddonStartup(StrEnum):
     """Startup types of Add-on."""
diff --git a/tests/addons/test_addon.py b/tests/addons/test_addon.py
index f67d6267d09..7ee520a61d4 100644
--- a/tests/addons/test_addon.py
+++ b/tests/addons/test_addon.py
@@ -691,6 +691,7 @@ async def test_local_example_install(
     mock_aarch64_arch_supported: None,
 ):
     """Test install of an addon."""
+    coresys.hardware.disk.get_disk_free_space = lambda x: 5000
     assert not (
         data_dir := tmp_supervisor_data / "addons" / "data" / "local_example"
     ).exists()
@@ -883,3 +884,14 @@ async def test_addon_load_succeeds_with_docker_errors(
     caplog.clear()
     await install_addon_ssh.load()
     assert "Unknown error with test/amd64-addon-ssh:9.2.1" in caplog.text
+
+
+async def test_addon_manual_only_boot(coresys: CoreSys, install_addon_example: Addon):
+    """Test an addon with manual only boot mode."""
+    assert install_addon_example.boot_config == "manual_only"
+    assert install_addon_example.boot == "manual"
+
+    # Users cannot change boot mode of an addon with manual forced so changing boot isn't realistic
+    # However boot mode can change on update and user may have set auto before, ensure it is ignored
+    install_addon_example.boot = "auto"
+    assert install_addon_example.boot == "manual"
diff --git a/tests/api/test_addons.py b/tests/api/test_addons.py
index ad8e5d00d2e..1e7ed79c4dd 100644
--- a/tests/api/test_addons.py
+++ b/tests/api/test_addons.py
@@ -346,3 +346,23 @@ async def test_api_addon_system_managed(
     body = await resp.json()
     assert body["data"]["system_managed"] is False
     assert body["data"]["system_managed_config_entry"] is None
+
+
+async def test_addon_options_boot_mode_manual_only_invalid(
+    api_client: TestClient, install_addon_example: Addon
+):
+    """Test changing boot mode is invalid if set to manual only."""
+    install_addon_example.data["ingress"] = False
+    resp = await api_client.get("/addons/local_example/info")
+    assert resp.status == 200
+    body = await resp.json()
+    assert body["data"]["boot"] == "manual"
+    assert body["data"]["boot_config"] == "manual_only"
+
+    resp = await api_client.post("/addons/local_example/options", json={"boot": "auto"})
+    assert resp.status == 400
+    body = await resp.json()
+    assert (
+        body["message"]
+        == "Addon local_example boot option is set to manual_only so it cannot be changed"
+    )
diff --git a/tests/fixtures/addons/local/example/config.yaml b/tests/fixtures/addons/local/example/config.yaml
index 8a269b562ef..ab94374ae7b 100644
--- a/tests/fixtures/addons/local/example/config.yaml
+++ b/tests/fixtures/addons/local/example/config.yaml
@@ -23,3 +23,4 @@ ingress_port: 0
 breaking_versions:
   - test
   - 1.0
+boot: manual_only