fix: smart-strategy resilience for refresh-status 5xx (counters, cache, recovery)

When the Toyota gateway returns persistent HTTP 500 on
POST /refresh-status (some Lexus / Aygo / Yaris vehicles per
ha_toyota#291 + ha_toyota#293), pytoyoda's controller exhausts its
4-attempt retry sequence and raises ToyotaApiError. The previous
implementation called vehicle.refresh_status() without a try/except,
which meant the exception propagated out of _refresh_one_vehicle
with three consequences:

1. on_post_layer1_failure() never ran (it sits inside the
   `return_code != "000000"` branch, which a raised POST never
   reaches), so consecutive_post_rejections never advanced and the
   _AUTO_DISABLE_REJECTION_THRESHOLD soft/hard-disable mechanism
   never fired. status_refresh_state stayed `active` forever.

2. _refresh_one_vehicle's post-decision bookkeeping was skipped:
   trips manager refresh, movement detection, diag state persistence,
   and the caller's `last_good_per_vin[vin] = vehicle_data` line.
   Phase 1 had already fetched fresh telemetry/location/etc., but
   that fresh data was never promoted to the cache layer; entities
   served from the prior cycle's cached VehicleData. Reported as
   parking location frozen at home, lock state stale, etc.

3. Once auto-disable did fire (via the existing returnCode-rejection
   branch on cars where that path could trip), the only documented
   recovery was the user toggling enable_status_refresh OFF then ON.
   No way to retry without disabling the feature first.

This commit:

- Wraps the POST in contextlib.suppress for the same exception set
  the Layer 2 poll loop already catches. Collapses the exception
  path and the non-"000000" returnCode path into a single Layer 1
  failure branch.
- Adds a bare GET fallback (`vehicle.update(only=["status"])`) on
  Layer 1 failure so /status entities still refresh this cycle,
  even before auto-disable kicks in.
- Lets explicit service calls bypass BOTH HARD_DISABLED_AUTO and
  HARD_DISABLED_USER. Matches the HA convention that polling
  toggles stop the cadence but explicit invocations still go
  through; users can disable the automatic strategy and drive POSTs
  from their own automations (geofence, garage door, time-of-day).
- After a successful POST clears auto_disabled_status_refresh,
  the strategy goes back to ACTIVE on the next cycle without manual
  toggling. Users can now recover from auto-disable by simply
  pressing the refresh button instead of toggling options OFF/ON.
- Three new tests in test_refresh_strategy.py covering the
  service-call bypass behaviour for both AUTO and USER disable +
  blocking when no service call is pending.
- Updates const.py docstring for CONF_ENABLE_STATUS_REFRESH and
  services.yaml description for refresh_vehicle_status to reflect
  the cadence-vs-capability distinction.

All 31 existing tests still pass; ruff clean.

Closes ha_toyota#293.

Author: nledenyi

custom_components/toyota/__init__.py

@@ -394,30 +394,56 @@ async def _execute_post_then_get(
         retries 429/5xx with exponential backoff, so this loop only iterates
         if the gateway returned 200 with a stale occurrence_date (legitimate
         "POST accepted but cache not yet warm").
+
+        On POST failure (exception OR non-"000000" returnCode): record a
+        Layer 1 rejection, possibly auto-disable, then fall back to a bare
+        GET so /status entities still refresh this cycle. See ha_toyota#293.
+        On POST success: clear any prior auto-disable flag so a service-call
+        retry (or a transient-5xx recovery) restores normal operation
+        without requiring the user to toggle the option manually.
         """
         opts = _strategy_options()
-        post_response = await _call_tagged(
-            "refresh_status", vin, vehicle.refresh_status()
-        )
+        # POST raised after pytoyoda's retries exhausted (persistent gateway
+        # 5xx) → post_response stays None and falls through to the Layer 1
+        # failure branch below, same family as a non-"000000" returnCode
+        # ("gateway will not process this POST"). _call_tagged has already
+        # logged the underlying error.
+        post_response = None
+        with contextlib.suppress(
+            ToyotaApiError,
+            httpx.ConnectTimeout,
+            httpcore.ConnectTimeout,
+            asyncioexceptions.TimeoutError,
+            httpx.ReadTimeout,
+        ):
+            post_response = await _call_tagged(
+                "refresh_status", vin, vehicle.refresh_status()
+            )
         state.last_post_attempt_at = dt_util.now()
 
         # Layer 1: gateway-level acceptance. payload.return_code "000000" =
-        # accepted; anything else = vehicle does not support refresh-status.
-        # (pytoyoda exposes the field as snake_case via Pydantic Field alias.)
-        payload = getattr(post_response, "payload", None)
+        # accepted; anything else (or no response = exception path) =
+        # vehicle does not support refresh-status this cycle.
+        payload = getattr(post_response, "payload", None) if post_response else None
         return_code = getattr(payload, "return_code", None) if payload else None
 
         if return_code != "000000":
             should_auto_disable = on_post_layer1_failure(state, opts)
-            _LOGGER.warning(
-                "Toyota refresh-status rejected for vin=...%s (returnCode=%s)",
-                vin[-6:],
-                return_code,
-            )
-            if should_auto_disable:
+            if post_response is not None:
+                # 200 OK with non-000000 returnCode (gateway-level rejection).
+                _LOGGER.warning(
+                    "Toyota refresh-status rejected for vin=...%s (returnCode=%s)",
+                    vin[-6:],
+                    return_code,
+                )
+            if should_auto_disable and not entry.options.get(
+                CONF_AUTO_DISABLED_STATUS_REFRESH, False
+            ):
                 # Persist auto-disable to config_entry.options. Triggers a
-                # listener-driven reload, which is fine - state survives via
-                # diag_bucket.
+                # listener-driven reload, which is fine - state survives
+                # via diag_bucket. Guarded against re-entrance: a service-
+                # call retry that still 500s would otherwise trip the
+                # threshold every cycle and trigger a redundant reload.
                 hass.config_entries.async_update_entry(
                     entry,
                     options={
@@ -426,13 +452,49 @@ async def _execute_post_then_get(
                     },
                 )
                 _LOGGER.warning(
-                    "Toyota auto-disabled smart refresh for vin=...%s after "
-                    "%d consecutive Layer 1 rejections",
+                    "Toyota auto-disabled smart refresh for vin=...%s "
+                    "after %d consecutive Layer 1 rejections",
                     vin[-6:],
                     state.consecutive_post_rejections,
                 )
+            # Fall back to a bare GET so /status entities still refresh
+            # this cycle (matches the HARD_DISABLED legacy path). Useful
+            # for cycles before auto-disable kicks in, and for any vehicle
+            # whose POST 500s but whose /status still serves stale-cache
+            # data we can read. Suppression list matches the POST's so
+            # transient connectivity issues during the fallback don't
+            # abort _refresh_one_vehicle's bookkeeping either.
+            with contextlib.suppress(
+                ToyotaApiError,
+                httpx.ConnectTimeout,
+                httpcore.ConnectTimeout,
+                asyncioexceptions.TimeoutError,
+                httpx.ReadTimeout,
+            ):
+                await _call_tagged(
+                    "status_after_post_fail",
+                    vin,
+                    vehicle.update(only=["status"]),
+                )
             return
         on_post_layer1_success(state)
+        # Auto-recovery from HARD_DISABLED_AUTO: a successful POST proves
+        # the gateway can process this endpoint. Lift the flag so the
+        # strategy goes back to ACTIVE on the next cycle. Triggered by
+        # service-call bypass (the user explicitly retrying via the
+        # refresh button) or by a transient 5xx clearing on its own.
+        if entry.options.get(CONF_AUTO_DISABLED_STATUS_REFRESH, False):
+            hass.config_entries.async_update_entry(
+                entry,
+                options={
+                    **entry.options,
+                    CONF_AUTO_DISABLED_STATUS_REFRESH: False,
+                },
+            )
+            _LOGGER.info(
+                "Toyota auto-disable cleared for vin=...%s after successful POST",
+                vin[-6:],
+            )
 
         # Layer 2: poll for occurrence_date advancement.
         deadline = dt_util.now() + timedelta(seconds=timeout_s)

custom_components/toyota/const.py

@@ -29,11 +29,14 @@
 # Smart status refresh strategy. POSTs /v1/global/remote/refresh-status to
 # wake the car's modem before reading /status, mimicking the Toyota mobile
 # app's two-stage protocol. Reduces stuck-stale lock/door state and 429s.
-# See rate-limit-remediation-plan.md Addendum 4.
+# Off = stop the automatic cadence; explicit refresh_vehicle_status service
+# calls still go through (per HA polling-toggle convention). See
+# rate-limit-remediation-plan.md Addendum 4.
 CONF_ENABLE_STATUS_REFRESH = "enable_status_refresh"
 DEFAULT_ENABLE_STATUS_REFRESH = True
 # Set automatically when the gateway repeatedly rejects the POST (vehicle
-# does not support refresh-status). Cleared when user toggles
+# does not support refresh-status). Cleared by either: (a) a successful
+# service-call POST proving the gateway works, or (b) the user toggling
 # CONF_ENABLE_STATUS_REFRESH OFF then ON. Hidden in the UI.
 CONF_AUTO_DISABLED_STATUS_REFRESH = "auto_disabled_status_refresh"
 DEFAULT_AUTO_DISABLED_STATUS_REFRESH = False

custom_components/toyota/refresh_strategy.py

@@ -191,15 +191,30 @@ class RefreshDecision:
 # ----------------------------------------------------------------------------
 
 
-def _hard_disable_decision(opts: StrategyOptions) -> RefreshDecision | None:
-    """Return a HARD_DISABLED decision if either disable flag is set, else None."""
-    if not opts.enable_status_refresh:
+def _hard_disable_decision(
+    opts: StrategyOptions,
+    *,
+    user_service_call_pending: bool = False,
+) -> RefreshDecision | None:
+    """Return a HARD_DISABLED decision if either disable flag is set, else None.
+
+    Service calls bypass BOTH disable forms. The convention everywhere in
+    HA is "polling toggle stops automatic polling, manual service calls
+    still work" - so enable_status_refresh:False means "stop the strategy's
+    cadence" rather than "lock out POSTs entirely". Users who want a
+    bespoke schedule (geofence arrival, garage-door close, etc.) disable
+    the cadence and drive POSTs from their own automations against the
+    refresh_vehicle_status service. After a successful service-call POST,
+    auto_disabled_status_refresh is cleared by the integration so a future
+    cadence re-enable doesn't land in the auto-disabled state.
+    """
+    if not opts.enable_status_refresh and not user_service_call_pending:
         return RefreshDecision(
             action=RefreshAction.HARD_DISABLED,
             trigger=RefreshTrigger.NONE,
             refresh_state=RefreshState.HARD_DISABLED_USER,
         )
-    if opts.auto_disabled_status_refresh:
+    if opts.auto_disabled_status_refresh and not user_service_call_pending:
         return RefreshDecision(
             action=RefreshAction.HARD_DISABLED,
             trigger=RefreshTrigger.NONE,
@@ -250,7 +265,9 @@ def decide(snapshot: CycleSnapshot) -> RefreshDecision:
     state = snapshot.state
     now = snapshot.now
 
-    hard = _hard_disable_decision(opts)
+    hard = _hard_disable_decision(
+        opts, user_service_call_pending=snapshot.user_service_call_pending
+    )
     if hard is not None:
         return hard
 

custom_components/toyota/services.yaml

@@ -6,6 +6,10 @@ refresh_vehicle_status:
     cellular airtime and 12V battery. Recommended for use after returning
     home from a drive when you want the lock state to be visible quickly,
     or wired to an automation that triggers on a specific event.
+    Works regardless of the integration's automatic refresh setting:
+    if you have disabled "Refresh vehicle status remotely" or the gateway
+    has auto-disabled it, this service still fires the POST so you can
+    drive a fully manual refresh schedule from your own automations.
   fields:
     device_id:
       name: Vehicle

tests/test_refresh_strategy.py

@@ -67,6 +67,51 @@ def test_auto_disabled_returns_hard_disabled_auto():
     assert d.refresh_state is RefreshState.HARD_DISABLED_AUTO
 
 
+def test_service_call_bypasses_hard_disabled_auto():
+    """Service call overrides auto-disable so the user can retry manually."""
+    s = _snap(
+        options=StrategyOptions(
+            enable_status_refresh=True, auto_disabled_status_refresh=True
+        ),
+        user_service_call_pending=True,
+    )
+    d = decide(s)
+    assert d.action is RefreshAction.POST_THEN_GET
+    assert d.trigger is RefreshTrigger.SERVICE_CALL
+
+
+def test_service_call_bypasses_hard_disabled_user():
+    """Service call also bypasses user-disable, matching HA convention.
+
+    `enable_status_refresh: False` stops the automatic cadence; explicit
+    service-call invocations (e.g. a garage-door automation calling
+    `refresh_vehicle_status`) still go through. Users who want full lockout
+    simply do not invoke the service.
+    """
+    s = _snap(
+        options=StrategyOptions(
+            enable_status_refresh=False, auto_disabled_status_refresh=False
+        ),
+        user_service_call_pending=True,
+    )
+    d = decide(s)
+    assert d.action is RefreshAction.POST_THEN_GET
+    assert d.trigger is RefreshTrigger.SERVICE_CALL
+
+
+def test_user_disable_blocks_non_service_triggers():
+    """Without a service call, user-disable still blocks the strategy."""
+    s = _snap(
+        options=StrategyOptions(
+            enable_status_refresh=False, auto_disabled_status_refresh=False
+        ),
+        user_service_call_pending=False,
+    )
+    d = decide(s)
+    assert d.action is RefreshAction.HARD_DISABLED
+    assert d.refresh_state is RefreshState.HARD_DISABLED_USER
+
+
 # ---------------------------------------------------------------------------
 # Step 4: service-call wins over everything except hard-disable
 # ---------------------------------------------------------------------------