Load a config entry offline from the last discovery snapshot (#295)

An appliance switched off at the wall used to take its whole config entry
down with it: async_setup_entry raised ConfigEntryNotReady, so the device
read as failed and its entities existed only as registry rows until the
appliance came back.

Loading the entry anyway isn't enough on its own. Entities here are the
output of discovery, discovery only runs inside a successful poll, and
platforms enumerate `bound` exactly once at forward time -- so an entry
that loads while offline loads empty, and with no listeners subscribed the
base coordinator stops rescheduling and never polls again.

Bank the resources dict each successful first cycle hands _run_discovery,
along with the subdevice candidate list and the /oic identity that route
the registry, and replay it through _run_discovery when the first refresh
fails. Storing the poll input rather than a rendered entity list keeps one
implementation of discovery instead of two: the offline entity set is
produced by the same code that produced the live one.

Three things fall out of that:

- Platforms judge entity existence against `discovery_resources`, not the
  live cache. The live cache deliberately stays empty, which is what keeps
  a restored entity `unavailable` rather than rendering a stale value for
  an appliance nobody can currently reach.
- A live discovery that disagrees with the snapshot reloads the entry --
  platforms can't adopt a changed set in place, so a firmware update or a
  sibling subdevice that starts answering needs a fresh setup.
- The entry holds one coordinator listener for its lifetime, so polling is
  scheduled regardless of how many entities are live.

An entry that has never reached the device has no snapshot, keeps raising
ConfigEntryNotReady, and closes its session on the way out as before -- no
metadata to build a device from, and it leaves room for setup flows that
need to interact with the appliance (#168).

Restores the two tests PR #303 rewrote, narrowed to that no-snapshot path.
This commit is contained in:
Marc Billow committed 2026-08-15 20:05:58 +00:00
1 parent bc03ada208
commit e684146f61
10 files changed
+709 -69

No files matched your search

+26 -10
View File
@@ -70,8 +70,13 @@ async def test_summary_interval(hass: HomeAssistant, mock_entry, mock_coordinato
assert coordinator.update_interval == timedelta(seconds=SUMMARY_INTERVAL_S)
async def test_offline_initial_setup_succeeds(hass: HomeAssistant, mock_entry) -> None:
"""ConfigEntry setup succeeds in offline mode when initial poll fails."""
async def test_update_failed_on_persistent_poll_error(hass: HomeAssistant, mock_entry) -> None:
"""ConfigEntryNotReady raised when poll fails even after reconnect.
An entry with no stored discovery snapshot has never reached this device,
so there is nothing to load offline from (issue #295) -- it stays on HA's
backoff rather than loading empty.
"""
with (
patch("custom_components.localthings.coordinator.LocalThingsCoordinator._connect_session"),
@@ -84,10 +89,8 @@ async def test_offline_initial_setup_succeeds(hass: HomeAssistant, mock_entry) -
result = await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
# Setup succeeds — entry should be in hass.data and state is LOADED
assert result
assert mock_entry.entry_id in hass.data.get(DOMAIN, {})
assert mock_entry.state == ConfigEntryState.LOADED
# Setup fails — entry should not be in hass.data
assert not result or mock_entry.entry_id not in hass.data.get(DOMAIN, {})
# ---------------------------------------------------------------------------
@@ -1823,11 +1826,14 @@ async def test_first_refresh_timeout_recovers_via_reconnect(
assert coordinator._consecutive_poll_timeouts == 0
async def test_first_refresh_persistent_timeout_succeeds_offline(
async def test_first_refresh_persistent_timeout_fails_setup(
hass: HomeAssistant, mock_entry
) -> None:
"""When initial refresh times out, setup still succeeds in offline mode
and retries in background."""
"""With no snapshot to load from, a reconnect that times out too must
fail the first refresh so HA retries on its backoff -- not load an
entity-less entry. The session it left open is closed on the way out
(`_poll_once` keeps it up on a `TimeoutError`, and the source port is
fixed per device)."""
with (
patch("custom_components.localthings.coordinator.LocalThingsCoordinator._connect_session"),
patch(
@@ -1835,11 +1841,21 @@ async def test_first_refresh_persistent_timeout_succeeds_offline(
side_effect=_HANDSHAKE_TIMEOUT,
),
patch("custom_components.localthings.coordinator.LocalThingsCoordinator._close_session"),
# Asserted on `async_close` rather than `_close_session`: the
# reconnect path calls the latter on its own, so it is already true
# whether or not setup cleans up after itself.
patch.object(
LocalThingsCoordinator,
"async_close",
autospec=True,
) as mock_async_close,
):
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
assert mock_entry.state is ConfigEntryState.LOADED
assert mock_entry.state is ConfigEntryState.SETUP_RETRY
assert not hass.states.async_all()
mock_async_close.assert_awaited_once()
async def test_post_discovery_timeout_is_still_deferred(
+366
View File
@@ -0,0 +1,366 @@
"""Loading a config entry while the appliance is unreachable (issue #295).
The device's entity set only exists as the output of a live poll, so coming
up offline means replaying the last successful discovery from a stored
snapshot. These tests pin the four things that makes load-bearing: the
snapshot gets written, it produces the same entity set offline, the
coordinator keeps polling until the device answers, and a live discovery that
disagrees with the snapshot reloads the entry rather than silently keeping a
stale set.
"""
from __future__ import annotations
from contextlib import contextmanager
from datetime import timedelta
from unittest.mock import patch
import pytest
from homeassistant.config_entries import ConfigEntryState
from homeassistant.core import HomeAssistant
from homeassistant.util import dt as dt_util
from pytest_homeassistant_custom_component.common import async_fire_time_changed
from custom_components.localthings.const import DOMAIN, SUMMARY_INTERVAL_S
from custom_components.localthings.coordinator import (
_SNAPSHOT_SAVE_DELAY_S,
LocalThingsCoordinator,
)
from custom_components.localthings.registry.identity import DeviceIdentity
from .conftest import _load_fridge_resources as _load_fridge
_COORD = "custom_components.localthings.coordinator.LocalThingsCoordinator"
@contextmanager
def _reachable(resources: dict, identity: DeviceIdentity | None = None):
"""A device that answers, optionally with an /oic/* identity -- which
`_connect_session` is what normally reads, so a test that patches it out
otherwise leaves `_identity` None."""
def _connect(self) -> None:
self._identity = identity
with (
patch(f"{_COORD}._connect_session", _connect),
patch(f"{_COORD}._poll_once", return_value=resources),
patch(f"{_COORD}._close_session"),
):
yield
@contextmanager
def _unreachable():
with (
patch(f"{_COORD}._connect_session"),
patch(f"{_COORD}._poll_once", side_effect=OSError("device offline")),
patch(f"{_COORD}._close_session"),
):
yield
def _store_key(entry) -> str:
return f"{DOMAIN}.{entry.entry_id}.discovery"
async def _flush_snapshot(hass: HomeAssistant) -> None:
"""Run out `async_delay_save`'s timer without reaching the next poll."""
async_fire_time_changed(hass, dt_util.utcnow() + timedelta(seconds=_SNAPSHOT_SAVE_DELAY_S + 1))
await hass.async_block_till_done()
async def _tick(hass: HomeAssistant) -> None:
"""Advance past one summary interval so the coordinator polls again.
`wait_background_tasks` is load-bearing: DataUpdateCoordinator runs its
interval refresh as a background task, which a plain block_till_done
doesn't await -- the poll would still be in flight at the assertion.
"""
async_fire_time_changed(hass, dt_util.utcnow() + timedelta(seconds=SUMMARY_INTERVAL_S + 1))
await hass.async_block_till_done(wait_background_tasks=True)
async def _setup_online_then_unload(hass: HomeAssistant, entry, resources: dict) -> set[str]:
"""Bring the entry up against a live device, bank the snapshot, and take
it back down. Returns the entity_ids that run produced."""
with _reachable(resources):
await hass.config_entries.async_setup(entry.entry_id)
await hass.async_block_till_done()
entity_ids = {s.entity_id for s in hass.states.async_all()}
await _flush_snapshot(hass)
await hass.config_entries.async_unload(entry.entry_id)
await hass.async_block_till_done()
return entity_ids
# ---------------------------------------------------------------------------
# Writing the snapshot
# ---------------------------------------------------------------------------
async def test_snapshot_written_after_first_discovery(
hass: HomeAssistant, mock_entry, mock_coordinator_session, hass_storage
) -> None:
"""A successful first cycle banks what it handed _run_discovery."""
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
await _flush_snapshot(hass)
stored = hass_storage[_store_key(mock_entry)]["data"]
assert stored["resources"]
assert "/information/vs/0" in stored["resources"]
assert "subdevice_candidates" in stored
async def test_snapshot_not_written_when_device_never_answers(
hass: HomeAssistant, mock_entry, hass_storage
) -> None:
"""Nothing to bank, so nothing is -- this is what keeps the no-snapshot
gate meaningful on a brand-new entry."""
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
# Asserted before the flush: running the save timer out also runs out
# HA's own setup-retry timer, which puts the entry back into
# SETUP_IN_PROGRESS.
assert mock_entry.state is ConfigEntryState.SETUP_RETRY
await _flush_snapshot(hass)
assert _store_key(mock_entry) not in hass_storage
async def test_snapshot_removed_when_entry_removed(
hass: HomeAssistant, mock_entry, mock_coordinator_session, hass_storage
) -> None:
"""The store is keyed on entry_id, so re-adding the appliance mints a new
one -- the old file has to go with the entry that wrote it."""
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
await _flush_snapshot(hass)
assert _store_key(mock_entry) in hass_storage
await hass.config_entries.async_remove(mock_entry.entry_id)
await hass.async_block_till_done()
assert hass_storage.get(_store_key(mock_entry), {}).get("data") is None
# ---------------------------------------------------------------------------
# Loading from it
# ---------------------------------------------------------------------------
async def test_offline_load_restores_the_same_entity_set(
hass: HomeAssistant, mock_entry, hass_storage
) -> None:
"""The whole point: a restart with the appliance powered off comes up on
the entity set the device last actually reported."""
resources = _load_fridge()
online_ids = await _setup_online_then_unload(hass, mock_entry, resources)
assert online_ids # guard: the online run must actually produce entities
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
assert mock_entry.state is ConfigEntryState.LOADED
assert {s.entity_id for s in hass.states.async_all()} == online_ids
async def test_offline_entities_are_unavailable_not_stale(hass: HomeAssistant, mock_entry) -> None:
"""Restored entities must not render the snapshot's values -- the
appliance is unreachable, so `unavailable` is the honest state and the
live cache stays empty to enforce it."""
resources = _load_fridge()
await _setup_online_then_unload(hass, mock_entry, resources)
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
states = hass.states.async_all()
assert states
assert all(s.state == "unavailable" for s in states)
coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
assert coordinator.rehydrated
assert not coordinator.last_resources
async def test_offline_load_without_snapshot_still_fails(hass: HomeAssistant, mock_entry) -> None:
"""No snapshot means no device metadata to build anything from, so the
entry stays on HA's backoff rather than loading empty."""
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
assert mock_entry.state is ConfigEntryState.SETUP_RETRY
assert not hass.states.async_all()
async def test_corrupt_snapshot_falls_back_to_setup_retry(
hass: HomeAssistant, mock_entry, hass_storage
) -> None:
"""A snapshot whose resources no longer replay cleanly must not take the
entry down with it."""
key = _store_key(mock_entry)
hass_storage[key] = {
"version": 1,
"minor_version": 1,
"key": key,
"data": {"resources": {"/information/vs/0": "not-a-rep"}, "subdevice_candidates": []},
}
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
assert mock_entry.state is ConfigEntryState.SETUP_RETRY
async def test_snapshot_restores_identity(hass: HomeAssistant, mock_entry) -> None:
"""`/oic/d`'s device types route the registry, so an offline load that
lost them could resolve a different one than the live poll did -- which
would show up as a spurious reconcile reload every restart."""
resources = _load_fridge()
identity = DeviceIdentity(
manufacturer="Samsung",
model="TEST-MODEL",
name="Fridge",
serial=None,
device_types=("oic.d.refrigerator",),
raw={"/oic/p": {}, "/oic/d": {}, "/oic/res": []},
)
with _reachable(resources, identity):
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
await _flush_snapshot(hass)
await hass.config_entries.async_unload(mock_entry.entry_id)
await hass.async_block_till_done()
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
assert coordinator._identity is not None
assert coordinator._identity.device_types == ("oic.d.refrigerator",)
# ---------------------------------------------------------------------------
# Recovery and reconciliation
# ---------------------------------------------------------------------------
async def test_offline_load_keeps_polling_and_recovers(hass: HomeAssistant, mock_entry) -> None:
"""The failure the PR this replaces actually shipped: with zero live
listeners the base coordinator stops rescheduling, and the entry never
polls again. Entities must go available on the next interval once the
appliance answers."""
resources = _load_fridge()
await _setup_online_then_unload(hass, mock_entry, resources)
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
assert coordinator._unsub_refresh is not None # a poll is actually queued
assert not coordinator.last_update_success
with _reachable(resources):
await _tick(hass)
assert coordinator.last_update_success
assert any(s.state != "unavailable" for s in hass.states.async_all())
async def test_reconcile_reloads_when_live_discovery_differs(
hass: HomeAssistant, mock_entry
) -> None:
"""Platforms enumerate `bound` once, so a live set that disagrees with the
snapshot can only be adopted by bringing the entry back up."""
resources = _load_fridge()
with _reachable(resources):
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
victim = coordinator.bound[0].href
await _flush_snapshot(hass)
await hass.config_entries.async_unload(mock_entry.entry_id)
await hass.async_block_till_done()
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
reduced = {href: rep for href, rep in resources.items() if href != victim}
with (
_reachable(reduced),
patch.object(hass.config_entries, "async_schedule_reload") as reload,
):
await _tick(hass)
reload.assert_called_once_with(mock_entry.entry_id)
async def test_reconcile_is_quiet_when_live_discovery_agrees(
hass: HomeAssistant, mock_entry
) -> None:
"""The common case -- same appliance, same firmware -- must not reload,
or every offline restart would cost a second setup cycle."""
resources = _load_fridge()
await _setup_online_then_unload(hass, mock_entry, resources)
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
with (
_reachable(resources),
patch.object(hass.config_entries, "async_schedule_reload") as reload,
):
await _tick(hass)
reload.assert_not_called()
async def test_live_load_never_reconciles(
hass: HomeAssistant, mock_entry, mock_coordinator_session
) -> None:
"""An entry that came up against a live device has nothing to reconcile
against; the reload path must stay out of the normal startup entirely."""
with patch.object(hass.config_entries, "async_schedule_reload") as reload:
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
assert not coordinator.rehydrated
reload.assert_not_called()
@pytest.mark.parametrize("failures", [1, 3])
async def test_offline_load_survives_repeated_poll_failures(
hass: HomeAssistant, mock_entry, failures: int
) -> None:
"""Recovery isn't one-shot: the entry keeps its entities and keeps
retrying across however many intervals the appliance stays dark."""
resources = _load_fridge()
online_ids = await _setup_online_then_unload(hass, mock_entry, resources)
with _unreachable():
await hass.config_entries.async_setup(mock_entry.entry_id)
await hass.async_block_till_done()
for _ in range(failures):
await _tick(hass)
assert mock_entry.state is ConfigEntryState.LOADED
assert {s.entity_id for s in hass.states.async_all()} == online_ids
with _reachable(resources):
await _tick(hass)
coordinator: LocalThingsCoordinator = hass.data[DOMAIN][mock_entry.entry_id]
assert coordinator.last_update_success
@@ -36,6 +36,15 @@ class _FakeCoordinator:
def canonical_resources(self, subdevice):
return self.last_resources
# _is_included judges existence against the discovery view, which is the
# live cache for everything but an offline load (issue #295).
@property
def discovery_resources(self):
return self.last_resources
def discovery_canonical(self, subdevice):
return self.canonical_resources(subdevice)
def _resources():
return _load_device("airconditioner_ailp_fac")
+9
View File
@@ -29,6 +29,15 @@ class _FakeCoordinator:
# subdevices (issue #177).
return self.last_resources
# _is_included judges existence against the discovery view, which is the
# live cache for everything but an offline load (issue #295).
@property
def discovery_resources(self):
return self.last_resources
def discovery_canonical(self, subdevice):
return self.canonical_resources(subdevice)
def _coord(last_resources) -> LocalThingsCoordinator:
return cast(LocalThingsCoordinator, _FakeCoordinator(last_resources))
+9
View File
@@ -34,6 +34,15 @@ class _FakeCoordinator:
return canonical_view(subdevice, self.last_resources, self._subdevices)
# _is_included judges existence against the discovery view, which is the
# live cache for everything but an offline load (issue #295).
@property
def discovery_resources(self):
return self.last_resources
def discovery_canonical(self, subdevice):
return self.canonical_resources(subdevice)
@pytest.mark.parametrize("name", _FIXTURE_NAMES)
def test_key_is_unique_across_all_bound_entities(name):