raise-suite-sdk 0.1.0__tar.gz

raise_suite_sdk-0.1.0/LICENSE

@@ -0,0 +1,291 @@
+                      EUROPEAN UNION PUBLIC LICENCE v. 1.2
+                      EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as
+defined below) which is provided under the terms of this Licence. Any use of
+the Work, other than as authorised under this Licence is prohibited (to the
+extent such use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work:
+
+        Licensed under the EUPL
+
+or has expressed by any other means his willingness to license under the EUPL.
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+- ‘The Licence’: this Licence.
+
+- ‘The Original Work’: the work or software distributed or communicated by the
+  Licensor under this Licence, available as Source Code and also as Executable
+  Code as the case may be.
+
+- ‘Derivative Works’: the works or software that could be created by the
+  Licensee, based upon the Original Work or modifications thereof. This
+  Licence does not define the extent of modification or dependence on the
+  Original Work required in order to classify a work as a Derivative Work;
+  this extent is determined by copyright law applicable in the country
+  mentioned in Article 15.
+
+- ‘The Work’: the Original Work or its Derivative Works.
+
+- ‘The Source Code’: the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+- ‘The Executable Code’: any code which has generally been compiled and which
+  is meant to be interpreted by a computer as a program.
+
+- ‘The Licensor’: the natural or legal person that distributes or communicates
+  the Work under the Licence.
+
+- ‘Contributor(s)’: any natural or legal person who modifies the Work under
+  the Licence, or otherwise contributes to the creation of a Derivative Work.
+
+- ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+
+- ‘Distribution’ or ‘Communication’: any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright
+vested in the Original Work:
+
+- use the Work in any circumstance and for all usage,
+- reproduce the Work,
+- modify the Work, and make Derivative Works based upon the Work,
+- communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case
+  may be, the Work,
+- distribute the Work or copies thereof,
+- lend and rent the Work or copies thereof,
+- sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make
+effective the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights
+to any patents held by the Licensor, to the extent necessary to make use of
+the rights granted on the Work under this Licence.
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates,
+in a notice following the copyright notice attached to the Work, a repository
+where the Source Code is easily and freely accessible for as long as the
+Licensor continues to distribute or communicate the Work.
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits
+from any exception or limitation to the exclusive rights of the rights owners
+in the Work, of the exhaustion of those rights or of other applicable
+limitations thereto.
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices and
+a copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will be
+done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of
+the Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions
+on the Work or Derivative Work that alter or restrict the terms of the
+Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed
+under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause,
+‘Compatible Licence’ refers to the licences listed in the appendix attached to
+this Licence. Should the Licensee's obligations under the Compatible Licence
+conflict with his/her obligations under this Licence, the obligations of the
+Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the
+Work, the Licensee will provide a machine-readable copy of the Source Code or
+indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade
+names, trademarks, service marks, or names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright in the Original Work granted
+hereunder is owned by him/her or licensed to him/her and that he/she has the
+power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright in the modifications he/she
+brings to the Work are owned by him/her or licensed to him/her and that he/she
+has the power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under the
+terms of this Licence.
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+‘bugs’ inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an ‘as is’
+basis and without warranties of any kind concerning the Work, including
+without limitation merchantability, fitness for a particular purpose, absence
+of defects or errors, accuracy, non-infringement of intellectual property
+rights other than copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a
+condition for the grant of any rights to the Work.
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural
+persons, the Licensor will in no event be liable for any direct or indirect,
+material or moral, damages of any kind, arising out of the Licence or of the
+use of the Work, including without limitation, damages for loss of goodwill,
+work stoppage, computer failure or malfunction, loss of data or any commercial
+damage, even if the Licensor has been advised of the possibility of such
+damage. However, the Licensor will be liable under statutory product liability
+laws as far such laws apply to the Work.
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional
+agreement, defining obligations or services consistent with this Licence.
+However, if accepting obligations, You may act only on your own behalf and on
+your sole responsibility, not on behalf of the original Licensor or any other
+Contributor, and only if You agree to indemnify, defend, and hold each
+Contributor harmless for any liability incurred by, or claims asserted against
+such Contributor by the fact You have accepted any warranty or additional
+liability.
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon ‘I
+agree’ placed under the bottom of a window displaying the text of this Licence
+or by affirming consent in any other similar way, in accordance with the rules
+of applicable law. Clicking on that icon indicates your clear and irrevocable
+acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this
+Licence, such as the use of the Work, the creation by You of a Derivative Work
+or the Distribution or Communication by You of the Work or copies thereof.
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of
+electronic communication by You (for example, by offering to download the Work
+from a remote location) the distribution channel or media (for example, a
+website) must at least provide to the public the information requested by the
+applicable law regarding the Licensor, the Licence and the way it may be
+accessible, concluded, stored and reproduced by the Licensee.
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon
+any breach by the Licensee of the terms of the Licence.
+
+Such a termination will not terminate the licences of any person who has
+received the Work from the Licensee under the Licence, provided such persons
+remain in full compliance with the Licence.
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make it
+valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions
+of this Licence or updated versions of the Appendix, so far this is required
+and reasonable, without reducing the scope of the rights granted by the
+Licence. New versions of the Licence will be published with a unique version
+number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+- any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the Court
+  of Justice of the European Union, as laid down in article 272 of the Treaty
+  on the Functioning of the European Union,
+
+- any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive
+  jurisdiction of the competent court where the Licensor resides or conducts
+  its primary business.
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+- this Licence shall be governed by the law of the European Union Member State
+  where the Licensor has his seat, resides or has his registered office,
+
+- this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+
+- GNU General Public License (GPL) v. 2, v. 3
+- GNU Affero General Public License (AGPL) v. 3
+- Open Software License (OSL) v. 2.1, v. 3.0
+- Eclipse Public License (EPL) v. 1.0
+- CeCILL v. 2.0, v. 2.1
+- Mozilla Public Licence (MPL) v. 2
+- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+- European Union Public Licence (EUPL) v. 1.1, v. 1.2
+- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong
+  Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the
+above licences without producing a new version of the EUPL, as long as they
+provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+
+All other changes or additions to this Appendix require the production of a
+new EUPL version.

raise_suite_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: raise-suite-sdk
+Version: 0.1.0
+Summary: RAISE Suite SDK for local devices to communicate with the local RAISE Suite Agent
+License: EUPL-1.2
+License-File: LICENSE
+Author: RAISE Suite Developers
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: paho-mqtt (>=2.0.0,<3.0.0)
+Project-URL: Repository, https://github.com/cyclopt-pc/raise-suite-sdk
+Description-Content-Type: text/markdown
+
+# RAISE Suite SDK
+
+A Python SDK that enables local devices to communicate with a local RAISE Suite Agent over MQTT. It provides a clean, type-safe wrapper around `paho-mqtt` v2 for connecting, publishing, subscribing, and handling device messages.
+
+## Features
+- **Modern Packaging**: Fully managed via Poetry with `pyproject.toml`.
+- **Clean Namespace**: Main class exposed via `from raise_suite_sdk import MqttClient`.
+- **Robust Logging**: Zero direct terminal spam. All communications use structured standard Python logging under `raise_suite_sdk`.
+- **Type Hints**: Full PEP 484 type signatures for enhanced IDE autocomplete.
+
+## Installation
+
+Using Poetry:
+```bash
+poetry add raise-suite-sdk
+```
+
+Or pip:
+```bash
+pip install raise-suite-sdk
+```
+
+## Quick Start
+
+```python
+import logging
+from raise_suite_sdk import MqttClient
+
+# Configure logging in your parent application
+logging.basicConfig(level=logging.INFO)
+
+# Define callback
+def on_message_received(topic: str, payload: dict, qos: int):
+    print(f"Received message from {topic}: {payload}")
+
+# Initialize and start the client
+client = MqttClient(
+    client_id="my-app-client",
+    user="my_username",
+    password="my_password",
+    broker="localhost",
+    port=1883,
+    on_message=on_message_received
+)
+
+client.start()
+
+# Publish a dictionary payload (automatically serialized to JSON)
+client.publish("my/topic", {"status": "ok"}, qos=1)
+
+# Stop the client when done
+client.stop()
+```
+
+## License
+
+Licensed under the European Union Public Licence 1.2 (EUPL-1.2). See [LICENSE](LICENSE) for the full text.
+

raise_suite_sdk-0.1.0/README.md

@@ -0,0 +1,57 @@
+# RAISE Suite SDK
+
+A Python SDK that enables local devices to communicate with a local RAISE Suite Agent over MQTT. It provides a clean, type-safe wrapper around `paho-mqtt` v2 for connecting, publishing, subscribing, and handling device messages.
+
+## Features
+- **Modern Packaging**: Fully managed via Poetry with `pyproject.toml`.
+- **Clean Namespace**: Main class exposed via `from raise_suite_sdk import MqttClient`.
+- **Robust Logging**: Zero direct terminal spam. All communications use structured standard Python logging under `raise_suite_sdk`.
+- **Type Hints**: Full PEP 484 type signatures for enhanced IDE autocomplete.
+
+## Installation
+
+Using Poetry:
+```bash
+poetry add raise-suite-sdk
+```
+
+Or pip:
+```bash
+pip install raise-suite-sdk
+```
+
+## Quick Start
+
+```python
+import logging
+from raise_suite_sdk import MqttClient
+
+# Configure logging in your parent application
+logging.basicConfig(level=logging.INFO)
+
+# Define callback
+def on_message_received(topic: str, payload: dict, qos: int):
+    print(f"Received message from {topic}: {payload}")
+
+# Initialize and start the client
+client = MqttClient(
+    client_id="my-app-client",
+    user="my_username",
+    password="my_password",
+    broker="localhost",
+    port=1883,
+    on_message=on_message_received
+)
+
+client.start()
+
+# Publish a dictionary payload (automatically serialized to JSON)
+client.publish("my/topic", {"status": "ok"}, qos=1)
+
+# Stop the client when done
+client.stop()
+```
+
+## License
+
+Licensed under the European Union Public Licence 1.2 (EUPL-1.2). See [LICENSE](LICENSE) for the full text.

raise_suite_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.poetry]
+name = "raise-suite-sdk"
+version = "0.1.0"
+description = "RAISE Suite SDK for local devices to communicate with the local RAISE Suite Agent"
+license = "EUPL-1.2"
+repository = "https://github.com/cyclopt-pc/raise-suite-sdk"
+authors = ["RAISE Suite Developers"]
+readme = "README.md"
+packages = [{include = "raise_suite_sdk", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+paho-mqtt = "^2.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.0"
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: fast tests that do not need external services",
+    "integration: tests that require a running MQTT broker",
+]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

raise_suite_sdk-0.1.0/src/raise_suite_sdk/__init__.py

@@ -0,0 +1,21 @@
+import logging
+from .client import MqttClient
+from .exceptions import (
+    MqttSdkException,
+    MqttConnectionError,
+    MqttPublishError,
+    MqttTlsConfigurationError,
+    MqttSerializationError,
+)
+
+# Set default logging handler to prevent "No handler found" warnings
+logging.getLogger("raise_suite_sdk").addHandler(logging.NullHandler())
+
+__all__ = [
+    "MqttClient",
+    "MqttSdkException",
+    "MqttConnectionError",
+    "MqttPublishError",
+    "MqttTlsConfigurationError",
+    "MqttSerializationError",
+]

raise_suite_sdk-0.1.0/src/raise_suite_sdk/client.py

@@ -0,0 +1,438 @@
+"""Local MQTT Client Wrapper.
+
+This client wraps the paho-mqtt library to establish clean pub-sub connections,
+handles SSL/TLS, and monitors connection stability.
+"""
+
+import json
+import logging
+import ssl
+import struct
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from paho.mqtt import client as mqtt_client
+from paho.mqtt.reasoncodes import ReasonCode
+from paho.mqtt.packettypes import PacketTypes
+from paho.mqtt.properties import Properties
+
+from .exceptions import (
+    MqttSdkException,
+    MqttConnectionError,
+    MqttPublishError,
+    MqttTlsConfigurationError,
+    MqttSerializationError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _PatchedClient(mqtt_client.Client):  # pylint: disable=too-few-public-methods
+    """Paho Client subclass that captures the PUBREC reason code.
+
+    Mosquitto sends rc=135 (Not Authorized) in PUBREC when denying a QoS 2
+    publish, but paho discards it before calling on_publish (which only sees
+    the final PUBCOMP, always rc=0). This subclass intercepts the PUBREC
+    reason code and substitutes it into the on_publish callback so that
+    reason_code.is_failure correctly reflects broker-side ACL denials.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._pubrec_reason_codes: Dict[int, ReasonCode] = {}  # mid → ReasonCode captured from PUBREC
+
+    def _handle_pubrec(self) -> int:
+        rc = super()._handle_pubrec()  # let paho do state update + send PUBREL
+        mid, = struct.unpack("!H", self._in_packet['packet'][:2])
+        if self._protocol == mqtt_client.MQTTv5 and self._in_packet['remaining_length'] > 2:
+            reason_code = ReasonCode(PacketTypes.PUBREC)
+            reason_code.unpack(self._in_packet['packet'][2:])
+            self._pubrec_reason_codes[mid] = reason_code
+        return rc
+
+    def _do_on_publish(self, mid: int, reason_code: ReasonCode, properties: Optional[Properties]) -> None:
+        # Use the PUBREC reason code if captured; fall back to PUBCOMP reason code
+        real_rc = self._pubrec_reason_codes.pop(mid, reason_code)
+        return super()._do_on_publish(mid, real_rc, properties)
+
+
+class MqttClient:  # pylint: disable=too-many-instance-attributes
+    """MQTT client wrapper using Paho MQTT for clean, reliable pub-sub communication.
+
+    This class encapsulates connection setup, credential handling, TLS configuration,
+    and automatic reconnection loops. Key capabilities include:
+      - Custom callback handling for connections, publishing, message reception, and disconnection.
+      - Background reconnection logic via daemon thread (_reconnect).
+      - Session state tracking to re-establish active subscriptions upon reconnecting.
+      - JSON serialization of published payloads and message-info tracking.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        user: str,
+        password: str,
+        broker: str,
+        port: int,
+        ca_cert_path: Optional[str] = None,
+        on_message: Optional[Callable[[str, Any, int], None]] = None,
+        clean_start: bool = True,
+        session_expiry_interval: int = 0
+    ) -> None:
+        """Initialize the MQTT client SDK.
+
+        Args:
+            client_id (str): Unique identifier for this client session.
+            user (str): Username for MQTT broker authentication.
+            password (str): Password/token for MQTT broker authentication.
+            broker (str): Address/hostname of the MQTT broker.
+            port (int): Port number for connecting to the broker (e.g. 1883 for TCP, 8883 for TLS).
+            ca_cert_path (Optional[str]): Path to custom CA certificate for TLS verification.
+            on_message (Optional[Callable]): Callback invoked when a message arrives.
+                Signature: (topic: str, payload: dict, qos: int) -> None.
+            clean_start (bool): If True, starts a clean connection session. If False, attempts
+                to resume a persistent session. Defaults to True.
+            session_expiry_interval (int): Time in seconds the broker remembers this session
+                after disconnection. Set to 0 to expire immediately. Defaults to 0.
+        """
+        # Set variables for MQTT connection
+        self.client_id: str = client_id
+        self.user: str = user
+        self.password: str = password
+        self.broker: str = broker
+        self.port: int = port
+        self.ca_cert_path: Optional[str] = ca_cert_path
+        self.on_message: Optional[Callable[[str, Any, int], None]] = on_message
+        self.clean_start: bool = clean_start
+        self.session_expiry_interval: int = session_expiry_interval
+
+        self.connected: bool = False
+        self.reconnecting: bool = False
+        self._stored_subscriptions: List[Tuple[str, int]] = []  # Track subscriptions for reconnecting
+        self._connection_announced: bool = False  # Guard to prevent duplicate connection logs
+        self._mid_to_topic: Dict[int, Tuple[str, Optional[int]]] = {}
+        self._mid_to_topic_lock: threading.Lock = threading.Lock()
+
+        # Setup Logger (Inheriting from SDK parent namespace)
+        self.mqtt_logger = logging.getLogger(__name__)
+
+        # Initialize Client (patched subclass to capture PUBREC reason codes)
+        self.client = _PatchedClient(
+            callback_api_version=mqtt_client.CallbackAPIVersion.VERSION2,
+            client_id=client_id,
+            protocol=mqtt_client.MQTTv5
+        )
+
+        # Attach Callbacks
+        self.client.on_connect = self._on_connect
+        self.client.on_publish = self._on_publish
+        self.client.on_message = self._on_message
+        self.client.on_disconnect = self._on_disconnect
+
+        # Set credentials
+        # (Commented out token fallback logic: username/password are now strictly required)
+        # if password is not None and user is None:
+        #     self.client.username_pw_set("", password)
+        # else:
+        #     self.client.username_pw_set(user, password)
+
+        if not broker:
+            raise ValueError("Broker address must be provided.")
+        if not port or port <= 0:
+            raise ValueError("A valid port must be provided.")
+        if not user or not password:
+            raise ValueError("Both user (username) and password must be provided.")
+        self.client.username_pw_set(user, password)
+
+        # Enable Logger integration in Paho
+        self.client.enable_logger(self.mqtt_logger)
+
+        # Set TLS for secure connection
+        if self.ca_cert_path:
+            try:
+                self.client.tls_set(
+                    ca_certs=self.ca_cert_path,
+                    tls_version=ssl.PROTOCOL_TLSv1_2
+                )
+            except Exception as e:
+                self.mqtt_logger.error("[%s] Failed to set TLS: %s", self.client_id, e)
+                raise MqttTlsConfigurationError(f"Failed to set TLS with CA cert: {e}") from e
+        elif self.port == 8883:
+            try:
+                context = ssl.create_default_context()
+                self.client.tls_set_context(context)
+                self.client.tls_insecure_set(False)
+
+                self.mqtt_logger.info(
+                    "[%s] 🔒 No custom CA cert provided but using port %s. "
+                    "Connecting with secure TLS using system trust store.",
+                    self.client_id,
+                    self.port
+                )
+            except Exception as e:
+                self.mqtt_logger.error("[%s] Failed to set TLS context: %s", self.client_id, e)
+                raise MqttTlsConfigurationError(f"Failed to configure secure TLS context: {e}") from e
+        else:
+            self.mqtt_logger.warning(
+                "[%s] ⚠️ No CA cert provided and not on port 8883. Connecting without TLS.",
+                self.client_id
+            )
+
+    # Set connect callback
+    def _on_connect(
+        self,
+        _client: mqtt_client.Client,
+        _userdata: Any,
+        flags: Any,
+        reason_code: ReasonCode,
+        _properties: Optional[Properties]
+    ) -> None:
+        if reason_code == 0:
+            self.connected = True
+            # Only log connection message once per connection cycle
+            if not self._connection_announced:
+                self.mqtt_logger.info("[%s] ✅ Connection fully acknowledged!", self.client_id)
+                self._connection_announced = True
+
+            # Check if the broker remembered our session and subscriptions!
+            session_present = False
+            if hasattr(flags, 'session_present'):
+                session_present = flags.session_present
+            elif isinstance(flags, dict):
+                session_present = flags.get('session_present', False)
+
+            if session_present:
+                self.mqtt_logger.info(
+                    "[%s] 🧠 Session resumed! Broker remembered our subscriptions.",
+                    self.client_id
+                )
+            else:
+                self.mqtt_logger.info("[%s] 🆕 Clean session. Re-subscribing...", self.client_id)
+                for topic, qos in self._stored_subscriptions:
+                    self.client.subscribe(topic, qos=qos)
+        else:
+            self.mqtt_logger.error(
+                "[%s] ❌ Connection failed with reason code %s",
+                self.client_id,
+                reason_code
+            )
+
+    # Set publish callback
+    def _on_publish(
+        self,
+        _client: mqtt_client.Client,
+        _userdata: Any,
+        mid: int,
+        reason_code: ReasonCode,
+        _properties: Optional[Properties]
+    ) -> None:
+        with self._mid_to_topic_lock:
+            topic, qos = self._mid_to_topic.pop(mid, ("unknown", None))
+
+        if reason_code.is_failure:
+            self.mqtt_logger.error(
+                "[%s] ❌ Publish REJECTED by broker! Message ID: %d, reason: %s (topic: %s)",
+                self.client_id,
+                mid,
+                reason_code,
+                topic
+            )
+        else:
+            if qos == 0:
+                self.mqtt_logger.debug(
+                    "[%s] Message ID %d no handshake for QoS 0! (topic: %s)",
+                    self.client_id,
+                    mid,
+                    topic
+                )
+            elif qos == 1:
+                self.mqtt_logger.debug(
+                    "[%s] Message ID %d has completed the QoS 1 handshake! (topic: %s)",
+                    self.client_id,
+                    mid,
+                    topic
+                )
+            else:
+                self.mqtt_logger.debug(
+                    "[%s] Message ID %d has completed the QoS 2 handshake! (topic: %s)",
+                    self.client_id,
+                    mid,
+                    topic
+                )
+            self.mqtt_logger.info("[%s] ✅ Published! (topic: %s)", self.client_id, topic)
+
+    # Set message callback
+    def _on_message(self, _client: mqtt_client.Client, _userdata: Any, msg: mqtt_client.MQTTMessage) -> None:
+        payload_str = msg.payload.decode("utf-8", errors="replace")
+        self.mqtt_logger.debug("[%s] 📩 Received: %s -> %s", self.client_id, msg.topic, payload_str)
+        try:
+            payload = json.loads(payload_str)
+        except json.JSONDecodeError as e:
+            self.mqtt_logger.error("[%s] ⚠️ Failed to decode JSON payload: %s", self.client_id, e)
+            return  # Skip messages that aren't valid JSON
+        if self.on_message:
+            self.on_message(msg.topic, payload, msg.qos)
+
+    # Set disconnect callback
+    def _on_disconnect(
+        self,
+        _client: mqtt_client.Client,
+        _userdata: Any,
+        _disconnect_flags: Any,
+        reason_code: ReasonCode,
+        _properties: Optional[Properties]
+    ) -> None:
+        self.connected = False
+        self._connection_announced = False  # Reset flag for next connection
+        self.mqtt_logger.warning(
+            "[%s] ⚠️ Disconnected from broker. Reason: %s",
+            self.client_id,
+            reason_code
+        )
+        if reason_code != 0 and not self.reconnecting:  # Not a clean disconnect
+            self.reconnecting = True
+            # Start reconnection in a separate thread to avoid blocking
+            threading.Thread(target=self._reconnect, daemon=True).start()
+
+    def _reconnect(self) -> None:
+        """Keep trying to reconnect every 1 second"""
+        while not self.connected:
+            self.mqtt_logger.warning("[%s] 🔄 Attempting to reconnect...", self.client_id)
+            time.sleep(1)
+            try:
+                self.client.reconnect()
+                # Wait a bit to check if connected
+                time.sleep(1)
+                if self.connected:
+                    self.reconnecting = False
+                    return
+            except Exception as e:
+                self.mqtt_logger.error("[%s] ❌ Reconnect failed: %s", self.client_id, e)
+        self.reconnecting = False
+
+    def start(self) -> None:
+        """Initiate async connection to the MQTT broker and start the network loop.
+
+        Constructs connection properties, sets session lifetimes, and waits for connection success.
+        """
+        self.mqtt_logger.info("[%s] Connecting to MQTT Broker...", self.client_id)
+
+        # 1. Create properties and set the Session Expiry Interval
+        connect_properties = Properties(PacketTypes.CONNECT)
+        connect_properties.SessionExpiryInterval = self.session_expiry_interval
+
+        # 2. Connect with clean_start to force a persistent session
+        try:
+            self.client.connect_async(
+                self.broker,
+                self.port,
+                keepalive=60,
+                clean_start=self.clean_start,
+                properties=connect_properties
+            )
+        except Exception as e:
+            self.mqtt_logger.error("[%s] Connection async failed: %s", self.client_id, e)
+            raise MqttConnectionError(f"Failed to initiate connection: {e}") from e
+
+        self.mqtt_logger.info("[%s] Connection initiated...", self.client_id)
+        # Start the network loop
+        self.client.loop_start()
+        self.mqtt_logger.info("[%s] Waiting for connection...", self.client_id)
+        
+        # Wait up to 10 seconds for connection to succeed to avoid infinite hang
+        start_time = time.time()
+        while not self.connected:
+            if time.time() - start_time > 10.0:
+                self.mqtt_logger.error("[%s] Connection timed out after 10s", self.client_id)
+                raise MqttConnectionError("MQTT connection timed out after 10 seconds.")
+            time.sleep(0.1)
+            
+        self.mqtt_logger.info(
+            "[%s] ✅ Connected and ready to publish/subscribe messages...",
+            self.client_id
+        )
+
+    def publish(self, topic: str, message: Any, qos: int = 2) -> Optional[mqtt_client.MQTTMessageInfo]:
+        """Publish a message to a specific MQTT topic.
+
+        Args:
+            topic (str): Target MQTT topic.
+            message (Any): Payload message to serialize. Can be a dict, Pydantic model, or raw JSON string.
+            qos (int): Quality of Service level (default: 2).
+
+        Returns:
+            paho.mqtt.client.MQTTMessageInfo: Message info container with
+                message ID and publish status.
+        """
+        self.mqtt_logger.info(
+            "[%s] 📤 Handing message to internal queue: %s [QoS %d]...",
+            self.client_id,
+            topic,
+            qos
+        )
+
+        try:
+            message_json = json.dumps(message, ensure_ascii=False)
+        except TypeError as e:
+            self.mqtt_logger.error("[%s] ⚠️ Failed to encode message as JSON: %s", self.client_id, e)
+            raise MqttSerializationError(f"Object of type {type(message).__name__} is not JSON serializable") from e
+
+        try:
+            msg_info = self.client.publish(topic, message_json, qos=qos)
+        except Exception as e:
+            self.mqtt_logger.error("[%s] ❌ Failed to publish message: %s", self.client_id, e)
+            raise MqttPublishError(f"Publish failed: {e}") from e
+
+        with self._mid_to_topic_lock:
+            self._mid_to_topic[msg_info.mid] = (topic, qos)
+
+        if not self.connected:
+            self.mqtt_logger.warning(
+                "[%s] ⚠️ Not connected! Message will be queued locally...",
+                self.client_id
+            )
+
+        return msg_info
+
+    def subscribe(self, topic: str, qos: int = 2) -> None:
+        """Subscribe to a specific MQTT topic.
+
+        Args:
+            topic (str): Topic pattern to subscribe to.
+            qos (int): QoS level (default: 2).
+        """
+        # Store subscription to restore it after a disconnect
+        if (topic, qos) not in self._stored_subscriptions:
+            self._stored_subscriptions.append((topic, qos))
+        self.mqtt_logger.info("[%s] 👂 Subscribing to %s...", self.client_id, topic)
+        try:
+            self.client.subscribe(topic, qos=qos)
+        except Exception as e:
+            self.mqtt_logger.error("[%s] Failed to subscribe to %s: %s", self.client_id, topic, e)
+            raise MqttSdkException(f"Failed to subscribe to {topic}: {e}") from e
+
+    def stop(self) -> None:
+        """Gracefully disconnect from the MQTT broker and stop the background network loop.
+
+        Disconnects, waits for processing, and terminates the event loop.
+        """
+        try:
+            self.mqtt_logger.info("[%s] 🛑 Stopping client gracefully...", self.client_id)
+
+            # NOTE: For persistent sessions to work, we must NOT unsubscribe here.
+            # Unsubscribing tells the broker to discard all subscriptions and queued messages.
+            # By just sending DISCONNECT, the broker holds the session and queues messages.
+
+            # Send DISCONNECT packet while loop is still running
+            self.mqtt_logger.info("[%s] 📤 Sending DISCONNECT...", self.client_id)
+            self.client.disconnect()
+            time.sleep(0.5)
+
+            # Stop the network loop
+            self.mqtt_logger.info("[%s] 🔌 Stopping network loop...", self.client_id)
+            self.client.loop_stop()
+            self.mqtt_logger.info("[%s] ✅ Client stopped gracefully!", self.client_id)
+        except Exception as e:
+            self.mqtt_logger.error("[%s] ❌ Error during stop: %s", self.client_id, e)
+            raise MqttSdkException(f"Error during client shutdown: {e}") from e

raise_suite_sdk-0.1.0/src/raise_suite_sdk/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exceptions for the MQTT SDK."""
+
+class MqttSdkException(Exception):
+    """Base exception class for all errors raised by the MQTT SDK."""
+    pass
+
+
+class MqttConnectionError(MqttSdkException):
+    """Raised when connection to the MQTT broker fails or is refused."""
+    pass
+
+
+class MqttPublishError(MqttSdkException):
+    """Raised when publishing a message fails."""
+    pass
+
+
+class MqttTlsConfigurationError(MqttSdkException):
+    """Raised when SSL/TLS configuration fails."""
+    pass
+
+
+class MqttSerializationError(MqttSdkException):
+    """Raised when a message payload cannot be serialized to JSON."""
+    pass

raise_suite_sdk-0.1.0/src/raise_suite_sdk/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561. This package supports type hints.