dory-processor-sdk 0.0.1__py3-none-any.whl

dory/core/lifecycle.py

@@ -0,0 +1,214 @@
+"""
+LifecycleManager - Manages processor lifecycle state machine.
+
+Handles transitions between lifecycle states and enforces valid
+state transitions.
+"""
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from dory.types import LifecycleState
+from dory.utils.errors import DoryStartupError, DoryShutdownError
+
+if TYPE_CHECKING:
+    from dory.core.processor import BaseProcessor
+    from dory.core.context import ExecutionContext
+
+logger = logging.getLogger(__name__)
+
+
+class LifecycleManager:
+    """
+    Manages the processor lifecycle state machine.
+
+    States:
+        CREATED -> STARTING -> RUNNING -> SHUTTING_DOWN -> STOPPED
+                              |
+                              v
+                           FAILED (from any state on error)
+    """
+
+    # Valid state transitions
+    VALID_TRANSITIONS: dict[LifecycleState, set[LifecycleState]] = {
+        LifecycleState.CREATED: {LifecycleState.STARTING, LifecycleState.FAILED},
+        LifecycleState.STARTING: {LifecycleState.RUNNING, LifecycleState.FAILED},
+        LifecycleState.RUNNING: {LifecycleState.SHUTTING_DOWN, LifecycleState.FAILED},
+        LifecycleState.SHUTTING_DOWN: {LifecycleState.STOPPED, LifecycleState.FAILED},
+        LifecycleState.STOPPED: set(),  # Terminal state
+        LifecycleState.FAILED: set(),   # Terminal state
+    }
+
+    def __init__(self):
+        self._state = LifecycleState.CREATED
+        self._state_lock = asyncio.Lock()
+        self._state_changed = asyncio.Event()
+
+    @property
+    def state(self) -> LifecycleState:
+        """Current lifecycle state."""
+        return self._state
+
+    def is_running(self) -> bool:
+        """Check if processor is in running state."""
+        return self._state == LifecycleState.RUNNING
+
+    def is_stopped(self) -> bool:
+        """Check if processor has stopped (gracefully or failed)."""
+        return self._state in (LifecycleState.STOPPED, LifecycleState.FAILED)
+
+    def is_shutting_down(self) -> bool:
+        """Check if shutdown is in progress."""
+        return self._state == LifecycleState.SHUTTING_DOWN
+
+    async def transition_to(self, new_state: LifecycleState) -> None:
+        """
+        Transition to a new lifecycle state.
+
+        Args:
+            new_state: Target state
+
+        Raises:
+            ValueError: If transition is not valid
+        """
+        async with self._state_lock:
+            if new_state not in self.VALID_TRANSITIONS.get(self._state, set()):
+                raise ValueError(
+                    f"Invalid state transition: {self._state.name} -> {new_state.name}"
+                )
+
+            old_state = self._state
+            self._state = new_state
+            self._state_changed.set()
+            self._state_changed.clear()
+
+            logger.debug(f"Lifecycle transition: {old_state.name} -> {new_state.name}")
+
+    async def wait_for_state(
+        self,
+        target_states: set[LifecycleState],
+        timeout: float | None = None,
+    ) -> LifecycleState:
+        """
+        Wait for lifecycle to reach one of the target states.
+
+        Args:
+            target_states: Set of states to wait for
+            timeout: Maximum time to wait (None = forever)
+
+        Returns:
+            The state that was reached
+
+        Raises:
+            asyncio.TimeoutError: If timeout exceeded
+        """
+        while self._state not in target_states:
+            try:
+                await asyncio.wait_for(
+                    self._state_changed.wait(),
+                    timeout=timeout,
+                )
+            except asyncio.TimeoutError:
+                raise
+
+        return self._state
+
+    async def run_startup(
+        self,
+        processor: "BaseProcessor",
+        timeout: float = 60.0,
+    ) -> None:
+        """
+        Run processor startup with timeout.
+
+        Args:
+            processor: Processor instance to start
+            timeout: Maximum time for startup (seconds)
+
+        Raises:
+            DoryStartupError: If startup fails or times out
+        """
+        await self.transition_to(LifecycleState.STARTING)
+
+        try:
+            await asyncio.wait_for(
+                processor.startup(),
+                timeout=timeout,
+            )
+            await self.transition_to(LifecycleState.RUNNING)
+            logger.info("Processor startup completed")
+
+        except asyncio.TimeoutError:
+            await self.transition_to(LifecycleState.FAILED)
+            raise DoryStartupError(f"Startup timed out after {timeout}s")
+
+        except Exception as e:
+            await self.transition_to(LifecycleState.FAILED)
+            raise DoryStartupError(f"Startup failed: {e}", cause=e)
+
+    async def run_shutdown(
+        self,
+        processor: "BaseProcessor",
+        timeout: float = 30.0,
+    ) -> None:
+        """
+        Run processor shutdown with timeout.
+
+        Args:
+            processor: Processor instance to shutdown
+            timeout: Maximum time for shutdown (seconds)
+
+        Raises:
+            DoryShutdownError: If shutdown times out
+        """
+        if self._state in (LifecycleState.STOPPED, LifecycleState.FAILED):
+            return  # Already stopped
+
+        await self.transition_to(LifecycleState.SHUTTING_DOWN)
+
+        try:
+            await asyncio.wait_for(
+                processor.shutdown(),
+                timeout=timeout,
+            )
+            await self.transition_to(LifecycleState.STOPPED)
+            logger.info("Processor shutdown completed")
+
+        except asyncio.TimeoutError:
+            logger.error(f"Shutdown timed out after {timeout}s, forcing exit")
+            await self.transition_to(LifecycleState.FAILED)
+            raise DoryShutdownError(f"Shutdown timed out after {timeout}s")
+
+        except Exception as e:
+            # Log but continue - shutdown should complete
+            logger.error(f"Error during shutdown: {e}")
+            await self.transition_to(LifecycleState.STOPPED)
+
+    async def run_main_loop(
+        self,
+        processor: "BaseProcessor",
+        context: "ExecutionContext",
+    ) -> None:
+        """
+        Run processor main loop until shutdown requested.
+
+        Args:
+            processor: Processor instance to run
+            context: Execution context
+        """
+        if self._state != LifecycleState.RUNNING:
+            raise ValueError(f"Cannot run: state is {self._state.name}, expected RUNNING")
+
+        try:
+            await processor.run()
+            logger.info("Processor run() completed")
+
+        except asyncio.CancelledError:
+            logger.info("Processor run() cancelled")
+            raise
+
+        except Exception as e:
+            logger.error(f"Error in processor run(): {e}")
+            await self.transition_to(LifecycleState.FAILED)
+            raise

dory/core/meta.py

@@ -0,0 +1,121 @@
+"""
+Metaclass for automatic handler instrumentation.
+
+Automatically applies @auto_instrument to all async methods
+starting with "handle_" or "_handle_".
+
+No manual decorators needed!
+"""
+
+import inspect
+import logging
+from abc import ABCMeta
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class AutoInstrumentMeta(ABCMeta):
+    """
+    Metaclass that automatically applies @auto_instrument to handler methods.
+
+    This eliminates the need for developers to add decorators manually.
+
+    Usage:
+        class MyProcessor(BaseProcessor, metaclass=AutoInstrumentMeta):
+            async def handle_request(self, request):
+                # Automatically instrumented!
+                # - Request ID generated
+                # - Request tracked
+                # - Span created
+                # - Errors classified
+                return {"status": "ok"}
+
+            async def handle_webhook(self, webhook):
+                # Also automatically instrumented!
+                return {"received": True}
+
+            async def internal_method(self):
+                # NOT instrumented (doesn't start with handle_)
+                pass
+
+    Auto-instrumented methods:
+    - async def handle_*(...): Public handlers
+    - async def _handle_*(...): Private handlers
+
+    Not instrumented:
+    - Other methods (don't start with handle_)
+    - Sync methods
+    - Lifecycle methods (startup, shutdown, run)
+    """
+
+    # List of methods that should NOT be auto-instrumented
+    EXCLUDED_METHODS = {
+        "startup",
+        "shutdown",
+        "run",
+        "get_state",
+        "restore_state",
+        "on_state_restore_failed",
+        "on_rapid_restart_detected",
+        "on_health_check_failed",
+        "reset_caches",
+        "run_loop",
+        "is_shutting_down",
+    }
+
+    def __new__(mcs, name, bases, namespace):
+        """
+        Create new class with auto-instrumented handler methods.
+
+        Args:
+            name: Class name
+            bases: Base classes
+            namespace: Class namespace (attributes and methods)
+
+        Returns:
+            New class with auto-instrumented handlers
+        """
+        # Import here to avoid circular dependency
+        try:
+            from dory.auto_instrument import auto_instrument
+        except ImportError:
+            logger.warning(
+                "auto_instrument decorator not available, skipping auto-instrumentation"
+            )
+            return super().__new__(mcs, name, bases, namespace)
+
+        # Count of instrumented methods
+        instrumented_count = 0
+
+        # Auto-instrument handler methods
+        for attr_name, attr_value in list(namespace.items()):
+            # Check if this is an async method
+            if not inspect.iscoroutinefunction(attr_value):
+                continue
+
+            # Check if method should be instrumented
+            should_instrument = False
+
+            # Instrument methods starting with handle_ or _handle_
+            if attr_name.startswith("handle_") or attr_name.startswith("_handle_"):
+                should_instrument = True
+
+            # Don't instrument excluded methods
+            if attr_name in mcs.EXCLUDED_METHODS:
+                should_instrument = False
+
+            # Don't instrument special methods
+            if attr_name.startswith("__") and attr_name.endswith("__"):
+                should_instrument = False
+
+            # Apply auto-instrumentation
+            if should_instrument:
+                namespace[attr_name] = auto_instrument(attr_value)
+                instrumented_count += 1
+                logger.debug(f"Auto-instrumented method: {name}.{attr_name}")
+
+        if instrumented_count > 0:
+            logger.info(f"Auto-instrumented {instrumented_count} methods in {name}")
+
+        return super().__new__(mcs, name, bases, namespace)