aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/central/rpc_server.py

@@ -0,0 +1,353 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+XML-RPC server module.
+
+Provides the XML-RPC server which handles communication
+with the backend.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import threading
+from typing import Any, Final, cast
+from xmlrpc.server import SimpleXMLRPCRequestHandler, SimpleXMLRPCServer
+
+from aiohomematic import i18n
+from aiohomematic.central.decorators import callback_backend_system
+from aiohomematic.const import IP_ANY_V4, PORT_ANY, SystemEventType, UpdateDeviceHint
+from aiohomematic.interfaces.central import RpcServerCentralProtocol, RpcServerTaskSchedulerProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+from aiohomematic.schemas import normalize_device_description
+from aiohomematic.support import get_device_address, log_boundary_error
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+
+# pylint: disable=invalid-name
+class RPCFunctions:
+    """The RPC functions the backend will expect."""
+
+    # Disable kw-only linter
+    __kwonly_check__ = False
+
+    def __init__(self, *, rpc_server: RpcServer) -> None:
+        """Initialize RPCFunctions."""
+        self._rpc_server: Final = rpc_server
+
+    def deleteDevices(self, interface_id: str, addresses: list[str], /) -> None:
+        """Delete devices send from the backend."""
+        if entry := self.get_central_entry(interface_id=interface_id):
+            entry.looper.create_task(
+                target=lambda: entry.central.device_coordinator.delete_devices(
+                    interface_id=interface_id, addresses=tuple(addresses)
+                ),
+                name=f"deleteDevices-{interface_id}",
+            )
+
+    @callback_backend_system(system_event=SystemEventType.ERROR)
+    def error(self, interface_id: str, error_code: str, msg: str, /) -> None:
+        """When some error occurs the backend will send its error message here."""
+        # Structured boundary log (warning level). RPC server received error notification.
+        try:
+            raise RuntimeError(str(msg))
+        except RuntimeError as err:
+            log_boundary_error(
+                logger=_LOGGER,
+                boundary="rpc-server",
+                action="error",
+                err=err,
+                level=logging.WARNING,
+                log_context={"interface_id": interface_id, "error_code": int(error_code)},
+            )
+        _LOGGER.error(
+            i18n.tr(
+                key="log.central.rpc_server.error",
+                interface_id=interface_id,
+                error_code=int(error_code),
+                msg=str(msg),
+            )
+        )
+
+    def event(self, interface_id: str, channel_address: str, parameter: str, value: Any, /) -> None:
+        """If a device publishes some sort event, we will handle it here."""
+        if entry := self.get_central_entry(interface_id=interface_id):
+            entry.looper.create_task(
+                target=lambda: entry.central.event_coordinator.data_point_event(
+                    interface_id=interface_id,
+                    channel_address=channel_address,
+                    parameter=parameter,
+                    value=value,
+                ),
+                name=f"event-{interface_id}-{channel_address}-{parameter}",
+            )
+
+    def get_central_entry(self, *, interface_id: str) -> _CentralEntry | None:
+        """Return the central entry by interface_id."""
+        return self._rpc_server.get_central_entry(interface_id=interface_id)
+
+    def listDevices(self, interface_id: str, /) -> list[dict[str, Any]]:
+        """Return already existing devices to the backend."""
+        # No normalization needed here - data is already normalized in cache
+        if entry := self.get_central_entry(interface_id=interface_id):
+            return [
+                dict(device_description)
+                for device_description in entry.central.device_coordinator.list_devices(interface_id=interface_id)
+            ]
+        return []
+
+    def newDevices(self, interface_id: str, device_descriptions: list[dict[str, Any]], /) -> None:
+        """Add new devices send from the backend (normalized)."""
+        if entry := self.get_central_entry(interface_id=interface_id):
+            # Normalize at callback entry point
+            normalized = tuple(normalize_device_description(device_description=desc) for desc in device_descriptions)
+            entry.looper.create_task(
+                target=entry.central.device_coordinator.add_new_devices(
+                    interface_id=interface_id, device_descriptions=normalized
+                ),
+                name=f"newDevices-{interface_id}",
+            )
+
+    def readdedDevice(self, interface_id: str, addresses: list[str], /) -> None:
+        """
+        Handle re-added device after re-pairing in learn mode.
+
+        Gets called when a known device is put into learn-mode while installation
+        mode is active. The device parameters may have changed, so we refresh
+        the device data.
+        """
+        _LOGGER.debug(
+            "READDEDDEVICES: interface_id = %s, addresses = %s",
+            interface_id,
+            str(addresses),
+        )
+
+        # Filter to device addresses only (exclude channel addresses)
+        if (entry := self.get_central_entry(interface_id=interface_id)) and (
+            device_addresses := tuple(addr for addr in addresses if ":" not in addr)
+        ):
+            entry.looper.create_task(
+                target=lambda: entry.central.device_coordinator.readd_device(
+                    interface_id=interface_id, device_addresses=device_addresses
+                ),
+                name=f"readdedDevice-{interface_id}",
+            )
+
+    def replaceDevice(self, interface_id: str, old_device_address: str, new_device_address: str, /) -> None:
+        """
+        Handle device replacement from CCU.
+
+        Gets called when a user replaces a broken device with a new one using the
+        CCU's "Replace device" function. The old device is removed and the new
+        device is created with fresh descriptions.
+        """
+        _LOGGER.debug(
+            "REPLACEDEVICE: interface_id = %s, oldDeviceAddress = %s, newDeviceAddress = %s",
+            interface_id,
+            old_device_address,
+            new_device_address,
+        )
+
+        if entry := self.get_central_entry(interface_id=interface_id):
+            entry.looper.create_task(
+                target=lambda: entry.central.device_coordinator.replace_device(
+                    interface_id=interface_id,
+                    old_device_address=old_device_address,
+                    new_device_address=new_device_address,
+                ),
+                name=f"replaceDevice-{interface_id}-{old_device_address}-{new_device_address}",
+            )
+
+    def updateDevice(self, interface_id: str, address: str, hint: int, /) -> None:
+        """
+        Update a device after firmware update or link partner change.
+
+        When hint=0 (firmware update), this method triggers cache invalidation
+        and reloading of device/paramset descriptions. When hint=1 (link partner
+        change), it refreshes the link peer information for all channels.
+        """
+        _LOGGER.debug(
+            "UPDATEDEVICE: interface_id = %s, address = %s, hint = %s",
+            interface_id,
+            address,
+            str(hint),
+        )
+
+        if entry := self.get_central_entry(interface_id=interface_id):
+            device_address = get_device_address(address=address)
+            if hint == UpdateDeviceHint.FIRMWARE:
+                # Firmware update: invalidate cache and reload device
+                entry.looper.create_task(
+                    target=lambda: entry.central.device_coordinator.update_device(
+                        interface_id=interface_id, device_address=device_address
+                    ),
+                    name=f"updateDevice-firmware-{interface_id}-{device_address}",
+                )
+            elif hint == UpdateDeviceHint.LINKS:
+                # Link partner change: refresh link peer information
+                entry.looper.create_task(
+                    target=lambda: entry.central.device_coordinator.refresh_device_link_peers(
+                        device_address=device_address
+                    ),
+                    name=f"updateDevice-links-{interface_id}-{device_address}",
+                )
+
+
+# Restrict to specific paths.
+class RequestHandler(SimpleXMLRPCRequestHandler):
+    """We handle requests to / and /RPC2."""
+
+    rpc_paths = (
+        "/",
+        "/RPC2",
+    )
+
+
+class HomematicXMLRPCServer(SimpleXMLRPCServer):
+    """
+    Simple XML-RPC server.
+
+    Simple XML-RPC server that allows functions and a single instance
+    to be installed to handle requests. The default implementation
+    attempts to dispatch XML-RPC calls to the functions or instance
+    installed in the server. Override the _dispatch method inherited
+    from SimpleXMLRPCDispatcher to change this behavior.
+
+    This implementation adds an additional method:
+    system_listMethods(self, interface_id: str.
+    """
+
+    __kwonly_check__ = False
+
+    def system_listMethods(self, interface_id: str | None = None, /) -> list[str]:
+        """Return a list of the methods supported by the server."""
+        return SimpleXMLRPCServer.system_listMethods(self)
+
+
+class _CentralEntry:
+    """Container for central unit with its task scheduler."""
+
+    __slots__ = ("central", "looper")
+
+    def __init__(self, *, central: RpcServerCentralProtocol, looper: RpcServerTaskSchedulerProtocol) -> None:
+        """Initialize central entry."""
+        self.central: Final = central
+        self.looper: Final = looper
+
+
+class RpcServer(threading.Thread):
+    """RPC server thread to handle messages from the backend."""
+
+    _initialized: bool = False
+    _instances: Final[dict[tuple[str, int], RpcServer]] = {}
+
+    def __init__(self, *, server: SimpleXMLRPCServer) -> None:
+        """Initialize XmlRPC server."""
+        self._server = server
+        self._server.register_introspection_functions()
+        self._server.register_multicall_functions()
+        self._server.register_instance(RPCFunctions(rpc_server=self), allow_dotted_names=True)
+        self._initialized = True
+        self._address: Final[tuple[str, int]] = cast(tuple[str, int], server.server_address)
+        self._listen_ip_addr: Final = self._address[0]
+        self._listen_port: Final = self._address[1]
+        self._centrals: Final[dict[str, _CentralEntry]] = {}
+        self._instances[self._address] = self
+        threading.Thread.__init__(self, name=f"RpcServer {self._listen_ip_addr}:{self._listen_port}")
+
+    listen_ip_addr: Final = DelegatedProperty[str](path="_listen_ip_addr")
+    listen_port: Final = DelegatedProperty[int](path="_listen_port")
+
+    @property
+    def no_central_assigned(self) -> bool:
+        """Return if no central is assigned."""
+        return len(self._centrals) == 0
+
+    @property
+    def started(self) -> bool:
+        """Return if thread is active."""
+        return self._started.is_set() is True  # type: ignore[attr-defined]
+
+    def add_central(self, *, central: RpcServerCentralProtocol, looper: RpcServerTaskSchedulerProtocol) -> None:
+        """Register a central in the RPC-Server."""
+        if not self._centrals.get(central.name):
+            self._centrals[central.name] = _CentralEntry(central=central, looper=looper)
+
+    def get_central_entry(self, *, interface_id: str) -> _CentralEntry | None:
+        """Return a central entry by interface_id."""
+        for entry in self._centrals.values():
+            if entry.central.client_coordinator.has_client(interface_id=interface_id):
+                return entry
+        return None
+
+    def remove_central(self, *, central: RpcServerCentralProtocol) -> None:
+        """Unregister a central from RPC-Server."""
+        if self._centrals.get(central.name):
+            del self._centrals[central.name]
+
+    def run(self) -> None:
+        """Run the RPC-Server thread."""
+        _LOGGER.debug(
+            "RUN: Starting RPC-Server listening on %s:%i",
+            self._listen_ip_addr,
+            self._listen_port,
+        )
+        if self._server:
+            self._server.serve_forever()
+
+    def stop(self) -> None:
+        """Stop the RPC-Server."""
+        _LOGGER.debug("STOP: Shutting down RPC-Server")
+        self._server.shutdown()
+        _LOGGER.debug("STOP: Stopping RPC-Server")
+        self._server.server_close()
+        # Ensure the server thread has actually terminated to avoid slow teardown
+        with contextlib.suppress(RuntimeError):
+            self.join(timeout=1.0)
+        _LOGGER.debug("STOP: RPC-Server stopped")
+        if self._address in self._instances:
+            del self._instances[self._address]
+
+
+class XmlRpcServer(RpcServer):
+    """XML-RPC server thread to handle messages from the backend."""
+
+    def __init__(
+        self,
+        *,
+        ip_addr: str,
+        port: int,
+    ) -> None:
+        """Initialize XmlRPC server."""
+        if self._initialized:
+            return
+        super().__init__(
+            server=HomematicXMLRPCServer(
+                addr=(ip_addr, port),
+                requestHandler=RequestHandler,
+                logRequests=False,
+                allow_none=True,
+            )
+        )
+
+    def __new__(cls, ip_addr: str, port: int) -> XmlRpcServer:  # noqa: PYI034  # kwonly: disable
+        """Create new RPC server."""
+        if (rpc := cls._instances.get((ip_addr, port))) is None:
+            _LOGGER.debug("Creating XmlRpc server")
+            return super().__new__(cls)
+        return cast(XmlRpcServer, rpc)
+
+
+def create_xml_rpc_server(*, ip_addr: str = IP_ANY_V4, port: int = PORT_ANY) -> XmlRpcServer:
+    """Register the rpc server."""
+    rpc = XmlRpcServer(ip_addr=ip_addr, port=port)
+    if not rpc.started:
+        rpc.start()
+        _LOGGER.debug(
+            "CREATE_XML_RPC_SERVER: Starting XmlRPC-Server listening on %s:%i",
+            rpc.listen_ip_addr,
+            rpc.listen_port,
+        )
+    return rpc