Add progress reporting to addon, HA and Supervisor updates (#6195)

* Add progress reporting to addon, HA and Supervisor updates

* Fix assert in test

* Add progress to addon, core, supervisor updates/installs

* Fix double install bug in addons install

* Remove initial_install and re-arrange order of load

Author: mdegat01

supervisor/addons/addon.py

@@ -226,6 +226,7 @@ async def load(self) -> None:
         )
 
         await self._check_ingress_port()
+
         default_image = self._image(self.data)
         try:
             await self.instance.attach(version=self.version)
@@ -774,7 +775,6 @@ async def install(self) -> None:
             raise AddonsError("Missing from store, cannot install!")
 
         await self.sys_addons.data.install(self.addon_store)
-        await self.load()
 
         def setup_data():
             if not self.path_data.is_dir():
@@ -797,6 +797,9 @@ def setup_data():
             await self.sys_addons.data.uninstall(self)
             raise AddonsError() from err
 
+        # Finish initialization and set up listeners
+        await self.load()
+
         # Add to addon manager
         self.sys_addons.local[self.slug] = self
 

supervisor/addons/manager.py

@@ -9,8 +9,6 @@
 
 from attr import evolve
 
-from supervisor.jobs.const import JobConcurrency
-
 from ..const import AddonBoot, AddonStartup, AddonState
 from ..coresys import CoreSys, CoreSysAttributes
 from ..exceptions import (
@@ -21,6 +19,8 @@
     DockerError,
     HassioError,
 )
+from ..jobs import ChildJobSyncFilter
+from ..jobs.const import JobConcurrency
 from ..jobs.decorator import Job, JobCondition
 from ..resolution.const import ContextType, IssueType, SuggestionType
 from ..store.addon import AddonStore
@@ -182,6 +182,9 @@ async def shutdown(self, stage: AddonStartup) -> None:
         conditions=ADDON_UPDATE_CONDITIONS,
         on_condition=AddonsJobError,
         concurrency=JobConcurrency.QUEUE,
+        child_job_syncs=[
+            ChildJobSyncFilter("docker_interface_install", progress_allocation=1.0)
+        ],
     )
     async def install(
         self, slug: str, *, validation_complete: asyncio.Event | None = None
@@ -229,6 +232,13 @@ async def uninstall(self, slug: str, *, remove_config: bool = False) -> None:
         name="addon_manager_update",
         conditions=ADDON_UPDATE_CONDITIONS,
         on_condition=AddonsJobError,
+        # We assume for now the docker image pull is 100% of this task for progress
+        # allocation. But from a user perspective that isn't true. Other steps
+        # that take time which is not accounted for in progress include:
+        # partial backup, image cleanup, apparmor update, and addon restart
+        child_job_syncs=[
+            ChildJobSyncFilter("docker_interface_install", progress_allocation=1.0)
+        ],
     )
     async def update(
         self,
@@ -271,7 +281,10 @@ async def update(
                 addons=[addon.slug],
             )
 
-        return await addon.update()
+        task = await addon.update()
+
+        _LOGGER.info("Add-on '%s' successfully updated", slug)
+        return task
 
     @Job(
         name="addon_manager_rebuild",

supervisor/docker/interface.py

@@ -220,10 +220,12 @@ async def _docker_login(self, image: str) -> None:
 
         await self.sys_run_in_executor(self.sys_docker.docker.login, **credentials)
 
-    def _process_pull_image_log(self, job_id: str, reference: PullLogEntry) -> None:
+    def _process_pull_image_log(
+        self, install_job_id: str, reference: PullLogEntry
+    ) -> None:
         """Process events fired from a docker while pulling an image, filtered to a given job id."""
         if (
-            reference.job_id != job_id
+            reference.job_id != install_job_id
             or not reference.id
             or not reference.status
             or not (stage := PullImageLayerStage.from_status(reference.status))
@@ -237,21 +239,22 @@ def _process_pull_image_log(self, job_id: str, reference: PullLogEntry) -> None:
                 name="Pulling container image layer",
                 initial_stage=stage.status,
                 reference=reference.id,
-                parent_id=job_id,
+                parent_id=install_job_id,
+                internal=True,
             )
             job.done = False
             return
 
         # Find our sub job to update details of
         for j in self.sys_jobs.jobs:
-            if j.parent_id == job_id and j.reference == reference.id:
+            if j.parent_id == install_job_id and j.reference == reference.id:
                 job = j
                 break
 
         # This likely only occurs if the logs came in out of sync and we got progress before the Pulling FS Layer one
         if not job:
             raise DockerLogOutOfOrder(
-                f"Received pull image log with status {reference.status} for image id {reference.id} and parent job {job_id} but could not find a matching job, skipping",
+                f"Received pull image log with status {reference.status} for image id {reference.id} and parent job {install_job_id} but could not find a matching job, skipping",
                 _LOGGER.debug,
             )
 
@@ -325,10 +328,56 @@ def _process_pull_image_log(self, job_id: str, reference: PullLogEntry) -> None:
                 else job.extra,
             )
 
+        # Once we have received a progress update for every child job, start to set status of the main one
+        install_job = self.sys_jobs.get_job(install_job_id)
+        layer_jobs = [
+            job
+            for job in self.sys_jobs.jobs
+            if job.parent_id == install_job.uuid
+            and job.name == "Pulling container image layer"
+        ]
+
+        # First set the total bytes to be downloaded/extracted on the main job
+        if not install_job.extra:
+            total = 0
+            for job in layer_jobs:
+                if not job.extra:
+                    return
+                total += job.extra["total"]
+            install_job.extra = {"total": total}
+        else:
+            total = install_job.extra["total"]
+
+        # Then determine total progress based on progress of each sub-job, factoring in size of each compared to total
+        progress = 0.0
+        stage = PullImageLayerStage.PULL_COMPLETE
+        for job in layer_jobs:
+            if not job.extra:
+                return
+            progress += job.progress * (job.extra["total"] / total)
+            job_stage = PullImageLayerStage.from_status(cast(str, job.stage))
+
+            if job_stage < PullImageLayerStage.EXTRACTING:
+                stage = PullImageLayerStage.DOWNLOADING
+            elif (
+                stage == PullImageLayerStage.PULL_COMPLETE
+                and job_stage < PullImageLayerStage.PULL_COMPLETE
+            ):
+                stage = PullImageLayerStage.EXTRACTING
+
+        # Ensure progress is 100 at this point to prevent float drift
+        if stage == PullImageLayerStage.PULL_COMPLETE:
+            progress = 100
+
+        # To reduce noise, limit updates to when result has changed by an entire percent or when stage changed
+        if stage != install_job.stage or progress >= install_job.progress + 1:
+            install_job.update(stage=stage.status, progress=progress)
+
     @Job(
         name="docker_interface_install",
         on_condition=DockerJobError,
         concurrency=JobConcurrency.GROUP_REJECT,
+        internal=True,
     )
     async def install(
         self,
@@ -351,11 +400,11 @@ async def install(
                 # Try login if we have defined credentials
                 await self._docker_login(image)
 
-            job_id = self.sys_jobs.current.uuid
+            curr_job_id = self.sys_jobs.current.uuid
 
             async def process_pull_image_log(reference: PullLogEntry) -> None:
                 try:
-                    self._process_pull_image_log(job_id, reference)
+                    self._process_pull_image_log(curr_job_id, reference)
                 except DockerLogOutOfOrder as err:
                     # Send all these to sentry. Missing a few progress updates
                     # shouldn't matter to users but matters to us
@@ -629,7 +678,10 @@ async def check_image(
         concurrency=JobConcurrency.GROUP_REJECT,
     )
     async def update(
-        self, version: AwesomeVersion, image: str | None = None, latest: bool = False
+        self,
+        version: AwesomeVersion,
+        image: str | None = None,
+        latest: bool = False,
     ) -> None:
         """Update a Docker image."""
         image = image or self.image

supervisor/homeassistant/core.py

@@ -28,6 +28,7 @@
     HomeAssistantUpdateError,
     JobException,
 )
+from ..jobs import ChildJobSyncFilter
 from ..jobs.const import JOB_GROUP_HOME_ASSISTANT_CORE, JobConcurrency, JobThrottle
 from ..jobs.decorator import Job, JobCondition
 from ..jobs.job_group import JobGroup
@@ -224,6 +225,13 @@ async def install(self) -> None:
         ],
         on_condition=HomeAssistantJobError,
         concurrency=JobConcurrency.GROUP_REJECT,
+        # We assume for now the docker image pull is 100% of this task. But from
+        # a user perspective that isn't true. Other steps that take time which
+        # is not accounted for in progress include: partial backup, image
+        # cleanup, and Home Assistant restart
+        child_job_syncs=[
+            ChildJobSyncFilter("docker_interface_install", progress_allocation=1.0)
+        ],
     )
     async def update(
         self,

supervisor/jobs/__init__.py

@@ -282,8 +282,10 @@ def _on_job_change(
                 # reporting shouldn't raise and break the active job
                 continue
 
-            progress = sync.starting_progress + (
-                sync.progress_allocation * job_data["progress"]
+            progress = min(
+                100,
+                sync.starting_progress
+                + (sync.progress_allocation * job_data["progress"]),
             )
             # Using max would always trigger on change even if progress was unchanged
             # pylint: disable-next=R1731

supervisor/supervisor.py

@@ -13,6 +13,8 @@
 from aiohttp.client_exceptions import ClientError
 from awesomeversion import AwesomeVersion, AwesomeVersionException
 
+from supervisor.jobs import ChildJobSyncFilter
+
 from .const import (
     ATTR_SUPERVISOR_INTERNET,
     SUPERVISOR_VERSION,
@@ -195,6 +197,15 @@ def write_profile() -> Path:
             if temp_dir:
                 await self.sys_run_in_executor(temp_dir.cleanup)
 
+    @Job(
+        name="supervisor_update",
+        # We assume for now the docker image pull is 100% of this task. But from
+        # a user perspective that isn't true.  Other steps that take time which
+        # is not accounted for in progress include: app armor update and restart
+        child_job_syncs=[
+            ChildJobSyncFilter("docker_interface_install", progress_allocation=1.0)
+        ],
+    )
     async def update(self, version: AwesomeVersion | None = None) -> None:
         """Update Supervisor version."""
         version = version or self.latest_version or self.version
@@ -221,6 +232,7 @@ async def update(self, version: AwesomeVersion | None = None) -> None:
 
         # Update container
         _LOGGER.info("Update Supervisor to version %s", version)
+
         try:
             await self.instance.install(version, image=image)
             await self.instance.update_start_tag(image, version)

tests/api/test_homeassistant.py

@@ -2,16 +2,19 @@
 
 import asyncio
 from pathlib import Path
-from unittest.mock import MagicMock, PropertyMock, patch
+from unittest.mock import AsyncMock, MagicMock, PropertyMock, patch
 
 from aiohttp.test_utils import TestClient
 from awesomeversion import AwesomeVersion
 import pytest
 
 from supervisor.backups.manager import BackupManager
+from supervisor.const import CoreState
 from supervisor.coresys import CoreSys
+from supervisor.docker.homeassistant import DockerHomeAssistant
 from supervisor.docker.interface import DockerInterface
-from supervisor.homeassistant.api import APIState
+from supervisor.homeassistant.api import APIState, HomeAssistantAPI
+from supervisor.homeassistant.const import WSEvent
 from supervisor.homeassistant.core import HomeAssistantCore
 from supervisor.homeassistant.module import HomeAssistant
 
@@ -271,3 +274,96 @@ async def test_background_home_assistant_update_fails_fast(
     assert resp.status == 400
     body = await resp.json()
     assert body["message"] == "Version 2025.8.3 is already installed"
+
+
+@pytest.mark.usefixtures("tmp_supervisor_data")
+async def test_api_progress_updates_home_assistant_update(
+    api_client: TestClient, coresys: CoreSys, ha_ws_client: AsyncMock
+):
+    """Test progress updates sent to Home Assistant for updates."""
+    coresys.hardware.disk.get_disk_free_space = lambda x: 5000
+    coresys.core.set_state(CoreState.RUNNING)
+    coresys.docker.docker.api.pull.return_value = load_json_fixture(
+        "docker_pull_image_log.json"
+    )
+    coresys.homeassistant.version = AwesomeVersion("2025.8.0")
+
+    with (
+        patch.object(
+            DockerHomeAssistant,
+            "version",
+            new=PropertyMock(return_value=AwesomeVersion("2025.8.0")),
+        ),
+        patch.object(
+            HomeAssistantAPI, "get_config", return_value={"components": ["frontend"]}
+        ),
+    ):
+        resp = await api_client.post("/core/update", json={"version": "2025.8.3"})
+
+    assert resp.status == 200
+
+    events = [
+        {
+            "stage": evt.args[0]["data"]["data"]["stage"],
+            "progress": evt.args[0]["data"]["data"]["progress"],
+            "done": evt.args[0]["data"]["data"]["done"],
+        }
+        for evt in ha_ws_client.async_send_command.call_args_list
+        if "data" in evt.args[0]
+        and evt.args[0]["data"]["event"] == WSEvent.JOB
+        and evt.args[0]["data"]["data"]["name"] == "home_assistant_core_update"
+    ]
+    assert events[:5] == [
+        {
+            "stage": None,
+            "progress": 0,
+            "done": None,
+        },
+        {
+            "stage": None,
+            "progress": 0,
+            "done": False,
+        },
+        {
+            "stage": None,
+            "progress": 0.1,
+            "done": False,
+        },
+        {
+            "stage": None,
+            "progress": 1.2,
+            "done": False,
+        },
+        {
+            "stage": None,
+            "progress": 2.8,
+            "done": False,
+        },
+    ]
+    assert events[-5:] == [
+        {
+            "stage": None,
+            "progress": 97.2,
+            "done": False,
+        },
+        {
+            "stage": None,
+            "progress": 98.4,
+            "done": False,
+        },
+        {
+            "stage": None,
+            "progress": 99.4,
+            "done": False,
+        },
+        {
+            "stage": None,
+            "progress": 100,
+            "done": False,
+        },
+        {
+            "stage": None,
+            "progress": 100,
+            "done": True,
+        },
+    ]