* Derive App state from container state
The App.state setter mixed two responsibilities: it both mutated a
private `_state` field and dispatched side effects (WebSocket events,
issue dismissal, startup_event signaling). On top of that, an installed
but never-started app stayed in AppState.UNKNOWN forever, because the
attach() image-only fallback never fires a container state-change event
and the AppState therefore kept its constructor default. Conceptually,
ContainerState.UNKNOWN ("container does not exist") and AppState.UNKNOWN
("nothing observed yet") happened to share a name but meant different
things, which made the distinction easy to lose.
Make App.state a pure derived property. The source of truth is the last
observed ContainerState (cached on the App), plus a sticky operation-
error flag for start/stop failures that the docker event stream cannot
reflect. When no container has been observed yet, the derivation falls
back to install signals: an attached instance (image present) is
STOPPED, otherwise UNKNOWN. As a side effect, an installed-but-never-
started app now correctly reports STOPPED instead of UNKNOWN.
container_state_changed updates the cached container state and routes
all side effects through a single _emit_state_change helper that diffs
old vs new derived state. The two start/stop failure paths route
through _set_operation_error. Uninstall resets the cached signals so
the derivation naturally returns UNKNOWN.
Tests use a new tests/common.force_app_state helper that pokes the
underlying signals directly; the production class no longer carries
test-only setters.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Fix App state drive to AppState.UNKNOWN
* Unify state mutation through _update_state
Previously, state-driving signal changes were spread across two helpers
(_set_operation_error, _emit_state_change(old_state)) and required each
caller to capture self.state before mutating a private field — leaking
implementation details to call sites and raising the "why am I emitting
the old state?" question pointed out in code review.
Replace both helpers with a single _update_state(*, container_state=,
operation_error=) entry point. Callers describe what changed via
keyword arguments (None leaves a signal untouched); the helper captures
the previous state, applies the updates, recomputes the derived state
and emits side effects if anything changed.
Diff against a tracked _last_state instead of a freshly derived
"current" state, so that an out-of-band mutation between updates does
not silently shift the comparison baseline. The concrete case is
App.uninstall: instance.remove() clears the docker meta mid-flow, which
would otherwise reshape the derivation (RUNNING with no healthcheck
becomes STARTED instead of STARTUP) and suppress the STARTUP transition
that resolves the start-wait task. As a side effect, the initial
UNKNOWN -> STOPPED transition on attach is also now reliably emitted.
Switch the uninstall path to ContainerState.UNKNOWN ("we know there is
no container") rather than the constructor sentinel None.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Cache app state instead of deriving on every read
Building on the previous commit, make App.state a plain read of a
cached _state field rather than re-deriving on every property access.
The derivation moves to _derive_state(), and _update_state() is the
sole place that recomputes and assigns _state, so the value consumers
read always matches what was last emitted to listeners.
This removes the _last_state bookkeeping introduced previously: with a
single cached value there is no longer a separate "derived now" vs
"last emitted" distinction to reconcile, and out-of-band mutations
(e.g. instance.remove() clearing _meta during uninstall) can no longer
silently shift what state returns between updates.
Call _update_state() at the end of load() so the cached state settles
once attach() has run. Image-only attaches do not fire a docker event,
so without this an installed app would stay in the constructor-default
UNKNOWN until first start; this also makes the initial transition on
attach observable to listeners.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Pass operation error to _derive_state instead of storing it
The two state-driving signals were not symmetric. _container_state is
genuinely persisted state ("the last thing docker told us") that
re-derivation legitimately reads across calls. _operation_error, on the
other hand, is a momentary "force ERROR for this transition" signal; the
persistence of an error condition already lives in the cached _state.
Storing it as an instance attribute implied a sticky cross-call behavior
that no call path actually exercised: every caller either set it
explicitly right before deriving (start/stop failures, container events)
or ran argless only at load time, where no failure has occurred.
Drop the _operation_error field and pass operation_error as a parameter
to _derive_state(), defaulting to False in _update_state(). A container
observation now supersedes a prior error implicitly via the default,
which lets the container-event and uninstall call sites drop their
explicit operation_error=False.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Settle load state synchronously from current_state
The argless _update_state() settle at the end of load() raced attach()'s
container-state event. attach() fires DOCKER_CONTAINER_STATE_CHANGE via
the bus, which schedules the container_state_changed listener as a task
rather than running it inline. In the deprecated-arch early-return path
there is no await between attach() and the settle, so the listener had
not run yet: _container_state was still None and the settle derived
STOPPED (instance attached) — emitting a transient UNKNOWN->STOPPED even
for a running container before the listener corrected it. The main path
only avoided this incidentally, by having awaits (check_image,
save_persist) in between for the listener to run.
Derive the load-time state synchronously from instance.current_state()
instead of relying on the asynchronously delivered event. current_state()
returns the real container state, or UNKNOWN when only an image is
present (which derives to STOPPED), so both paths settle correctly
without racing the event.
Add a regression test that loading a running container settles to
STARTED, and mock current_state() in the state-listener test which
relies on a clean UNKNOWN baseline.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
HAOS will rename some hassos-prefixed binaries to haos-*, changing the
identifiers, so add the new variants to the default list.
The hassos-* entries are kept for backward compatibility with older OS
images and pre-upgrade journal history.
Refs home-assistant/operating-system#4725
The s6 supervision tree only waited S6_SERVICES_GRACETIME (10s) for the
Supervisor service in /etc/services.d to stop before tearing down the rest
of the tree, which cut graceful shutdown short well before the container's
stop timeout. Now that the OS grants the Supervisor container more time to
shut down, raise S6_SERVICES_GRACETIME to 415s so a long-running graceful
shutdown can complete.
Also set S6_KILL_GRACETIME explicitly to its default of 3000ms. It only acts
as the final SIGTERM-to-SIGKILL grace at the very end of shutdown, so the
default is fine, but stating it keeps both shutdown timers documented in one
place.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Investigating slow-callback warnings during `ha store list`, py-spy traces
showed ~70% of the on-CPU time spent under loop debug mode in
traceback.extract_stack() and linecache.checkcache(), triggered by N task
creations inside _all_store_apps_info()'s asyncio.gather.
In the non-extended path, _generate_app_information() never awaits, so each
gather'd coroutine runs straight through in its Task step. gather provides
zero concurrency here and only adds N task creations + scheduling cycles.
Under loop.set_debug(True) (supervisor dev mode) each create_task captures
its creation stack via extract_stack(), which made list responses ~5x
slower. Production overhead is negligible.
Replace with a plain async list comprehension. Behavior is unchanged: the
non-extended path was already serial; the extended path's
await app.long_description() still serializes the same way it would have
once gather observed the suspension.
* Fix off-by-one in unsupported os_version evaluation
Adjust check for unsupported OS version to match the boundary which is
documented in [1], which says:
> Supervisor considers Home Assistant Operating System older than the
> last 4 major releases as unsupported.
Also adjust the wording in the message to match the statement from the
docs.
This will make another major relase unsupported now, but it was the
original intention anyway.
[1] https://www.home-assistant.io/more-info/unsupported/os_version/
* Reword comments for test_os_version_evaluation test cases
On newer HAOS (home-assistant/operating-system#4736),
hassos-supervisor.service gets a long stop timeout (420 s docker stop +
450 s TimeoutStopSec) so Supervisor can handle the SIGTERM during host
teardown and gracefully stop Core, apps and plugins via its existing
shutdown handler. On older releases the timeout is too short, so
reboot()/shutdown() keep stopping Core in-process before requesting the
reboot/power off.
For host shutdowns not initiated by Supervisor (ACPI, power button,
systemctl reboot), the SIGTERM handler now checks the systemd manager
state. When it is "stopping", Supervisor runs Core.shutdown() to stop
managed services gracefully; on a plain Supervisor restart the state is
"running", so only Supervisor stops as before. The manager state is
exposed by every systemd version, so this works regardless of the OS
release.
Closeshome-assistant/operating-system#4642
The existing OS manager update tests only exercise precondition failure
paths (out-of-date supervisor, unhealthy state), which bail out before
the download / RAUC install / cleanup logic ever runs. That left the
finally-clause unlink in OSManager.update() unscanned by blockbuster,
so the blocking Path.unlink() regression fixed in #6863 slipped through
CI and only surfaced on a real device.
Add a happy-path test that stubs _download_raucb to create the bundle
file, drives the RAUC dbus mock to emit a successful Completed signal,
mocks the post-install reboot, and asserts the downloaded bundle is
removed. Reverting the executor wrapping on int_ota.unlink reproduces
the original failure with blockbuster reporting "Blocking call to
os.unlink", confirming the test catches the regression.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Bump aiodocker from 0.26.0 to 0.27.0
Bumps [aiodocker](https://github.com/aio-libs/aiodocker) from 0.26.0 to 0.27.0.
- [Release notes](https://github.com/aio-libs/aiodocker/releases)
- [Changelog](https://github.com/aio-libs/aiodocker/blob/main/CHANGES.rst)
- [Commits](https://github.com/aio-libs/aiodocker/compare/v0.26.0...v0.27.0)
---
updated-dependencies:
- dependency-name: aiodocker
dependency-version: 0.27.0
dependency-type: direct:production
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] <support@github.com>
* docker: pass mapping to images.list(filters=...)
aiodocker 0.27.0 deprecates pre-encoded JSON strings for the
``filters`` argument of ``DockerImages.list()`` and will remove
support in 1.0. Switch both call sites to the supported
``Mapping[str, Any]`` form, which the library now encodes
internally via ``clean_filters``.
Drop the now-unused ``json`` import from ``docker/manager.py``.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Stefan Agner <stefan@agner.ch>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Enable blocking I/O detection in integration tests
Write config.json with detect_blocking_io=true before starting
Supervisor in the run_supervisor CI job so blocking I/O in the
event loop is caught during integration tests, not just unit tests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix identified blocking I/O issue and temporarily reduce timeout
* Revert builder workflow changes and use dev system to set config like with others
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Migrate config file and directory paths from addons to apps
- Rename addons.json -> apps.json (FILE_HASSIO_APPS constant)
- Rename addons/{core,data,local,git} -> apps/{core,data,local,git}
- Rename addon_configs -> app_configs
Backwards compatibility: on startup, Supervisor checks for legacy
paths and renames them if the new paths don't already exist.
- addons.json migration runs in AppManager.load_config (executor)
- Directory migrations run in bootstrap before initialize_system (executor)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Rename SCHEMA_ADDON(S)_* constants to SCHEMA_APP(S)_* in apps/validate.py
Update all references in supervisor and tests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix remaining test references to legacy addons/* paths
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Opportunistic remove of addons dir since it should be empty post migration
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* watchdog: include container exit code in restart log message
Reported in #6868: a user saw a tight loop of "Watchdog found app
phpMyAdmin is failed, restarting..." and assumed the watchdog itself
was the problem, asking whether its window could be widened. The
message gives no hint that the container is exiting on its own, nor
what exit code it returned.
#6848 already plumbed the container exit code through
DockerContainerStateEvent and added a separate log line in
container_state_changed when an app exits non-zero. Build on that by
forwarding event.exit_code into _restart_after_problem for apps, Home
Assistant Core, and plugins, and use it in the watchdog warning when
the state is FAILED. The fallback message is kept for STOPPED and
UNHEALTHY where an exit code is not meaningful.
After this change the example above reads "Watchdog found app
phpMyAdmin exited with code 1, restarting...", making it immediately
clear that the container itself is dying and giving the user a code
to grep for in the add-on logs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Drop unnecessary None check
* tests: set exit_code on FAILED watchdog events
The previous commit dropped the `exit_code is not None` guard from the
watchdog `_restart_after_problem` log statements, which assumed the
production invariant that `ContainerState.FAILED` always carries a
non-None exit code (enforced by `docker/monitor.py` and
`docker/interface.py`). Several tests, however, fired FAILED
`DockerContainerStateEvent`s with no `exit_code`, causing the new
unconditional `%d` formatter to raise `TypeError` at log time.
Align the test fixtures with the production invariant by passing
`exit_code=1` on FAILED events in the apps, Home Assistant Core, plugin
base, and DNS plugin watchdog tests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* apps: model client-state Apps* errors as APIError
Follow-up on #6739: with HassioError now logged and captured by Sentry
in api_process, a handful of Apps* exceptions raised from
AppManager.install/update/rebuild and AppModel._validate_availability
surfaced as "unexpected" 400s with a noisy log entry and a Sentry
event, even though they are all user/client-state errors (clicked
install on an already-installed add-on, "no update available", local
and store versions diverged, system architecture/machine/HA version
incompatible, etc.). The dominant offender is SUPERVISOR-1JVV
("No update available for app core_mosquitto", ~19k events / ~12k
users), but several siblings show the same shape.
Map these through properly so the API returns clean, structured 400s:
- Add modeled APIError subclasses in exceptions.py for the previously
raw raises in apps/manager.py: AppAlreadyInstalledError,
AppNotFoundError, AppNotInstalledError, AppNotInStoreError,
AppNoUpdateAvailableError, AppRebuildVersionChangedError,
AppRebuildImageBasedError. Each gets a stable error_key, a
message_template, and an "addon" extra_field.
- Add APIError to AppNotSupportedArchitectureError,
AppNotSupportedMachineTypeError and
AppNotSupportedHomeAssistantVersionError so they behave the same as
the other Apps* APIErrors instead of being treated as unexpected.
- Pass the app's display name (app.name from the add-on config)
instead of the slug to extra_fields wherever an App or AppModel is
available at the raise site, so users see "Mosquitto broker" rather
than "core_mosquitto" in error messages. Slug is only used as a
fallback when no app object exists (install of an unknown slug,
update/rebuild of a slug that is not installed).
- Update raise sites in apps/manager.py and apps/model.py to use the
new typed exceptions and the addon= keyword.
These are all runtime states users hit during normal interaction with
the apps UI, not Supervisor bugs worth paging on.
* apps: include slug alongside name in Apps* APIError extra_fields
Address review feedback from #6856: clients still need the slug to look
up additional add-on information (the name is for display only), and we
should be consistent about it across the Apps* errors touched by this
PR.
Every Apps* APIError raised with an App/AppModel available now carries
both `addon` (display name, used by the message_template) and `slug` in
extra_fields. Raise sites in apps/manager.py and apps/model.py pass
both. The two errors raised before an app object exists keep slug-only
extra_fields and use {slug} in their message:
- AppNotFoundError (install of an unknown slug)
- AppNotInstalledError (update/rebuild of a slug not in self.local)
Pre-existing Apps* APIErrors outside the scope of this PR
(AppUnknownError, AppConfigurationInvalidError, AppBootConfigCannot
ChangeError, AppNotRunningError, AppPortConflict, AppNotSupportedWrite
StdinError, AppBuild*) will be migrated in a follow-up.
* apps: introduce AppAPIError base for uniform addon/slug extra_fields
Address review follow-up on #6856: the addon/slug convention was
enforced only by hand-rolled __init__s, easy to drift on (forget slug,
use a different key, etc.). Promote it to a base class that owns the
shape of extra_fields for all App-related API errors.
- Add AppAPIError(AppsError, APIError). Its __init__ takes
`app: AppModel | App | AppStore | str` and uniformly populates
extra_fields with `addon` (display name) and `slug`. Pass a string
when no app object exists; only `slug` is set in that case. Extra
per-error fields flow through **extra_fields and merge with the
defaults.
- Convert the new exceptions added in this PR
(AppAlreadyInstalledError, AppNotFoundError, AppNotInstalledError,
AppNotInStoreError, AppNoUpdateAvailableError,
AppRebuildVersionChangedError) into thin subclasses that only declare
error_key and message_template -- the __init__ is inherited.
- Migrate the AppNotSupported* errors (architecture, machine type, HA
version) and AppRebuildImageBasedError to use AppAPIError too;
their bespoke per-error fields go through **extra_fields. They keep
inheriting AppNotSupportedError so `except AppNotSupportedError`
callers (e.g., AppModel._available) still work; MRO routes __init__
through AppAPIError.
- Update raise sites in apps/manager.py and apps/model.py to pass
`app=<obj-or-slug>` instead of repeating `addon=...` and `slug=...`.
Pre-existing App* APIErrors outside this PR's scope
(AppUnknownError, AppConfigurationInvalidError,
AppBootConfigCannotChangeError, AppNotRunningError, AppPortConflict,
AppNotSupportedWriteStdinError, AppBuild*) will be migrated to
AppAPIError in a follow-up; the base class is in place for them.
* apps: tighten AppAPIError model per review
Address mdegat01's two follow-ups on #6856 (review approved as-is,
this is the cleanup):
- AppNotFoundError and AppNotInstalledError are raised before any
App/AppModel object exists (unknown slug; not-installed slug). Pull
them out of AppAPIError and inherit (AppsError, APIError) directly
with a slug-only __init__ + {slug} message_template. Removes the
conceptually-wrong str branch from AppAPIError.__init__: it now
strictly requires an app-like object with .name and .slug.
- Restore per-class typed __init__ on AppNotSupportedArchitectureError,
AppNotSupportedMachineTypeError and
AppNotSupportedHomeAssistantVersionError so callers get an explicit
signature for the bespoke architectures/machine_types/version params
instead of dumping them through **extra_fields. Each override just
delegates to AppAPIError.__init__, which keeps ownership of the
addon/slug shape. The list-joining for architectures/machine_types
moves back into the override (raise sites pass the raw list again).
AppRebuildImageBasedError takes no bespoke fields and stays a plain
AppAPIError subclass.
Serving aiohttp FileResponse triggers BlockBuster's os.sendfile guard
because the actual syscall happens in asyncio/unix_events.py's
_sock_sendfile_native_impl rather than the base_events.sendfile entry
point that blockbuster whitelists. The socket is non-blocking and
EAGAIN is handled by re-registering a writer, so the call is safe.
Extend the os.sendfile allowlist with the selector-loop caller as a
local workaround. Fixed upstream by
https://github.com/cbornet/blockbuster/pull/58 (issue
https://github.com/cbornet/blockbuster/issues/57); drop this once
blockbuster is bumped to a version that includes the fix.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The cleanup of the downloaded RAUC bundle in OSManager.update() called
Path.unlink() directly on the event loop, which blockbuster flagged as a
blocking call. Run it in the executor instead.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* apps: avoid blocking is_file() check in restore
Restoring an app off a backup called `Path.is_file()` directly on the
event loop to check whether the bundle contained an `image.tar`, which
triggered a blockbuster BlockingError on `os.stat` in environments where
blocking-call detection is enabled. Wrap the check in
`self.sys_run_in_executor(...)` so the stat happens off the main thread,
matching the pattern already used in `api/backups.py`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* tests: cover restore path where addon image is missing
The blocking ``is_file()`` call that the previous commit replaced lived
in the ``not instance.exists()`` branch of ``App.restore()`` -- reached
only when the local Docker image for the addon is absent. Existing
app-restore tests start from ``install_app_ssh`` / ``install_app_example``
and rely on the mocked ``docker images.inspect`` which always reports
the image as present, so that branch never executed and blockbuster
never had a chance to flag the blocking stat.
Add a focused test that uninstalls the app after backup, patches
``DockerApp.exists`` to ``False``, and stubs ``install`` / ``import_image``
so the restore drives through the ``image.tar`` check. Verified that
this test raises ``BlockingError: Blocking call to os.stat`` when run
against the unpatched code.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Enable the PYI, RET and RSE ruff rule sets and fix the resulting
violations across the codebase. The pylint no-else-* checks
(RET505-508) are now disabled since ruff covers them.
The cleanups are mechanical:
- RSE102: drop empty parentheses from `raise Exception()` when no
arguments are passed.
- RET505-508: drop `else` branches that follow a `return`, `raise`,
`continue` or `break`, flattening control flow.
- RET502/504: add explicit return values and remove redundant
assign-then-return patterns.
- PYI030/032/041: tidy up type annotations (collapse literal unions,
use `object` for `__eq__`/`__ne__`, drop redundant numeric unions).
Stored registry credentials are applied globally to any pull whose image
matches the configured registry hostname. This is fine while the
credentials are valid, but our public images on ghcr.io (Core,
Supervisor, plugins) can normally be pulled anonymously - so as soon as
the stored credentials become invalid (token expired or revoked), every
ghcr.io pull starts failing with 401/403 even though anonymous access
would still work. The user has typically forgotten the credentials were
ever added (often during a private add-on install), and the logs give
no hint that credentials are in play (see home-assistant/core#170281).
Promote the credential-use log lines from DEBUG to INFO in both the pull
path (DockerInterface) and the manifest fetcher, and include the image
or repository being accessed. A failed pull that used stored credentials
now leaves a visible breadcrumb pointing at the likely cause.
Usernames are not secret and are already routinely shared in support
logs, so logging them at INFO is acceptable. Credentials aren't used for
most pulls, so this does not add meaningful log noise.
Building the app container mount list called Path.exists() on candidate
GPIO sysfs paths from the event loop, which blockbuster flagged as a
blocking os.stat. Whether these sysfs paths exist is determined by the
kernel at boot and does not change at runtime, so resolve them once in
HwHelper.load() (invoked from HardwareManager.load()) and expose the
result via helper.gpio_mount_paths. DockerApp.mounts can then stay a
plain sync property.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Turn on the PTH rule set in ruff and convert the remaining call sites
that triggered violations:
- `supervisor/utils/yaml.py` and `tests/homeassistant/test_module.py`
use `Path.open()` instead of the builtin `open()`.
- `tests/backups/test_backup.py` and
`tests/resolution/fixup/test_store_execute_reset.py` use
`Path.iterdir()` instead of `os.listdir()`.
- `tests/mounts/test_mount.py` uses `Path.unlink()` instead of
`os.remove()`.
- `tests/store/test_translation_load.py` uses `Path.mkdir(parents=True)`
instead of `os.makedirs()`.
- `tests/hardware/test_disk.py` captures the unpatched `Path.is_dir`,
`Path.is_symlink` and `Path.stat` before the `patch.object(Path, ...)`
block so the mocks can delegate to the real implementations without
reaching for `os.path.isdir`/`os.path.islink`/`os.stat`.
* tests: enable flake8-pytest-style (PT) ruff rules
Enable the `PT` ruff rule set and fix the resulting violations across the
test suite:
- PT006: pass parametrize argument names as tuples instead of a single
comma-separated string.
- PT022: switch fixtures that have no teardown from `yield` to `return`
so the lack of cleanup is obvious at a glance.
- PT011: add `match=` to broad `pytest.raises(ValueError)` blocks so the
expected error is anchored to a specific message.
- PT012: hoist setup (patches, branching) out of `pytest.raises()`
blocks so only the call that is expected to raise remains inside.
- PT013: replace `from pytest import X` with `import pytest` and access
attributes via the module.
- PT015: replace `try/except` + `assert False` patterns with
`pytest.raises(...)`.
- PT017: replace `assert` on exceptions inside `except` blocks with
`pytest.raises(...) as exc_info` and assert on `exc_info.value`.
No behavioral changes to the tests; the full suite still passes.
* tests: address review feedback on PT ruff rule enablement
- Fix fixture return-type annotations after switching `yield` to `return`
in tests/conftest.py: drop the `Generator[...]`/`AsyncGenerator[...]`
wrapper for `dns_manager_service`, `supervisor_internet`, `websession`,
and `mock_update_data` so the annotation matches what the fixture
actually returns.
- Correct the return-type annotation of `fixture_ip6config_service` from
`IP4ConfigService` to `IP6ConfigService`.
- Fix recurring "excepiton" typo in tests/utils/test_exception_helper.py.
* tests: verify backup cleanup on permission error
After `test_new_backup_permission_error` raises `BackupPermissionError`,
assert that no tarfile was left behind and `tmp_path` is empty. The
previous version only checked that the exception was raised, which
missed any regression where a partial tarfile would survive the failed
create.
* tests: rename DNS_GOOD_V6 to DNS_V6_UNSUPPORTED
The constant was named "good" but its tests assert that the URLs are
rejected by the DNS validator. The IPv6 URLs are well-formed but
currently rejected because IPv6 doesn't work with the Docker network
(see `dns_url` in supervisor/validate.py). Rename the constant and the
related test to make the intent obvious.
* Don't fail Supervisor setup when an app image is missing
A missing builder image (docker:<version>-cli) during a build-required app
load aborted Supervisor setup entirely, leaving the system stuck in setup
state where every subsequent operation was blocked by the not-healthy
guard. Triggered in practice when the host's Docker patch version had no
matching `-cli` tag published on Docker Hub.
Two issues compounded the failure: `images.pull` in `run_command` leaked a
raw `aiodocker.DockerError` past the `@Job` decorator, which rewrapped it
as `JobException` and bypassed the `suppress(DockerError, ...)` guard in
`addon.load()`; and the load path treated all Docker errors the same
whether the image was simply missing or the daemon itself was misbehaving.
Wrap the pull error in `run_command` so it propagates as Supervisor's
`DockerError` (a `HassioError`) and is preserved by the decorator.
Distinguish 404s in `attach()` and `check_image()` by raising
`DockerNotFound`/`DockerAPIError` instead of generic `DockerError`. In
`addon.load()`, only the `DockerNotFound` path is treated as "image
missing": for build-required apps we skip the inline build and surface a
`MISSING_IMAGE` repair so the resolution autofix loop handles it off the
critical path; for pull-based apps we still attempt install during load
and create the repair on failure. Other `DockerError`s (daemon trouble or
a failed internal install in `check_image`) are logged at CRITICAL — which
the Sentry logging integration captures — and the addon is left detached
rather than masked as a misleading missing-image repair.
In the autofix path, swallow `DockerBuildError`, `DockerNoSpaceOnDevice`,
`DockerRegistryAuthError`, and `DockerRegistryRateLimitExceeded` as
`ResolutionFixupError` so they don't generate Sentry events on every
retry. The repair stays available for manual retry once the underlying
cause (registry tag published, disk freed, credentials fixed, rate limit
expired) is resolved.
* Clarify outer DockerError comment in App.load()
The comment claimed "a future load will reattempt and surface a
MISSING_IMAGE repair if appropriate", but App.load() is only called at
Supervisor startup, on fresh install, and on backup restore — there is no
automatic retry mechanism. Reword to match reality: the CRITICAL log
captures the issue for diagnostics (Sentry), and the user can trigger a
manual repair once the daemon is healthy.
* Clarify comment about user interaction
* Update Supervisor before installing Home Assistant Core
During the install loop, check if Supervisor has a pending update
before attempting to install Home Assistant Core. Supervisor must
always be updated first to avoid incompatibilities.
- If auto-update is enabled, attempt to update Supervisor first.
On success, the process restarts automatically. On failure, log
a warning, capture the exception to Sentry, and retry after the
standard install retry period.
- If auto-update is disabled, log a warning that unknown issues may
occur and proceed with the Core install anyway to avoid leaving
users without a UI.
Also extract the 30-second install retry wait into a shared
INSTALL_RETRY_WAIT_SECS constant used across all sleep calls and
log messages in install() and install_landingpage().
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix too many nested blocks issue
* Better log messages
Co-authored-by: Stefan Agner <stefan@agner.ch>
* Remove unnecessary exception capture and fix tests
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Stefan Agner <stefan@agner.ch>
* apps: log container exit code when app exits non-zero
Issue #6840 reports that stopping an app whose process exits 143 (SIGTERM
default disposition) leaves the app in AppState.ERROR. ERROR is the right
state for that — Docker itself treats any non-zero exit as a failure
(e.g. `--restart on-failure`), and 143 specifically means the SIGTERM
grace period was wasted because the app never installed a handler. But
Supervisor previously logged nothing about it, leaving authors with no
hint that their image is misbehaving.
Plumb the exit code through DockerContainerStateEvent and log it from
App.container_state_changed on transitions to FAILED: a warning for 143
nudging the author to trap SIGTERM and exit 0, and an error for any
other non-zero code (crashes, SIGKILL after grace, app's own error
exit).
Refactor _container_state_from_model to return (state, exit_code) so
the docker event monitor and DockerInterface.attach feed the same exit
code through one code path instead of re-reading State.ExitCode in the
caller.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* apps: address review feedback on exit-code logging
- Replace bare 143 with EXIT_CODE_SIGTERM_DEFAULT (128 + signal.SIGTERM)
in supervisor/docker/const.py so the reasoning is documented in code,
not just in the log string.
- Stop populating exit_code on STOPPED transitions. Previously the
refactor made DockerInterface.attach emit exit_code=0 for cleanly
stopped containers, while the monitor only emitted an exit code for
abnormal exits. Align both paths so exit_code is only set on FAILED.
- Add test_app_failed_logs_exit_code covering the three new branches
(warning on 143, error on other non-zero, silent when None) and
extend test_attach_existing_container to assert the event's exit_code
field per state.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docker/monitor: flatten exit_code branch to satisfy pylint
The previous if/else inside the `die` branch pushed the function over
pylint's too-many-nested-blocks threshold (6/5). Collapse it back into
a pair of conditional expressions: container_state via ternary on the
exit code, exit_code via `die_exit_code or None` so 0 stays None.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Update supervisor/apps/app.py
Co-authored-by: Mike Degatano <michael.degatano@gmail.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Mike Degatano <michael.degatano@gmail.com>
* mounts: use softerr for NFS instead of soft
Switch the NFS mount option from `soft` to `softerr`. For HAOS-style
supervisor mounts (media, share, backup — not the root filesystem) the
error semantics matter:
* `softerr` returns `ETIMEDOUT` on timeout instead of `EIO` (`soft`).
`EIO` is indistinguishable from "the disk is dying"; tools like
SQLite, restic, rsync, ffmpeg tend to treat it as a hard storage
failure (mark database corrupt, abort backup with a hard error,
etc.). `ETIMEDOUT` is unambiguously "the network/server is gone,
transient" and is more commonly handled as retry-later. Supervisor
can also surface a clear "server unreachable" notification rather
than a generic I/O error.
* `softerr` was added in kernel 5.10 precisely to give the fail-fast
behavior of `soft` with a distinct errno so well-behaved apps can
do the right thing.
* For writes-must-not-be-lost use cases (databases, paid storage,
evidence-grade logging) one would want `hard,intr` and a different
recovery story. HAOS NFS mounts are not that — they're add-on
storage where "the share went offline, try again later" is the
correct user-visible behavior.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* mounts: make is_mounted honest about server reachability
systemd's "active/mounted" state is derived from /proc/self/mountinfo
and doesn't reflect whether the backing server actually answers. For
CIFS in particular, smb3_reconfigure never contacts the server, so a
reload of a dead share returns active/mounted with no recovery
attempted. PR #4882 added a Path.is_mount() cross-check to catch this,
but Path.is_mount() relies on os.stat() of the mountpoint root — and
both NFS (softreval) and CIFS (cached root inode attrs) can serve that
stat from local state without going to the wire, so it lies in exactly
the dead-share scenario it was meant to detect.
The visible failure: an API reload of a backup mount whose server had
gone away "succeeded", supervisor then kicked off sys_backups.reload()
against the dead share, and the executor fanned out hundreds of
"Task exception was never retrieved" OSError(112) tracebacks as each
backup tarball's stat() parked in the kernel and failed.
Replace the local-state checks with a statvfs() probe in
NetworkMount.is_mounted(). os.statvfs() returns per-filesystem data
(free blocks, total blocks) that has no client-side cache in either
kernel — neither cifs_statfs() nor nfs_statfs() has an early-return on
cache freshness; both build and send a real FSSTAT / QUERY_FS_INFO
request. So the kernel either reaches the server or gives up with
ETIMEDOUT / EHOSTDOWN / ECONNABORTED. is_mounted() now reflects actual
reachability, finally fulfilling PR #4882's stated intent.
With is_mounted() honest, the reload/restart machinery falls out
naturally: Mount.reload()'s fast path is just `if await self.is_mounted()`,
the post-reload check is the same call, and the "reload succeeded
systemd-wise but probe failed" branch collapses into the existing
"not mounted after reload, try restart" branch. mount(), _restart()
and update() already call is_mounted(); they now get the probe for
free.
To make the probe meaningful, the network mount option strings get
explicit kernel-side timeouts:
* NFS switches from `soft` to `softerr` so timeouts surface as
ETIMEDOUT rather than EIO. EIO is indistinguishable from
"disk dying" and gets misinterpreted by SQLite/restic/rsync as a
hard storage failure; ETIMEDOUT is unambiguously transient.
* CIFS gains `soft,echo_interval=10,retrans=0`, giving a ~30s
per-operation detection budget (3 x echo_interval since last server
response) that matches the NFS budget from `timeo=100,retrans=2`.
Both protocols now fail bounded operations in roughly the same time.
The probe is intentionally not wrapped in an asyncio timeout: the
kernel-side bound is authoritative, and an asyncio timeout would only
orphan the executor thread without unblocking the syscall. The probe
emits debug logs with timing so the ~30s syscall wait on a dead share
is visible in LOGLEVEL=debug traces instead of appearing as a hang.
Tests:
* mock_is_mount fixture extended to also patch os.statvfs so existing
tests that rely on a healthy mount don't need to know about the
probe.
* New manager test split into _healthy_skips_systemd (probe succeeds,
fast path, no systemd call) and _probe_failure_triggers_systemd_reload
(probe fails, escalation runs). API reload test covers both paths.
* Existing tests that simulated "mount is down" via
mock_is_mount.return_value=False updated to simulate probe failure
via OSError(EHOSTDOWN), since is_mount is no longer the signal.
* mounts: drive systemd job waits via JobRemoved instead of state polling
`_update_state_await` had a race that has been present since network
mounts were introduced (#4269) and survived every subsequent rewrite
(#4733, c75f36305): the wait function reads the unit's ActiveState
*after* the systemd dispatch returns, then matches against a target
set that almost always includes the pre-call state (ACTIVE). If
systemd has not yet started dispatching the queued job — and for
fast operations like CIFS reload (smb3_reconfigure completes in
milliseconds with no server contact) it routinely has not — the wait
matches immediately on the pre-call state and returns "done" before
the operation has actually begun. The race was invisible until the
probe commit started doing honest network work after the wait
returned, at which point we spent a full ~30s NFS probe wait on a
mount that systemd was still in the middle of restarting.
Switch the job-dispatching paths (mount/unmount/reload/restart) to
systemd's `JobRemoved` Manager signal. The pattern:
async with sys_dbus.systemd.job_removed() as jobs:
job_path = await sys_dbus.systemd.restart_unit(...)
await jobs.wait_for_job(job_path)
is structurally race-free: subscription is set up before dispatch,
the job_path is allocated synchronously inside the dispatch call,
and any JobRemoved for that path after subscription is queued. Even
for operations that complete faster than we can process the dispatch
return value (the CIFS reload case), the signal cannot be missed.
`_update_state_await` is kept for `load()` — that path observes
existing state without having dispatched a job, so the
PropertiesChanged-driven wait is the right primitive there.
* mounts: verify the path is a mount point before trusting statvfs
The userspace probe trusted statvfs() alone to declare a network mount
healthy. statvfs is uncacheable client-side for both NFS and CIFS, so
on a real mount it forces a wire RPC — but if the mount is gone from
the kernel mount table (e.g., after a restart cycle whose umount
succeeded but whose mount step failed, leaving the unit ACTIVE in
systemd's view), statvfs() operates on a plain directory on the
underlying root filesystem and happily returns the root fs's stats.
The mount is reported healthy when in fact it doesn't exist.
Add a pre-check using `Path.is_mount` — a parent-vs-path `st_dev`
comparison via stat() — to detect "this path is not actually a mount
point" before issuing statvfs. For the ghost-mount case (path on the
root fs) both stats are local and return immediately. For a real
mount the path-stat may cross into the filesystem driver, but the
result is correct in either case and the statvfs that follows
catches server-unreachable mounts that is_mount can't.
The full is_mounted contract is now: ACTIVE per systemd, present as
a mount point in our namespace, and server-reachable per statvfs.
* mounts: skip wasted probes when systemd already reported job failed
JobRemoved tells us whether the systemd job completed successfully —
we just weren't using it. The previous reload/restart paths ran their
post-job probe unconditionally, including the case where systemd had
already told us the operation failed. On a dead NFS share the kernel
is in transport-reconnect churn for tens of seconds after a killed
mount helper exits, so that probe takes 90+ seconds — and confirms
exactly what systemd already said. Plain wasted time.
* `Mount.reload()` now uses the systemd job result. On "done" we
still probe (CIFS reload is local-only — smb3_reconfigure returns
"done" even against a dead server, so the probe is the only check
that catches the lying-CIFS case). On anything else (failed,
timeout, canceled, dependency, skipped, or our own timeout
returning None) we escalate directly to `_restart()` without
probing.
* `Mount._restart()` skips the probe entirely on non-"done" results.
The mount is definitively not active in that case and the probe
would just spend another 30-90s on a dead share.
Also bump the JobRemoved wait timeout from UPDATE_STATE_TIMEOUT (40s,
sized for a single-helper invocation) to a new SYSTEMD_JOB_TIMEOUT
(90s). RestartUnit runs as stop + start, each bounded by the unit's
TimeoutSec (35s from #6834), so the worst case is ~70s plus systemd
queue dispatch. The previous 40s budget caused supervisor to time
out exactly one second before JobRemoved fired in the observed
dead-NFS restart cycle. UPDATE_STATE_TIMEOUT is kept at 40s for the
PropertiesChanged-driven wait in `load()`, where the layered timeout
invariant from #6827 still applies.
* dbus: filter signals at the wrapper level, drop JobRemovedSignal class
Mike's review on #6838: instead of carrying a bespoke JobRemovedSignal
context-manager class, push the filtering concept into the generic
DBusSignalWrapper. Any caller that subscribes to a broadcast signal
but only cares about specific payloads can pass a predicate.
* DBus.signal() gains an optional `message_filter: Callable[..., bool]`.
* DBusSignalWrapper.wait_for_signal() loops past messages where the
filter returns False, returning the next match.
* JobRemovedSignal goes away. supervisor/dbus/systemd.py exposes a
small factory `job_removed_filter(get_job_path)` that returns the
matching predicate; the getter indirection lets callers subscribe
before the dispatch returns the job path (which is required to be
race-free — see the previous commit).
Mount._run_systemd_job() switches to:
job_path: str | None = None
async with systemd.connected_dbus.signal(
DBUS_SIGNAL_SYSTEMD_JOB_REMOVED,
job_removed_filter(lambda: job_path),
) as signal:
job_path = await dispatch
_id, _path, _unit, result = await signal.wait_for_signal()
The behavior is identical to the previous JobRemovedSignal-based
implementation. The signal queue still buffers messages received
after AddMatch is installed, so subscribing before dispatch keeps
the race-free guarantee.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Rename addon/addons to app/apps in filenames and imports
Continues the addon→app terminology migration (#6786).
Renames all source files, test files, fixture files, and
directories that contained 'addon'/'addons' in their names,
and updates all imports accordingly.
Resolution check files in supervisor/resolution/checks/ that were
renamed override the slug property to preserve the existing API
contract (slugs are exposed via the resolution info API and used
to run checks by name).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Rename add-on.json fixture
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
When a network mount's backing server became unreachable while the
supervisor's periodic mount reload ran, the host could be force-reset by
the hardware watchdog within ~60 seconds. Fixes#6827.
Mechanism observed in a reproducer on HAOS x86 (iTCO_wdt, 30 s
heartbeat):
1. `Mount.reload()` issues `ReloadUnit` over D-Bus. systemd spawns
`mount -o remount` against the dead NFS server. The remount helper
parks in `TASK_UNINTERRUPTIBLE` inside the kernel NFS client, and
any unrelated userspace operation that touches the same mount
path (stat, getdents, readdir) joins it there.
2. After 30 s `_update_state_await()` gives up waiting for the unit
to leave `reloading`. The unit is still in `reloading` from
systemd's point of view; the helper is still pinned in the kernel.
3. Because the reload did not converge, `Mount.reload()` escalates by
calling `_restart()`, which issues `RestartUnit`. To restart,
systemd has to stop the active mount; the umount runs into the
same in-kernel stall as the remount helper. The job queue stops
making progress and PID 1 stops being able to pet
/dev/watchdog0. ~30 s later the iTCO chip resets the box.
The underlying PID 1 livelock is reported upstream as
systemd/systemd#42050. The bug is reproducible with NFS; we have not
been able to reproduce it with CIFS. HAOS also bumped the systemd
runtime watchdog timeout to give more headroom for slow workers
(home-assistant/operating-system#4705), but that does not on its own
prevent the wedge. The fix here removes the trigger from the supervisor
side.
Changes:
* Switch the NFS option string from `timeo=200` to
`timeo=100,retrans=2`, and pass `TimeoutUSec=35s` as a
unit-level property on each transient mount unit. The supervisor's
existing state-await is bumped from 30 s to 40 s. Three layered
timeouts now cooperate to avoid the reload → restart escalation that
triggers the bug:
NFS RPC timeout (timeo=100,retrans=2) ~30 s
< systemd unit TimeoutSec 35 s
< supervisor state-await 40 s
Ordering is what matters. The kernel RPC layer fails first so the
mount helper can exit; systemd then SIGTERMs anything that did not
and moves the unit to `failed` before supervisor abandons its
observation. Supervisor sees `failed`, never enters the
reload → restart escalation, and any subsequent fixup-triggered
restart runs from `failed` (no in-flight helper, no pinned kernel
task) — the safe path. systemd's `TimeoutSec` covers all
mount/umount/remount helpers for a `.mount` unit; no separate reload
timeout exists.
* Safety net for the reload → restart escalation. In `Mount.reload()`,
if the unit is still in `reloading` after the state-await returns,
raise `MountActivationError` directly instead of calling
`_restart()`. With the layered timeouts above this should not be
reachable; the guard exists so that if it ever does fire (e.g. a
future kernel/option regression), we surface a clear log at
CRITICAL level and refuse to issue the destructive `RestartUnit`
call rather than wedging PID 1 again. Normal reload → restart for
the "unit left reloading but is not active" case is preserved.
* `FixupMountExecuteReload` now catches `MountError`, logs a warning,
and re-raises `ResolutionFixupError` so `FixupBase` skips
issue/suggestion cleanup. The user retains the "execute reload"
suggestion to retry once the underlying problem is fixed, instead of
the fixup returning success when nothing was actually fixed (which
would dismiss the issue and let the next reload cycle hit the same
bug again).
Tests:
* New `test_reload_does_not_escalate_when_still_reloading` asserts that
`RestartUnit` is not called when the unit stays in `reloading` after
the state-await — the regression guard for the watchdog reset.
* `test_fixup_error_after_reload` updated for the new fixup behavior
(no longer propagates `MountActivationError`; issue/suggestion
remain in place).
* All existing mount/manager tests updated to include the new
`TimeoutUSec` property in expected `StartTransientUnit` option
lists, and NFS option strings updated to the new defaults.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Stefan Agner
Jan Čermák
dependabot[bot]
Mike Degatano