enapter 0.6.3__py3-none-any.whl → 0.12.1__py3-none-any.whl

enapter/mqtt/api/device/__init__.py

@@ -0,0 +1,21 @@
+from .channel import Channel
+from .command_request import CommandRequest
+from .command_response import CommandResponse
+from .command_state import CommandState
+from .log import Log
+from .log_severity import LogSeverity
+from .message import Message
+from .properties import Properties
+from .telemetry import Telemetry
+
+__all__ = [
+    "CommandRequest",
+    "CommandResponse",
+    "Channel",
+    "CommandState",
+    "Log",
+    "LogSeverity",
+    "Message",
+    "Properties",
+    "Telemetry",
+]

enapter/mqtt/api/device/channel.py

@@ -0,0 +1,56 @@
+from typing import AsyncContextManager, AsyncGenerator
+
+from enapter import async_, mqtt
+
+from .command_request import CommandRequest
+from .command_response import CommandResponse
+from .log import Log
+from .properties import Properties
+from .telemetry import Telemetry
+
+
+class Channel:
+
+    def __init__(self, client: mqtt.Client, hardware_id: str, channel_id: str) -> None:
+        self._client = client
+        self._hardware_id = hardware_id
+        self._channel_id = channel_id
+
+    @property
+    def hardware_id(self) -> str:
+        return self._hardware_id
+
+    @property
+    def channel_id(self) -> str:
+        return self._channel_id
+
+    @async_.generator
+    async def subscribe_to_command_requests(
+        self,
+    ) -> AsyncGenerator[CommandRequest, None]:
+        async with self._subscribe("v1/command/requests") as messages:
+            async for msg in messages:
+                assert isinstance(msg.payload, str) or isinstance(msg.payload, bytes)
+                yield CommandRequest.from_json(msg.payload)
+
+    async def publish_command_response(self, response: CommandResponse) -> None:
+        await self._publish("v1/command/responses", response.to_json())
+
+    async def publish_telemetry(self, telemetry: Telemetry, **kwargs) -> None:
+        await self._publish("v1/telemetry", telemetry.to_json(), **kwargs)
+
+    async def publish_properties(self, properties: Properties, **kwargs) -> None:
+        await self._publish("v1/register", properties.to_json(), **kwargs)
+
+    async def publish_log(self, log: Log, **kwargs) -> None:
+        await self._publish("v3/logs", log.to_json(), **kwargs)
+
+    def _subscribe(
+        self, path: str
+    ) -> AsyncContextManager[AsyncGenerator[mqtt.Message, None]]:
+        topic = f"v1/to/{self._hardware_id}/{self._channel_id}/{path}"
+        return self._client.subscribe(topic)
+
+    async def _publish(self, path: str, payload: str, **kwargs) -> None:
+        topic = f"v1/from/{self._hardware_id}/{self._channel_id}/{path}"
+        await self._client.publish(topic, payload, **kwargs)

enapter/mqtt/api/device/command_request.py

@@ -0,0 +1,38 @@
+import dataclasses
+from typing import Any, Self
+
+from .command_response import CommandResponse
+from .command_state import CommandState
+from .message import Message
+
+
+@dataclasses.dataclass
+class CommandRequest(Message):
+
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        return cls(
+            id=dto["id"],
+            name=dto["name"],
+            arguments=dto.get("arguments", {}),
+        )
+
+    def to_dto(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "arguments": self.arguments,
+        }
+
+    def new_response(
+        self, state: CommandState, payload: dict[str, Any]
+    ) -> CommandResponse:
+        return CommandResponse(
+            id=self.id,
+            state=state,
+            payload=payload,
+        )

enapter/mqtt/api/device/command_response.py

@@ -0,0 +1,28 @@
+import dataclasses
+from typing import Any, Self
+
+from .command_state import CommandState
+from .message import Message
+
+
+@dataclasses.dataclass
+class CommandResponse(Message):
+
+    id: str
+    state: CommandState
+    payload: dict[str, Any]
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        return cls(
+            id=dto["id"],
+            state=CommandState(dto["state"]),
+            payload=dto.get("payload", {}),
+        )
+
+    def to_dto(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "state": self.state.value,
+            "payload": self.payload,
+        }

enapter/mqtt/api/device/command_state.py

@@ -0,0 +1,8 @@
+import enum
+
+
+class CommandState(enum.Enum):
+
+    COMPLETED = "completed"
+    ERROR = "error"
+    LOG = "log"

enapter/mqtt/api/device/log.py

@@ -0,0 +1,31 @@
+import dataclasses
+from typing import Any, Self
+
+from .log_severity import LogSeverity
+from .message import Message
+
+
+@dataclasses.dataclass
+class Log(Message):
+
+    timestamp: int
+    message: str
+    severity: LogSeverity
+    persist: bool
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        return cls(
+            timestamp=dto["timestamp"],
+            message=dto["message"],
+            severity=LogSeverity(dto["severity"]),
+            persist=dto["persist"],
+        )
+
+    def to_dto(self) -> dict[str, Any]:
+        return {
+            "timestamp": self.timestamp,
+            "message": self.message,
+            "severity": self.severity.value,
+            "persist": self.persist,
+        }

enapter/mqtt/api/device/log_severity.py

@@ -0,0 +1,9 @@
+import enum
+
+
+class LogSeverity(enum.Enum):
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"

enapter/mqtt/api/device/message.py

@@ -0,0 +1,24 @@
+import abc
+import json
+from typing import Any, Self
+
+
+class Message(abc.ABC):
+
+    @classmethod
+    @abc.abstractmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        pass
+
+    @abc.abstractmethod
+    def to_dto(self) -> dict[str, Any]:
+        pass
+
+    @classmethod
+    def from_json(cls, data: str | bytes) -> Self:
+        dto = json.loads(data)
+        return cls.from_dto(dto)
+
+    def to_json(self) -> str:
+        dto = self.to_dto()
+        return json.dumps(dto)

enapter/mqtt/api/device/properties.py

@@ -0,0 +1,24 @@
+import dataclasses
+from typing import Any, Self
+
+from .message import Message
+
+
+@dataclasses.dataclass
+class Properties(Message):
+
+    timestamp: int
+    values: dict[str, Any] = dataclasses.field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if "timestamp" in self.values:
+            raise ValueError("`timestamp` is reserved")
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        timestamp = dto["timestamp"]
+        values = {k: v for k, v in dto.items() if k != "timestamp"}
+        return cls(timestamp=timestamp, values=values)
+
+    def to_dto(self) -> dict[str, Any]:
+        return {"timestamp": self.timestamp, **self.values}

enapter/mqtt/api/device/telemetry.py

@@ -0,0 +1,28 @@
+import dataclasses
+from typing import Any, Self
+
+from .message import Message
+
+
+@dataclasses.dataclass
+class Telemetry(Message):
+
+    timestamp: int
+    alerts: list[str] | None = None
+    values: dict[str, Any] = dataclasses.field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if "timestamp" in self.values:
+            raise ValueError("`timestamp` is reserved")
+        if "alerts" in self.values:
+            raise ValueError("`alerts` is reserved")
+
+    @classmethod
+    def from_dto(cls, dto: dict[str, Any]) -> Self:
+        dto = dto.copy()
+        timestamp = dto.pop("timestamp")
+        alerts = dto.pop("alerts", None)
+        return cls(timestamp=timestamp, alerts=alerts, values=dto)
+
+    def to_dto(self) -> dict[str, Any]:
+        return {"timestamp": self.timestamp, "alerts": self.alerts, **self.values}

enapter/mqtt/client.py

@@ -2,157 +2,126 @@ import asyncio
 import contextlib
 import logging
 import ssl
-import tempfile
+from typing import AsyncGenerator
 
-import asyncio_mqtt
+import aiomqtt  # type: ignore
 
-from .. import async_, mdns
-from .device_channel import DeviceChannel
+from enapter import async_, mdns
+
+from .message import Message
 
 LOGGER = logging.getLogger(__name__)
 
 
 class Client(async_.Routine):
-    def __init__(self, config):
-        self._logger = self._new_logger(config)
-        self._config = config
-        self._mdns_resolver = mdns.Resolver()
-        self._tls_context = self._new_tls_context(config)
-        self._lock = asyncio.Lock()
-        self._client = None
-        self._client_ready = asyncio.Event()
-
-    @staticmethod
-    def _new_logger(config):
-        extra = {"host": config.host, "port": config.port}
-        return logging.LoggerAdapter(LOGGER, extra=extra)
-
-    def config(self):
-        return self._config
-
-    def device_channel(self, hardware_id, channel_id):
-        return DeviceChannel(
-            client=self, hardware_id=hardware_id, channel_id=channel_id
-        )
 
-    async def publish(self, *args, **kwargs):
-        client = None
-
-        while True:
-            await self._client_ready.wait()
-            async with self._lock:
-                if self._client_ready.is_set():
-                    client = self._client
-                    break
+    def __init__(
+        self,
+        hostname: str,
+        port: int = 1883,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        tls_context: ssl.SSLContext | None = None,
+        task_group: asyncio.TaskGroup | None = None
+    ) -> None:
+        super().__init__(task_group=task_group)
+        self._logger = logging.LoggerAdapter(
+            LOGGER, extra={"hostname": hostname, "port": port}
+        )
+        self._hostname = hostname
+        self._port = port
+        self._username = username
+        self._password = password
+        self._tls_context = tls_context
+        self._mdns_resolver = mdns.Resolver()
+        self._publisher: aiomqtt.Client | None = None
+        self._publisher_connected = asyncio.Event()
 
-        await client.publish(*args, **kwargs)
+    async def publish(self, *args, **kwargs) -> None:
+        await self._publisher_connected.wait()
+        assert self._publisher is not None
+        await self._publisher.publish(*args, **kwargs)
 
     @async_.generator
-    async def subscribe(self, topic):
+    async def subscribe(self, *topics: str) -> AsyncGenerator[Message, None]:
         while True:
-            client = None
-
-            while True:
-                await self._client_ready.wait()
-                async with self._lock:
-                    if self._client_ready.is_set():
-                        client = self._client
-                        break
-
             try:
-                async with client.filtered_messages(topic) as messages:
-                    await client.subscribe(topic)
-                    async for msg in messages:
+                async with self._connect() as subscriber:
+                    for topic in topics:
+                        await subscriber.subscribe(topic)
+                    self._logger.info("subscriber [%s] connected", ",".join(topics))
+                    async for msg in subscriber.messages:
                         yield msg
-
-            except asyncio_mqtt.MqttError as e:
+            except aiomqtt.MqttError as e:
                 self._logger.error(e)
                 retry_interval = 5
                 await asyncio.sleep(retry_interval)
 
-    async def _run(self):
+    async def _run(self) -> None:
         self._logger.info("starting")
-
-        self._started.set()
-
         while True:
             try:
-                async with self._connect() as client:
-                    async with self._lock:
-                        self._client = client
-                        self._client_ready.set()
-                        self._logger.info("client ready")
-
-                    async with client.unfiltered_messages() as messages:
-                        async for message in messages:
-                            self._logger.warn(
-                                "received unfiltered message: %s", message.topic
-                            )
-            except asyncio_mqtt.MqttError as e:
+                async with self._connect() as publisher:
+                    self._logger.info("publisher connected")
+                    self._publisher = publisher
+                    self._publisher_connected.set()
+                    async for msg in publisher.messages:
+                        pass
+            except aiomqtt.MqttError as e:
                 self._logger.error(e)
                 retry_interval = 5
                 await asyncio.sleep(retry_interval)
             finally:
-                async with self._lock:
-                    self._client_ready.clear()
-                    self._client = None
-                    self._logger.info("client not ready")
+                self._publisher_connected.clear()
+                self._publisher = None
 
     @contextlib.asynccontextmanager
-    async def _connect(self):
-        host = await self._maybe_resolve_mdns(self._config.host)
-
-        try:
-            async with asyncio_mqtt.Client(
-                hostname=host,
-                port=self._config.port,
-                username=self._config.user,
-                password=self._config.password,
-                logger=self._logger,
-                tls_context=self._tls_context,
-            ) as client:
-                yield client
-        except asyncio.CancelledError:
-            # FIXME: A cancelled `asyncio_mqtt.Client.connect` leaks resources.
-            raise
-
-    @staticmethod
-    def _new_tls_context(config):
-        if not config.tls_enabled:
-            return None
-
-        ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
-
-        ctx.verify_mode = ssl.CERT_REQUIRED
-        ctx.check_hostname = False
-        ctx.load_verify_locations(None, None, config.tls_ca_cert)
-
-        with contextlib.ExitStack() as stack:
-            certfile = stack.enter_context(tempfile.NamedTemporaryFile())
-            certfile.write(config.tls_cert.encode())
-            certfile.flush()
-
-            keyfile = stack.enter_context(tempfile.NamedTemporaryFile())
-            keyfile.write(config.tls_secret_key.encode())
-            keyfile.flush()
-
-            ctx.load_cert_chain(certfile.name, keyfile=keyfile.name)
-
-        return ctx
-
-    async def _maybe_resolve_mdns(self, host):
-        if not host.endswith(".local"):
-            return host
+    async def _connect(self) -> AsyncGenerator[aiomqtt.Client, None]:
+        hostname = await self._maybe_resolve_hostname()
+        async with _new_aiomqtt_client(
+            hostname=hostname,
+            port=self._port,
+            username=self._username,
+            password=self._password,
+            logger=LOGGER,
+            tls_context=self._tls_context,
+        ) as client:
+            yield client
+
+    async def _maybe_resolve_hostname(self) -> str:
+        if not self._hostname.endswith(".local"):
+            return self._hostname
 
         while True:
             try:
-                ip = await self._mdns_resolver.resolve(host)
+                return await self._mdns_resolver.resolve(self._hostname)
             except Exception as e:
-                self._logger.error("failed to resolve mDNS host %r: %s", host, e)
+                self._logger.error("failed to resolve mDNS host: %s", e)
                 retry_interval = 5
                 await asyncio.sleep(retry_interval)
-                continue
 
-        self._logger.info("mDNS host resolved: %s", ip)
 
-        return ip
+@contextlib.asynccontextmanager
+async def _new_aiomqtt_client(*args, **kwargs) -> AsyncGenerator[aiomqtt.Client, None]:
+    """
+    Creates `aiomqtt.Client` shielding `__aenter__` from cancellation.
+
+    See:
+        - https://github.com/empicano/aiomqtt/issues/377
+    """
+    client = aiomqtt.Client(*args, **kwargs)
+    setup_task = asyncio.create_task(client.__aenter__())
+    try:
+        await asyncio.shield(setup_task)
+    except asyncio.CancelledError as e:
+        await setup_task
+        await client.__aexit__(type(e), e, e.__traceback__)
+        raise
+    try:
+        yield client
+    except BaseException as e:
+        await client.__aexit__(type(e), e, e.__traceback__)
+        raise
+    else:
+        await client.__aexit__(None, None, None)

enapter/mqtt/errors.py

@@ -0,0 +1,3 @@
+import aiomqtt
+
+Error = aiomqtt.MqttError

enapter/mqtt/message.py

@@ -0,0 +1,3 @@
+import aiomqtt
+
+Message = aiomqtt.Message

enapter/standalone/__init__.py

@@ -0,0 +1,25 @@
+from .config import Config
+from .device import Device
+from .device_protocol import (
+    CommandArgs,
+    CommandResult,
+    DeviceProtocol,
+    Log,
+    Properties,
+    Telemetry,
+)
+from .logger import Logger
+from .run import run
+
+__all__ = [
+    "CommandArgs",
+    "CommandResult",
+    "Config",
+    "Device",
+    "DeviceProtocol",
+    "Log",
+    "Logger",
+    "Properties",
+    "Telemetry",
+    "run",
+]