truthound-dashboard 1.3.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

truthound_dashboard/core/plugins/lifecycle/machine.py

@@ -0,0 +1,419 @@
+"""Plugin State Machine.
+
+This module provides the state machine implementation
+for plugin lifecycle management.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable, Awaitable
+
+from .states import (
+    PluginState,
+    StateTransition,
+    StateTransitionError,
+    is_valid_transition,
+    get_valid_transitions,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# Callback types
+SyncCallback = Callable[["PluginStateMachine", StateTransition], None]
+AsyncCallback = Callable[["PluginStateMachine", StateTransition], Awaitable[None]]
+TransitionCallback = SyncCallback | AsyncCallback
+
+
+@dataclass
+class PluginContext:
+    """Context for plugin state machine.
+
+    Attributes:
+        plugin_id: Plugin identifier.
+        version: Plugin version.
+        path: Plugin installation path.
+        config: Plugin configuration.
+        state_data: State-specific data.
+        error: Last error message.
+        last_error_at: When last error occurred.
+        retry_count: Number of retry attempts.
+    """
+
+    plugin_id: str
+    version: str = ""
+    path: str = ""
+    config: dict[str, Any] = field(default_factory=dict)
+    state_data: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+    last_error_at: datetime | None = None
+    retry_count: int = 0
+
+
+class PluginStateMachine:
+    """State machine for managing plugin lifecycle.
+
+    This class provides:
+    - State transition management
+    - Transition callbacks (before/after)
+    - State history tracking
+    - Error recovery and rollback
+    """
+
+    def __init__(
+        self,
+        plugin_id: str,
+        initial_state: PluginState = PluginState.DISCOVERED,
+        context: PluginContext | None = None,
+    ) -> None:
+        """Initialize the state machine.
+
+        Args:
+            plugin_id: Plugin identifier.
+            initial_state: Initial state.
+            context: Optional plugin context.
+        """
+        self.plugin_id = plugin_id
+        self._state = initial_state
+        self._previous_state: PluginState | None = None
+        self._state_entered_at = datetime.utcnow()
+        self._history: list[StateTransition] = []
+        self._context = context or PluginContext(plugin_id=plugin_id)
+
+        # Callbacks
+        self._before_callbacks: dict[PluginState, list[TransitionCallback]] = {}
+        self._after_callbacks: dict[PluginState, list[TransitionCallback]] = {}
+        self._on_any_transition: list[TransitionCallback] = []
+
+        # Locking
+        self._lock = asyncio.Lock()
+
+    @property
+    def state(self) -> PluginState:
+        """Get current state."""
+        return self._state
+
+    @property
+    def previous_state(self) -> PluginState | None:
+        """Get previous state."""
+        return self._previous_state
+
+    @property
+    def context(self) -> PluginContext:
+        """Get plugin context."""
+        return self._context
+
+    @property
+    def history(self) -> list[StateTransition]:
+        """Get state transition history."""
+        return self._history.copy()
+
+    def can_transition_to(self, target_state: PluginState) -> bool:
+        """Check if transition to target state is possible.
+
+        Args:
+            target_state: Target state.
+
+        Returns:
+            True if transition is valid.
+        """
+        return is_valid_transition(self._state, target_state)
+
+    def get_available_transitions(self) -> list[PluginState]:
+        """Get states that can be transitioned to from current state.
+
+        Returns:
+            List of valid target states.
+        """
+        return get_valid_transitions(self._state)
+
+    def transition(
+        self,
+        target_state: PluginState,
+        trigger: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> StateTransition:
+        """Transition to a new state synchronously.
+
+        Args:
+            target_state: Target state.
+            trigger: What triggered the transition.
+            metadata: Additional metadata.
+
+        Returns:
+            StateTransition record.
+
+        Raises:
+            StateTransitionError: If transition is invalid.
+        """
+        if not is_valid_transition(self._state, target_state):
+            raise StateTransitionError(self._state, target_state)
+
+        # Calculate time in previous state
+        now = datetime.utcnow()
+        duration_ms = (now - self._state_entered_at).total_seconds() * 1000
+
+        # Create transition record
+        transition = StateTransition(
+            from_state=self._state,
+            to_state=target_state,
+            timestamp=now,
+            trigger=trigger,
+            duration_ms=duration_ms,
+            metadata=metadata or {},
+        )
+
+        # Execute before callbacks
+        self._execute_before_callbacks(transition)
+
+        # Perform transition
+        self._previous_state = self._state
+        self._state = target_state
+        self._state_entered_at = now
+        self._history.append(transition)
+
+        # Execute after callbacks
+        self._execute_after_callbacks(transition)
+
+        logger.info(
+            f"Plugin {self.plugin_id}: {transition.from_state.value} -> "
+            f"{transition.to_state.value} (trigger: {trigger})"
+        )
+
+        return transition
+
+    async def transition_async(
+        self,
+        target_state: PluginState,
+        trigger: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> StateTransition:
+        """Transition to a new state asynchronously.
+
+        Args:
+            target_state: Target state.
+            trigger: What triggered the transition.
+            metadata: Additional metadata.
+
+        Returns:
+            StateTransition record.
+
+        Raises:
+            StateTransitionError: If transition is invalid.
+        """
+        async with self._lock:
+            if not is_valid_transition(self._state, target_state):
+                raise StateTransitionError(self._state, target_state)
+
+            # Calculate time in previous state
+            now = datetime.utcnow()
+            duration_ms = (now - self._state_entered_at).total_seconds() * 1000
+
+            # Create transition record
+            transition = StateTransition(
+                from_state=self._state,
+                to_state=target_state,
+                timestamp=now,
+                trigger=trigger,
+                duration_ms=duration_ms,
+                metadata=metadata or {},
+            )
+
+            # Execute before callbacks
+            await self._execute_before_callbacks_async(transition)
+
+            # Perform transition
+            self._previous_state = self._state
+            self._state = target_state
+            self._state_entered_at = now
+            self._history.append(transition)
+
+            # Execute after callbacks
+            await self._execute_after_callbacks_async(transition)
+
+            logger.info(
+                f"Plugin {self.plugin_id}: {transition.from_state.value} -> "
+                f"{transition.to_state.value} (trigger: {trigger})"
+            )
+
+            return transition
+
+    def fail(self, error: str, trigger: str = "error") -> StateTransition:
+        """Transition to FAILED state.
+
+        Args:
+            error: Error message.
+            trigger: What triggered the failure.
+
+        Returns:
+            StateTransition record.
+        """
+        self._context.error = error
+        self._context.last_error_at = datetime.utcnow()
+
+        return self.transition(
+            PluginState.FAILED,
+            trigger=trigger,
+            metadata={"error": error},
+        )
+
+    def rollback(self, trigger: str = "rollback") -> StateTransition | None:
+        """Rollback to previous state if possible.
+
+        Args:
+            trigger: What triggered the rollback.
+
+        Returns:
+            StateTransition record, or None if rollback not possible.
+        """
+        if self._previous_state is None:
+            return None
+
+        if not is_valid_transition(self._state, self._previous_state):
+            return None
+
+        return self.transition(
+            self._previous_state,
+            trigger=trigger,
+            metadata={"rollback": True},
+        )
+
+    def on_before(
+        self,
+        state: PluginState,
+        callback: TransitionCallback,
+    ) -> None:
+        """Register a callback to run before entering a state.
+
+        Args:
+            state: Target state.
+            callback: Callback function.
+        """
+        if state not in self._before_callbacks:
+            self._before_callbacks[state] = []
+        self._before_callbacks[state].append(callback)
+
+    def on_after(
+        self,
+        state: PluginState,
+        callback: TransitionCallback,
+    ) -> None:
+        """Register a callback to run after entering a state.
+
+        Args:
+            state: Target state.
+            callback: Callback function.
+        """
+        if state not in self._after_callbacks:
+            self._after_callbacks[state] = []
+        self._after_callbacks[state].append(callback)
+
+    def on_transition(self, callback: TransitionCallback) -> None:
+        """Register a callback for any transition.
+
+        Args:
+            callback: Callback function.
+        """
+        self._on_any_transition.append(callback)
+
+    def _execute_before_callbacks(self, transition: StateTransition) -> None:
+        """Execute before callbacks synchronously."""
+        callbacks = self._before_callbacks.get(transition.to_state, [])
+        for callback in callbacks:
+            try:
+                result = callback(self, transition)
+                if asyncio.iscoroutine(result):
+                    # Run async callback synchronously
+                    asyncio.get_event_loop().run_until_complete(result)
+            except Exception as e:
+                logger.error(f"Before callback error: {e}")
+
+    def _execute_after_callbacks(self, transition: StateTransition) -> None:
+        """Execute after callbacks synchronously."""
+        callbacks = self._after_callbacks.get(transition.to_state, [])
+        callbacks.extend(self._on_any_transition)
+        for callback in callbacks:
+            try:
+                result = callback(self, transition)
+                if asyncio.iscoroutine(result):
+                    asyncio.get_event_loop().run_until_complete(result)
+            except Exception as e:
+                logger.error(f"After callback error: {e}")
+
+    async def _execute_before_callbacks_async(
+        self, transition: StateTransition
+    ) -> None:
+        """Execute before callbacks asynchronously."""
+        callbacks = self._before_callbacks.get(transition.to_state, [])
+        for callback in callbacks:
+            try:
+                result = callback(self, transition)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as e:
+                logger.error(f"Before callback error: {e}")
+
+    async def _execute_after_callbacks_async(
+        self, transition: StateTransition
+    ) -> None:
+        """Execute after callbacks asynchronously."""
+        callbacks = self._after_callbacks.get(transition.to_state, [])
+        callbacks.extend(self._on_any_transition)
+        for callback in callbacks:
+            try:
+                result = callback(self, transition)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as e:
+                logger.error(f"After callback error: {e}")
+
+    def get_state_info(self) -> dict[str, Any]:
+        """Get information about current state.
+
+        Returns:
+            State information dictionary.
+        """
+        return {
+            "plugin_id": self.plugin_id,
+            "state": self._state.value,
+            "previous_state": self._previous_state.value if self._previous_state else None,
+            "state_entered_at": self._state_entered_at.isoformat(),
+            "available_transitions": [s.value for s in self.get_available_transitions()],
+            "history_length": len(self._history),
+            "context": {
+                "version": self._context.version,
+                "error": self._context.error,
+                "retry_count": self._context.retry_count,
+            },
+        }
+
+
+def create_state_machine(
+    plugin_id: str,
+    version: str = "",
+    initial_state: PluginState = PluginState.DISCOVERED,
+) -> PluginStateMachine:
+    """Create a new plugin state machine.
+
+    Args:
+        plugin_id: Plugin identifier.
+        version: Plugin version.
+        initial_state: Initial state.
+
+    Returns:
+        Configured PluginStateMachine.
+    """
+    context = PluginContext(
+        plugin_id=plugin_id,
+        version=version,
+    )
+    return PluginStateMachine(
+        plugin_id=plugin_id,
+        initial_state=initial_state,
+        context=context,
+    )

truthound_dashboard/core/plugins/lifecycle/states.py

@@ -0,0 +1,266 @@
+"""Plugin Lifecycle States.
+
+This module defines the state machine states and transitions
+for plugin lifecycle management.
+
+State Diagram:
+    DISCOVERED --> LOADING --> LOADED --> ACTIVATING --> ACTIVE
+         |           |           |            |            |
+         v           v           v            v            v
+       FAILED     FAILED     FAILED       FAILED    DEACTIVATING
+                                                         |
+                                                         v
+                                                    UNLOADING --> UNLOADED
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class PluginState(str, Enum):
+    """Plugin lifecycle states."""
+
+    # Initial state when plugin is found
+    DISCOVERED = "discovered"
+
+    # Plugin is being loaded (reading files, parsing)
+    LOADING = "loading"
+
+    # Plugin code is loaded but not active
+    LOADED = "loaded"
+
+    # Plugin is being activated (initializing)
+    ACTIVATING = "activating"
+
+    # Plugin is active and running
+    ACTIVE = "active"
+
+    # Plugin is being deactivated
+    DEACTIVATING = "deactivating"
+
+    # Plugin is being unloaded
+    UNLOADING = "unloading"
+
+    # Plugin has been unloaded
+    UNLOADED = "unloaded"
+
+    # Plugin failed to load or activate
+    FAILED = "failed"
+
+    # Plugin is being reloaded (hot reload)
+    RELOADING = "reloading"
+
+    # Plugin is being upgraded to new version
+    UPGRADING = "upgrading"
+
+
+class StateTransitionError(Exception):
+    """Raised when an invalid state transition is attempted."""
+
+    def __init__(
+        self,
+        current_state: PluginState,
+        target_state: PluginState,
+        message: str | None = None,
+    ) -> None:
+        """Initialize the error.
+
+        Args:
+            current_state: Current plugin state.
+            target_state: Attempted target state.
+            message: Optional error message.
+        """
+        self.current_state = current_state
+        self.target_state = target_state
+        msg = message or f"Cannot transition from {current_state.value} to {target_state.value}"
+        super().__init__(msg)
+
+
+@dataclass
+class StateTransition:
+    """Represents a state transition event.
+
+    Attributes:
+        from_state: Previous state.
+        to_state: New state.
+        timestamp: When the transition occurred.
+        trigger: What triggered the transition.
+        duration_ms: Time spent in previous state.
+        metadata: Additional transition metadata.
+        error: Error message if transition failed.
+    """
+
+    from_state: PluginState
+    to_state: PluginState
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    trigger: str = ""
+    duration_ms: float = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "from_state": self.from_state.value,
+            "to_state": self.to_state.value,
+            "timestamp": self.timestamp.isoformat(),
+            "trigger": self.trigger,
+            "duration_ms": self.duration_ms,
+            "metadata": self.metadata,
+            "error": self.error,
+        }
+
+
+# Valid state transitions
+VALID_TRANSITIONS: dict[PluginState, set[PluginState]] = {
+    PluginState.DISCOVERED: {
+        PluginState.LOADING,
+        PluginState.FAILED,
+        PluginState.UNLOADED,
+    },
+    PluginState.LOADING: {
+        PluginState.LOADED,
+        PluginState.FAILED,
+    },
+    PluginState.LOADED: {
+        PluginState.ACTIVATING,
+        PluginState.UNLOADING,
+        PluginState.FAILED,
+    },
+    PluginState.ACTIVATING: {
+        PluginState.ACTIVE,
+        PluginState.FAILED,
+        PluginState.LOADED,  # Rollback on failure
+    },
+    PluginState.ACTIVE: {
+        PluginState.DEACTIVATING,
+        PluginState.RELOADING,
+        PluginState.UPGRADING,
+        PluginState.FAILED,
+    },
+    PluginState.DEACTIVATING: {
+        PluginState.LOADED,
+        PluginState.UNLOADING,
+        PluginState.FAILED,
+    },
+    PluginState.UNLOADING: {
+        PluginState.UNLOADED,
+        PluginState.FAILED,
+    },
+    PluginState.UNLOADED: {
+        PluginState.DISCOVERED,  # Re-install
+        PluginState.LOADING,     # Re-load
+    },
+    PluginState.FAILED: {
+        PluginState.DISCOVERED,  # Retry discovery
+        PluginState.LOADING,     # Retry load
+        PluginState.UNLOADING,   # Unload failed plugin
+    },
+    PluginState.RELOADING: {
+        PluginState.ACTIVE,
+        PluginState.FAILED,
+        PluginState.LOADED,  # Rollback
+    },
+    PluginState.UPGRADING: {
+        PluginState.ACTIVE,
+        PluginState.FAILED,
+        PluginState.LOADED,  # Rollback
+    },
+}
+
+
+def is_valid_transition(from_state: PluginState, to_state: PluginState) -> bool:
+    """Check if a state transition is valid.
+
+    Args:
+        from_state: Current state.
+        to_state: Target state.
+
+    Returns:
+        True if transition is valid.
+    """
+    valid_targets = VALID_TRANSITIONS.get(from_state, set())
+    return to_state in valid_targets
+
+
+def get_valid_transitions(state: PluginState) -> list[PluginState]:
+    """Get valid target states from a given state.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        List of valid target states.
+    """
+    return list(VALID_TRANSITIONS.get(state, []))
+
+
+def can_activate(state: PluginState) -> bool:
+    """Check if plugin can be activated from current state.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        True if activation is possible.
+    """
+    return state in {PluginState.LOADED, PluginState.FAILED}
+
+
+def can_deactivate(state: PluginState) -> bool:
+    """Check if plugin can be deactivated from current state.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        True if deactivation is possible.
+    """
+    return state == PluginState.ACTIVE
+
+
+def is_running(state: PluginState) -> bool:
+    """Check if plugin is in a running state.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        True if plugin is running.
+    """
+    return state == PluginState.ACTIVE
+
+
+def is_transitioning(state: PluginState) -> bool:
+    """Check if plugin is in a transitional state.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        True if plugin is transitioning.
+    """
+    return state in {
+        PluginState.LOADING,
+        PluginState.ACTIVATING,
+        PluginState.DEACTIVATING,
+        PluginState.UNLOADING,
+        PluginState.RELOADING,
+        PluginState.UPGRADING,
+    }
+
+
+def is_terminal(state: PluginState) -> bool:
+    """Check if plugin is in a terminal state.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        True if plugin is in terminal state.
+    """
+    return state in {PluginState.UNLOADED, PluginState.FAILED}