helin-edge-sdk 0.0.1__tar.gz

helin_edge_sdk-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

helin_edge_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: helin-edge-sdk
+Version: 0.0.1
+Summary: Receive and respond to Helin Platform edge-module-requests.
+License: MIT
+License-File: LICENSE
+Keywords: iot,azure-iot-edge,edge,helin,helin platform,configuration
+Author: Helin
+Author-email: support@helindata.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+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
+Classifier: Topic :: Communications
+Requires-Dist: paho-mqtt (>=2.1.0,<3.0.0)
+Project-URL: Homepage, https://www.helindata.com
+Description-Content-Type: text/markdown
+
+# helin-edge-sdk
+Using this SDK in your module allows you to securely and reliably receive and respond to the Helin Platform's **edge-module-requests** API: `get_configuration`, `set_configuration`and `get_health` deployed on Nodes on the edge. 
+
+For more information see https://docs.helinplatform.com
+
+## Install
+
+```bash
+pip install helin-edge-sdk
+```
+
+## Usage
+
+Implement the three methods and run the client:
+
+```python
+from typing import Any
+from helin_edge_sdk import EdgeModuleRequestsHandler, EdgeModuleClient, ConfigurationFailedError
+
+class MyModule(EdgeModuleRequestsHandler):
+    def __init__(self) -> None:
+        self.configuration = {"opcua_ip": "123.34.233.1", "opcua_port": 4840, "poll_interval_ms": 1000}
+
+    def on_get_configuration(self, payload: dict[str, Any]) -> Any:
+        return self.configuration
+
+    def on_set_configuration(self, payload: dict[str, Any]) -> Any:
+        cfg = payload.get("configuration")
+        if cfg is None:
+            raise ConfigurationFailedError("missing configuration", status_code=400,
+                                           current_configuration=self.configuration)
+        self.configuration = cfg
+        return {"configuration": cfg}
+
+    def on_get_health(self, payload: dict[str, Any]) -> Any:
+        return {"metrics": [{"name": "opcua_connected", "value": 1}]}
+
+EdgeModuleClient.from_edge_environment(MyModule()).run() #Fetches all required env variables on your provisioned Node
+```
+
+Each callback receives the **decompressed** request payload and returns a
+JSON-serializable value, which is wrapped as 
+```{"status": 200, "response": <value>}```
+
+compressed, and published back to the caller. 
+
+Raise `ConfigurationFailedError` to return the configuration-failure envelope:
+
+```{"status": <code>, "response": {"error": ..., "current_configuration": ...}}```.
+
+## Status codes
+
+| Handler outcome | Status |
+| --- | --- |
+| Returns a value | 200 |
+| Raises `ValueError` | 400 |
+| Raises `ConnectionError` | 400 |
+| Unknown method | 400 |
+| Raises `FileNotFoundError` | 404 |
+| Raises `ConfigurationFailedError` | its `status_code` (default 409) |
+| Raises any other exception | 500 |
+
+## Local testing
+
+```bash
+# 1. start a plaintext broker
+docker compose -f docker/docker-compose.test.yml up -d
+
+# 2. run the module against it
+python -m examples.run_local
+
+# 3. invoke a method (simulates the Platform API)
+python -m examples.publish_method get_health
+python -m examples.publish_method set_configuration '{"configuration": {"opcua_ip": "10.0.0.5", "opcua_port": 4840}}'
+```
+
+## Develop
+
+```bash
+poetry install
+poetry run pytest -m "not integration"   # unit tests, no broker
+poetry run pytest                        # all tests (needs the broker above)
+poetry run ruff check
+poetry run ty check
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph platform["Cloud"]
+        API["Platform API <br/> POST /api/v1/edge-module-requests/nodes/{node_id}/modules/{module_id} <br/> GET /api/v1/edge-module-requests/nodes/{node_id}/modules/{module_id} <br/> GET /api/v1/edge-module-requests/nodes/{node_id}/modules/{module_id}/health"]
+    end
+
+    subgraph hub["Azure IoT Hub (Cloud)"]
+        IOTHUB
+    end
+
+    subgraph edge["Node — Edge runtime"]
+        EDGEHUB["edgeHub<br/>MQTT broker :8883 (TLS)"]
+        WL["Edge workload API<br/>unix:///…/workload.sock<br/>/sign · /trust-bundle"]
+
+        subgraph mod["Module using helin-edge-sdk"]
+            direction TB
+            CLIENT["EdgeModuleClient<br/>from_edge_environment()"]
+            LISTENER["MqttModuleListener<br/>(paho-mqtt transport)"]
+            HANDLER["EdgeModuleRequestsHandler<br/>(your on_* callbacks)"]
+            CLIENT --> LISTENER
+            LISTENER -- "dispatch(method, payload)" --> HANDLER
+            HANDLER -- "result / ConfigurationFailedError" --> LISTENER
+        end
+    end
+
+    API <== "edge-module-requests<br/>(gzip payload)" ==> IOTHUB
+    IOTHUB <== "cloud uplink" ==> EDGEHUB
+
+    EDGEHUB -- "SUB - (gzip payload)" --> LISTENER
+    LISTENER -- "PUB - (gzip payload)" --> EDGEHUB
+
+    LISTENER -- "SAS token + trust bundle" --> WL
+```

helin_edge_sdk-0.0.1/README.md

@@ -0,0 +1,121 @@
+# helin-edge-sdk
+Using this SDK in your module allows you to securely and reliably receive and respond to the Helin Platform's **edge-module-requests** API: `get_configuration`, `set_configuration`and `get_health` deployed on Nodes on the edge. 
+
+For more information see https://docs.helinplatform.com
+
+## Install
+
+```bash
+pip install helin-edge-sdk
+```
+
+## Usage
+
+Implement the three methods and run the client:
+
+```python
+from typing import Any
+from helin_edge_sdk import EdgeModuleRequestsHandler, EdgeModuleClient, ConfigurationFailedError
+
+class MyModule(EdgeModuleRequestsHandler):
+    def __init__(self) -> None:
+        self.configuration = {"opcua_ip": "123.34.233.1", "opcua_port": 4840, "poll_interval_ms": 1000}
+
+    def on_get_configuration(self, payload: dict[str, Any]) -> Any:
+        return self.configuration
+
+    def on_set_configuration(self, payload: dict[str, Any]) -> Any:
+        cfg = payload.get("configuration")
+        if cfg is None:
+            raise ConfigurationFailedError("missing configuration", status_code=400,
+                                           current_configuration=self.configuration)
+        self.configuration = cfg
+        return {"configuration": cfg}
+
+    def on_get_health(self, payload: dict[str, Any]) -> Any:
+        return {"metrics": [{"name": "opcua_connected", "value": 1}]}
+
+EdgeModuleClient.from_edge_environment(MyModule()).run() #Fetches all required env variables on your provisioned Node
+```
+
+Each callback receives the **decompressed** request payload and returns a
+JSON-serializable value, which is wrapped as 
+```{"status": 200, "response": <value>}```
+
+compressed, and published back to the caller. 
+
+Raise `ConfigurationFailedError` to return the configuration-failure envelope:
+
+```{"status": <code>, "response": {"error": ..., "current_configuration": ...}}```.
+
+## Status codes
+
+| Handler outcome | Status |
+| --- | --- |
+| Returns a value | 200 |
+| Raises `ValueError` | 400 |
+| Raises `ConnectionError` | 400 |
+| Unknown method | 400 |
+| Raises `FileNotFoundError` | 404 |
+| Raises `ConfigurationFailedError` | its `status_code` (default 409) |
+| Raises any other exception | 500 |
+
+## Local testing
+
+```bash
+# 1. start a plaintext broker
+docker compose -f docker/docker-compose.test.yml up -d
+
+# 2. run the module against it
+python -m examples.run_local
+
+# 3. invoke a method (simulates the Platform API)
+python -m examples.publish_method get_health
+python -m examples.publish_method set_configuration '{"configuration": {"opcua_ip": "10.0.0.5", "opcua_port": 4840}}'
+```
+
+## Develop
+
+```bash
+poetry install
+poetry run pytest -m "not integration"   # unit tests, no broker
+poetry run pytest                        # all tests (needs the broker above)
+poetry run ruff check
+poetry run ty check
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph platform["Cloud"]
+        API["Platform API <br/> POST /api/v1/edge-module-requests/nodes/{node_id}/modules/{module_id} <br/> GET /api/v1/edge-module-requests/nodes/{node_id}/modules/{module_id} <br/> GET /api/v1/edge-module-requests/nodes/{node_id}/modules/{module_id}/health"]
+    end
+
+    subgraph hub["Azure IoT Hub (Cloud)"]
+        IOTHUB
+    end
+
+    subgraph edge["Node — Edge runtime"]
+        EDGEHUB["edgeHub<br/>MQTT broker :8883 (TLS)"]
+        WL["Edge workload API<br/>unix:///…/workload.sock<br/>/sign · /trust-bundle"]
+
+        subgraph mod["Module using helin-edge-sdk"]
+            direction TB
+            CLIENT["EdgeModuleClient<br/>from_edge_environment()"]
+            LISTENER["MqttModuleListener<br/>(paho-mqtt transport)"]
+            HANDLER["EdgeModuleRequestsHandler<br/>(your on_* callbacks)"]
+            CLIENT --> LISTENER
+            LISTENER -- "dispatch(method, payload)" --> HANDLER
+            HANDLER -- "result / ConfigurationFailedError" --> LISTENER
+        end
+    end
+
+    API <== "edge-module-requests<br/>(gzip payload)" ==> IOTHUB
+    IOTHUB <== "cloud uplink" ==> EDGEHUB
+
+    EDGEHUB -- "SUB - (gzip payload)" --> LISTENER
+    LISTENER -- "PUB - (gzip payload)" --> EDGEHUB
+
+    LISTENER -- "SAS token + trust bundle" --> WL
+```

helin_edge_sdk-0.0.1/pyproject.toml

@@ -0,0 +1,60 @@
+[tool.poetry]
+name = "helin-edge-sdk"
+version = "0.0.1"
+description = "Receive and respond to Helin Platform edge-module-requests."
+authors = ["Helin <support@helindata.com>"]
+readme = "README.md"
+license = "MIT"
+keywords = ["iot", "azure-iot-edge", "edge", "helin", "helin platform", "configuration"]
+packages = [{ include = "helin_edge_sdk", from = "src" }]
+exclude = ["platform-demo", "examples", "docker", "tests"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Topic :: Communications",
+]
+
+[tool.poetry.urls]
+Homepage = "https://www.helindata.com"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+paho-mqtt = "^2.1.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.0"
+pytest-cov = ">7"
+ruff = "^0.15.0"
+ty = ">=0.0.49"
+invoke = "^2.0.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ty.environment]
+python-version = "3.11"
+root = ["src", "."]
+
+[tool.ty.src]
+include = ["src", "tests", "examples"]
+
+[tool.coverage.run]
+relative_files = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: tests that require a running MQTT broker (deselect with -m 'not integration')",
+]

helin_edge_sdk-0.0.1/src/helin_edge_sdk/__init__.py

@@ -0,0 +1,36 @@
+"""helin-edge-sdk: receive and respond to Helin Platform edge-module-requests on an edge module."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from helin_edge_sdk.client import EdgeModuleClient
+from helin_edge_sdk.compression import compress_payload, decompress_payload
+from helin_edge_sdk.config import ConnectionConfig
+from helin_edge_sdk.errors import ConfigurationFailedError
+from helin_edge_sdk.handler import (
+    GET_CONFIGURATION,
+    GET_HEALTH,
+    SET_CONFIGURATION,
+    SUPPORTED_METHODS,
+    EdgeModuleRequestsHandler,
+)
+from helin_edge_sdk.responses import ResponseStatus
+
+try:
+    __version__ = version("helin-edge-sdk")
+except PackageNotFoundError:  # running from a source checkout without installed metadata
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "EdgeModuleClient",
+    "ConnectionConfig",
+    "EdgeModuleRequestsHandler",
+    "ConfigurationFailedError",
+    "ResponseStatus",
+    "compress_payload",
+    "decompress_payload",
+    "GET_CONFIGURATION",
+    "SET_CONFIGURATION",
+    "GET_HEALTH",
+    "SUPPORTED_METHODS",
+    "__version__",
+]

helin_edge_sdk-0.0.1/src/helin_edge_sdk/auth.py

@@ -0,0 +1,183 @@
+"""Authentication primitives for connecting to edgeHub over MQTT.
+
+Two ways to obtain the MQTT password (a SAS token):
+
+* :class:`EdgeWorkloadSigner` — production. The module holds no key; it asks the
+  IoT Edge workload API (the ``IOTEDGE_WORKLOADURI`` unix socket) to sign the
+  token and to hand over the trust-bundle CA so TLS to edgeHub can be verified.
+* :class:`LocalKeySigner` — local/testing. Signs with a shared access key taken
+  from a connection string, using HMAC-SHA256 locally.
+
+The wire formats (SAS token string, sign string, workload endpoints) match the
+Microsoft ``azure-iot-device`` SDK, so edgeHub accepts our connection unchanged.
+"""
+
+import base64
+import hashlib
+import hmac
+import http.client
+import json
+import socket
+import time
+import urllib.parse
+from collections.abc import Callable
+from typing import Any, Protocol
+
+DEFAULT_SAS_TTL_SECONDS = 3600
+_WORKLOAD_TIMEOUT_SECONDS = 30
+
+
+class Signer(Protocol):
+    def sign(self, data: str) -> str:
+        """Return the base64-encoded HMAC-SHA256 signature of ``data``."""
+        ...
+
+
+class LocalKeySigner:
+    def __init__(self, shared_access_key_b64: str) -> None:
+        self._key = base64.b64decode(shared_access_key_b64)
+
+    def sign(self, data: str) -> str:
+        digest = hmac.new(self._key, data.encode("utf-8"), hashlib.sha256).digest()
+        return base64.b64encode(digest).decode("ascii")
+
+
+class IoTEdgeError(Exception):
+    pass
+
+
+class EdgeWorkloadSigner:
+    """Signs SAS tokens and fetches the trust bundle via the IoT Edge workload API."""
+
+    def __init__(
+        self, module_id: str, generation_id: str, workload_uri: str, api_version: str
+    ) -> None:
+        self.module_id = urllib.parse.quote(module_id, safe="")
+        self.generation_id = generation_id
+        self.api_version = api_version
+        self.workload_uri = workload_uri
+
+    def sign(self, data: str) -> str:
+        encoded = base64.b64encode(data.encode("utf-8")).decode()
+        body = {"keyId": "primary", "algo": "HMACSHA256", "data": encoded}
+        response = self._request(
+            "POST", f"modules/{self.module_id}/genid/{self.generation_id}/sign", body=body
+        )
+        digest = response.get("digest")
+        if not digest:
+            raise IoTEdgeError("No digest in workload sign response")
+        return str(digest)
+
+    def get_certificate(self) -> str:
+        response = self._request("GET", "trust-bundle")
+        certificate = response.get("certificate")
+        if not certificate:
+            raise IoTEdgeError("No certificate in trust bundle")
+        return str(certificate)
+
+    def _request(
+        self, method: str, sub_path: str, body: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return _workload_request(
+            self.workload_uri, method, sub_path, {"api-version": self.api_version}, body
+        )
+
+
+def build_sas_token(resource_uri: str, signer: Signer, expiry: int) -> str:
+    """Build a ``SharedAccessSignature sr=...&sig=...&se=...`` token for ``resource_uri``."""
+    quoted_uri = urllib.parse.quote(resource_uri, safe="")
+    signature = signer.sign(f"{quoted_uri}\n{expiry}")
+    quoted_signature = urllib.parse.quote(signature, safe="")
+    return f"SharedAccessSignature sr={quoted_uri}&sig={quoted_signature}&se={expiry}"
+
+
+def sas_password_provider(
+    resource_uri: str, signer: Signer, ttl: int = DEFAULT_SAS_TTL_SECONDS
+) -> Callable[[], str]:
+    """Return a zero-arg callable that mints a fresh SAS token on each call."""
+
+    def provider() -> str:
+        return build_sas_token(resource_uri, signer, int(time.time()) + ttl)
+
+    return provider
+
+
+def parse_connection_string(connection_string: str) -> dict[str, str]:
+    parts = dict(
+        segment.split("=", 1) for segment in connection_string.split(";") if "=" in segment
+    )
+    return parts
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    """HTTPConnection that talks plain HTTP over a unix domain socket."""
+
+    def __init__(self, socket_path: str) -> None:
+        super().__init__("localhost", timeout=_WORKLOAD_TIMEOUT_SECONDS)
+        self._socket_path = socket_path
+
+    def connect(self) -> None:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(self.timeout)
+        sock.connect(self._socket_path)
+        self.sock = sock
+
+
+def _open_workload_connection(
+    parsed: urllib.parse.ParseResult, sub_path: str, query: str
+) -> tuple[http.client.HTTPConnection, str]:
+    """Build the (connection, request path) pair for the workload endpoint.
+
+    Supports a unix-socket URI (the usual edge case) and http/https URIs (for
+    non-socket environments). The connection is not yet opened.
+    """
+    if parsed.scheme == "unix":
+        return _UnixHTTPConnection(parsed.path), f"/{sub_path}{query}"
+
+    request_path = f"{parsed.path.rstrip('/')}/{sub_path}{query}"
+    if parsed.scheme == "https":
+        connection: http.client.HTTPConnection = http.client.HTTPSConnection(
+            parsed.hostname or "", parsed.port, timeout=_WORKLOAD_TIMEOUT_SECONDS
+        )
+    else:
+        connection = http.client.HTTPConnection(
+            parsed.hostname or "", parsed.port, timeout=_WORKLOAD_TIMEOUT_SECONDS
+        )
+    return connection, request_path
+
+
+def _workload_request(
+    workload_uri: str,
+    method: str,
+    sub_path: str,
+    params: dict[str, str],
+    body: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Call the IoT Edge workload API over its unix socket (or http/https) endpoint.
+
+    ``IOTEDGE_WORKLOADURI`` is typically ``unix:///var/run/iotedge/workload.sock`` on a
+    Linux edge node; http(s) URIs are also handled for non-socket environments.
+    """
+    parsed = urllib.parse.urlparse(workload_uri)
+    query = "?" + urllib.parse.urlencode(params) if params else ""
+    connection, request_path = _open_workload_connection(parsed, sub_path, query)
+
+    headers = {}
+    payload = None
+    if body is not None:
+        payload = json.dumps(body)
+        headers["Content-Type"] = "application/json"
+
+    try:
+        connection.request(method, request_path, body=payload, headers=headers)
+        response = connection.getresponse()
+        data = response.read()
+        if response.status >= 300:
+            raise IoTEdgeError(
+                f"Workload API {method} {sub_path} returned {response.status}: {data!r}"
+            )
+        return json.loads(data)  # type: ignore[no-any-return]
+    except OSError as exc:
+        raise IoTEdgeError(f"Workload API {method} {sub_path} failed: {exc}") from exc
+    finally:
+        connection.close()

helin_edge_sdk-0.0.1/src/helin_edge_sdk/client.py

@@ -0,0 +1,47 @@
+"""Public entry point: tie a :class:`EdgeModuleRequestsHandler` to an MQTT connection."""
+
+from helin_edge_sdk.config import ConnectionConfig
+from helin_edge_sdk.handler import EdgeModuleRequestsHandler
+from helin_edge_sdk.transport import MqttModuleListener
+
+
+class EdgeModuleClient:
+    def __init__(self, config: ConnectionConfig, handler: EdgeModuleRequestsHandler) -> None:
+        self._listener = MqttModuleListener(config, handler)
+
+    @classmethod
+    def from_edge_environment(cls, handler: EdgeModuleRequestsHandler) -> "EdgeModuleClient":
+        """Production constructor: read the ``IOTEDGE_*`` envs injected by edgeHub."""
+        return cls(ConnectionConfig.from_edge_environment(), handler)
+
+    @classmethod
+    def manual(
+        cls,
+        handler: EdgeModuleRequestsHandler,
+        host: str,
+        port: int = 1883,
+        tls: bool = False,
+        connection_string: str | None = None,
+        ca_cert_path: str | None = None,
+        client_id: str = "helin-edge-sdk",
+    ) -> "EdgeModuleClient":
+        """Local/testing constructor: point at a broker by host/port (e.g. mosquitto)."""
+        config = ConnectionConfig.manual(
+            host=host,
+            port=port,
+            tls=tls,
+            connection_string=connection_string,
+            ca_cert_path=ca_cert_path,
+            client_id=client_id,
+        )
+        return cls(config, handler)
+
+    def run(self) -> None:
+        """Block, listening for direct methods until interrupted."""
+        self._listener.run()
+
+    def start(self) -> None:
+        self._listener.start()
+
+    def stop(self) -> None:
+        self._listener.stop()

helin_edge_sdk-0.0.1/src/helin_edge_sdk/compression.py

@@ -0,0 +1,41 @@
+"""Gzip transport envelope for edge-module-requests of the Helin Platform.
+
+Wrapped as:
+``{"encoding": "gzip", "data": "<base64 of gzip-compressed minified JSON>"}``.
+"""
+
+import gzip
+import json
+from base64 import b64decode, b64encode
+from typing import Any
+
+IOTHUB_DIRECT_METHOD_MAX_PAYLOAD_BYTES = 128 * 1024
+
+_ENCODING_KEY = "encoding"
+_DATA_KEY = "data"
+_GZIP_ENCODING = "gzip"
+
+
+def compress_payload(payload: Any) -> dict[str, str]:
+    """Minify, gzip (level 9) and base64-encode ``payload`` into a transport envelope."""
+    json_bytes = json.dumps(payload, separators=(",", ":"), default=str).encode("utf-8")
+    compressed = gzip.compress(json_bytes, compresslevel=9)
+    encoded = b64encode(compressed).decode("ascii")
+    return {_ENCODING_KEY: _GZIP_ENCODING, _DATA_KEY: encoded}
+
+
+def decompress_payload(payload: Any) -> Any:
+    """Reverse :func:`compress_payload`."""
+    if not isinstance(payload, dict):
+        return payload
+    if _DATA_KEY not in payload:
+        return payload
+    compressed = b64decode(payload[_DATA_KEY])
+    decompressed = gzip.decompress(compressed)
+    return json.loads(decompressed)
+
+
+def exceeds_max_payload_size(compressed_envelope: dict[str, str]) -> bool:
+    """Whether the serialized envelope exceeds the 128 KB limit."""
+    serialized = json.dumps(compressed_envelope, separators=(",", ":")).encode("utf-8")
+    return len(serialized) > IOTHUB_DIRECT_METHOD_MAX_PAYLOAD_BYTES

helin_edge_sdk-0.0.1/src/helin_edge_sdk/config.py

@@ -0,0 +1,113 @@
+"""Resolve MQTT connection parameters for edge-environment and manual modes."""
+
+import os
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from helin_edge_sdk.auth import (
+    DEFAULT_SAS_TTL_SECONDS,
+    EdgeWorkloadSigner,
+    LocalKeySigner,
+    parse_connection_string,
+    sas_password_provider,
+)
+
+MQTT_API_VERSION = "2019-10-01"
+MQTT_TLS_PORT = 8883
+MQTT_PLAINTEXT_PORT = 1883
+
+
+@dataclass
+class ConnectionConfig:
+    broker_host: str
+    broker_port: int
+    client_id: str
+    tls: bool
+    username: str | None = None
+    password_provider: Callable[[], str | None] | None = None
+    ca_cert_path: str | None = None
+    # TTL of the SAS token minted by ``password_provider``; lets the listener renew
+    # proactively before expiry. ``None`` when no token auth is used (anonymous broker).
+    sas_ttl_seconds: int | None = None
+
+    @classmethod
+    def from_edge_environment(cls) -> "ConnectionConfig":
+        """Build the production config from the ``IOTEDGE_*`` variables edgeHub injects."""
+        hostname = os.environ["IOTEDGE_IOTHUBHOSTNAME"]
+        device_id = os.environ["IOTEDGE_DEVICEID"]
+        module_id = os.environ["IOTEDGE_MODULEID"]
+        gateway_hostname = os.environ["IOTEDGE_GATEWAYHOSTNAME"]
+        generation_id = os.environ["IOTEDGE_MODULEGENERATIONID"]
+        workload_uri = os.environ["IOTEDGE_WORKLOADURI"]
+        api_version = os.environ["IOTEDGE_APIVERSION"]
+
+        signer = EdgeWorkloadSigner(module_id, generation_id, workload_uri, api_version)
+        ca_cert_path = _write_temp_cert(signer.get_certificate())
+        resource_uri = f"{hostname}/devices/{device_id}/modules/{module_id}"
+
+        return cls(
+            broker_host=gateway_hostname,
+            broker_port=MQTT_TLS_PORT,
+            client_id=f"{device_id}/{module_id}",
+            tls=True,
+            username=_build_username(hostname, device_id, module_id),
+            password_provider=sas_password_provider(resource_uri, signer),
+            ca_cert_path=ca_cert_path,
+            sas_ttl_seconds=DEFAULT_SAS_TTL_SECONDS,
+        )
+
+    @classmethod
+    def manual(
+        cls,
+        host: str,
+        port: int = MQTT_PLAINTEXT_PORT,
+        tls: bool = False,
+        connection_string: str | None = None,
+        ca_cert_path: str | None = None,
+        client_id: str = "helin-edge-sdk",
+    ) -> "ConnectionConfig":
+        """Build a config for local testing.
+
+        With ``connection_string`` the module authenticates with a locally-signed SAS
+        token; without it the connection is anonymous (for a plaintext broker such as
+        a local mosquitto).
+        """
+        if connection_string is None:
+            return cls(
+                broker_host=host,
+                broker_port=port,
+                client_id=client_id,
+                tls=tls,
+                ca_cert_path=ca_cert_path,
+            )
+
+        parts = parse_connection_string(connection_string)
+        hostname = parts["HostName"]
+        device_id = parts["DeviceId"]
+        module_id = parts["ModuleId"]
+        signer = LocalKeySigner(parts["SharedAccessKey"])
+        resource_uri = f"{hostname}/devices/{device_id}/modules/{module_id}"
+        return cls(
+            broker_host=parts.get("GatewayHostName", host),
+            broker_port=port,
+            client_id=f"{device_id}/{module_id}",
+            tls=tls,
+            username=_build_username(hostname, device_id, module_id),
+            password_provider=sas_password_provider(resource_uri, signer),
+            ca_cert_path=ca_cert_path,
+            sas_ttl_seconds=DEFAULT_SAS_TTL_SECONDS,
+        )
+
+
+def _build_username(hostname: str, device_id: str, module_id: str) -> str:
+    return f"{hostname}/{device_id}/{module_id}/?api-version={MQTT_API_VERSION}"
+
+
+def _write_temp_cert(pem: str) -> str:
+    handle = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".pem", prefix="edge-trust-bundle-", delete=False
+    )
+    with handle:
+        handle.write(pem)
+    return handle.name

helin_edge_sdk-0.0.1/src/helin_edge_sdk/errors.py

@@ -0,0 +1,21 @@
+"""Exceptions the SDK maps to direct-method response status codes."""
+
+from typing import Any
+
+
+class ConfigurationFailedError(Exception):
+    """A ``set_configuration`` attempt failed but the module is still healthy.
+
+    The response can carry the configuration state as it stands after the failed
+    attempt, under the ``current_configuration`` key.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 409,
+        current_configuration: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.current_configuration = current_configuration

helin_edge_sdk-0.0.1/src/helin_edge_sdk/handler.py

@@ -0,0 +1,52 @@
+"""The three edge-module-requests methods a module must implement.
+
+The Helin Platform's edge-module-requests API invokes exactly three methods on a
+module: ``get_configuration``, ``set_configuration`` and ``get_health`` (the wire
+names are singular). Subclass :class:`EdgeModuleRequestsHandler`, implement the three
+callbacks, and hand it to :class:`~helin_edge_sdk.client.EdgeModuleClient`.
+
+Each callback receives the already-decompressed request payload (a dict) and
+returns any JSON-serializable value, which the SDK wraps as
+``{"status": 200, "response": <return value>}``. Raise
+:class:`~helin_edge_sdk.errors.ConfigurationFailedError` from
+``on_set_configuration`` to return the configuration-failure envelope.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+GET_CONFIGURATION = "get_configuration"
+SET_CONFIGURATION = "set_configuration"
+GET_HEALTH = "get_health"
+
+SUPPORTED_METHODS = (GET_CONFIGURATION, SET_CONFIGURATION, GET_HEALTH)
+
+
+class EdgeModuleRequestsHandler(ABC):
+    @abstractmethod
+    def on_get_configuration(self, payload: dict[str, Any]) -> Any: ...
+
+    @abstractmethod
+    def on_set_configuration(self, payload: dict[str, Any]) -> Any: ...
+
+    @abstractmethod
+    def on_get_health(self, payload: dict[str, Any]) -> Any: ...
+
+    def dispatch(self, method_name: str, payload: dict[str, Any]) -> Any:
+        """Route ``method_name`` to the matching callback.
+
+        :raises UnknownMethodError: if the method is not one of the three supported.
+        """
+        if method_name == GET_CONFIGURATION:
+            return self.on_get_configuration(payload)
+        if method_name == SET_CONFIGURATION:
+            return self.on_set_configuration(payload)
+        if method_name == GET_HEALTH:
+            return self.on_get_health(payload)
+        raise UnknownMethodError(method_name)
+
+
+class UnknownMethodError(Exception):
+    def __init__(self, method_name: str) -> None:
+        super().__init__(f"Unsupported direct method: {method_name!r}")
+        self.method_name = method_name

helin_edge_sdk-0.0.1/src/helin_edge_sdk/logger.py

@@ -0,0 +1,12 @@
+import logging
+import os
+
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if not logging.getLogger().handlers and not logger.handlers:
+        logging.basicConfig(
+            level=os.getenv("LOG_LEVEL", "INFO").upper(),
+            format="%(asctime)s %(levelname)s %(name)s %(message)s",
+        )
+    return logger

helin_edge_sdk-0.0.1/src/helin_edge_sdk/responses.py

@@ -0,0 +1,58 @@
+"""Direct-method response envelopes."""
+
+from enum import IntEnum
+from typing import Any
+
+from helin_edge_sdk.errors import ConfigurationFailedError
+
+
+class ResponseStatus(IntEnum):
+    OK = 200
+    BAD_REQUEST = 400
+    UNAUTHORIZED = 401
+    NOT_FOUND = 404
+    CONFLICT = 409
+    INTERNAL_SERVER_ERROR = 500
+
+
+def build_ok(response: Any) -> dict[str, Any]:
+    return {"status": ResponseStatus.OK, "response": response}
+
+
+def build_error(status: int, message: str, reason: int = 0) -> dict[str, Any]:
+    """Legacy error envelope used for every error except a configuration failure."""
+    return {"status": status, "error": message, "reason": reason}
+
+
+def build_config_failed(error: ConfigurationFailedError) -> dict[str, Any]:
+    """Configuration-failure envelope carrying the module's current configuration."""
+    return {
+        "status": error.status_code,
+        "response": {
+            "error": str(error),
+            "current_configuration": error.current_configuration,
+        },
+    }
+
+
+def status_for_exception(exception: Exception) -> ResponseStatus:
+    """Map a handler exception to a response status."""
+    if isinstance(exception, ConfigurationFailedError):
+        try:
+            return ResponseStatus(exception.status_code)
+        except ValueError:
+            return ResponseStatus.INTERNAL_SERVER_ERROR
+    if isinstance(exception, ValueError | ConnectionError):
+        return ResponseStatus.BAD_REQUEST
+    if isinstance(exception, FileNotFoundError):
+        return ResponseStatus.NOT_FOUND
+    return ResponseStatus.INTERNAL_SERVER_ERROR
+
+
+def build_for_exception(exception: Exception) -> tuple[ResponseStatus, dict[str, Any]]:
+    """Build the (status, envelope) pair for a handler exception."""
+    if isinstance(exception, ConfigurationFailedError):
+        envelope = build_config_failed(exception)
+        return ResponseStatus(envelope["status"]), envelope
+    status = status_for_exception(exception)
+    return status, build_error(status, str(exception))

helin_edge_sdk-0.0.1/src/helin_edge_sdk/topics.py

@@ -0,0 +1,51 @@
+"""MQTT topic helpers for IoT Hub / edgeHub direct methods.
+
+Requests arrive on ``$iothub/methods/POST/{method}/?$rid={id}`` and responses are
+published to ``$iothub/methods/res/{status}/?$rid={id}`` — the same topics the
+Microsoft SDK uses, so edgeHub routes them unchanged.
+"""
+
+import urllib.parse
+
+METHOD_SUBSCRIBE_TOPIC = "$iothub/methods/POST/#"
+
+_POST_PREFIX = "$iothub/methods/POST/"
+
+
+def is_method_topic(topic: str) -> bool:
+    return topic.startswith(_POST_PREFIX)
+
+
+def parse_method_topic(topic: str) -> tuple[str, str]:
+    """Extract ``(method_name, request_id)`` from an incoming method-request topic.
+
+    :raises ValueError: if the topic is not a well-formed method-request topic.
+    """
+    if not is_method_topic(topic):
+        raise ValueError(f"Not a method topic: {topic!r}")
+    parts = topic.split("/")
+    if len(parts) < 4 or "?" not in topic:
+        raise ValueError(f"Malformed method topic: {topic!r}")
+    method_name = urllib.parse.unquote(parts[3].split("?")[0])
+    query = topic.split("?", 1)[1]
+    properties = _parse_query(query)
+    if "rid" not in properties:
+        raise ValueError(f"Method topic missing $rid: {topic!r}")
+    return method_name, properties["rid"]
+
+
+def build_response_topic(request_id: str, status: int) -> str:
+    return "$iothub/methods/res/{status}/?$rid={rid}".format(
+        status=urllib.parse.quote(str(status), safe=""),
+        rid=urllib.parse.quote(str(request_id), safe=""),
+    )
+
+
+def _parse_query(query: str) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for entry in query.split("&"):
+        if not entry:
+            continue
+        key, _, value = entry.partition("=")
+        result[urllib.parse.unquote(key).lstrip("$")] = urllib.parse.unquote(value)
+    return result

helin_edge_sdk-0.0.1/src/helin_edge_sdk/transport.py

@@ -0,0 +1,162 @@
+"""paho-mqtt transport: subscribe, dispatch a direct method, publish the response."""
+
+import json
+import threading
+from typing import Any
+
+import paho.mqtt.client as mqtt
+from paho.mqtt.enums import CallbackAPIVersion
+
+from helin_edge_sdk.compression import (
+    IOTHUB_DIRECT_METHOD_MAX_PAYLOAD_BYTES,
+    compress_payload,
+    decompress_payload,
+    exceeds_max_payload_size,
+)
+from helin_edge_sdk.config import ConnectionConfig
+from helin_edge_sdk.handler import EdgeModuleRequestsHandler, UnknownMethodError
+from helin_edge_sdk.logger import get_logger
+from helin_edge_sdk.responses import ResponseStatus, build_error, build_for_exception, build_ok
+from helin_edge_sdk.topics import (
+    METHOD_SUBSCRIBE_TOPIC,
+    build_response_topic,
+    is_method_topic,
+    parse_method_topic,
+)
+
+logger = get_logger(__name__)
+
+# Renew the SAS token after this fraction of its TTL
+RENEWAL_FRACTION = 0.8
+
+
+class MqttModuleListener:
+    def __init__(self, config: ConnectionConfig, handler: EdgeModuleRequestsHandler) -> None:
+        self._config = config
+        self._handler = handler
+        self._renewal_timer: threading.Timer | None = None
+        self._client = mqtt.Client(
+            callback_api_version=CallbackAPIVersion.VERSION2,
+            client_id=config.client_id,
+            protocol=mqtt.MQTTv311,
+        )
+        self._client.on_connect = self._on_connect
+        self._client.on_message = self._on_message
+        self._client.on_disconnect = self._on_disconnect
+        self._client.reconnect_delay_set(min_delay=1, max_delay=30)
+        self._apply_credentials()
+        if config.tls:
+            self._client.tls_set(ca_certs=config.ca_cert_path)
+
+    def run(self) -> None:
+        """Connect and block forever, reconnecting on failure."""
+        self._client.connect(self._config.broker_host, self._config.broker_port)
+        self._client.loop_forever()
+
+    def start(self) -> None:
+        """Connect and service the network loop on a background thread (for tests)."""
+        self._client.connect(self._config.broker_host, self._config.broker_port)
+        self._client.loop_start()
+
+    def stop(self) -> None:
+        self._cancel_renewal()
+        self._client.loop_stop()
+        self._client.disconnect()
+
+    def _apply_credentials(self) -> None:
+        if self._config.username is not None:
+            password = self._config.password_provider() if self._config.password_provider else None
+            self._client.username_pw_set(self._config.username, password)
+
+    def _renewal_delay(self) -> float | None:
+        """Seconds until the SAS token should be renewed, or ``None`` if no token auth."""
+        ttl = self._config.sas_ttl_seconds
+        if ttl is None or self._config.password_provider is None:
+            return None
+        return ttl * RENEWAL_FRACTION
+
+    def _schedule_renewal(self) -> None:
+        """(Re)arm the proactive token-renewal timer; no-op when not using token auth."""
+        self._cancel_renewal()
+        delay = self._renewal_delay()
+        if delay is None:
+            return
+        self._renewal_timer = threading.Timer(delay, self._renew)
+        self._renewal_timer.daemon = True
+        self._renewal_timer.start()
+
+    def _cancel_renewal(self) -> None:
+        if self._renewal_timer is not None:
+            self._renewal_timer.cancel()
+            self._renewal_timer = None
+
+    def _renew(self) -> None:
+        """Mint a fresh SAS token and reconnect on our own schedule, before expiry."""
+        try:
+            logger.info("Renewing SAS token and reconnecting")
+            self._apply_credentials()
+            self._client.reconnect()
+        except Exception:  # noqa: BLE001 - a failed renewal just defers to the next reconnect
+            logger.exception("Proactive SAS renewal failed; will retry on next reconnect")
+
+    def _on_connect(
+        self, client: mqtt.Client, userdata: Any, flags: Any, reason_code: Any, properties: Any
+    ) -> None:  # noqa: E501
+        if reason_code != 0:
+            logger.error("MQTT connect failed: %s", reason_code)
+            return
+        logger.info("Connected to broker %s; subscribing", self._config.broker_host)
+        client.subscribe(METHOD_SUBSCRIBE_TOPIC, qos=0)
+        # Arm proactive token renewal for this connection's lifetime.
+        self._schedule_renewal()
+
+    def _on_disconnect(
+        self, client: mqtt.Client, userdata: Any, flags: Any, reason_code: Any, properties: Any
+    ) -> None:  # noqa: E501
+        logger.info("Disconnected from broker (%s); reconnecting", reason_code)
+        # Refresh the SAS token so the automatic reconnect uses a non-expired credential.
+        self._apply_credentials()
+
+    def _on_message(self, client: mqtt.Client, userdata: Any, message: mqtt.MQTTMessage) -> None:
+        topic = message.topic
+        if not is_method_topic(topic):
+            return
+        try:
+            method_name, request_id = parse_method_topic(topic)
+        except ValueError:
+            logger.exception("Ignoring malformed method topic: %s", topic)
+            return
+
+        status, response_payload = self._handle(method_name, message.payload)
+        envelope = compress_payload(response_payload)
+        if exceeds_max_payload_size(envelope):
+            logger.error(
+                "Response to %s (rid=%s) exceeds the %d-byte direct-method limit; "
+                "returning 500",
+                method_name,
+                request_id,
+                IOTHUB_DIRECT_METHOD_MAX_PAYLOAD_BYTES,
+            )
+            status = ResponseStatus.INTERNAL_SERVER_ERROR
+            envelope = compress_payload(
+                build_error(status, "response exceeds the 128 KB edge-module-requests limit")
+            )
+        client.publish(build_response_topic(request_id, status), json.dumps(envelope), qos=0)
+        logger.info("Responded to %s (rid=%s) with status %s", method_name, request_id, status)
+
+    def _handle(
+        self, method_name: str, raw_payload: bytes
+    ) -> tuple[ResponseStatus, dict[str, Any]]:  # noqa: E501
+        try:
+            decoded = json.loads(raw_payload.decode("utf-8") or "null")
+            payload = decompress_payload(decoded)
+            if payload is None:
+                payload = {}
+            result = self._handler.dispatch(method_name, payload)
+            return ResponseStatus.OK, build_ok(result)
+        except UnknownMethodError as exc:
+            logger.warning("%s", exc)
+            return ResponseStatus.BAD_REQUEST, build_error(ResponseStatus.BAD_REQUEST, str(exc))
+        except Exception as exc:  # noqa: BLE001 - handler errors become method responses
+            logger.exception("Error handling method %s", method_name)
+            return build_for_exception(exc)