dory-sdk 2.1.0__py3-none-any.whl

dory/core/signals.py

@@ -0,0 +1,122 @@
+"""
+SignalHandler - Handles OS signals for graceful shutdown.
+
+Captures SIGTERM, SIGINT, and SIGUSR1 and triggers appropriate
+actions in the SDK.
+"""
+
+import asyncio
+import logging
+import signal
+import sys
+from typing import Callable, Awaitable
+
+logger = logging.getLogger(__name__)
+
+
+class SignalHandler:
+    """
+    Handles OS signals for graceful shutdown.
+
+    Signals handled:
+        SIGTERM: Graceful shutdown (from Kubelet)
+        SIGINT: Graceful shutdown (Ctrl+C for local testing)
+        SIGUSR1: Trigger state snapshot (for debugging)
+    """
+
+    def __init__(self):
+        self._shutdown_callback: Callable[[], Awaitable[None]] | None = None
+        self._snapshot_callback: Callable[[], Awaitable[None]] | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._shutdown_triggered = False
+
+    def setup(
+        self,
+        shutdown_callback: Callable[[], Awaitable[None]],
+        snapshot_callback: Callable[[], Awaitable[None]] | None = None,
+    ) -> None:
+        """
+        Setup signal handlers.
+
+        Args:
+            shutdown_callback: Async callback for graceful shutdown
+            snapshot_callback: Optional async callback for state snapshot
+        """
+        self._shutdown_callback = shutdown_callback
+        self._snapshot_callback = snapshot_callback
+        self._loop = asyncio.get_event_loop()
+
+        # Register signal handlers
+        if sys.platform != "win32":
+            # Unix signals
+            self._loop.add_signal_handler(
+                signal.SIGTERM,
+                self._handle_shutdown_signal,
+                "SIGTERM",
+            )
+            self._loop.add_signal_handler(
+                signal.SIGINT,
+                self._handle_shutdown_signal,
+                "SIGINT",
+            )
+            self._loop.add_signal_handler(
+                signal.SIGUSR1,
+                self._handle_snapshot_signal,
+            )
+            logger.debug("Signal handlers registered (Unix)")
+        else:
+            # Windows - limited signal support
+            signal.signal(signal.SIGTERM, self._handle_shutdown_signal_sync)
+            signal.signal(signal.SIGINT, self._handle_shutdown_signal_sync)
+            logger.debug("Signal handlers registered (Windows)")
+
+    def _handle_shutdown_signal(self, sig_name: str) -> None:
+        """Handle SIGTERM/SIGINT asynchronously."""
+        if self._shutdown_triggered:
+            logger.warning(f"Received {sig_name} but shutdown already in progress")
+            return
+
+        self._shutdown_triggered = True
+        logger.info(f"Received {sig_name}, initiating graceful shutdown")
+
+        if self._shutdown_callback and self._loop:
+            asyncio.ensure_future(
+                self._shutdown_callback(),
+                loop=self._loop,
+            )
+
+    def _handle_shutdown_signal_sync(self, signum: int, frame) -> None:
+        """Handle signal synchronously (Windows compatibility)."""
+        sig_name = signal.Signals(signum).name
+        self._handle_shutdown_signal(sig_name)
+
+    def _handle_snapshot_signal(self) -> None:
+        """Handle SIGUSR1 for debug state snapshot."""
+        logger.info("Received SIGUSR1, triggering state snapshot")
+
+        if self._snapshot_callback and self._loop:
+            asyncio.ensure_future(
+                self._snapshot_callback(),
+                loop=self._loop,
+            )
+
+    def remove_handlers(self) -> None:
+        """Remove signal handlers during shutdown."""
+        if self._loop and sys.platform != "win32":
+            try:
+                self._loop.remove_signal_handler(signal.SIGTERM)
+                self._loop.remove_signal_handler(signal.SIGINT)
+                self._loop.remove_signal_handler(signal.SIGUSR1)
+                logger.debug("Signal handlers removed")
+            except (ValueError, RuntimeError):
+                # Handler not registered or loop closed
+                pass
+
+    @property
+    def shutdown_triggered(self) -> bool:
+        """Check if shutdown has been triggered."""
+        return self._shutdown_triggered
+
+    def reset(self) -> None:
+        """Reset shutdown state (for testing)."""
+        self._shutdown_triggered = False

dory/decorators.py

@@ -0,0 +1,142 @@
+"""
+Decorators for simplified Dory SDK integration.
+
+Provides @stateful decorator for automatic state management,
+eliminating the need to manually implement get_state() and restore_state().
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, TypeVar, Generic, Callable
+
+T = TypeVar('T')
+
+
+@dataclass
+class StatefulVar(Generic[T]):
+    """
+    A stateful variable that automatically participates in state save/restore.
+
+    Usage:
+        from dory import stateful
+
+        class MyProcessor(BaseProcessor):
+            counter = stateful(0)
+            sessions = stateful(dict)
+
+            async def run(self):
+                self.counter += 1  # Automatically saved/restored
+    """
+    _default: T | Callable[[], T]
+    _name: str = ""
+    _value: T = field(default=None, repr=False)
+    _initialized: bool = field(default=False, repr=False)
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        """Called when descriptor is assigned to a class attribute."""
+        self._name = name
+        # Register this stateful var with the class
+        if not hasattr(owner, '_stateful_vars'):
+            owner._stateful_vars = {}
+        owner._stateful_vars[name] = self
+
+    def __get__(self, obj: Any, objtype: type | None = None) -> T:
+        """Get the current value."""
+        if obj is None:
+            return self
+
+        # Initialize on first access
+        if not hasattr(obj, f'_stateful_{self._name}_value'):
+            default = self._default() if callable(self._default) else self._default
+            setattr(obj, f'_stateful_{self._name}_value', default)
+
+        return getattr(obj, f'_stateful_{self._name}_value')
+
+    def __set__(self, obj: Any, value: T) -> None:
+        """Set the value."""
+        setattr(obj, f'_stateful_{self._name}_value', value)
+
+
+def stateful(default: T | Callable[[], T] = None) -> StatefulVar[T]:
+    """
+    Mark a class attribute as stateful for automatic state management.
+
+    The SDK will automatically include this attribute in get_state() output
+    and restore it in restore_state().
+
+    Args:
+        default: Default value or factory function (use factory for mutable defaults)
+
+    Usage:
+        class MyProcessor(BaseProcessor):
+            # Simple values
+            counter = stateful(0)
+            name = stateful("default")
+
+            # Mutable defaults (use factory to avoid sharing)
+            sessions = stateful(dict)  # Same as stateful(lambda: {})
+            items = stateful(list)     # Same as stateful(lambda: [])
+
+    Example:
+        from dory import DoryApp, BaseProcessor, stateful
+
+        class MyProcessor(BaseProcessor):
+            counter = stateful(0)
+            data = stateful(dict)
+
+            async def run(self):
+                while not self.context.is_shutdown_requested():
+                    self.counter += 1
+                    await asyncio.sleep(1)
+
+            # No need to implement get_state() or restore_state()!
+            # SDK handles it automatically.
+    """
+    return StatefulVar(_default=default)
+
+
+def get_stateful_vars(obj: Any) -> dict[str, Any]:
+    """
+    Get all stateful variables from an object.
+
+    Used internally by SDK to auto-generate get_state().
+    """
+    cls = type(obj)
+    if not hasattr(cls, '_stateful_vars'):
+        return {}
+
+    result = {}
+    for name in cls._stateful_vars:
+        result[name] = getattr(obj, name)
+    return result
+
+
+def set_stateful_vars(obj: Any, state: dict[str, Any]) -> None:
+    """
+    Set stateful variables on an object from state dict.
+
+    Used internally by SDK to auto-generate restore_state().
+    """
+    cls = type(obj)
+    if not hasattr(cls, '_stateful_vars'):
+        return
+
+    for name in cls._stateful_vars:
+        if name in state:
+            setattr(obj, name, state[name])
+
+
+class StatefulMixin:
+    """
+    Mixin that provides automatic get_state() and restore_state() for @stateful vars.
+
+    If a class has @stateful decorated attributes but doesn't override
+    get_state()/restore_state(), this mixin provides default implementations.
+    """
+
+    def _get_stateful_state(self) -> dict:
+        """Get state from @stateful decorated attributes."""
+        return get_stateful_vars(self)
+
+    def _set_stateful_state(self, state: dict) -> None:
+        """Set state to @stateful decorated attributes."""
+        set_stateful_vars(self, state)

dory/errors/__init__.py

@@ -0,0 +1,117 @@
+"""
+Error classification and handling for Dory SDK.
+
+Provides intelligent error classification to determine appropriate recovery strategies.
+
+Error types:
+- TRANSIENT: Temporary failures (network, timeout) - retry
+- PERMANENT: Logic errors (validation, not found) - don't retry
+- RESOURCE: Resource exhaustion (memory, disk) - backoff + scale
+- EXTERNAL: External dependency failures - circuit breaker
+- LOGIC: Application logic errors - fix code
+
+Usage:
+    from dory.errors import ErrorClassifier, ErrorType
+
+    classifier = ErrorClassifier()
+    error_type = classifier.classify(exception)
+
+    if error_type == ErrorType.TRANSIENT:
+        # Retry the operation
+        await retry_operation()
+    elif error_type == ErrorType.EXTERNAL:
+        # Use circuit breaker
+        await circuit_breaker.call(operation)
+"""
+
+from .classification import (
+    ErrorType,
+    ErrorClassifier,
+    ClassificationResult,
+    RecoveryAction,
+    register_error_type,
+)
+from .codes import (
+    ErrorCode,
+    ErrorDomain,
+    ErrorCodeRegistry,
+    DoryError,
+    # Retry errors
+    E_RET_001,
+    E_RET_002,
+    E_RET_003,
+    # Circuit breaker errors
+    E_CBR_001,
+    E_CBR_002,
+    E_CBR_003,
+    # Error classification errors
+    E_ECL_001,
+    E_ECL_002,
+    # Golden image errors
+    E_GLD_001,
+    E_GLD_002,
+    E_GLD_003,
+    E_GLD_004,
+    E_GLD_005,
+    # Validation errors
+    E_VAL_001,
+    E_VAL_002,
+    E_VAL_003,
+    # Processing mode errors
+    E_MOD_001,
+    E_MOD_002,
+    E_MOD_003,
+    # Request tracking errors
+    E_REQ_001,
+    E_REQ_002,
+    # Connection errors
+    E_CON_001,
+    E_CON_002,
+    E_CON_003,
+    # State management errors
+    E_STA_001,
+    E_STA_002,
+    E_STA_003,
+)
+
+__all__ = [
+    # Classification
+    "ErrorType",
+    "ErrorClassifier",
+    "ClassificationResult",
+    "RecoveryAction",
+    "register_error_type",
+    # Error codes
+    "ErrorCode",
+    "ErrorDomain",
+    "ErrorCodeRegistry",
+    "DoryError",
+    # Specific error codes
+    "E_RET_001",
+    "E_RET_002",
+    "E_RET_003",
+    "E_CBR_001",
+    "E_CBR_002",
+    "E_CBR_003",
+    "E_ECL_001",
+    "E_ECL_002",
+    "E_GLD_001",
+    "E_GLD_002",
+    "E_GLD_003",
+    "E_GLD_004",
+    "E_GLD_005",
+    "E_VAL_001",
+    "E_VAL_002",
+    "E_VAL_003",
+    "E_MOD_001",
+    "E_MOD_002",
+    "E_MOD_003",
+    "E_REQ_001",
+    "E_REQ_002",
+    "E_CON_001",
+    "E_CON_002",
+    "E_CON_003",
+    "E_STA_001",
+    "E_STA_002",
+    "E_STA_003",
+]