pyronix-cloud 0.1.0__py3-none-any.whl

pyronix_cloud/cloud.py

@@ -0,0 +1,208 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Cloud relay control language: build `<p>` requests and parse `<e>` replies.
+
+PROTOCOL.md §3.3-3.4.
+
+Requests are ported from ``HomeControl.makeCloudMessage`` (field order exact, no
+XML escaping, ``SaveAppPwd = 0`` so the app password travels in plain text inside
+``<z>``). Replies are parsed from the ``<e>`` position and tolerate the short
+forms seen live (``<e>u</e>``, ``<e>j </e>``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+import enum
+import re
+from typing import Final
+
+from pyronix_cloud.errors import (
+    AccessDeniedError,
+    CloudError,
+    PanelBusyError,
+    PanelOfflineError,
+    SubscriptionExpiredError,
+    UnknownCloudReplyError,
+)
+from pyronix_cloud.transport import wrap
+
+LIVE_URL: Final = "wss://app.pyronixcloud.com:443"
+TEST_URL: Final = "wss://apptestlb.pyronixcloud.com:443"
+APP_VERSION: Final = "6.03.001"
+APP_TYPE: Final = 16
+OS_NAME: Final = "Android"
+OS_VERSION: Final = "14"
+NETWORK_TYPE: Final = "Wifi"
+APP_LANG: Final = "uk"
+DEFAULT_PUSH_ID: Final = "ha-pyronix"
+
+_REQUIRED_FIELDS: Final = ("app_user", "panel_id", "device_id", "push_id")
+_FORBIDDEN_CHARS: Final = frozenset("<>&")
+_REPLY_START: Final = "<e>"
+_REPLY_END: Final = "</e>"
+_SECRET_TAG: Final = re.compile(r"<z>.*?(?:</z>|\Z)", re.DOTALL)
+_REDACTED: Final = "<z>[REDACTED]</z>"
+
+_ERROR_LETTERS: Final[dict[str, type[CloudError]]] = {
+    error.letter: error
+    for error in (
+        AccessDeniedError,
+        PanelBusyError,
+        SubscriptionExpiredError,
+        PanelOfflineError,
+    )
+}
+_OK_LETTERS: Final = frozenset("wmjuox")
+
+
+class CloudRequest(enum.Enum):
+    """The cloud control messages this library sends (``CloudMsgType``)."""
+
+    SUBSCRIPTION = enum.auto()
+    REQ_PWD = enum.auto()
+    CONN_TO_CLOUD = enum.auto()
+    CONN_TO_PANEL = enum.auto()
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CloudIdentity:
+    """The values that identify the app and the panel to the cloud relay.
+
+    Raises:
+        ValueError: A required field is empty, or a field contains ``<``, ``>``
+            or ``&`` (the protocol does no XML escaping). The message names the
+            field, never its value.
+    """
+
+    app_user: str
+    panel_id: str
+    app_password: str = field(repr=False)
+    device_id: str
+    push_id: str = DEFAULT_PUSH_ID
+    system_name: str = "Home"
+
+    def __post_init__(self) -> None:
+        """Validate every field."""
+        for name in _REQUIRED_FIELDS:
+            if not getattr(self, name):
+                msg = f"{name} must not be empty"
+                raise ValueError(msg)
+        for item in fields(self):
+            if _FORBIDDEN_CHARS.intersection(getattr(self, item.name)):
+                msg = f"{item.name} must not contain '<', '>' or '&'"
+                raise ValueError(msg)
+
+
+def _type_tags(identity: CloudIdentity, kind: CloudRequest) -> str:
+    """Return the type-specific tags of a request (PROTOCOL.md §3.3)."""
+    if kind is CloudRequest.SUBSCRIPTION:
+        return f"<w>{identity.panel_id}</w>"
+    if kind is CloudRequest.REQ_PWD:
+        return f"<j>{identity.panel_id}</j>"
+    return (
+        f"<a>{identity.panel_id}</a><b>{identity.system_name}</b>"
+        f"<z>{identity.app_password}</z>"
+    )
+
+
+def build_request(identity: CloudIdentity, kind: CloudRequest) -> str:
+    """Build the WebSocket text of a cloud control request.
+
+    The result contains the app password for the two connect requests; log it
+    only through :func:`redact`, and never log the base64 form.
+
+    Args:
+        identity: The app and panel identity.
+        kind: Which request to build.
+
+    Returns:
+        ``"(" + base64 + ")"`` for the first three kinds, ``"(" + XML + ")"``
+        for :attr:`CloudRequest.CONN_TO_PANEL`.
+    """
+    xml = (
+        f"<p><n>{identity.app_user}</n><u>{identity.push_id}</u>"
+        f"{_type_tags(identity, kind)}"
+        f"<i>{identity.device_id}</i><l>{APP_VERSION}</l><t>{APP_TYPE}</t>"
+        f"<m>{OS_NAME}</m><v>{OS_VERSION}</v><c>{NETWORK_TYPE}</c>"
+        f"<lang>{APP_LANG}</lang></p>"
+    )
+    if kind is CloudRequest.CONN_TO_PANEL:
+        return f"({xml})"
+    return wrap(xml.encode("utf-8"))
+
+
+def redact(text: str) -> str:
+    """Replace the content of every ``<z>…</z>`` tag with ``[REDACTED]``.
+
+    An unterminated ``<z>`` is redacted to the end of the text.
+
+    Args:
+        text: Plain (not base64) request text.
+
+    Returns:
+        The text, safe to log.
+    """
+    return _SECRET_TAG.sub(_REDACTED, text)
+
+
+@dataclass(frozen=True, slots=True)
+class CloudReply:
+    """A parsed ``<e>`` reply from the cloud relay."""
+
+    letter: str
+    data: str = field(repr=False)
+
+
+def is_heartbeat(message: str) -> bool:
+    """Tell whether a text message is the cloud heartbeat.
+
+    Args:
+        message: One inbound WebSocket text message.
+
+    Returns:
+        True only for a single whitespace character. Any other one-character
+        message (such as a split-off ``)``) is frame data.
+    """
+    return len(message) == 1 and message.isspace()
+
+
+def parse_reply(message: str) -> CloudReply | None:
+    """Parse a cloud ``<e>`` reply.
+
+    Parsing starts at ``<e>``, wherever it is. The letter is the next character;
+    the data is what follows the letter and one separator character, up to
+    ``</e>`` (or the end of the text if ``</e>`` is missing).
+
+    Args:
+        message: One inbound WebSocket text message.
+
+    Returns:
+        The reply (with an empty letter if nothing follows ``<e>``), or None if
+        the message holds no ``<e>``.
+    """
+    start = message.find(_REPLY_START)
+    if start < 0:
+        return None
+    start += len(_REPLY_START)
+    end = message.find(_REPLY_END, start)
+    body = message[start:] if end < 0 else message[start:end]
+    return CloudReply(letter=body[:1], data=body[2:])
+
+
+def check_reply(reply: CloudReply) -> None:
+    """Raise the error that a cloud reply letter stands for.
+
+    Args:
+        reply: A parsed reply.
+
+    Raises:
+        CloudError: The matching subclass for ``a``, ``b``, ``i`` and ``n``.
+        UnknownCloudReplyError: The letter is not one of ``a b i n w m j u o x``.
+    """
+    error = _ERROR_LETTERS.get(reply.letter)
+    if error is not None:
+        raise error(error.__doc__)
+    if reply.letter not in _OK_LETTERS:
+        msg = f"unknown cloud reply letter {reply.letter!r}"
+        raise UnknownCloudReplyError(msg)

pyronix_cloud/cloud_stages.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Advance the cloud relay stages from ``<e>`` replies to the panel relay.
+
+PROTOCOL.md §3.4. Sans-IO: each function maps a parsed reply to what the session
+does next, and raises the cloud error for an error letter.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Final
+
+from pyronix_cloud import cloud, errors
+from pyronix_cloud.cloud import CloudReply, CloudRequest
+from pyronix_cloud.session_events import Stage
+
+_NEXT: Final[dict[str, tuple[Stage, CloudRequest]]] = {
+    "w": (Stage.REQUESTING_PASSWORD, CloudRequest.REQ_PWD),
+    "m": (Stage.REQUESTING_PASSWORD, CloudRequest.REQ_PWD),
+    "j": (Stage.CONNECTING_PANEL, CloudRequest.CONN_TO_CLOUD),
+    "u": (Stage.HANDSHAKE, CloudRequest.CONN_TO_PANEL),
+}
+
+
+def next_step(reply: CloudReply) -> tuple[Stage, CloudRequest] | None:
+    """Return the stage and request a reply leads to in the cloud stages.
+
+    Args:
+        reply: A parsed ``<e>`` reply received before the panel relay.
+
+    Returns:
+        The next stage and the request to send, or None for a reply that only
+        acknowledges (``o``, ``x``).
+
+    Raises:
+        CloudError: The reply is an error letter or an unknown one.
+    """
+    cloud.check_reply(reply)
+    return _NEXT.get(reply.letter)
+
+
+def check_relay_reply(reply: CloudReply) -> None:
+    """Check a reply that arrives once the panel relay is up.
+
+    Only error letters matter here; unknown letters and stage letters are
+    ignored, since the session has moved past them.
+
+    Args:
+        reply: A parsed ``<e>`` reply received in a panel stage.
+
+    Raises:
+        CloudError: The reply is a known error letter.
+    """
+    with contextlib.suppress(errors.UnknownCloudReplyError):
+        cloud.check_reply(reply)

pyronix_cloud/commands.py

@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Build application-layer command payloads carried in `D` frames (PROTOCOL.md §5).
+
+These are plaintext payloads; :mod:`pyronix_cloud.frames` encrypts and frames
+them. Only the commands this library uses are defined here.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+HEARTBEAT: Final = 0x20
+SET_AREAS: Final = 0x2D
+UNSET_AREAS: Final = 0x2F
+REQUEST_LOG: Final = 0x35
+
+_MAX_CODE_LEN: Final = 8
+_MAX_AREAS: Final = 127
+_MAX_BYTE: Final = 0xFF
+_FORCE_OMITS: Final = 0x80
+
+
+def login(user_code: str) -> bytes:
+    r"""Build the login payload ``"," + code + "\n"``.
+
+    Args:
+        user_code: The keypad user code, 1 to 8 ASCII digits.
+
+    Returns:
+        The payload. It contains the user code; never log it.
+
+    Raises:
+        ValueError: The code is not 1 to 8 ASCII digits. The message does not
+            contain the code.
+    """
+    if not (
+        0 < len(user_code) <= _MAX_CODE_LEN
+        and user_code.isascii()
+        and user_code.isdigit()
+    ):
+        msg = f"user code must be 1 to {_MAX_CODE_LEN} ASCII digits"
+        raise ValueError(msg)
+    return b"," + user_code.encode("ascii") + b"\n"
+
+
+def heartbeat() -> bytes:
+    """Build the panel heartbeat payload, sent in reply to a cloud heartbeat.
+
+    Returns:
+        ``[0x20]``.
+    """
+    return bytes([HEARTBEAT])
+
+
+def _area_bytes(areas: Iterable[int]) -> bytes:
+    """Validate area numbers and return them sorted, one byte each."""
+    values = list(areas)
+    unique = sorted(set(values))
+    if not 0 < len(values) <= _MAX_AREAS:
+        msg = f"between 1 and {_MAX_AREAS} areas are required, got {len(values)}"
+        raise ValueError(msg)
+    if len(unique) != len(values):
+        msg = "area numbers must be distinct"
+        raise ValueError(msg)
+    if not all(0 <= area <= _MAX_BYTE for area in unique):
+        msg = f"area numbers must be between 0 and {_MAX_BYTE}"
+        raise ValueError(msg)
+    return bytes(unique)
+
+
+def set_areas(areas: Iterable[int], *, force: bool = True) -> bytes:
+    """Build the set (arm) payload ``[0x2D, n | 0x80 if force, areas…]``.
+
+    Args:
+        areas: 1 to 127 distinct area numbers, each 0 to 255.
+        force: Set even if inputs are open, omitting them (the app always does).
+
+    Returns:
+        The payload, with the areas sorted.
+
+    Raises:
+        ValueError: The areas are invalid.
+    """
+    numbers = _area_bytes(areas)
+    flags = _FORCE_OMITS if force else 0
+    return bytes([SET_AREAS, len(numbers) | flags]) + numbers
+
+
+def unset_areas(areas: Iterable[int]) -> bytes:
+    """Build the unset (disarm) payload ``[0x2F, n, areas…]``.
+
+    Args:
+        areas: 1 to 127 distinct area numbers, each 0 to 255.
+
+    Returns:
+        The payload, with the areas sorted.
+
+    Raises:
+        ValueError: The areas are invalid.
+    """
+    numbers = _area_bytes(areas)
+    return bytes([UNSET_AREAS, len(numbers)]) + numbers
+
+
+def request_log(count: int) -> bytes:
+    """Build the event-log request payload ``[0x35, count]``.
+
+    Args:
+        count: How many events to request, 1 to 255.
+
+    Returns:
+        The payload.
+
+    Raises:
+        ValueError: The count is out of range.
+    """
+    if not 0 < count <= _MAX_BYTE:
+        msg = f"log count must be between 1 and {_MAX_BYTE}"
+        raise ValueError(msg)
+    return bytes([REQUEST_LOG, count])

pyronix_cloud/connection.py

@@ -0,0 +1,223 @@
+# SPDX-FileCopyrightText: 2026 Paul Fryer
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Drive a ProtocolSession over a WebSocket: reader task, sends and goodbye.
+
+A :class:`Connection` owns one open socket and one
+:class:`~pyronix_cloud.session.ProtocolSession`. A reader task feeds every
+inbound message into the session, sends what the session asks for and hands
+the events to a callback. Every way out, whether a reader error, a panel
+goodbye, :meth:`Connection.close` or cancellation, sends the session's goodbye
+(best effort) and closes the socket (PROTOCOL.md §4.8).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from functools import partial
+import logging
+from typing import TYPE_CHECKING, Final
+
+import aiohttp
+
+from pyronix_cloud.errors import (
+    ConnectionClosedError,
+    NotConnectedError,
+    ProtocolError,
+    PyronixError,
+    PyronixTimeoutError,
+)
+from pyronix_cloud.session import (
+    DocumentReceived,
+    PanelHeartbeat,
+    SessionEnded,
+    StageChanged,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from pyronix_cloud.session import ProtocolSession, SessionOutput
+    from pyronix_cloud.websocket import Connector, WebSocket
+
+_LOGGER = logging.getLogger(__name__)
+
+_SOCKET_ERRORS: Final = (OSError, aiohttp.ClientError)
+
+type SessionEvent = StageChanged | DocumentReceived | PanelHeartbeat | SessionEnded
+type EventHandler = Callable[[SessionEvent], None]
+type EndHandler = Callable[[PyronixError | None], None]
+
+
+async def open_socket(connector: Connector, url: str, within: float) -> WebSocket:
+    """Open the WebSocket through ``connector`` within ``within`` seconds.
+
+    Raises:
+        PyronixTimeoutError: The socket did not open in time.
+        CommunicationError: The connector could not reach the relay.
+    """
+    try:
+        async with asyncio.timeout(within):
+            return await connector(url)
+    except TimeoutError as err:
+        msg = "timed out opening the cloud WebSocket"
+        raise PyronixTimeoutError(msg) from err
+
+
+class Connection:
+    """One protocol session running over one open WebSocket."""
+
+    def __init__(
+        self,
+        socket: WebSocket,
+        session: ProtocolSession,
+        *,
+        on_event: EventHandler,
+        on_end: EndHandler,
+        close_timeout: float,
+    ) -> None:
+        """Attach to an open socket; nothing is sent until :meth:`start`.
+
+        Args:
+            socket: The open WebSocket to the cloud relay.
+            session: A session that has not been started.
+            on_event: Called with each session event, after the messages the
+                session produced for it have been sent.
+            on_end: Called once if the session ends on its own: with the error,
+                or None after a clean panel goodbye. Not called after
+                :meth:`close`.
+            close_timeout: Seconds allowed for the goodbye and socket close.
+        """
+        self._socket = socket
+        self._session = session
+        self._on_event = on_event
+        self._on_end = on_end
+        self._close_timeout = close_timeout
+        self._lock = asyncio.Lock()
+        self._reader: asyncio.Task[None] | None = None
+        self._closer: asyncio.Task[None] | None = None
+        self._ending = False
+
+    async def start(self) -> None:
+        """Send the session's first request and start the reader task.
+
+        Raises:
+            ConnectionClosedError: The socket failed while sending.
+        """
+        await self._exchange(self._session.start)
+        self._reader = asyncio.get_running_loop().create_task(
+            self._read(), name="pyronix_cloud reader"
+        )
+
+    async def send_command(self, payload: bytes) -> None:
+        """Send one application command to the panel.
+
+        Args:
+            payload: A payload from :mod:`pyronix_cloud.commands`.
+
+        Raises:
+            NotConnectedError: The connection is closing or not in data mode.
+            ConnectionClosedError: The socket failed while sending.
+        """
+        if self._closer is not None:
+            msg = "the panel session is closing"
+            raise NotConnectedError(msg)
+        await self._exchange(lambda: self._session.send_command(payload))
+
+    async def close(self) -> None:
+        """Say goodbye, close the socket and stop the reader. Idempotent.
+
+        The work runs in its own task, so cancelling the caller does not stop
+        the goodbye; it is bounded by ``close_timeout``.
+        """
+        if self._closer is None:
+            self._closer = asyncio.get_running_loop().create_task(
+                self._close(), name="pyronix_cloud close"
+            )
+        await asyncio.shield(self._closer)
+        reader = self._reader
+        if reader is not None and reader is not asyncio.current_task():
+            await asyncio.wait([reader])
+
+    async def _exchange(self, step: Callable[[], SessionOutput]) -> bool:
+        """Run one session step, send its output, then dispatch its events.
+
+        The lock keeps frames in the order the session numbered them.
+
+        Returns:
+            True if the panel ended the session.
+        """
+        async with self._lock:
+            output = step()
+            for message in output.outbound:
+                await self._send(message)
+        for event in output.events:
+            self._on_event(event)
+        return any(isinstance(event, SessionEnded) for event in output.events)
+
+    async def _read(self) -> None:
+        """Feed inbound messages to the session until it ends or fails."""
+        error: PyronixError | None = None
+        try:
+            while True:
+                message = await self._receive()
+                if await self._exchange(partial(self._session.receive, message)):
+                    break
+        except PyronixError as err:
+            error = err
+        except Exception as err:
+            _LOGGER.exception("Unexpected error in the panel session reader")
+            error = ProtocolError(f"unexpected {type(err).__name__} in the reader")
+            error.__cause__ = err
+        self._ending = True
+        _LOGGER.debug("Panel session ended: %s", error or "panel goodbye")
+        await self.close()
+        self._on_end(error)
+
+    async def _send(self, message: str) -> None:
+        """Send one text message, mapping socket failures to library errors."""
+        try:
+            await self._socket.send_text(message)
+        except _SOCKET_ERRORS as err:
+            msg = f"sending failed: {type(err).__name__}"
+            raise ConnectionClosedError(msg) from err
+
+    async def _receive(self) -> str | bytes:
+        """Return the next message, or raise once the socket has closed."""
+        try:
+            message = await self._socket.receive()
+        except _SOCKET_ERRORS as err:
+            msg = f"receiving failed: {type(err).__name__}"
+            raise ConnectionClosedError(msg) from err
+        if message is None:
+            msg = "the cloud relay closed the WebSocket"
+            raise ConnectionClosedError(msg)
+        return message
+
+    async def _close(self) -> None:
+        """Send the goodbye and close the socket within the close timeout."""
+        try:
+            async with asyncio.timeout(self._close_timeout):
+                await self._goodbye()
+        except TimeoutError:
+            _LOGGER.debug("Goodbye not finished within %.1f s", self._close_timeout)
+        self._stop_reader()
+
+    async def _goodbye(self) -> None:
+        """Stop the reader, send the session's goodbye, then close the socket."""
+        async with self._lock:
+            self._stop_reader()
+            for message in self._session.close().outbound:
+                try:
+                    await self._send(message)
+                except PyronixError as err:
+                    _LOGGER.debug("Could not send the goodbye: %s", err)
+                    break
+        try:
+            await self._socket.close()
+        except _SOCKET_ERRORS as err:
+            _LOGGER.debug("Closing the WebSocket failed: %s", type(err).__name__)
+
+    def _stop_reader(self) -> None:
+        """Cancel the reader unless it is the task ending the session."""
+        if self._reader is not None and not self._ending:
+            self._reader.cancel()