pybluetti 0.2.2__tar.gz → 0.2.3__tar.gz

{pybluetti-0.2.2 → pybluetti-0.2.3}/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.2.3
+
+- `StompClient` now stops retrying (instead of reconnecting forever, every ~30s with backoff) once the cloud sends msgCode 400, 403, or 600 in an ERROR frame - these are confirmed (600, directly observed retried unsuccessfully for over a day against a real device) or strongly implied (400, 403, per BLUETTI's own official Home Assistant integration's client, which groups all three with a genuine token expiry - msgCode 805 - as needing the same "stop and don't retry" response) to never succeed on retry. Deliberately not folded into the existing `on_auth_expired` (805) path: none of these three necessarily mean the access token itself is the problem, so claiming that would be misleading - they still reach a caller via `on_error`, with the real message, same as any other non-805 code.
+
 # 0.2.2
 
 - `ApplicationRuntimeException`'s `msgCode` is now included in `str(exc)` itself (e.g. `[500] server error`), not just the separate `.msgCode` attribute - every existing caller that logs or displays this exception (notably `bluetti-home-assistant`'s own websocket-error Repair issue, which shows `str(err)` directly to the end user) now surfaces the code with no changes needed on its end. Prompted by a real user hitting an unrecognized code with no way to report which one it was short of digging through a raw STOMP frame dump (bluetti-community/bluetti-home-assistant#35). `.message` is unchanged - still the plain, code-free text.

{pybluetti-0.2.2 → pybluetti-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pybluetti
-Version: 0.2.2
+Version: 0.2.3
 Summary: Async Python client for the BLUETTI cloud API - device discovery, state, and control.
 Project-URL: Homepage, https://github.com/bluetti-community/pybluetti
 Project-URL: Used by, https://github.com/bluetti-community/bluetti-home-assistant

{pybluetti-0.2.2 → pybluetti-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pybluetti"
-version = "0.2.2"
+version = "0.2.3"
 description = "Async Python client for the BLUETTI cloud API - device discovery, state, and control."
 readme = "README.md"
 license = "MIT"

{pybluetti-0.2.2 → pybluetti-0.2.3}/src/pybluetti/websocket.py

@@ -19,6 +19,22 @@ from .exceptions import ApplicationRuntimeException
 
 __LOGGER__ = logging.getLogger(__name__)
 
+# ERROR frame msgCodes that mean this connection can never succeed as-is -
+# retrying it is pointless, not just unlikely. 600 ("Upgrade required, and
+# then reconfigure the BLUETTI integration") is directly confirmed against
+# a real device: retried every ~30s for over a day with the identical
+# rejection every time (bluetti-community/bluetti-home-assistant#35). 400
+# and 403 aren't yet directly observed here, but BLUETTI's own official
+# client (bluetti-official/bluetti-home-assistant's api/websocket.py)
+# groups all three with 805 (a genuinely expired token) as needing the same
+# response - stop and don't retry. They're kept out of on_auth_expired's
+# 805 path below deliberately: unlike 805, none of these three necessarily
+# mean the access token itself is the problem (600's own real cause is
+# still unconfirmed - see the issue above), so claiming that would be
+# actively misleading. They still reach a caller via on_error, same as any
+# other non-805 code - this only stops the pointless retry loop.
+_TERMINAL_ERROR_CODES = frozenset({400, 403, 600})
+
 
 class StompClient:
     """A STOMP client connected to the BLUETTI cloud's push-update websocket."""
@@ -43,11 +59,15 @@ class StompClient:
         - on_auth_expired: called when the cloud reports the access token as
           expired (msgCode 805), so the caller can react.
         - on_error: called with any other ERROR frame the cloud sends back
-          (a msgCode other than 805). The client still retries with backoff
-          regardless - some of these are transient - but nothing else
-          surfaces a persistent one distinctly from a run-of-the-mill
-          connection drop, so a caller that wants to react (log once, show
-          the user something actionable) has no other hook for it.
+          (a msgCode other than 805). The client keeps retrying with
+          backoff for most of these - some are transient - except a known
+          set (see _TERMINAL_ERROR_CODES) it stops retrying for, since
+          those are confirmed (or, per BLUETTI's own official client,
+          strongly implied) to never succeed on retry either. Either way,
+          nothing else surfaces a persistent one distinctly from a
+          run-of-the-mill connection drop, so a caller that wants to react
+          (log once, show the user something actionable) has no other hook
+          for it.
         """
         self._session = session
         self.__url = url + "/websocket"
@@ -259,6 +279,18 @@ class StompClient:
                 self.on_auth_expired()
             __LOGGER__.info("token have expired stop ws connect")
         else:
+            if error["msgCode"] in _TERMINAL_ERROR_CODES:
+                # Same "stop, don't retry" outcome as 805 above, reached
+                # the same way _run() already stops retrying on any other
+                # exit from its receive loop: setting running False here,
+                # before raising, means the "if self.running: reconnect()"
+                # check it does afterwards is already False by the time it
+                # runs. Deliberately not the 805 branch above - on_error
+                # (below, via the raise) still fires with the real message,
+                # instead of on_auth_expired's specifically-token-expired
+                # framing, which wouldn't be accurate here (see
+                # _TERMINAL_ERROR_CODES's own comment).
+                self.running = False
             raise ApplicationRuntimeException(msgCode=error["msgCode"], errMessage=error["message"])
 
     async def _handle_connected_frame(self, frame: stomper.Frame) -> None:

{pybluetti-0.2.2 → pybluetti-0.2.3}/tests/test_websocket.py

@@ -351,6 +351,24 @@ async def test_run_catches_application_runtime_exception_logs_full_and_calls_on_
     client.reconnect.assert_awaited_once()
 
 
+async def test_run_does_not_reconnect_after_a_terminal_error_code():
+    ws = _FakeWebSocket([_error_message(600, "Upgrade required")])
+    on_error = MagicMock()
+    session = _FakeSession(ws)
+    client = StompClient(session, GATEWAY_WS_URL, "token", on_error=on_error)
+    client._ws = ws
+    client.running = True
+    client.reconnect = AsyncMock()
+
+    await client._run()
+
+    on_error.assert_called_once()
+    assert on_error.call_args[0][0].msgCode == 600
+    assert ws.close_called is True
+    client.reconnect.assert_not_awaited()
+    assert client.running is False
+
+
 async def test_run_downgrades_repeated_identical_application_runtime_exception():
     ws = _FakeWebSocket([_error_message(500, "server error")])
     session = _FakeSession(ws)
@@ -442,6 +460,41 @@ async def test_handle_frame_error_other_code_raises():
     assert exc_info.value.msgCode == 500
 
 
+async def test_handle_frame_error_other_code_does_not_stop_retrying():
+    # A non-terminal, non-805 code (500) must not be mistaken for one of
+    # the codes known to never succeed on retry - client.running is left
+    # exactly as it was (True: a real, live connection still exists).
+    client, _session, _on_auth_expired = _client()
+    client.running = True
+    payload = json.dumps({"msgCode": 500, "message": "server error"}).replace(":", "\\c")
+    raw = f"ERROR\nmessage:{payload}\n\n\x00"
+
+    with pytest.raises(ApplicationRuntimeException):
+        await client._handle_frame(raw)
+
+    assert client.running is True
+
+
+@pytest.mark.parametrize("msg_code", [400, 403, 600])
+async def test_handle_frame_error_terminal_code_stops_retrying_but_still_raises(msg_code):
+    # 400/403/600: confirmed (600) or strongly implied (400, 403 - see
+    # _TERMINAL_ERROR_CODES's own comment) to never succeed on retry.
+    # Unlike 805, these still raise (on_error fires with the real message)
+    # rather than calling on_auth_expired - none of the three necessarily
+    # mean the token itself is the problem.
+    client, _session, on_auth_expired = _client()
+    client.running = True
+    payload = json.dumps({"msgCode": msg_code, "message": "terminal"}).replace(":", "\\c")
+    raw = f"ERROR\nmessage:{payload}\n\n\x00"
+
+    with pytest.raises(ApplicationRuntimeException) as exc_info:
+        await client._handle_frame(raw)
+
+    assert exc_info.value.msgCode == msg_code
+    assert client.running is False
+    on_auth_expired.assert_not_called()
+
+
 async def test_handle_frame_connected_without_websocket_logs_and_returns():
     client, _session, _on_auth_expired = _client()
     raw = "CONNECTED\nheart-beat:10000,10000\nuser-name:bob\n\n\x00"