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

dory/config/defaults.py

@@ -0,0 +1,24 @@
+"""Default configuration values for Dory SDK.
+
+Only values referenced by DoryConfig schema are included here.
+Component-specific defaults (circuit breakers, OpenTelemetry, etc.)
+live in the components themselves.
+"""
+
+from dory.types import StateBackend
+
+# Default configuration dictionary
+DEFAULT_CONFIG = {
+    # Lifecycle timeouts
+    "startup_timeout_sec": 30,
+    "shutdown_timeout_sec": 30,
+
+    # Health server
+    "health_port": 8080,
+
+    # State management
+    "state_backend": StateBackend.CONFIGMAP.value,
+
+    # Logging
+    "log_level": "INFO",
+}

dory/config/loader.py

@@ -0,0 +1,430 @@
+"""
+Configuration loader for Dory SDK.
+
+Supports loading from:
+1. YAML configuration file
+2. Environment variables (DORY_ prefix)
+3. Configuration presets
+4. Auto-detection (service name, version, environment)
+5. Default values
+"""
+
+import logging
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+
+from dory.config.schema import DoryConfig
+from dory.config.presets import get_preset, list_presets, DEVELOPMENT_PRESET
+from dory.utils.errors import DoryConfigError
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigLoader:
+    """
+    Smart configuration loader with:
+    - Auto-detection of service name/version
+    - Preset support (development, production, high-availability)
+    - Zero-config mode
+    - Progressive disclosure
+
+    Priority order:
+    1. Environment variables (highest)
+    2. Config file
+    3. Preset (if specified)
+    4. Auto-detected defaults
+    5. Default values (lowest)
+    """
+
+    ENV_PREFIX = "DORY_"
+    DEFAULT_CONFIG_PATHS = [
+        "/etc/dory/config.yaml",
+        "/app/config/dory.yaml",
+        "./dory.yaml",
+    ]
+
+    def __init__(self, config_file: str | None = None):
+        """
+        Initialize config loader.
+
+        Args:
+            config_file: Optional path to YAML config file
+        """
+        self._config_file = config_file
+
+    def load(self) -> DoryConfig:
+        """
+        Load and validate configuration.
+
+        In Kubernetes (under orchestrator):
+            All config comes from orchestrator-injected env vars + defaults.
+            YAML files and presets are ignored — the orchestrator is the
+            single source of truth for health_port, state_backend, log_level,
+            timeouts, version, etc.
+
+        In local development (no orchestrator):
+            1. Environment variables (DORY_*)
+            2. Config file (dory.yaml)
+            3. Preset (if specified)
+            4. Auto-detected defaults
+            5. Default values
+
+        Returns:
+            Validated DoryConfig instance
+
+        Raises:
+            DoryConfigError: If configuration is invalid
+        """
+        if self._is_running_in_kubernetes():
+            return self._load_orchestrated()
+        return self._load_local()
+
+    def _load_orchestrated(self) -> DoryConfig:
+        """Load config when running under orchestrator in K8s.
+
+        All settings come from orchestrator-injected env vars.
+        YAML files and presets are ignored.
+        """
+        # Start with production defaults
+        config_dict = get_preset("production")
+
+        # App info from orchestrator env vars only
+        app_config = {
+            "name": os.environ.get("PROCESSOR_ID", Path.cwd().name),
+            "version": os.environ.get("DORY_APP_VERSION", "0.0.0"),
+            "environment": "production",
+        }
+        config_dict["app"] = app_config
+
+        # Apply orchestrator-injected env vars (the only override source)
+        env_config = self._load_from_env()
+        config_dict = self._deep_merge(config_dict, env_config)
+
+        try:
+            config = DoryConfig(**config_dict)
+            logger.info(
+                f"Configuration loaded (orchestrated): "
+                f"{app_config['name']} v{app_config['version']}"
+            )
+            logger.debug(f"Full configuration: {config.model_dump()}")
+            return config
+        except Exception as e:
+            raise DoryConfigError(f"Invalid configuration: {e}", cause=e)
+
+    def _load_local(self) -> DoryConfig:
+        """Load config for local development (no orchestrator).
+
+        Supports YAML files, presets, and auto-detection.
+        """
+        # Try to load config file
+        file_config = self._load_from_file()
+
+        # Determine which preset to use
+        preset_name = self._determine_preset(file_config)
+
+        # Start with preset
+        if preset_name in list_presets():
+            config_dict = get_preset(preset_name)
+            logger.info(f"Using configuration preset: {preset_name}")
+        else:
+            config_dict = DEVELOPMENT_PRESET.copy()
+            logger.warning(f"Unknown preset '{preset_name}', using development defaults")
+
+        # Auto-detect application info
+        app_config = self._auto_detect_app_info(
+            file_config.get("app", {}) if file_config else {}
+        )
+        config_dict["app"] = app_config
+
+        # Deep merge file config (overrides preset), excluding app
+        if file_config:
+            file_config_without_app = {
+                k: v for k, v in file_config.items() if k != "app"
+            }
+            config_dict = self._deep_merge(config_dict, file_config_without_app)
+
+        # Apply environment variable overrides (highest priority)
+        env_config = self._load_from_env()
+        config_dict = self._deep_merge(config_dict, env_config)
+
+        # Validate and create config object
+        try:
+            config = DoryConfig(**config_dict)
+            logger.info(
+                f"Configuration loaded (local): "
+                f"{app_config.get('name', 'unknown')} v{app_config.get('version', 'unknown')}"
+            )
+            logger.debug(f"Full configuration: {config.model_dump()}")
+            return config
+        except Exception as e:
+            raise DoryConfigError(f"Invalid configuration: {e}", cause=e)
+
+    def _load_from_file(self) -> dict[str, Any] | None:
+        """Load configuration from YAML file."""
+        config_path = self._find_config_file()
+
+        if not config_path:
+            logger.debug("No config file found, using defaults")
+            return None
+
+        try:
+            with open(config_path) as f:
+                config = yaml.safe_load(f) or {}
+
+            logger.info(f"Loaded config from {config_path}")
+            return config
+
+        except yaml.YAMLError as e:
+            raise DoryConfigError(f"Invalid YAML in {config_path}: {e}", cause=e)
+        except Exception as e:
+            raise DoryConfigError(f"Failed to read {config_path}: {e}", cause=e)
+
+    def _find_config_file(self) -> Path | None:
+        """Find config file from explicit path or default locations."""
+        # Check explicit path first
+        if self._config_file:
+            path = Path(self._config_file)
+            if path.exists():
+                return path
+            raise DoryConfigError(f"Config file not found: {self._config_file}")
+
+        # Check environment variable
+        env_path = os.environ.get("DORY_CONFIG_FILE")
+        if env_path:
+            path = Path(env_path)
+            if path.exists():
+                return path
+            logger.warning(f"DORY_CONFIG_FILE set but not found: {env_path}")
+
+        # Check default locations
+        for default_path in self.DEFAULT_CONFIG_PATHS:
+            path = Path(default_path)
+            if path.exists():
+                return path
+
+        return None
+
+    def _load_from_env(self) -> dict[str, Any]:
+        """Load configuration from environment variables."""
+        config = {}
+
+        # Map of config keys to environment variable names.
+        # Only settings that legitimately vary per deployment are exposed.
+        # Internal tuning, system invariants, and hardcoded values are
+        # managed by the SDK defaults and should not be overridden.
+        env_mapping = {
+            # Lifecycle timeouts (vary by app workload)
+            "startup_timeout_sec": "DORY_STARTUP_TIMEOUT_SEC",
+            "shutdown_timeout_sec": "DORY_SHUTDOWN_TIMEOUT_SEC",
+            # Health server
+            "health_port": "DORY_HEALTH_PORT",
+            # State management (backend choice is per-deployment)
+            "state_backend": "DORY_STATE_BACKEND",
+            # Logging
+            "log_level": "DORY_LOG_LEVEL",
+        }
+
+        for config_key, env_var in env_mapping.items():
+            value = os.environ.get(env_var)
+            if value is not None:
+                # Convert to appropriate type
+                config[config_key] = self._convert_env_value(config_key, value)
+
+        return config
+
+    def _convert_env_value(self, key: str, value: str) -> Any:
+        """Convert environment variable string to appropriate type."""
+        int_fields = {
+            "startup_timeout_sec",
+            "shutdown_timeout_sec",
+            "health_port",
+        }
+
+        if key in int_fields:
+            try:
+                return int(value)
+            except ValueError:
+                raise DoryConfigError(f"Invalid integer for {key}: {value}")
+
+        return value
+
+    def _determine_preset(self, file_config: Optional[Dict[str, Any]]) -> Optional[str]:
+        """
+        Determine which preset to use.
+
+        Priority:
+        1. DORY_PRESET environment variable
+        2. preset field in config file
+        3. Auto-detect based on environment (Kubernetes vs local)
+
+        Args:
+            file_config: Configuration loaded from file
+
+        Returns:
+            Preset name
+        """
+        # Check environment variable first
+        preset = os.environ.get("DORY_PRESET")
+        if preset:
+            logger.debug(f"Preset from environment: {preset}")
+            return preset
+
+        # Check config file
+        if file_config and "preset" in file_config:
+            preset = file_config["preset"]
+            logger.debug(f"Preset from config file: {preset}")
+            return preset
+
+        # Auto-detect: if running in Kubernetes, use production preset
+        if self._is_running_in_kubernetes():
+            logger.info("Kubernetes environment detected, using production preset")
+            return "production"
+
+        # Default to development for local runs
+        logger.debug("Local environment detected, using development preset")
+        return "development"
+
+    def _is_running_in_kubernetes(self) -> bool:
+        """
+        Detect if running inside a Kubernetes cluster.
+
+        Checks for:
+        - KUBERNETES_SERVICE_HOST (set by K8s)
+        - DORY_POD_NAME (set by deployment)
+        - /var/run/secrets/kubernetes.io (K8s service account)
+
+        Returns:
+            True if running in Kubernetes
+        """
+        # Check K8s service host (always set in K8s pods)
+        if os.environ.get("KUBERNETES_SERVICE_HOST"):
+            return True
+
+        # Check Dory-specific pod name (set in deployment)
+        if os.environ.get("DORY_POD_NAME"):
+            return True
+
+        # Check for K8s service account directory
+        if Path("/var/run/secrets/kubernetes.io").exists():
+            return True
+
+        return False
+
+    def _auto_detect_app_info(self, user_app: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Auto-detect service name, version, and environment.
+
+        Args:
+            user_app: User-provided app configuration
+
+        Returns:
+            Dictionary with app configuration
+        """
+        app = {}
+
+        # Auto-detect service name
+        if "name" in user_app:
+            app["name"] = user_app["name"]
+        else:
+            # Try to detect from directory name
+            cwd = Path.cwd()
+            app["name"] = cwd.name
+            logger.debug(f"Auto-detected service name: {app['name']}")
+
+        # Version: DORY_APP_VERSION is injected by the orchestrator from DB
+        # and always takes precedence. Local auto-detection is only for dev.
+        if os.environ.get("DORY_APP_VERSION"):
+            app["version"] = os.environ["DORY_APP_VERSION"]
+            logger.debug(f"Version from orchestrator: {app['version']}")
+        elif "version" in user_app:
+            app["version"] = user_app["version"]
+        else:
+            app["version"] = self._detect_version()
+            logger.debug(f"Auto-detected version: {app['version']}")
+
+        # Auto-detect environment
+        if "environment" in user_app:
+            app["environment"] = user_app["environment"]
+        else:
+            app["environment"] = os.environ.get("ENVIRONMENT", "development")
+            logger.debug(f"Auto-detected environment: {app['environment']}")
+
+        # Copy any other user-provided app config
+        for key, value in user_app.items():
+            if key not in app:
+                app[key] = value
+
+        return app
+
+    def _detect_version(self) -> str:
+        """
+        Try to detect version from various sources.
+
+        Returns:
+            Version string
+        """
+        # Try git tag
+        try:
+            result = subprocess.run(
+                ["git", "describe", "--tags", "--abbrev=0"],
+                capture_output=True,
+                text=True,
+                timeout=1,
+                check=False,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                return result.stdout.strip()
+        except Exception:
+            pass
+
+        # Try pyproject.toml
+        pyproject_path = Path("pyproject.toml")
+        if pyproject_path.exists():
+            try:
+                with open(pyproject_path) as f:
+                    content = f.read()
+                    # Simple regex to extract version
+                    match = re.search(r'version\s*=\s*"([^"]+)"', content)
+                    if match:
+                        return match.group(1)
+            except Exception:
+                pass
+
+        # Try package.json (for Node.js projects)
+        package_json_path = Path("package.json")
+        if package_json_path.exists():
+            try:
+                with open(package_json_path) as f:
+                    import json
+                    data = json.load(f)
+                    if "version" in data:
+                        return data["version"]
+            except Exception:
+                pass
+
+        # Default
+        return "0.1.0-dev"
+
+    def _deep_merge(self, base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Deep merge two dictionaries.
+
+        Args:
+            base: Base dictionary
+            override: Dictionary with override values
+
+        Returns:
+            Merged dictionary
+        """
+        result = base.copy()
+        for key, value in override.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._deep_merge(result[key], value)
+            else:
+                result[key] = value
+        return result

dory/config/presets.py

@@ -0,0 +1,73 @@
+"""Configuration presets for common scenarios.
+
+Presets provide sensible defaults for different deployment environments.
+Only flat keys that DoryConfig recognizes are included — nested component
+tuning (circuit breakers, OpenTelemetry, etc.) uses SDK defaults and can
+be customized in code by overriding BaseProcessor.__init__.
+"""
+
+from typing import Dict, Any
+
+# Development preset - developer-friendly defaults
+DEVELOPMENT_PRESET: Dict[str, Any] = {
+    "environment": "development",
+    "log_level": "DEBUG",
+    "health_port": 0,  # Auto-select available port
+    "state_backend": "local",
+    "startup_timeout_sec": 30,
+    "shutdown_timeout_sec": 30,
+}
+
+# Production preset - production-ready defaults
+PRODUCTION_PRESET: Dict[str, Any] = {
+    "environment": "production",
+    "log_level": "INFO",
+    "health_port": 8080,
+    "state_backend": "configmap",
+    "startup_timeout_sec": 120,
+    "shutdown_timeout_sec": 30,
+}
+
+# High-availability preset - aggressive fault tolerance
+HIGH_AVAILABILITY_PRESET: Dict[str, Any] = {
+    "environment": "production",
+    "log_level": "INFO",
+    "health_port": 8080,
+    "state_backend": "pvc",
+    "startup_timeout_sec": 120,
+    "shutdown_timeout_sec": 60,
+}
+
+PRESETS: Dict[str, Dict[str, Any]] = {
+    "development": DEVELOPMENT_PRESET,
+    "production": PRODUCTION_PRESET,
+    "high-availability": HIGH_AVAILABILITY_PRESET,
+}
+
+
+def get_preset(name: str) -> Dict[str, Any]:
+    """
+    Get configuration preset by name.
+
+    Args:
+        name: Preset name (development, production, high-availability)
+
+    Returns:
+        Dictionary with preset configuration
+
+    Raises:
+        ValueError: If preset name is unknown
+    """
+    if name not in PRESETS:
+        raise ValueError(f"Unknown preset: {name}. Available: {list(PRESETS.keys())}")
+    return PRESETS[name].copy()
+
+
+def list_presets() -> list[str]:
+    """
+    Get list of available preset names.
+
+    Returns:
+        List of preset names
+    """
+    return list(PRESETS.keys())

dory/config/schema.py

@@ -0,0 +1,84 @@
+"""
+Configuration schema for Dory SDK.
+
+Uses Pydantic for validation and type coercion.
+Only settings that legitimately vary per deployment are configurable.
+
+RabbitMQ settings are intentionally absent — the publisher reads
+directly from DORY_RABBITMQ_* environment variables because they
+contain secrets (OAuth2 credentials) that should not flow through
+YAML config files.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+from dory.types import StateBackend
+from dory.config.defaults import DEFAULT_CONFIG
+
+
+class DoryConfig(BaseModel):
+    """
+    Dory SDK configuration schema.
+
+    Configurable settings can be set via:
+    1. YAML config file (dory.yaml)
+    2. Environment variables (DORY_ prefix)
+    3. Constructor arguments
+    """
+
+    # Lifecycle timeouts (vary by app workload)
+    startup_timeout_sec: int = Field(
+        default=DEFAULT_CONFIG["startup_timeout_sec"],
+        ge=1,
+        le=300,
+        description="Maximum time for startup in seconds",
+    )
+    shutdown_timeout_sec: int = Field(
+        default=DEFAULT_CONFIG["shutdown_timeout_sec"],
+        ge=1,
+        le=300,
+        description="Maximum time for shutdown in seconds",
+    )
+
+    # Health server
+    health_port: int = Field(
+        default=DEFAULT_CONFIG["health_port"],
+        ge=0,  # 0 = auto-select available port (development mode)
+        le=65535,
+        description="Port for health/metrics HTTP server (0 = auto-select)",
+    )
+
+    # State management (backend choice is per-deployment)
+    state_backend: str = Field(
+        default=DEFAULT_CONFIG["state_backend"],
+        description="Backend for state persistence",
+    )
+
+    # Logging
+    log_level: str = Field(
+        default=DEFAULT_CONFIG["log_level"],
+        description="Logging level (DEBUG, INFO, WARNING, ERROR)",
+    )
+
+    @field_validator("state_backend")
+    @classmethod
+    def validate_state_backend(cls, v: str) -> str:
+        """Validate state backend value."""
+        valid_backends = [b.value for b in StateBackend]
+        if v not in valid_backends:
+            raise ValueError(f"state_backend must be one of {valid_backends}")
+        return v
+
+    @field_validator("log_level")
+    @classmethod
+    def validate_log_level(cls, v: str) -> str:
+        """Validate log level."""
+        valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        v_upper = v.upper()
+        if v_upper not in valid_levels:
+            raise ValueError(f"log_level must be one of {valid_levels}")
+        return v_upper
+
+    model_config = {
+        "extra": "ignore",  # Ignore unknown fields
+    }

dory/core/__init__.py

@@ -0,0 +1,27 @@
+"""Core modules for Dory SDK."""
+
+from dory.core.processor import BaseProcessor
+from dory.core.context import ExecutionContext
+from dory.core.app import DoryApp
+from dory.core.lifecycle import LifecycleManager
+from dory.core.signals import SignalHandler
+from dory.core.modes import (
+    ModeManager,
+    ProcessingMode,
+    ModeTransition,
+    ModeTransitionReason,
+    ModeConfig,
+)
+
+__all__ = [
+    "BaseProcessor",
+    "ExecutionContext",
+    "DoryApp",
+    "LifecycleManager",
+    "SignalHandler",
+    "ModeManager",
+    "ProcessingMode",
+    "ModeTransition",
+    "ModeTransitionReason",
+    "ModeConfig",
+]