aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/central/state_machine.py

@@ -0,0 +1,391 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Central state machine for orchestrating overall system health.
+
+This module provides the CentralStateMachine which manages the overall state
+of the system based on individual client states. It acts as an orchestrator
+above the client-level state machines.
+
+Overview
+--------
+The CentralStateMachine provides:
+- Unified view of system health
+- Coordinated state transitions
+- Event emission for state changes
+- Validation of state transitions
+
+State Machine
+-------------
+```
+STARTING ──► INITIALIZING ──► RUNNING ◄──► DEGRADED
+                  │              │            │
+                  │              ▼            ▼
+                  │          RECOVERING ◄────┘
+                  │              │
+                  │              ├──► RUNNING
+                  │              ├──► DEGRADED
+                  │              └──► FAILED
+                  │
+                  └──► FAILED
+
+STOPPED ◄── (from any state)
+```
+
+The CentralStateMachine observes client state machines and determines the
+overall system state:
+- RUNNING: All clients are CONNECTED
+- DEGRADED: At least one client is not CONNECTED
+- RECOVERING: Recovery is in progress
+- FAILED: Max retries reached, manual intervention required
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+import logging
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final
+
+from aiohomematic.central.events import SystemStatusChangedEvent
+from aiohomematic.central.events.types import CentralStateChangedEvent
+from aiohomematic.const import CentralState, FailureReason
+from aiohomematic.interfaces import CentralStateMachineProtocol
+from aiohomematic.property_decorators import DelegatedProperty
+
+if TYPE_CHECKING:
+    from aiohomematic.central.events import EventBus
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+# Valid state transitions define which state changes are allowed.
+# This forms a directed graph where each state maps to its valid successors.
+VALID_CENTRAL_TRANSITIONS: Final[dict[CentralState, frozenset[CentralState]]] = {
+    # Initial state - Central is being created
+    CentralState.STARTING: frozenset(
+        {
+            CentralState.INITIALIZING,
+            CentralState.STOPPED,  # stop() before start()
+        }
+    ),
+    # During initialization - clients are being initialized
+    CentralState.INITIALIZING: frozenset(
+        {
+            CentralState.RUNNING,  # All clients OK
+            CentralState.DEGRADED,  # At least one client not OK
+            CentralState.FAILED,  # Critical init error
+            CentralState.STOPPED,  # stop() during init
+        }
+    ),
+    # Normal operation - all clients connected
+    CentralState.RUNNING: frozenset(
+        {
+            CentralState.DEGRADED,  # Client problem detected
+            CentralState.RECOVERING,  # Proactive recovery
+            CentralState.STOPPED,  # Graceful shutdown
+        }
+    ),
+    # Limited operation - at least one client not connected
+    CentralState.DEGRADED: frozenset(
+        {
+            CentralState.RUNNING,  # All clients recovered
+            CentralState.RECOVERING,  # Start recovery
+            CentralState.FAILED,  # Too long degraded
+            CentralState.STOPPED,  # Shutdown
+        }
+    ),
+    # Active recovery in progress
+    CentralState.RECOVERING: frozenset(
+        {
+            CentralState.RUNNING,  # Recovery successful
+            CentralState.DEGRADED,  # Partial recovery
+            CentralState.FAILED,  # Max retries reached
+            CentralState.STOPPED,  # Shutdown during recovery
+        }
+    ),
+    # Critical error - manual intervention required
+    CentralState.FAILED: frozenset(
+        {
+            CentralState.RECOVERING,  # Manual retry
+            CentralState.STOPPED,  # Shutdown
+        }
+    ),
+    # Terminal state - no transitions allowed
+    CentralState.STOPPED: frozenset(),
+}
+
+
+class InvalidCentralStateTransitionError(Exception):
+    """Raised when an invalid central state transition is attempted."""
+
+    def __init__(self, *, current: CentralState, target: CentralState, central_name: str) -> None:
+        """Initialize the error."""
+        self.current = current
+        self.target = target
+        self.central_name = central_name
+        super().__init__(f"Invalid central state transition from {current.value} to {target.value} for {central_name}")
+
+
+class CentralStateMachine(CentralStateMachineProtocol):
+    """
+    State machine for central system health orchestration.
+
+    This class manages the overall state of the central system based on
+    individual client states. It provides:
+    - Unified system state (RUNNING, DEGRADED, RECOVERING, FAILED)
+    - Validated state transitions
+    - Event emission for monitoring via EventBus
+
+    Thread Safety
+    -------------
+    This class is NOT thread-safe. All calls should happen from the same
+    event loop/thread.
+
+    Example:
+        from aiohomematic.central.events import CentralStateChangedEvent, EventBus
+
+        def on_state_changed(*, event: CentralStateChangedEvent) -> None:
+            print(f"Central state: {event.old_state} -> {event.new_state}")
+
+        event_bus = EventBus()
+        sm = CentralStateMachine(central_name="ccu-main", event_bus=event_bus)
+
+        # Subscribe to state changes via EventBus
+        event_bus.subscribe(
+            event_type=CentralStateChangedEvent,
+            handler=on_state_changed,
+        )
+
+        sm.transition_to(target=CentralState.INITIALIZING, reason="start() called")
+        sm.transition_to(target=CentralState.RUNNING, reason="all clients connected")
+
+    """
+
+    __slots__ = (
+        "_central_name",
+        "_degraded_interfaces",
+        "_event_bus",
+        "_failure_interface_id",
+        "_failure_message",
+        "_failure_reason",
+        "_last_state_change",
+        "_state",
+        "_state_history",
+    )
+
+    def __init__(
+        self,
+        *,
+        central_name: str,
+        event_bus: EventBus | None = None,
+    ) -> None:
+        """
+        Initialize the central state machine.
+
+        Args:
+            central_name: Name of the central unit for logging
+            event_bus: Optional event bus for publishing state change events
+
+        """
+        self._central_name: Final = central_name
+        self._event_bus = event_bus
+        self._state: CentralState = CentralState.STARTING
+        self._failure_reason: FailureReason = FailureReason.NONE
+        self._failure_message: str = ""
+        self._failure_interface_id: str | None = None
+        self._degraded_interfaces: Mapping[str, FailureReason] = MappingProxyType({})
+        self._last_state_change: datetime = datetime.now()
+        self._state_history: list[tuple[datetime, CentralState, CentralState, str]] = []
+
+    degraded_interfaces: Final = DelegatedProperty[Mapping[str, FailureReason]](path="_degraded_interfaces")
+    failure_interface_id: Final = DelegatedProperty[str | None](path="_failure_interface_id")
+    failure_message: Final = DelegatedProperty[str](path="_failure_message")
+    failure_reason: Final = DelegatedProperty[FailureReason](path="_failure_reason")
+    last_state_change: Final = DelegatedProperty[datetime](path="_last_state_change")
+    state: Final = DelegatedProperty[CentralState](path="_state")
+
+    @property
+    def is_degraded(self) -> bool:
+        """Return True if system is in degraded state."""
+        return self._state == CentralState.DEGRADED
+
+    @property
+    def is_failed(self) -> bool:
+        """Return True if system is in failed state."""
+        return self._state == CentralState.FAILED
+
+    @property
+    def is_operational(self) -> bool:
+        """Return True if system is operational (RUNNING or DEGRADED)."""
+        return self._state in (CentralState.RUNNING, CentralState.DEGRADED)
+
+    @property
+    def is_recovering(self) -> bool:
+        """Return True if recovery is in progress."""
+        return self._state == CentralState.RECOVERING
+
+    @property
+    def is_running(self) -> bool:
+        """Return True if system is fully running."""
+        return self._state == CentralState.RUNNING
+
+    @property
+    def is_stopped(self) -> bool:
+        """Return True if system is stopped."""
+        return self._state == CentralState.STOPPED
+
+    @property
+    def seconds_in_current_state(self) -> float:
+        """Return seconds since last state change."""
+        return (datetime.now() - self._last_state_change).total_seconds()
+
+    @property
+    def state_history(self) -> list[tuple[datetime, CentralState, CentralState, str]]:
+        """Return state transition history (timestamp, old_state, new_state, reason)."""
+        return self._state_history.copy()
+
+    def can_transition_to(self, *, target: CentralState) -> bool:
+        """
+        Check if transition to target state is valid.
+
+        Args:
+            target: Target state to check
+
+        Returns:
+            True if transition is valid, False otherwise
+
+        """
+        return target in VALID_CENTRAL_TRANSITIONS.get(self._state, frozenset())
+
+    def set_event_bus(self, *, event_bus: EventBus) -> None:
+        """
+        Set the event bus for publishing state change events.
+
+        This is useful when the event bus is created after the state machine.
+
+        Args:
+            event_bus: The event bus to use
+
+        """
+        self._event_bus = event_bus
+
+    def transition_to(
+        self,
+        *,
+        target: CentralState,
+        reason: str = "",
+        force: bool = False,
+        failure_reason: FailureReason = FailureReason.NONE,
+        failure_interface_id: str | None = None,
+        degraded_interfaces: Mapping[str, FailureReason] | None = None,
+    ) -> None:
+        """
+        Transition to a new state.
+
+        Args:
+            target: Target state to transition to
+            reason: Human-readable reason for the transition
+            force: If True, skip validation (use with caution)
+            failure_reason: Categorized failure reason (only used when target is FAILED)
+            failure_interface_id: Interface ID that caused the failure (optional)
+            degraded_interfaces: Map of interface_id to failure reason (only used when target is DEGRADED)
+
+        Raises:
+            InvalidCentralStateTransitionError: If transition is not valid and force=False
+
+        """
+        if not force and not self.can_transition_to(target=target):
+            raise InvalidCentralStateTransitionError(
+                current=self._state,
+                target=target,
+                central_name=self._central_name,
+            )
+
+        old_state = self._state
+        self._state = target
+        self._last_state_change = datetime.now()
+
+        # Track failure reason when entering FAILED state
+        if target == CentralState.FAILED:
+            self._failure_reason = failure_reason
+            self._failure_message = reason
+            self._failure_interface_id = failure_interface_id
+            self._degraded_interfaces = MappingProxyType({})
+        elif target == CentralState.DEGRADED:
+            # Track degraded interfaces with their reasons
+            self._degraded_interfaces = MappingProxyType(dict(degraded_interfaces or {}))
+        elif target == CentralState.RUNNING:
+            # Clear failure and degraded info on successful state
+            self._failure_reason = FailureReason.NONE
+            self._failure_message = ""
+            self._failure_interface_id = None
+            self._degraded_interfaces = MappingProxyType({})
+
+        # Record in history (keep last 100 transitions)
+        self._state_history.append((self._last_state_change, old_state, target, reason))
+        if len(self._state_history) > 100:
+            self._state_history = self._state_history[-100:]
+
+        # Log the transition
+        if old_state != target:
+            extra_info = ""
+            if target == CentralState.FAILED:
+                extra_info = f" [reason={failure_reason.value}]"
+            elif target == CentralState.DEGRADED and degraded_interfaces:
+                iface_reasons = ", ".join(f"{k}={v.value}" for k, v in degraded_interfaces.items())
+                extra_info = f" [interfaces: {iface_reasons}]"
+            _LOGGER.info(  # i18n-log: ignore
+                "CENTRAL_STATE: %s: %s -> %s (%s)%s",
+                self._central_name,
+                old_state.value,
+                target.value,
+                reason or "no reason specified",
+                extra_info,
+            )
+
+        # Publish event to event bus
+        if self._event_bus is not None:
+            self._publish_state_change_event(old_state=old_state, new_state=target, reason=reason)
+
+    def _publish_state_change_event(self, *, old_state: CentralState, new_state: CentralState, reason: str) -> None:
+        """
+        Publish state change event to the event bus.
+
+        Args:
+            old_state: Previous state
+            new_state: New state
+            reason: Reason for the transition
+
+        """
+        if self._event_bus is None:
+            return
+
+        # Include failure info when transitioning to FAILED state
+        failure_reason = self._failure_reason if new_state == CentralState.FAILED else None
+        failure_interface_id = self._failure_interface_id if new_state == CentralState.FAILED else None
+
+        # Include degraded interfaces when transitioning to DEGRADED state
+        degraded_interfaces = self._degraded_interfaces if new_state == CentralState.DEGRADED else None
+
+        # Emit SystemStatusChangedEvent for integration compatibility
+        self._event_bus.publish_sync(
+            event=SystemStatusChangedEvent(
+                timestamp=self._last_state_change,
+                central_state=new_state,
+                failure_reason=failure_reason,
+                failure_interface_id=failure_interface_id,
+                degraded_interfaces=degraded_interfaces,
+            )
+        )
+
+        # Emit CentralStateChangedEvent for observability
+        self._event_bus.publish_sync(
+            event=CentralStateChangedEvent(
+                timestamp=self._last_state_change,
+                central_name=self._central_name,
+                old_state=old_state,
+                new_state=new_state,
+                trigger=reason or None,
+            )
+        )

aiohomematic/client/__init__.py

@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Client adapters for communicating with Homematic CCU and compatible backends.
+
+This package provides client implementations that abstract the transport details
+of Homematic backends (CCU via JSON-RPC/XML-RPC or Homegear) and expose a
+consistent API used by the central module.
+
+Package structure
+-----------------
+- ccu.py: Client implementations (ClientCCU, ClientJsonCCU, ClientHomegear, ClientConfig)
+- config.py: InterfaceConfig for per-interface connection settings
+- circuit_breaker.py: CircuitBreaker, CircuitBreakerConfig, CircuitState
+- state_machine.py: ClientStateMachine for connection state tracking
+- rpc_proxy.py: BaseRpcProxy, AioXmlRpcProxy for XML-RPC transport
+- json_rpc.py: AioJsonRpcAioHttpClient for JSON-RPC transport
+- request_coalescer.py: RequestCoalescer for deduplicating concurrent requests
+- handlers/: Protocol-specific operation handlers
+- backends/: Backend strategy implementations (CCU, CCU-Jack, Homegear)
+- interface_client.py: InterfaceClient using backend strategy pattern
+
+Public API
+----------
+- Clients: ClientCCU, ClientJsonCCU, ClientHomegear, ClientConfig, InterfaceClient
+- Configuration: InterfaceConfig
+- Circuit breaker: CircuitBreaker, CircuitBreakerConfig, CircuitState
+- State machine: ClientStateMachine, InvalidStateTransitionError
+- Transport: BaseRpcProxy, AioJsonRpcAioHttpClient
+- Coalescing: RequestCoalescer, make_coalesce_key
+- Factory functions: create_client, get_client
+
+Notes
+-----
+- Most users interact with clients via CentralUnit; direct usage is for advanced scenarios
+- Clients are created via ClientConfig.create_client() or the create_client() function
+- XML-RPC is used for device operations; JSON-RPC for metadata/programs/sysvars (CCU only)
+- InterfaceClient with backends can be enabled via:
+  - OptionalSettings.USE_INTERFACE_CLIENT in config, OR
+  - Environment variable AIOHOMEMATIC_USE_INTERFACE_CLIENT=1 (for CI testing)
+
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Final
+
+from aiohomematic import central as hmcu, i18n
+from aiohomematic.client.backends import create_backend
+from aiohomematic.client.ccu import ClientCCU, ClientConfig, ClientHomegear, ClientJsonCCU
+from aiohomematic.client.circuit_breaker import CircuitBreaker, CircuitBreakerConfig
+from aiohomematic.client.config import InterfaceConfig
+from aiohomematic.client.interface_client import InterfaceClient
+from aiohomematic.client.json_rpc import AioJsonRpcAioHttpClient
+from aiohomematic.client.request_coalescer import RequestCoalescer, make_coalesce_key
+from aiohomematic.client.rpc_proxy import BaseRpcProxy
+from aiohomematic.client.state_machine import ClientStateMachine, InvalidStateTransitionError
+from aiohomematic.const import CircuitState, OptionalSettings
+from aiohomematic.exceptions import NoConnectionException
+from aiohomematic.interfaces.client import ClientDependenciesProtocol, ClientProtocol
+
+_LOGGER: Final = logging.getLogger(__name__)
+
+__all__ = [
+    # Circuit breaker
+    "CircuitBreaker",
+    "CircuitBreakerConfig",
+    "CircuitState",
+    # Clients
+    "ClientCCU",
+    "ClientConfig",
+    "ClientHomegear",
+    "ClientJsonCCU",
+    "InterfaceClient",
+    # Config
+    "InterfaceConfig",
+    # Factory functions
+    "create_client",
+    "get_client",
+    # JSON RPC
+    "AioJsonRpcAioHttpClient",
+    # RPC proxy
+    "BaseRpcProxy",
+    # Request coalescing
+    "RequestCoalescer",
+    "make_coalesce_key",
+    # State machine
+    "ClientStateMachine",
+    "InvalidStateTransitionError",
+]
+
+
+_ENV_USE_INTERFACE_CLIENT: Final = "AIOHOMEMATIC_USE_INTERFACE_CLIENT"
+
+
+def _should_use_interface_client(*, client_deps: ClientDependenciesProtocol) -> bool:
+    """
+    Determine if InterfaceClient should be used.
+
+    Checks in order:
+    1. Environment variable AIOHOMEMATIC_USE_INTERFACE_CLIENT (for CI testing)
+    2. OptionalSettings.USE_INTERFACE_CLIENT in config
+    """
+    # Environment variable takes precedence (for CI testing)
+    if (env_value := os.environ.get(_ENV_USE_INTERFACE_CLIENT)) is not None:
+        return env_value.lower() in ("1", "true", "yes")
+
+    # Check config setting
+    return OptionalSettings.USE_INTERFACE_CLIENT in client_deps.config.optional_settings
+
+
+async def create_client(
+    *,
+    client_deps: ClientDependenciesProtocol,
+    interface_config: InterfaceConfig,
+) -> ClientProtocol:
+    """
+    Return a new client for with a given interface_config.
+
+    Uses InterfaceClient with backend strategy pattern if:
+    - Environment variable AIOHOMEMATIC_USE_INTERFACE_CLIENT=1 is set, OR
+    - USE_INTERFACE_CLIENT is enabled in optional_settings
+
+    Otherwise uses legacy ClientCCU family.
+    """
+    if _should_use_interface_client(client_deps=client_deps):
+        return await _create_interface_client(client_deps=client_deps, interface_config=interface_config)
+
+    # Legacy path - unchanged
+    return await ClientConfig(
+        client_deps=client_deps,
+        interface_config=interface_config,
+    ).create_client()
+
+
+async def _create_interface_client(
+    *,
+    client_deps: ClientDependenciesProtocol,
+    interface_config: InterfaceConfig,
+) -> ClientProtocol:
+    """Create InterfaceClient using backend strategy pattern."""
+    # Get version first (needed for backend selection)
+    client_config = ClientConfig(
+        client_deps=client_deps,
+        interface_config=interface_config,
+    )
+    version = await client_config._get_version()  # noqa: SLF001  # pylint: disable=protected-access
+
+    # Create appropriate backend
+    backend = await create_backend(
+        interface=interface_config.interface,
+        interface_id=interface_config.interface_id,
+        version=version,
+        proxy=await client_config.create_rpc_proxy(
+            interface=interface_config.interface,
+            auth_enabled=True,
+        )
+        if client_config.has_rpc_callback
+        else None,
+        proxy_read=await client_config.create_rpc_proxy(
+            interface=interface_config.interface,
+            auth_enabled=True,
+            max_workers=client_config.max_read_workers,
+        )
+        if client_config.has_rpc_callback
+        else None,
+        json_rpc=client_deps.json_rpc_client,
+        paramset_provider=client_deps.cache_coordinator.paramset_descriptions,
+        device_details_provider=client_deps.cache_coordinator.device_details.device_channel_rega_ids,
+        has_push_updates=client_config.has_push_updates,
+    )
+
+    _LOGGER.debug(
+        "CREATE_INTERFACE_CLIENT: Created %s backend for %s",
+        backend.model,
+        interface_config.interface_id,
+    )
+
+    # Create InterfaceClient
+    client = InterfaceClient(
+        backend=backend,
+        central=client_deps,
+        interface_config=interface_config,
+        version=version,
+    )
+    await client.init_client()
+
+    if await client.check_connection_availability(handle_ping_pong=False):
+        return client
+
+    raise NoConnectionException(
+        i18n.tr(key="exception.client.client_config.no_connection", interface_id=interface_config.interface_id)
+    )
+
+
+def get_client(*, interface_id: str) -> ClientProtocol | None:
+    """Return client by interface_id."""
+    for central in hmcu.CENTRAL_INSTANCES.values():
+        if central.client_coordinator.has_client(interface_id=interface_id):
+            return central.client_coordinator.get_client(interface_id=interface_id)
+    return None