aiohomematic 2026.1.29__py3-none-any.whl

aiohomematic/client/state_machine.py

@@ -0,0 +1,324 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2021-2026
+"""
+Client state machine for managing connection lifecycle.
+
+This module provides a state machine for tracking client connection states
+with validated transitions and event emission.
+
+The state machine ensures:
+- Only valid state transitions occur
+- State changes are logged for debugging
+- Invalid transitions raise exceptions for early error detection
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+from typing import TYPE_CHECKING, Final
+
+from aiohomematic.central.events.types import ClientStateChangedEvent
+from aiohomematic.const import ClientState, FailureReason
+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.
+#
+# State Diagram:
+#
+#   CREATED ──► INITIALIZING ──► INITIALIZED ──► CONNECTING ──► CONNECTED
+#                    │                               ▲              │
+#                    ▼                               │              ▼
+#                 FAILED ◄─────────────────────────┬┴─────── DISCONNECTED
+#                    │                             │              ▲
+#                    ├─────► INITIALIZING          │              │
+#                    ├─────► CONNECTING ◄──────────┴──────── RECONNECTING
+#                    ├─────► DISCONNECTED (for graceful shutdown) ▲
+#                    └─────► RECONNECTING ────────────────────────┘
+#
+#   STOPPED ◄── STOPPING ◄─────────────────────────(from CONNECTED/DISCONNECTED/RECONNECTING)
+#
+_VALID_TRANSITIONS: Final[dict[ClientState, frozenset[ClientState]]] = {
+    # Initial state after client creation - can only begin initialization
+    ClientState.CREATED: frozenset({ClientState.INITIALIZING}),
+    # During initialization (loading metadata, etc.) - succeeds or fails
+    ClientState.INITIALIZING: frozenset({ClientState.INITIALIZED, ClientState.FAILED}),
+    # Initialization complete - ready to establish connection
+    ClientState.INITIALIZED: frozenset({ClientState.CONNECTING}),
+    # Attempting to connect to backend - succeeds or fails
+    ClientState.CONNECTING: frozenset({ClientState.CONNECTED, ClientState.FAILED}),
+    # Fully connected and operational
+    ClientState.CONNECTED: frozenset(
+        {
+            ClientState.DISCONNECTED,  # Connection lost unexpectedly
+            ClientState.RECONNECTING,  # Attempting automatic reconnection
+            ClientState.STOPPING,  # Graceful shutdown requested
+        }
+    ),
+    # Connection was lost or intentionally closed
+    ClientState.DISCONNECTED: frozenset(
+        {
+            ClientState.CONNECTING,  # Manual reconnection attempt
+            ClientState.DISCONNECTED,  # Idempotent - allows repeated deinitialize calls
+            ClientState.RECONNECTING,  # Automatic reconnection attempt
+            ClientState.STOPPING,  # Graceful shutdown requested
+        }
+    ),
+    # Automatic reconnection in progress
+    ClientState.RECONNECTING: frozenset(
+        {
+            ClientState.CONNECTED,  # Reconnection succeeded
+            ClientState.DISCONNECTED,  # Reconnection abandoned
+            ClientState.FAILED,  # Reconnection failed permanently
+            ClientState.CONNECTING,  # Retry connection establishment
+        }
+    ),
+    # Graceful shutdown in progress - one-way to STOPPED
+    ClientState.STOPPING: frozenset({ClientState.STOPPED}),
+    # Terminal state - client is fully stopped, no transitions allowed
+    ClientState.STOPPED: frozenset(),
+    # Error state - allows retry via re-initialization, reconnection, or graceful shutdown
+    ClientState.FAILED: frozenset(
+        {
+            ClientState.INITIALIZING,  # Retry initialization
+            ClientState.CONNECTING,  # Retry connection
+            ClientState.RECONNECTING,  # Automatic reconnection attempt
+            ClientState.DISCONNECTED,  # Graceful shutdown via deinitialize_proxy
+        }
+    ),
+}
+
+
+class InvalidStateTransitionError(Exception):
+    """Raised when an invalid state transition is attempted."""
+
+    def __init__(self, *, current: ClientState, target: ClientState, interface_id: str) -> None:
+        """Initialize the error."""
+        self.current = current
+        self.target = target
+        self.interface_id = interface_id
+        super().__init__(
+            f"Invalid state transition from {current.value} to {target.value} for interface {interface_id}"
+        )
+
+
+class ClientStateMachine:
+    """
+    State machine for client connection lifecycle.
+
+    This class manages the connection state of a client with validated
+    transitions and event emission 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 ClientStateChangedEvent, EventBus
+
+        def on_state_changed(*, event: ClientStateChangedEvent) -> None:
+            print(f"State changed: {event.old_state} -> {event.new_state}")
+
+        event_bus = EventBus()
+        sm = ClientStateMachine(interface_id="BidCos-RF", event_bus=event_bus)
+
+        # Subscribe to state changes via EventBus
+        event_bus.subscribe(
+            event_type=ClientStateChangedEvent,
+            event_key="BidCos-RF",
+            handler=on_state_changed,
+        )
+
+        sm.transition_to(target=ClientState.INITIALIZING)
+        sm.transition_to(target=ClientState.INITIALIZED)
+        sm.transition_to(target=ClientState.CONNECTING)
+        sm.transition_to(target=ClientState.CONNECTED)
+
+    """
+
+    __slots__ = (
+        "_event_bus",
+        "_failure_message",
+        "_failure_reason",
+        "_interface_id",
+        "_state",
+    )
+
+    def __init__(
+        self,
+        *,
+        interface_id: str,
+        event_bus: EventBus | None = None,
+    ) -> None:
+        """
+        Initialize the state machine.
+
+        Args:
+        ----
+            interface_id: Interface identifier for logging
+            event_bus: Optional EventBus for state change events
+
+        """
+        self._interface_id: Final = interface_id
+        self._event_bus = event_bus
+        self._state: ClientState = ClientState.CREATED
+        self._failure_reason: FailureReason = FailureReason.NONE
+        self._failure_message: str = ""
+
+    failure_message: Final = DelegatedProperty[str](path="_failure_message")
+    failure_reason: Final = DelegatedProperty[FailureReason](path="_failure_reason")
+    state: Final = DelegatedProperty[ClientState](path="_state")
+
+    @property
+    def can_reconnect(self) -> bool:
+        """Return True if reconnection is allowed from current state."""
+        return ClientState.RECONNECTING in _VALID_TRANSITIONS.get(self._state, frozenset())
+
+    @property
+    def is_available(self) -> bool:
+        """Return True if client is available (connected or reconnecting)."""
+        return self._state in (ClientState.CONNECTED, ClientState.RECONNECTING)
+
+    @property
+    def is_connected(self) -> bool:
+        """Return True if client is in connected state."""
+        return self._state == ClientState.CONNECTED
+
+    @property
+    def is_failed(self) -> bool:
+        """Return True if client is in failed state."""
+        return self._state == ClientState.FAILED
+
+    @property
+    def is_stopped(self) -> bool:
+        """Return True if client is stopped."""
+        return self._state == ClientState.STOPPED
+
+    def can_transition_to(self, *, target: ClientState) -> 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_TRANSITIONS.get(self._state, frozenset())
+
+    def reset(self) -> None:
+        """
+        Reset state machine to CREATED state.
+
+        This should only be used during testing or exceptional recovery.
+        """
+        old_state = self._state
+        self._state = ClientState.CREATED
+        self._failure_reason = FailureReason.NONE
+        self._failure_message = ""
+        _LOGGER.warning(  # i18n-log: ignore
+            "STATE_MACHINE: %s: Reset from %s to CREATED",
+            self._interface_id,
+            old_state.value,
+        )
+
+    def transition_to(
+        self,
+        *,
+        target: ClientState,
+        reason: str = "",
+        force: bool = False,
+        failure_reason: FailureReason = FailureReason.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)
+
+        Raises:
+        ------
+            InvalidStateTransitionError: If transition is not valid and force=False
+
+        """
+        if not force and not self.can_transition_to(target=target):
+            raise InvalidStateTransitionError(
+                current=self._state,
+                target=target,
+                interface_id=self._interface_id,
+            )
+
+        old_state = self._state
+        self._state = target
+
+        # Track failure reason when entering FAILED state
+        if target == ClientState.FAILED:
+            self._failure_reason = failure_reason
+            self._failure_message = reason
+        elif target in (ClientState.CONNECTED, ClientState.INITIALIZED):
+            # Clear failure info on successful states
+            self._failure_reason = FailureReason.NONE
+            self._failure_message = ""
+
+        # Log at INFO level for important transitions, DEBUG for others
+        if target in (ClientState.CONNECTED, ClientState.DISCONNECTED, ClientState.FAILED):
+            failure_info = f" [reason={failure_reason.value}]" if target == ClientState.FAILED else ""
+            _LOGGER.info(  # i18n-log: ignore
+                "CLIENT_STATE: %s: %s -> %s%s%s",
+                self._interface_id,
+                old_state.value,
+                target.value,
+                f" ({reason})" if reason else "",
+                failure_info,
+            )
+        else:
+            _LOGGER.debug(
+                "CLIENT_STATE: %s: %s -> %s%s",
+                self._interface_id,
+                old_state.value,
+                target.value,
+                f" ({reason})" if reason else "",
+            )
+
+        # Emit state change event
+        self._emit_state_change_event(
+            old_state=old_state,
+            new_state=target,
+            trigger=reason or None,
+        )
+
+    def _emit_state_change_event(
+        self,
+        *,
+        old_state: ClientState,
+        new_state: ClientState,
+        trigger: str | None,
+    ) -> None:
+        """Emit a client state change event."""
+        if self._event_bus is None:
+            return
+
+        self._event_bus.publish_sync(
+            event=ClientStateChangedEvent(
+                timestamp=datetime.now(),
+                interface_id=self._interface_id,
+                old_state=old_state,
+                new_state=new_state,
+                trigger=trigger,
+            )
+        )