place-integration-api 0.2.6__tar.gz → 0.2.8__tar.gz

{place_integration_api-0.2.6/src/place_integration_api.egg-info → place_integration_api-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: place-integration-api
-Version: 0.2.6
+Version: 0.2.8
 Summary: Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place.
 Author-email: Nicholas Aelick <niaexa@syntronic.com>, Andrew Tran <andrew.tran@gentex.com>
 Project-URL: Homepage, https://placehomesolutions.com
@@ -28,6 +28,14 @@ Dynamic: license-file
 
 This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration
 
+## Requesting a device shadow
+
+Call `PlaceMessages.subscribe_shadow_and_get(thing_name)` from the MQTT client's
+`on_connect` callback. It subscribes to the device's shadow topics and sends the
+shadow GET only after the broker acknowledges the subscription. The `on_connect`
+callback is also invoked on reconnect, so it should subscribe every device again.
+Rejected subscriptions are logged and do not send a GET.
+
 ## Setup
 
 This repo utilizes VS Code [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) so you don't need to alter your global python environment.

{place_integration_api-0.2.6 → place_integration_api-0.2.8}/README.md

@@ -2,6 +2,14 @@
 
 This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration
 
+## Requesting a device shadow
+
+Call `PlaceMessages.subscribe_shadow_and_get(thing_name)` from the MQTT client's
+`on_connect` callback. It subscribes to the device's shadow topics and sends the
+shadow GET only after the broker acknowledges the subscription. The `on_connect`
+callback is also invoked on reconnect, so it should subscribe every device again.
+Rejected subscriptions are logged and do not send a GET.
+
 ## Setup
 
 This repo utilizes VS Code [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) so you don't need to alter your global python environment.

{place_integration_api-0.2.6 → place_integration_api-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "place-integration-api"
-version = "0.2.6"
+version = "0.2.8"
 description = "Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place."
 readme = "README.md"
 requires-python = ">=3.11"

place_integration_api-0.2.8/src/place/errors.py

@@ -0,0 +1,17 @@
+"""Errors for the Place API."""
+
+
+class PlaceApiError(Exception):
+    """Base error for Place API failures."""
+
+
+class PlaceFulfillmentError(PlaceApiError):
+    """Raised when the fulfillment API reports a business-logic failure."""
+
+
+class PlaceMqttConnectionError(PlaceApiError):
+    """Raised when the MQTT broker rejects or fails to establish a connection."""
+
+
+class PlaceMqttSubscriptionError(PlaceApiError):
+    """Raised when an MQTT subscription cannot be sent."""

{place_integration_api-0.2.6 → place_integration_api-0.2.8}/src/place/messages.py

@@ -73,6 +73,18 @@ class PlaceMessages:
         self._client.subscribe(topic, qos=qos)
         return name
 
+    def subscribe_shadow_and_get(self, thing_name: str, qos: int = 1) -> str:
+        """Subscribe to a shadow and request its state after a successful SUBACK."""
+        name = thing_name.strip()
+        assert name
+        topic = shadow_subscription_topic(name)
+        self._client.subscribe(
+            topic,
+            qos=qos,
+            on_subscribe=lambda: self.publish_shadow_get(name, qos=qos),
+        )
+        return name
+
     def publish_shadow_get(self, thing_name: str, qos: int = 1) -> str:
         name = thing_name.strip()
         assert name

{place_integration_api-0.2.6 → place_integration_api-0.2.8}/src/place/mqtt_client.py

@@ -2,16 +2,22 @@ from __future__ import annotations
 
 import hashlib
 import hmac
+import logging
+import threading
 import uuid
 from datetime import datetime, timezone
 from typing import Callable
 from urllib.parse import quote
 
 import paho.mqtt.client as mqtt
+from paho.mqtt.reasoncodes import ReasonCode
 
 from .config import ALGORITHM, EXPIRE_SEC, KEEP_ALIVE_SEC, PATH, REGION, SCHEME, SERVICE
+from .errors import PlaceMqttConnectionError, PlaceMqttSubscriptionError
 from .models import Credentials
 
+_LOGGER = logging.getLogger(__name__)
+
 
 def _hmac_sha256(key: bytes, msg: str) -> bytes:
     return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
@@ -92,12 +98,19 @@ class MqttClient:
         self.endpoint = endpoint
         self.credentials = credentials
         self._client: mqtt.Client | None = None
+        self._connected_event = threading.Event()
+        self._connect_error: ReasonCode | None = None
+        self._subscription_lock = threading.RLock()
+        self._pending_subscriptions: dict[int, tuple[str, Callable[[], None]]] = {}
 
     def connect(
         self,
         on_message: Callable[[str, bytes], None] | None = None,
         on_connect: Callable[[], None] | None = None,
     ) -> None:
+        self._connected_event.clear()
+        self._connect_error = None
+
         signed_uri = get_signed_uri(
             access_key_id=self.credentials.access_key_id,
             secret_access_key=self.credentials.secret_access_key,
@@ -117,10 +130,16 @@ class MqttClient:
         client.tls_set()
 
         def _on_connect(_client, _userdata, _flags, reason_code, _properties):
+            with self._subscription_lock:
+                self._pending_subscriptions.clear()
             if reason_code.is_failure:
                 print(f"Connect failed: {reason_code}")
+                self._connect_error = reason_code
+                self._connected_event.set()
                 return
             print("Connected")
+            self._connect_error = None
+            self._connected_event.set()
             if on_connect:
                 try:
                     on_connect()
@@ -131,17 +150,38 @@ class MqttClient:
             if on_message:
                 on_message(msg.topic, msg.payload)
 
+        def _on_subscribe(_client, _userdata, mid, reason_codes, _properties):
+            with self._subscription_lock:
+                pending = self._pending_subscriptions.pop(mid, None)
+            if pending is None:
+                return
+            topic, callback = pending
+            if not reason_codes or any(code.is_failure for code in reason_codes):
+                _LOGGER.error(
+                    "MQTT subscription to %s was rejected: %s", topic, reason_codes
+                )
+                return
+            try:
+                callback()
+            except Exception:
+                _LOGGER.exception("MQTT subscription callback failed for %s", topic)
+
         def _on_disconnect(_client, _userdata, _flags, reason_code, _properties):
+            with self._subscription_lock:
+                self._pending_subscriptions.clear()
             print(f"Disconnected: {reason_code}")
 
         client.on_connect = _on_connect
         client.on_message = _on_message
+        client.on_subscribe = _on_subscribe
         client.on_disconnect = _on_disconnect
         client.enable_logger()
         client.connect(self.endpoint, 443, KEEP_ALIVE_SEC)
         self._client = client
 
     def disconnect(self) -> None:
+        with self._subscription_lock:
+            self._pending_subscriptions.clear()
         if self._client:
             self._client.disconnect()
 
@@ -149,9 +189,41 @@ class MqttClient:
         if self._client:
             self._client.loop_stop()
 
-    def subscribe(self, topic: str, qos: int = 1) -> None:
+    def wait_for_connection(self, timeout: float = 10.0) -> None:
+        """Block until the initial CONNACK is received.
+
+        Raises PlaceMqttConnectionError if the broker rejects the connection
+        or none arrives within timeout, tearing down the client in that case.
+        """
+        if not self._connected_event.wait(timeout):
+            self.disconnect()
+            self.loop_stop()
+            raise PlaceMqttConnectionError("Timed out waiting for MQTT CONNACK")
+        if self._connect_error is not None:
+            self.disconnect()
+            self.loop_stop()
+            raise PlaceMqttConnectionError(
+                f"MQTT connection rejected: {self._connect_error}"
+            )
+
+    def subscribe(
+        self, topic: str, qos: int = 1, *, on_subscribe: Callable[[], None] | None = None
+    ) -> None:
+        """Subscribe to a topic and optionally call back after a successful SUBACK.
+
+        The callback runs on the MQTT network thread. Pending callbacks are
+        discarded on disconnect, so resubscribe from on_connect after a reconnect.
+        """
         assert self._client is not None
-        self._client.subscribe(topic, qos=qos)
+        # Keep the network thread from handling SUBACK before the MID (message identifier) is recorded.
+        with self._subscription_lock:
+            result, mid = self._client.subscribe(topic, qos=qos)
+            if result != mqtt.MQTT_ERR_SUCCESS:
+                raise PlaceMqttSubscriptionError(
+                    f"Could not subscribe to {topic}: {mqtt.error_string(result)}"
+                )
+            if on_subscribe is not None:
+                self._pending_subscriptions[mid] = (topic, on_subscribe)
 
     def publish(self, topic: str, payload: str | bytes = b"", qos: int = 1) -> None:
         assert self._client is not None
@@ -165,4 +237,3 @@ class MqttClient:
     def loop_forever(self) -> None:
         assert self._client is not None
         self._client.loop_forever()
-

{place_integration_api-0.2.6 → place_integration_api-0.2.8/src/place_integration_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: place-integration-api
-Version: 0.2.6
+Version: 0.2.8
 Summary: Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place.
 Author-email: Nicholas Aelick <niaexa@syntronic.com>, Andrew Tran <andrew.tran@gentex.com>
 Project-URL: Homepage, https://placehomesolutions.com
@@ -28,6 +28,14 @@ Dynamic: license-file
 
 This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration
 
+## Requesting a device shadow
+
+Call `PlaceMessages.subscribe_shadow_and_get(thing_name)` from the MQTT client's
+`on_connect` callback. It subscribes to the device's shadow topics and sends the
+shadow GET only after the broker acknowledges the subscription. The `on_connect`
+callback is also invoked on reconnect, so it should subscribe every device again.
+Rejected subscriptions are logged and do not send a GET.
+
 ## Setup
 
 This repo utilizes VS Code [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) so you don't need to alter your global python environment.

place_integration_api-0.2.8/tests/test_mqtt_client.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import logging
+from threading import Event, Thread
+from unittest.mock import MagicMock, call, patch
+
+import paho.mqtt.client as mqtt
+from paho.mqtt.packettypes import PacketTypes
+from paho.mqtt.reasoncodes import ReasonCode
+import pytest
+
+from place.errors import PlaceMqttConnectionError, PlaceMqttSubscriptionError
+from place.messages import PlaceMessages
+from place.models import Credentials
+from place.mqtt_client import get_signed_uri, MqttClient
+
+
+def test_get_signed_uri_includes_host_and_token() -> None:
+    uri = get_signed_uri(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token123",
+        host="example.iot.amazonaws.com",
+    )
+    assert uri.startswith("wss://example.iot.amazonaws.com/mqtt?")
+    assert "X-Amz-Algorithm=" in uri
+    assert "X-Amz-Signature=" in uri
+    assert "X-Amz-Security-Token=token123" in uri
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_mqtt_client_connect_sets_up_client(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+
+    mqtt_client = MqttClient(
+        endpoint="example.iot.amazonaws.com",
+        credentials=creds,
+    )
+    mqtt_client.connect()
+
+    mock_get_signed_uri.assert_called_once()
+    client.ws_set_options.assert_called()
+    client.tls_set.assert_called_once()
+    client.connect.assert_called_once()
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_wait_for_connection_succeeds_on_connack_success(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+    mqtt_client = MqttClient(endpoint="example.iot.amazonaws.com", credentials=creds)
+    mqtt_client.connect()
+
+    client.on_connect(
+        client, None, None, ReasonCode(PacketTypes.CONNACK, identifier=0), None
+    )
+
+    mqtt_client.wait_for_connection(timeout=1)
+
+    client.disconnect.assert_not_called()
+    client.loop_stop.assert_not_called()
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_wait_for_connection_raises_on_connack_rejection(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+    mqtt_client = MqttClient(endpoint="example.iot.amazonaws.com", credentials=creds)
+    mqtt_client.connect()
+
+    client.on_connect(
+        client, None, None, ReasonCode(PacketTypes.CONNACK, identifier=135), None
+    )
+
+    with pytest.raises(PlaceMqttConnectionError, match="rejected"):
+        mqtt_client.wait_for_connection(timeout=1)
+
+    client.disconnect.assert_called_once()
+    client.loop_stop.assert_called_once()
+
+
+@patch("place.mqtt_client.mqtt.Client")
+@patch("place.mqtt_client.get_signed_uri")
+def test_wait_for_connection_raises_on_timeout(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+    mqtt_client = MqttClient(endpoint="example.iot.amazonaws.com", credentials=creds)
+    mqtt_client.connect()
+
+    with pytest.raises(PlaceMqttConnectionError, match="Timed out"):
+        mqtt_client.wait_for_connection(timeout=0.05)
+
+    client.disconnect.assert_called_once()
+    client.loop_stop.assert_called_once()
+
+
+@pytest.fixture
+def mqtt_pair() -> tuple[MqttClient, MagicMock]:
+    """Set up the wrapper with a mocked Paho client."""
+    with patch("place.mqtt_client.mqtt.Client") as client_cls:
+        client = client_cls.return_value
+        credentials = Credentials(
+            access_key_id="key",
+            secret_access_key="secret",
+            session_token="token",
+            identity_id="identity",
+        )
+        wrapper = MqttClient(
+            endpoint="example.iot.amazonaws.com", credentials=credentials
+        )
+        wrapper.connect()
+    return wrapper, client
+
+
+def test_shadow_get_waits_for_each_successful_suback(
+    mqtt_pair: tuple[MqttClient, MagicMock],
+) -> None:
+    wrapper, client = mqtt_pair
+    messages = PlaceMessages(wrapper)
+    client.subscribe.side_effect = [(mqtt.MQTT_ERR_SUCCESS, mid) for mid in range(1, 5)]
+
+    for name in ("one", "two", "three", "four"):
+        messages.subscribe_shadow_and_get(name)
+
+    client.publish.assert_not_called()
+    for mid, name in ((3, "three"), (1, "one"), (4, "four"), (2, "two")):
+        client.on_subscribe(
+            client, None, mid, [ReasonCode(PacketTypes.SUBACK, identifier=1)], None
+        )
+        assert client.publish.call_args == call(
+            f"$aws/things/{name}/shadow/get", b"", qos=1
+        )
+    assert client.publish.call_count == 4
+    client.on_subscribe(
+        client, None, 1, [ReasonCode(PacketTypes.SUBACK, identifier=1)], None
+    )
+    assert client.publish.call_count == 4
+
+
+@pytest.mark.parametrize("reason_codes", [[ReasonCode(PacketTypes.SUBACK, identifier=128)], []])
+def test_failed_suback_does_not_request_shadow(
+    mqtt_pair: tuple[MqttClient, MagicMock],
+    caplog: pytest.LogCaptureFixture,
+    reason_codes: list[ReasonCode],
+) -> None:
+    wrapper, client = mqtt_pair
+    client.subscribe.return_value = (mqtt.MQTT_ERR_SUCCESS, 1)
+    PlaceMessages(wrapper).subscribe_shadow_and_get("one")
+
+    with caplog.at_level(logging.ERROR):
+        client.on_subscribe(client, None, 1, reason_codes, None)
+
+    client.publish.assert_not_called()
+    assert "$aws/things/one/shadow/#" in caplog.text
+
+
+def test_shadow_subscription_preserves_name_and_qos(
+    mqtt_pair: tuple[MqttClient, MagicMock],
+) -> None:
+    wrapper, client = mqtt_pair
+    client.subscribe.return_value = (mqtt.MQTT_ERR_SUCCESS, 1)
+    assert PlaceMessages(wrapper).subscribe_shadow_and_get(" one ", qos=0) == "one"
+    client.subscribe.assert_called_once_with("$aws/things/one/shadow/#", qos=0)
+    client.on_subscribe(
+        client, None, 1, [ReasonCode(PacketTypes.SUBACK, identifier=0)], None
+    )
+    client.publish.assert_called_once_with("$aws/things/one/shadow/get", b"", qos=0)
+
+
+def test_subscribe_send_failure_raises(
+    mqtt_pair: tuple[MqttClient, MagicMock],
+) -> None:
+    wrapper, client = mqtt_pair
+    client.subscribe.return_value = (mqtt.MQTT_ERR_NO_CONN, None)
+
+    with pytest.raises(PlaceMqttSubscriptionError, match="one"):
+        PlaceMessages(wrapper).subscribe_shadow_and_get("one")
+
+    client.publish.assert_not_called()
+
+
+def test_reconnect_discards_pending_subscriptions(
+    mqtt_pair: tuple[MqttClient, MagicMock],
+) -> None:
+    wrapper, client = mqtt_pair
+    messages = PlaceMessages(wrapper)
+    client.subscribe.side_effect = [
+        (mqtt.MQTT_ERR_SUCCESS, 1),
+        (mqtt.MQTT_ERR_SUCCESS, 2),
+    ]
+    with patch("place.mqtt_client.mqtt.Client", return_value=client):
+        wrapper.connect(on_connect=lambda: messages.subscribe_shadow_and_get("one"))
+    client.on_connect(
+        client, None, None, ReasonCode(PacketTypes.CONNACK, identifier=0), None
+    )
+    client.on_disconnect(client, None, None, None, None)
+    client.on_connect(
+        client, None, None, ReasonCode(PacketTypes.CONNACK, identifier=0), None
+    )
+
+    client.on_subscribe(
+        client, None, 1, [ReasonCode(PacketTypes.SUBACK, identifier=1)], None
+    )
+    client.publish.assert_not_called()
+    client.on_subscribe(
+        client, None, 2, [ReasonCode(PacketTypes.SUBACK, identifier=1)], None
+    )
+    assert client.subscribe.call_count == 2
+    client.publish.assert_called_once_with("$aws/things/one/shadow/get", b"", qos=1)
+
+
+def test_suback_cannot_arrive_before_subscription_is_registered(
+    mqtt_pair: tuple[MqttClient, MagicMock],
+) -> None:
+    wrapper, client = mqtt_pair
+    attempted_ack = Event()
+    ack_finished = Event()
+
+    def acknowledge() -> None:
+        attempted_ack.set()
+        client.on_subscribe(
+            client, None, 1, [ReasonCode(PacketTypes.SUBACK, identifier=1)], None
+        )
+        ack_finished.set()
+
+    def subscribe(topic: str, qos: int) -> tuple[int, int]:
+        ack_thread.start()
+        assert attempted_ack.wait(1)
+        assert not ack_finished.is_set()
+        return mqtt.MQTT_ERR_SUCCESS, 1
+
+    ack_thread = Thread(target=acknowledge)
+    client.subscribe.side_effect = subscribe
+    PlaceMessages(wrapper).subscribe_shadow_and_get("one")
+    ack_thread.join(timeout=1)
+
+    assert not ack_thread.is_alive()
+    client.publish.assert_called_once_with("$aws/things/one/shadow/get", b"", qos=1)

place_integration_api-0.2.6/src/place/errors.py

@@ -1,9 +0,0 @@
-"""Errors for the Place API."""
-
-
-class PlaceApiError(Exception):
-    """Base error for Place API failures."""
-
-
-class PlaceFulfillmentError(PlaceApiError):
-    """Raised when the fulfillment API reports a business-logic failure."""

place_integration_api-0.2.6/tests/test_mqtt_client.py

@@ -1,48 +0,0 @@
-from __future__ import annotations
-
-from unittest.mock import MagicMock, patch
-
-from place.models import Credentials
-from place.mqtt_client import get_signed_uri, MqttClient
-
-
-def test_get_signed_uri_includes_host_and_token() -> None:
-    uri = get_signed_uri(
-        access_key_id="AKIA...",
-        secret_access_key="secret",
-        session_token="token123",
-        host="example.iot.amazonaws.com",
-    )
-    assert uri.startswith("wss://example.iot.amazonaws.com/mqtt?")
-    assert "X-Amz-Algorithm=" in uri
-    assert "X-Amz-Signature=" in uri
-    assert "X-Amz-Security-Token=token123" in uri
-
-
-@patch("place.mqtt_client.mqtt.Client")
-@patch("place.mqtt_client.get_signed_uri")
-def test_mqtt_client_connect_sets_up_client(
-    mock_get_signed_uri: MagicMock,
-    mock_client_cls: MagicMock,
-) -> None:
-    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
-    client = MagicMock()
-    mock_client_cls.return_value = client
-
-    creds = Credentials(
-        access_key_id="AKIA...",
-        secret_access_key="secret",
-        session_token="token",
-        identity_id="identity-123",
-    )
-
-    mqtt_client = MqttClient(
-        endpoint="example.iot.amazonaws.com",
-        credentials=creds,
-    )
-    mqtt_client.connect()
-
-    mock_get_signed_uri.assert_called_once()
-    client.ws_set_options.assert_called()
-    client.tls_set.assert_called_once()
-    client.connect.assert_called_once()