pybluetti 0.2.4__tar.gz → 0.2.6__tar.gz

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

@@ -1,3 +1,14 @@
+# 0.2.6
+
+- Fixed `StompClient.connect()` never returning while the cloud is unreachable: a failed attempt awaited `reconnect()`, which slept and called `connect()` again, so every retry nested inside the caller's own await instead of running behind it. A caller that connects during its start-up - `bluetti-home-assistant` awaits this inside `async_setup_entry` - then stayed in start-up for the whole outage: the config entry sat on "initialising" for three hours, with no reload offered in its menu and nothing but a Home Assistant restart to clear it (bluetti-community/bluetti-home-assistant#65). `connect()` now makes a single attempt and schedules the retry loop in the background, and `reconnect()` loops instead of recursing, so the stack no longer grows by a frame per attempt either.
+- Fixed a socket leak on the failing side of that loop: `ws_connect()` can succeed and the CONNECT frame still fail, which left that socket open with nothing left to close it - one per failed attempt, until the session's connection pool had no free slot and every new connection waited for one and timed out instead. That is the `_wait_for_available_connection` timeout in the same report, and the reason each retry took five minutes rather than the thirty seconds its backoff asked for. Every attempt now closes whatever the previous one left behind, on both paths.
+- `reconnect_delay` is reset once a connection succeeds, so the backoff is per outage rather than cumulative: without it, every later reconnect started at whatever delay the last outage had grown it to, up to `max_reconnect_delay`.
+- `disconnect()` now cancels a pending reconnect task as well as the receive and heartbeat ones.
+
+# 0.2.5
+
+- Added `HttpStatusException` (an `ApplicationRuntimeException`), raised by `_request()` when the gateway answers with a non-2xx HTTP status instead of the plain base class: `status` and `reason` carry the HTTP status and reason phrase (`str(exc)` is e.g. `[504] HTTP 504 Gateway Timeout` instead of `[504] An unknown error has occurred.`), `data` the response body, and `is_transient` says whether one immediate retry is worth a try (502/503/504). `msgCode` is still the HTTP status, so every existing caller keeps working; a caller can now tell a gateway 504 from an API `msgCode` that happens to be 504. Prompted by bluetti-community/bluetti-home-assistant#53, a lone 504 on one poll of thirty failing the whole poll.
+
 # 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.

{pybluetti-0.2.4 → pybluetti-0.2.6}/PKG-INFO

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

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

{pybluetti-0.2.4 → pybluetti-0.2.6}/src/pybluetti/__init__.py

@@ -12,7 +12,7 @@ bluetti-home-assistant to depend on this package is a separate follow-up.
 
 from .client import Bluetti
 from .const import Method
-from .exceptions import ApplicationRuntimeException
+from .exceptions import ApplicationRuntimeException, HttpStatusException
 from .models import UserProduct
 from .product_client import ProductClient
 from .unify_response import UnifyResponse
@@ -23,6 +23,7 @@ __version__ = "0.1.1"
 __all__ = [
     "ApplicationRuntimeException",
     "Bluetti",
+    "HttpStatusException",
     "Method",
     "ProductClient",
     "StompClient",

{pybluetti-0.2.4 → pybluetti-0.2.6}/src/pybluetti/client.py

@@ -10,7 +10,7 @@ import aiohttp
 from pydantic import TypeAdapter
 
 from .const import Method
-from .exceptions import ApplicationRuntimeException
+from .exceptions import HttpStatusException
 from .unify_response import UnifyResponse
 
 
@@ -107,7 +107,9 @@ class Bluetti:
             self.logger.debug("<====== Server response type is: %s", response.content_type)
 
             if not response.ok:
-                raise ApplicationRuntimeException(msgCode=response.status, data=await response.text())
+                raise HttpStatusException(
+                    response.status, response.reason or "", data=await response.text()
+                )
 
             if response.content_type.lower().startswith("application/json"):
                 data = await response.json()  # read response body to JSON

{pybluetti-0.2.4 → pybluetti-0.2.6}/src/pybluetti/exceptions.py

@@ -33,3 +33,33 @@ class ApplicationRuntimeException(Exception):
         # a person actually looks by default). .message stays the plain,
         # code-free text for any caller that only wants that.
         super().__init__(f"[{msgCode}] {self.message}")
+
+
+class HttpStatusException(ApplicationRuntimeException):
+    """
+    Raised when the BLUETTI gateway answers with a non-2xx HTTP status.
+
+    The API's own failures come back as HTTP 200 with a non-zero ``msgCode``
+    in the body; this one is the layer below that - the gateway itself
+    (502/503/504 from a proxy, 401 from the edge) - and ``msgCode`` is the
+    HTTP status code, which is what every caller matched on before this
+    class existed (still an ApplicationRuntimeException, so nothing
+    changes for them). ``status`` says the same thing under its real name,
+    ``reason`` is the HTTP reason phrase, ``data`` the response body. A
+    caller that wants to retry a transient gateway error - a lone 504 on
+    one poll of thirty (bluetti-community/bluetti-home-assistant#53) - can
+    now tell it apart from an API ``msgCode`` that happens to be 504.
+    """
+
+    status: int
+    reason: str
+
+    def __init__(self, status: int, reason: str, data: dict[str, Any] | str | None = None) -> None:
+        self.status = status
+        self.reason = reason
+        super().__init__(msgCode=status, data=data, errMessage=f"HTTP {status} {reason}".rstrip())
+
+    @property
+    def is_transient(self) -> bool:
+        """Whether one immediate retry is worth a try (a proxy/gateway hiccup)."""
+        return self.status in (502, 503, 504)

{pybluetti-0.2.4 → pybluetti-0.2.6}/src/pybluetti/websocket.py

@@ -99,6 +99,7 @@ class StompClient:
 
         self._receive_task: asyncio.Task[None] | None = None
         self._heartbeat_task: asyncio.Task[None] | None = None
+        self._reconnect_task: asyncio.Task[None] | None = None
         self.heartbeat_interval = 10
         # The most recent ApplicationRuntimeException message _run() logged
         # at full severity, cleared once a CONNECTED frame proves the
@@ -156,10 +157,25 @@ class StompClient:
         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."""
+        """
+        Connect to the ws server and start the background receive/heartbeat tasks.
+
+        Returns once a single attempt has been made: a failure schedules the
+        retry in the background instead of awaiting it here. Callers connect
+        during their own start-up - Home Assistant awaits this inside
+        async_setup_entry - and a retry loop that only returns on success
+        leaves that start-up hanging for as long as the cloud is unreachable,
+        with the entry stuck "initialising", no reload offered, and nothing
+        but a restart to clear it (bluetti-community/bluetti-home-assistant#65).
+        """
         __LOGGER__.info("Start to connect the BLUETTI WebSocket Server.")
         self.running = True
+        if await self._connect_once():
+            return
+        self._schedule_reconnect()
 
+    async def _connect_once(self) -> bool:
+        """One connection attempt; True when the socket and its tasks are up."""
         # A reconnect (whether from a dropped connection or a rejected one)
         # leaves the previous heartbeat task still scheduled on the old,
         # now-stale websocket - only the msgCode-805 path cancels it before
@@ -169,6 +185,7 @@ class StompClient:
         # whatever actually triggered this reconnect.
         if self._heartbeat_task is not None:
             self._heartbeat_task.cancel()
+        await self._close_socket()
 
         try:
             self._ws = await self._session.ws_connect(self.__url, headers=self.__headers)
@@ -187,18 +204,50 @@ class StompClient:
             # Same resilience as a run-time disconnect: log and retry with
             # backoff rather than letting a connection failure go silent.
             __LOGGER__.exception("Failed to connect to the BLUETTI WebSocket Server")
-            await self.reconnect()
-            return
+            # ws_connect can succeed and the CONNECT frame still fail, which
+            # leaves that socket open with nothing left to close it. One per
+            # failed attempt fills the session's connection pool, until every
+            # new connection waits for a free slot and times out - which is
+            # what a failing reconnect loop eventually does to the rest of the
+            # integration (bluetti-community/bluetti-home-assistant#65).
+            await self._close_socket()
+            return False
 
         __LOGGER__.info("Connect the BLUETTI WebSocket Server successfully.")
 
+        # The backoff is per outage, not cumulative: without this, every later
+        # reconnect starts at whatever delay the last outage grew it to.
+        self.reconnect_delay = 1
         self._receive_task = asyncio.ensure_future(self._run())
         self._heartbeat_task = asyncio.ensure_future(self._heartbeat_loop())
+        return True
+
+    async def _close_socket(self) -> None:
+        """Close and forget the current socket, if there is one left open."""
+        ws, self._ws = self._ws, None
+        if ws is None or ws.closed:
+            return
+        try:
+            await ws.close()
+        except Exception:
+            __LOGGER__.debug("Error while closing a stale websocket", exc_info=True)
+
+    def _schedule_reconnect(self) -> None:
+        """Run the retry loop in the background, unless one is already running."""
+        if not self.running:
+            return
+        if self._reconnect_task is not None and not self._reconnect_task.done():
+            return
+        self._reconnect_task = asyncio.ensure_future(self.reconnect())
 
     async def disconnect(self) -> None:
         """Stop reconnecting, cancel background tasks, and close the connection."""
         self.running = False
-        tasks = [t for t in (self._receive_task, self._heartbeat_task) if t is not None]
+        tasks = [
+            t
+            for t in (self._receive_task, self._heartbeat_task, self._reconnect_task)
+            if t is not None
+        ]
         for task in tasks:
             task.cancel()
         if tasks:
@@ -207,14 +256,25 @@ class StompClient:
             await self._ws.close()
 
     async def reconnect(self) -> None:
-        """Reconnect with exponential backoff, if still running."""
-        __LOGGER__.info("Websocket reconnect")
-        if self.running:
+        """
+        Retry with exponential backoff until connected, or until stopped.
+
+        A loop rather than a call back into connect(): each retry used to nest
+        inside the previous one's await, so the first caller's await never
+        returned while the cloud stayed unreachable, and the stack grew by a
+        frame per attempt (bluetti-community/bluetti-home-assistant#65).
+        """
+        if not self.running:
+            __LOGGER__.info("Websocket have stop do not reconnect")
+            return
+        while self.running:
+            __LOGGER__.info("Websocket reconnect")
             await asyncio.sleep(self.reconnect_delay)
             self.reconnect_delay = min(self.reconnect_delay * 2, self.max_reconnect_delay)
-            await self.connect()
-        else:
-            __LOGGER__.info("Websocket have stop do not reconnect")
+            if not self.running:
+                return
+            if await self._connect_once():
+                return
 
     async def _heartbeat_loop(self) -> None:
         r"""Send a STOMP heartbeat ("\n") on the configured interval."""

pybluetti-0.2.6/tests/test_exceptions.py

@@ -0,0 +1,58 @@
+"""Tests for exceptions.py."""
+
+from pybluetti.exceptions import ApplicationRuntimeException, HttpStatusException
+
+
+def test_str_includes_msg_code_and_custom_message() -> None:
+    # The msgCode must be visible in str(exc) itself, not just the .msgCode
+    # attribute - see this file's own docstring in exceptions.py for why
+    # (bluetti-community/bluetti-home-assistant#35: a real user had no way
+    # to report which error code they got, since nothing that logs or
+    # displays this exception showed it).
+    err = ApplicationRuntimeException(msgCode=1234, errMessage="Upgrade required.")
+
+    assert str(err) == "[1234] Upgrade required."
+    assert err.message == "Upgrade required."
+    assert err.msgCode == 1234
+
+
+def test_str_includes_msg_code_with_default_message() -> None:
+    err = ApplicationRuntimeException(msgCode=500)
+
+    assert str(err) == "[500] An unknown error has occurred."
+
+
+def test_data_is_stored_unchanged() -> None:
+    err = ApplicationRuntimeException(msgCode=401, data="unauthorized")
+
+    assert err.data == "unauthorized"
+
+
+def test_http_status_exception_is_an_application_runtime_exception() -> None:
+    # Every caller that matched on ApplicationRuntimeException / msgCode
+    # before this class existed keeps working unchanged.
+    err = HttpStatusException(504, "Gateway Timeout", data="<html>...</html>")
+
+    assert isinstance(err, ApplicationRuntimeException)
+    assert err.msgCode == 504
+    assert err.status == 504
+    assert err.reason == "Gateway Timeout"
+    assert err.data == "<html>...</html>"
+    assert str(err) == "[504] HTTP 504 Gateway Timeout"
+
+
+def test_http_status_exception_without_a_reason_phrase() -> None:
+    err = HttpStatusException(502, "")
+
+    assert str(err) == "[502] HTTP 502"
+
+
+def test_transient_gateway_statuses() -> None:
+    # A lone 502/503/504 on one poll of thirty is a proxy hiccup worth one
+    # immediate retry (bluetti-community/bluetti-home-assistant#53); a
+    # 401 or 404 is not.
+    assert HttpStatusException(502, "Bad Gateway").is_transient
+    assert HttpStatusException(503, "Service Unavailable").is_transient
+    assert HttpStatusException(504, "Gateway Timeout").is_transient
+    assert not HttpStatusException(401, "Unauthorized").is_transient
+    assert not HttpStatusException(404, "Not Found").is_transient

{pybluetti-0.2.4 → pybluetti-0.2.6}/tests/test_product_client.py

@@ -4,7 +4,7 @@ from unittest.mock import MagicMock
 
 import pytest
 
-from pybluetti.exceptions import ApplicationRuntimeException
+from pybluetti.exceptions import ApplicationRuntimeException, HttpStatusException
 from pybluetti.product_client import ProductClient
 
 GATEWAY_URL = "https://gw.bluettipower.com"
@@ -13,6 +13,7 @@ GATEWAY_URL = "https://gw.bluettipower.com"
 class _FakeResponse:
     def __init__(self, status=200, content_type="application/json", json_data=None, text_data=""):
         self.status = status
+        self.reason = {200: "OK", 401: "Unauthorized", 504: "Gateway Timeout"}.get(status)
         self.ok = 200 <= status < 400
         self.content_type = content_type
         self.url = "https://gw.bluettipower.com/fake"
@@ -132,6 +133,22 @@ async def test_request_raises_on_non_ok_status():
     assert exc_info.value.data == "unauthorized"
 
 
+async def test_request_raises_http_status_exception_with_status_and_reason():
+    # A gateway timeout is the HTTP layer, not the API: the exception says
+    # so, and says it is transient (bluetti-community/bluetti-home-assistant#53).
+    response = _FakeResponse(status=504, text_data="An unknown error has occurred.")
+    session = _FakeSession(response)
+    client, _on_auth_expired = _client(session)
+
+    with pytest.raises(HttpStatusException) as exc_info:
+        await client.get_user_products()
+
+    assert exc_info.value.status == 504
+    assert exc_info.value.reason == "Gateway Timeout"
+    assert exc_info.value.is_transient
+    assert str(exc_info.value) == "[504] HTTP 504 Gateway Timeout"
+
+
 async def test_request_returns_raw_text_for_non_json_response():
     response = _FakeResponse(content_type="text/plain", text_data="plain response")
     session = _FakeSession(response)

{pybluetti-0.2.4 → pybluetti-0.2.6}/tests/test_websocket.py

@@ -168,7 +168,11 @@ async def test_update_access_token_affects_the_next_connect():
     await client.disconnect()  # tidy up the background tasks started above
 
 
-async def test_connect_failure_triggers_reconnect():
+async def test_connect_failure_schedules_a_reconnect_and_returns():
+    # Regression test: connect() used to await the retry loop, so a caller
+    # connecting during its own start-up - Home Assistant inside
+    # async_setup_entry - hung there for as long as the cloud was unreachable
+    # (bluetti-community/bluetti-home-assistant#65). It must return.
     class _FailingSession:
         async def ws_connect(self, url, **kwargs):
             msg = "boom"
@@ -179,9 +183,82 @@ async def test_connect_failure_triggers_reconnect():
 
     await client.connect()
 
+    assert client._reconnect_task is not None
+    await client._reconnect_task
     client.reconnect.assert_awaited_once()
 
 
+async def test_connect_closes_a_socket_whose_connect_frame_failed():
+    # The leak behind the timeouts in #65: ws_connect can succeed and the
+    # CONNECT frame still fail, leaving that socket open with nothing left to
+    # close it - one per failed attempt, until the pool has no free slot.
+    ws = _FakeWebSocket()
+
+    async def _failing_send(_data):
+        msg = "boom"
+        raise aiohttp.ClientConnectionError(msg)
+
+    ws.send_str = _failing_send
+    client, _session, _on_auth_expired = _client(ws)
+    client.reconnect = AsyncMock()
+
+    await client.connect()
+
+    assert ws.close_called is True
+    assert client._ws is None
+
+
+async def test_connect_resets_the_backoff_so_it_is_per_outage():
+    ws = _FakeWebSocket()
+    client, _session, _on_auth_expired = _client(ws)
+    client.reconnect_delay = 30
+
+    await client.connect()
+
+    assert client.reconnect_delay == 1
+
+    await client.disconnect()  # tidy up the background tasks started above
+
+
+async def test_schedule_reconnect_does_nothing_when_stopped_or_already_running():
+    client, _session, _on_auth_expired = _client()
+    client.running = False
+    client._schedule_reconnect()
+    assert client._reconnect_task is None
+
+    client.running = True
+    running_task = MagicMock()
+    running_task.done.return_value = False
+    client._reconnect_task = running_task
+    client._schedule_reconnect()
+    assert client._reconnect_task is running_task
+
+
+async def test_close_socket_survives_a_socket_that_will_not_close():
+    ws = _FakeWebSocket()
+
+    async def _failing_close():
+        msg = "boom"
+        raise aiohttp.ClientConnectionError(msg)
+
+    ws.close = _failing_close
+    client, _session, _on_auth_expired = _client(ws)
+
+    await client._close_socket()  # must not raise
+
+    assert client._ws is None
+
+
+async def test_close_socket_leaves_an_already_closed_socket_alone():
+    ws = _FakeWebSocket()
+    ws.closed = True
+    client, _session, _on_auth_expired = _client(ws)
+
+    await client._close_socket()
+
+    assert ws.close_called is False
+
+
 # --- StompClient.disconnect ---------------------------------------------------
 
 async def test_disconnect_cancels_tasks_and_closes_socket():
@@ -208,26 +285,67 @@ async def test_reconnect_when_running_backs_off_and_reconnects():
     client.running = True
     client.reconnect_delay = 1
     client.max_reconnect_delay = 30
-    client.connect = AsyncMock()
+    client._connect_once = AsyncMock(return_value=True)
 
     with patch("pybluetti.websocket.asyncio.sleep", AsyncMock()) as mock_sleep:
         await client.reconnect()
 
     mock_sleep.assert_awaited_once_with(1)
     assert client.reconnect_delay == 2
-    client.connect.assert_awaited_once()
+    client._connect_once.assert_awaited_once()
+
+
+async def test_reconnect_keeps_trying_until_a_connection_is_made():
+    # A loop, not a recursive call back into connect(): each retry used to
+    # nest inside the previous one's await (#65).
+    client, _session, _on_auth_expired = _client()
+    client.running = True
+    client.reconnect_delay = 1
+    client.max_reconnect_delay = 4
+    client._connect_once = AsyncMock(side_effect=[False, False, True])
+
+    with patch("pybluetti.websocket.asyncio.sleep", AsyncMock()) as mock_sleep:
+        await client.reconnect()
+
+    assert client._connect_once.await_count == 3
+    assert [c.args[0] for c in mock_sleep.await_args_list] == [1, 2, 4]
+
+
+async def test_reconnect_stops_when_the_client_is_disconnected_mid_wait():
+    client, _session, _on_auth_expired = _client()
+    client.running = True
+    client._connect_once = AsyncMock(return_value=False)
+
+    async def _stop(_delay):
+        client.running = False
+
+    with patch("pybluetti.websocket.asyncio.sleep", AsyncMock(side_effect=_stop)):
+        await client.reconnect()
+
+    client._connect_once.assert_not_awaited()
 
 
 async def test_reconnect_when_stopped_does_nothing():
     client, _session, _on_auth_expired = _client()
     client.running = False
-    client.connect = AsyncMock()
+    client._connect_once = AsyncMock()
 
     with patch("pybluetti.websocket.asyncio.sleep", AsyncMock()) as mock_sleep:
         await client.reconnect()
 
     mock_sleep.assert_not_awaited()
-    client.connect.assert_not_awaited()
+    client._connect_once.assert_not_awaited()
+
+
+async def test_disconnect_cancels_a_pending_reconnect():
+    client, _session, _on_auth_expired = _client()
+    pending = MagicMock()
+    client._reconnect_task = pending
+
+    with patch("pybluetti.websocket.asyncio.gather", AsyncMock()):
+        await client.disconnect()
+
+    pending.cancel.assert_called_once()
 
 
 # --- StompClient._heartbeat_loop ----------------------------------------------

pybluetti-0.2.4/tests/test_exceptions.py

@@ -1,28 +0,0 @@
-"""Tests for exceptions.py."""
-
-from pybluetti.exceptions import ApplicationRuntimeException
-
-
-def test_str_includes_msg_code_and_custom_message() -> None:
-    # The msgCode must be visible in str(exc) itself, not just the .msgCode
-    # attribute - see this file's own docstring in exceptions.py for why
-    # (bluetti-community/bluetti-home-assistant#35: a real user had no way
-    # to report which error code they got, since nothing that logs or
-    # displays this exception showed it).
-    err = ApplicationRuntimeException(msgCode=1234, errMessage="Upgrade required.")
-
-    assert str(err) == "[1234] Upgrade required."
-    assert err.message == "Upgrade required."
-    assert err.msgCode == 1234
-
-
-def test_str_includes_msg_code_with_default_message() -> None:
-    err = ApplicationRuntimeException(msgCode=500)
-
-    assert str(err) == "[500] An unknown error has occurred."
-
-
-def test_data_is_stored_unchanged() -> None:
-    err = ApplicationRuntimeException(msgCode=401, data="unauthorized")
-
-    assert err.data == "unauthorized"