Document the reconnect-timing change from smartthings-local's fail-fast fix

Answers a review callout on the 0.1.6 upgrade that wasn't actually
addressed, only mentioned in a commit message: a dead reader now raises
SessionClosedError (a ConnectionError) instead of hanging a request out
to its timeout and surfacing as an ambiguous TimeoutError. Mechanically
this was already routed correctly -- SessionClosedError isn't a
TimeoutError, so _defer_reconnect_for's isinstance check already skips
its multi-cycle tolerance for it -- but nothing recorded *why*, and the
callout's whole point was that downstream (i.e. this repo) should hear
about the resulting timing change explicitly, not infer it from the
dependency bump.

Before 0.1.6, a truly dead reader was indistinguishable here from a
slow blockwise transfer: both could only ever surface as a TimeoutError,
so _POLL_TIMEOUT_LIMIT's multi-cycle tolerance (~2 minutes at the
default 30s interval) was the only thing standing between a genuinely
dead session and a reconnect. Now that the library confirms reader
death directly, that failure mode skips the tolerance and reconnects on
the very first occurrence -- intended, and strictly faster recovery,
but a real change in observed timing worth calling out for anyone
correlating reconnect-log cadence with device behavior.

- _poll_once, _defer_reconnect_for, and the _POLL_TIMEOUT_LIMIT comment
  now say so directly, cross-referencing each other.
- README's "Known device behavior" section gets a paragraph so this
  isn't only visible to someone reading the coordinator's source.
- Two new unit tests pin the distinction directly:
  _defer_reconnect_for(SessionClosedError()) is False (no tolerance),
  while SessionTimeoutError keeps the existing _POLL_TIMEOUT_LIMIT
  tolerance -- so a future change can't quietly merge the two paths
  back together.

Full suite (1523 tests), ruff, and ty pass.
This commit is contained in:
Marc Billow committed 2026-08-14 18:15:32 +00:00
1 parent f949ff04c2
commit 74bdc04f56
3 files changed
+58 -2

No files matched your search

+25 -1
View File
@@ -208,7 +208,10 @@ class LocalThingsCoordinator(DataUpdateCoordinator[dict[str, Any]]):
# A block-level ACK timeout on the summary GET doesn't prove the session
# is dead (see _poll_once) -- require this many in a row before treating
# it as one, so one slow transfer doesn't tear down a working OBSERVE
# subscription.
# subscription. Only covers that ambiguous case: smartthings-local
# >= 0.1.6 raises a distinct SessionClosedError, not a TimeoutError, the
# moment a dead reader thread is confirmed, and _defer_reconnect_for
# never defers that -- see its docstring for what changed there.
_POLL_TIMEOUT_LIMIT: int = 3
# Named (not inline literals) so the write-settle window in
@@ -722,6 +725,14 @@ class LocalThingsCoordinator(DataUpdateCoordinator[dict[str, Any]]):
not that the session is dead (earlier blocks succeeded). Left open;
`_async_update_data` decides whether repeated timeouts warrant a
reconnect. Any other exception is unambiguous -- close immediately.
smartthings-local >= 0.1.6 tells those two cases apart itself now:
a reader thread that has actually died raises `SessionClosedError`
(a ConnectionError, not a TimeoutError) the moment the next request
notices, instead of the old behavior of quietly hanging out to this
call's own timeout and surfacing as an ambiguous `TimeoutError`.
See `_defer_reconnect_for` for what that changes about how soon a
confirmed-dead session gets reconnected.
"""
if self._session is None:
self._connect_session()
@@ -1256,6 +1267,19 @@ class LocalThingsCoordinator(DataUpdateCoordinator[dict[str, Any]]):
`_POLL_TIMEOUT_LIMIT` consecutive timeouts pile up. Any other
exception reconnects immediately.
That includes `SessionClosedError`, which is the point: before
smartthings-local 0.1.6, a reader thread that had actually died was
indistinguishable from a slow transfer -- both surfaced here only as
a `TimeoutError`, so this tolerance was the only thing standing
between a truly dead session and a reconnect, worst case about
`_POLL_TIMEOUT_LIMIT` poll cycles (~2 minutes at the default 30s
interval). 0.1.6 confirms reader death directly and raises a
ConnectionError subclass for it instead, which isn't a TimeoutError
and so skips this tolerance entirely -- a genuinely dead session now
reconnects on the very first occurrence. Intended (see this repo's
README, "Known device behavior"), not a regression, but a real
change in observed reconnect timing for that one failure mode.
Never defers before first discovery (issue #254): deferring returns
an empty dict, which the base coordinator treats as a successful
first refresh -- and since platforms enumerate `bound` once, the