dory-sdk 2.1.0__py3-none-any.whl

dory/types.py

@@ -0,0 +1,75 @@
+"""
+Type definitions for Dory SDK.
+
+This module contains all type hints and type aliases used across the SDK.
+No application-specific types should be defined here.
+"""
+
+from typing import TypeVar, Callable, Awaitable, Any, Protocol
+from enum import Enum, auto
+
+
+class LifecycleState(Enum):
+    """States in the processor lifecycle state machine."""
+
+    CREATED = auto()       # Instance created, not yet started
+    STARTING = auto()      # startup() in progress
+    RUNNING = auto()       # run() in progress
+    SHUTTING_DOWN = auto() # shutdown() in progress
+    STOPPED = auto()       # Gracefully stopped
+    FAILED = auto()        # Error occurred
+
+
+class StateBackend(Enum):
+    """Supported state storage backends."""
+
+    CONFIGMAP = "configmap"  # Kubernetes ConfigMap (default, <1MB)
+    PVC = "pvc"              # Persistent Volume Claim
+    S3 = "s3"                # AWS S3 (for multi-cluster)
+    LOCAL = "local"          # Local file (for testing)
+
+
+class LogFormat(Enum):
+    """Log output formats."""
+
+    JSON = "json"   # Structured JSON (default, for production)
+    TEXT = "text"   # Human-readable text (for local dev)
+
+
+class RecoveryStrategy(Enum):
+    """Recovery strategies after fault detection."""
+
+    RESTORE_STATE = "restore_state"          # Try to restore from checkpoint
+    GOLDEN_IMAGE = "golden_image"            # Start fresh, discard state
+    GOLDEN_WITH_BACKOFF = "golden_backoff"   # Start fresh with delay
+
+
+class FaultType(Enum):
+    """Types of faults detected by SDK."""
+
+    CLEAN_EXIT = "clean_exit"           # Normal termination
+    UNEXPECTED_CRASH = "crash"          # Exit code non-zero
+    HUNG_PROCESS = "hung"               # Liveness probe timeout
+    STATE_CORRUPTION = "state_corrupt"  # State validation failed
+    STARTUP_FAILURE = "startup_fail"    # Startup threw exception
+    HEALTH_CHECK_FAILURE = "health_fail"  # Health endpoint returned error
+
+
+# Type aliases
+StateDict = dict[str, Any]
+ConfigDict = dict[str, Any]
+MetadataDict = dict[str, str]
+
+# Callback types
+ShutdownCallback = Callable[[], Awaitable[None]]
+StateCallback = Callable[[], StateDict]
+
+
+class ProcessorProtocol(Protocol):
+    """Protocol defining the processor interface."""
+
+    async def startup(self) -> None: ...
+    async def run(self) -> None: ...
+    async def shutdown(self) -> None: ...
+    def get_state(self) -> StateDict: ...
+    async def restore_state(self, state: StateDict) -> None: ...

dory/utils/__init__.py

@@ -0,0 +1,25 @@
+"""Utility modules for Dory SDK."""
+
+from dory.utils.errors import (
+    DoryError,
+    DoryStartupError,
+    DoryShutdownError,
+    DoryStateError,
+    DoryConfigError,
+    DoryK8sError,
+)
+from dory.utils.retry import retry_async, RetryConfig
+from dory.utils.timeout import timeout_async, TimeoutConfig
+
+__all__ = [
+    "DoryError",
+    "DoryStartupError",
+    "DoryShutdownError",
+    "DoryStateError",
+    "DoryConfigError",
+    "DoryK8sError",
+    "retry_async",
+    "RetryConfig",
+    "timeout_async",
+    "TimeoutConfig",
+]

dory/utils/errors.py

@@ -0,0 +1,59 @@
+"""
+Dory SDK Exception Classes.
+
+All SDK-specific exceptions inherit from DoryError for easy catching.
+"""
+
+
+class DoryError(Exception):
+    """Base exception for all Dory SDK errors."""
+
+    def __init__(self, message: str, cause: Exception | None = None):
+        super().__init__(message)
+        self.message = message
+        self.cause = cause
+
+    def __str__(self) -> str:
+        if self.cause:
+            return f"{self.message}: {self.cause}"
+        return self.message
+
+
+class DoryStartupError(DoryError):
+    """Raised when processor startup fails."""
+    pass
+
+
+class DoryShutdownError(DoryError):
+    """Raised when processor shutdown fails or times out."""
+    pass
+
+
+class DoryStateError(DoryError):
+    """Raised when state operations fail (snapshot, restore, validation)."""
+    pass
+
+
+class DoryConfigError(DoryError):
+    """Raised when configuration is invalid or missing."""
+    pass
+
+
+class DoryK8sError(DoryError):
+    """Raised when Kubernetes API operations fail."""
+    pass
+
+
+class DoryHealthError(DoryError):
+    """Raised when health check operations fail."""
+    pass
+
+
+class DoryTimeoutError(DoryError):
+    """Raised when an operation times out."""
+    pass
+
+
+class DoryValidationError(DoryError):
+    """Raised when validation fails (state schema, config, etc.)."""
+    pass

dory/utils/retry.py

@@ -0,0 +1,115 @@
+"""
+Retry utilities with exponential backoff.
+"""
+
+import asyncio
+import functools
+import random
+from dataclasses import dataclass, field
+from typing import Callable, TypeVar, ParamSpec, Awaitable
+import logging
+
+logger = logging.getLogger(__name__)
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+@dataclass
+class RetryConfig:
+    """Configuration for retry behavior."""
+
+    max_attempts: int = 3
+    base_delay: float = 1.0  # seconds
+    max_delay: float = 60.0  # seconds
+    exponential_base: float = 2.0
+    jitter: bool = True
+    retryable_exceptions: tuple[type[Exception], ...] = field(
+        default_factory=lambda: (Exception,)
+    )
+
+
+def calculate_delay(
+    attempt: int,
+    config: RetryConfig,
+) -> float:
+    """Calculate delay for next retry with exponential backoff."""
+    delay = config.base_delay * (config.exponential_base ** (attempt - 1))
+    delay = min(delay, config.max_delay)
+
+    if config.jitter:
+        # Add random jitter (0-25% of delay)
+        delay = delay * (1 + random.uniform(0, 0.25))
+
+    return delay
+
+
+async def retry_async(
+    func: Callable[P, Awaitable[T]],
+    *args: P.args,
+    config: RetryConfig | None = None,
+    **kwargs: P.kwargs,
+) -> T:
+    """
+    Execute an async function with retry logic.
+
+    Args:
+        func: Async function to execute
+        *args: Positional arguments for func
+        config: Retry configuration (uses defaults if None)
+        **kwargs: Keyword arguments for func
+
+    Returns:
+        Result of func
+
+    Raises:
+        Last exception if all retries fail
+    """
+    if config is None:
+        config = RetryConfig()
+
+    last_exception: Exception | None = None
+
+    for attempt in range(1, config.max_attempts + 1):
+        try:
+            return await func(*args, **kwargs)
+        except config.retryable_exceptions as e:
+            last_exception = e
+
+            if attempt == config.max_attempts:
+                logger.warning(
+                    f"Retry exhausted after {attempt} attempts: {e}"
+                )
+                break
+
+            delay = calculate_delay(attempt, config)
+            logger.debug(
+                f"Retry attempt {attempt}/{config.max_attempts} failed: {e}. "
+                f"Retrying in {delay:.2f}s"
+            )
+            await asyncio.sleep(delay)
+
+    if last_exception:
+        raise last_exception
+
+    # Should never reach here, but satisfy type checker
+    raise RuntimeError("Retry logic error")
+
+
+def with_retry(
+    config: RetryConfig | None = None,
+) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T]]]:
+    """
+    Decorator to add retry logic to async functions.
+
+    Usage:
+        @with_retry(RetryConfig(max_attempts=5))
+        async def my_flaky_function():
+            ...
+    """
+    def decorator(func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            return await retry_async(func, *args, config=config, **kwargs)
+        return wrapper
+    return decorator

dory/utils/timeout.py

@@ -0,0 +1,80 @@
+"""
+Timeout utilities for async operations.
+"""
+
+import asyncio
+import functools
+from dataclasses import dataclass
+from typing import Callable, TypeVar, ParamSpec, Awaitable
+
+from dory.utils.errors import DoryTimeoutError
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+@dataclass
+class TimeoutConfig:
+    """Configuration for timeout behavior."""
+
+    timeout_seconds: float
+    error_message: str | None = None
+
+
+async def timeout_async(
+    func: Callable[P, Awaitable[T]],
+    *args: P.args,
+    timeout_seconds: float,
+    error_message: str | None = None,
+    **kwargs: P.kwargs,
+) -> T:
+    """
+    Execute an async function with a timeout.
+
+    Args:
+        func: Async function to execute
+        *args: Positional arguments for func
+        timeout_seconds: Maximum time to wait
+        error_message: Custom error message on timeout
+        **kwargs: Keyword arguments for func
+
+    Returns:
+        Result of func
+
+    Raises:
+        DoryTimeoutError: If function doesn't complete within timeout
+    """
+    try:
+        return await asyncio.wait_for(
+            func(*args, **kwargs),
+            timeout=timeout_seconds,
+        )
+    except asyncio.TimeoutError:
+        msg = error_message or f"Operation timed out after {timeout_seconds}s"
+        raise DoryTimeoutError(msg)
+
+
+def with_timeout(
+    timeout_seconds: float,
+    error_message: str | None = None,
+) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T]]]:
+    """
+    Decorator to add timeout to async functions.
+
+    Usage:
+        @with_timeout(30, "Startup took too long")
+        async def startup():
+            ...
+    """
+    def decorator(func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            return await timeout_async(
+                func,
+                *args,
+                timeout_seconds=timeout_seconds,
+                error_message=error_message,
+                **kwargs,
+            )
+        return wrapper
+    return decorator