pybluetti 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -1,3 +1,11 @@
+# 0.2.4
+
+- `StompClient` accepts optional `app_key`/`app_ver` keyword arguments, sent as `x-app-key`/`x-app-ver` CONNECT headers (alongside a fixed `x-os:open`) - BLUETTI's cloud gateway does client identification/version gating on this connection (see 0.2.3's own `msgCode 600` fix), and BLUETTI's own official Home Assistant integration's client already sends exactly these three headers on every connection. Optional and independent of everything else here - a caller with nothing to identify itself with still gets exactly the previous behavior, not headers claiming an identity it doesn't have. Raises `ValueError` if only one of the two is given.
+
+# 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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pybluetti
-Version: 0.2.2
+Version: 0.2.4
 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.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pybluetti"
-version = "0.2.2"
+version = "0.2.4"
 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.4}/src/pybluetti/websocket.py

@@ -19,11 +19,27 @@ 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."""
 
-    def __init__(  # noqa: PLR0913 -- three optional, independently-set callbacks, all keyword-only; bundling them into one object would just move the same information one level down without simplifying a caller that only wants one of them
+    def __init__(  # noqa: PLR0913 -- five optional, independently-set values, all keyword-only; bundling them into one object would just move the same information one level down without simplifying a caller that only wants some of them
         self,
         session: aiohttp.ClientSession,
         url: str,
@@ -32,6 +48,8 @@ class StompClient:
         handler: Callable[[str], None] | None = None,
         on_auth_expired: Callable[[], None] | None = None,
         on_error: Callable[[ApplicationRuntimeException], None] | None = None,
+        app_key: str | None = None,
+        app_ver: str | None = None,
     ) -> None:
         """
         Initialize the client.
@@ -43,18 +61,36 @@ 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.
+        - app_key, app_ver: client-identification headers the CONNECT frame
+          sends as x-app-key/x-app-ver, alongside a fixed x-os:open (see
+          _client_identification_headers' own docstring for why this
+          exists at all). Optional and independent of everything else here
+          - a caller with nothing to identify itself with still gets a
+          connection attempt with exactly today's headers, not a forced
+          value it doesn't have. Raises ValueError if only one is given -
+          the cloud is only known to accept both together or neither.
         """
+        if (app_key is None) != (app_ver is None):
+            msg = "app_key and app_ver must be given together"
+            raise ValueError(msg)
+
         self._session = session
         self.__url = url + "/websocket"
         self.__headers = {
             "Host": self.__get_host(url),
             "Authorization": access_token,
         }
+        self._app_key = app_key
+        self._app_ver = app_ver
         self.__handler = handler
         self.on_auth_expired = on_auth_expired
         self.on_error = on_error
@@ -95,6 +131,30 @@ class StompClient:
             host = host.split(":")[0]
         return host
 
+    def _client_identification_headers(self) -> str:
+        """
+        Return the x-os/x-app-key/x-app-ver CONNECT header lines, or "".
+
+        The cloud's websocket gateway does client identification/version
+        gating - confirmed by a real, persistent rejection (msgCode 600,
+        "Upgrade required, and then reconfigure the BLUETTI integration")
+        that never once succeeded on retry against a real device (bluetti-
+        community/bluetti-home-assistant#35). BLUETTI's own official
+        client (bluetti-official/bluetti-home-assistant's api/websocket.py)
+        sends exactly these three headers on every CONNECT frame, which
+        this client never did.
+
+        x-os is always "open" - not something a caller configures, since
+        BLUETTI's own official client hardcodes the identical value
+        regardless of the platform the integration itself runs on.
+        x-app-key/x-app-ver are per-caller (see __init__'s own docstring):
+        a real client-identification value belongs to whichever
+        integration was actually issued one, not to this library itself.
+        """
+        if self._app_key is None or self._app_ver is None:
+            return ""
+        return f"x-os:open\nx-app-key:{self._app_key}\nx-app-ver:{self._app_ver}\n"
+
     async def connect(self) -> None:
         """Connect to the ws server and start the background receive/heartbeat tasks."""
         __LOGGER__.info("Start to connect the BLUETTI WebSocket Server.")
@@ -119,7 +179,8 @@ class StompClient:
                 "Host:" + self.__headers["Host"] + "\n"
                 "Authorization: " + self.__headers["Authorization"] + "\n"
                 "heart-beat:10000,10000\n"
-                "\n\x00\n"
+                + self._client_identification_headers()
+                + "\n\x00\n"
             )
             await self._ws.send_str(connect_frame)
         except Exception:
@@ -259,6 +320,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.4}/tests/test_websocket.py

@@ -84,6 +84,20 @@ def test_get_host_strips_port_and_path(url, expected):
     assert StompClient._StompClient__get_host(url) == expected
 
 
+# --- StompClient.__init__'s app_key/app_ver validation -----------------------
+
+def test_init_raises_if_only_app_key_given():
+    session = _FakeSession(None)
+    with pytest.raises(ValueError, match="app_key and app_ver must be given together"):
+        StompClient(session, GATEWAY_WS_URL, "token", app_key="key")
+
+
+def test_init_raises_if_only_app_ver_given():
+    session = _FakeSession(None)
+    with pytest.raises(ValueError, match="app_key and app_ver must be given together"):
+        StompClient(session, GATEWAY_WS_URL, "token", app_ver="1.3.0")
+
+
 # --- StompClient.connect ------------------------------------------------------
 
 async def test_connect_opens_socket_sends_connect_frame_and_starts_tasks():
@@ -100,6 +114,32 @@ async def test_connect_opens_socket_sends_connect_frame_and_starts_tasks():
     assert client._heartbeat_task is not None
 
 
+async def test_connect_omits_client_identification_headers_by_default():
+    ws = _FakeWebSocket()
+    client, _session, _on_auth_expired = _client(ws)
+
+    await client.connect()
+
+    assert "x-app-key" not in ws.sent[0]
+    assert "x-app-ver" not in ws.sent[0]
+    assert "x-os" not in ws.sent[0]
+
+
+async def test_connect_sends_client_identification_headers_when_given():
+    ws = _FakeWebSocket()
+    session = _FakeSession(ws)
+    client = StompClient(
+        session, GATEWAY_WS_URL, "token", app_key="the-key", app_ver="1.3.0"
+    )
+    client._ws = ws
+
+    await client.connect()
+
+    assert "x-os:open" in ws.sent[0]
+    assert "x-app-key:the-key" in ws.sent[0]
+    assert "x-app-ver:1.3.0" in ws.sent[0]
+
+
 async def test_connect_cancels_a_stale_heartbeat_task_from_a_previous_connection():
     ws = _FakeWebSocket()
     client, _session, _on_auth_expired = _client(ws)
@@ -351,6 +391,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 +500,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"