fraiseql-confiture 0.3.4__cp311-cp311-win_amd64.whl

confiture/core/hooks/base.py

@@ -0,0 +1,232 @@
+"""Base classes for hooks with priority and dependencies."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from .context import HookContext
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class HookError(Exception):
+    """Exception raised during hook execution.
+
+    Provides detailed error information including the hook that failed,
+    the context in which it failed, and any nested exceptions.
+
+    Attributes:
+        hook_id: ID of the hook that failed
+        hook_name: Name of the hook that failed
+        phase: Migration phase when error occurred (e.g., "pre_migration", "post_migration")
+        message: Error message
+        cause: Original exception that caused this error
+    """
+
+    def __init__(
+        self,
+        message: str,
+        hook_id: str | None = None,
+        hook_name: str | None = None,
+        phase: str | None = None,
+        cause: Exception | None = None,
+    ):
+        """Initialize hook error.
+
+        Args:
+            message: Error message
+            hook_id: ID of hook that failed
+            hook_name: Name of hook that failed
+            phase: Migration phase when error occurred
+            cause: Original exception (for chaining)
+        """
+        self.hook_id = hook_id
+        self.hook_name = hook_name
+        self.phase = phase
+        self.cause = cause
+
+        # Build detailed error message
+        parts = [message]
+        if hook_name:
+            parts.append(f"(hook: {hook_name})")
+        if phase:
+            parts.append(f"(phase: {phase})")
+
+        full_message = " ".join(parts)
+        super().__init__(full_message)
+
+
+@dataclass
+class HookResult:
+    """Result of hook execution."""
+
+    success: bool
+    rows_affected: int = 0
+    stats: dict[str, Any] | None = None
+    error: str | None = None
+
+
+class Hook(Generic[T], ABC):
+    """Base class for all hooks."""
+
+    def __init__(
+        self,
+        hook_id: str,
+        name: str,
+        priority: int = 5,  # 1-10, lower = higher priority
+        depends_on: list[str] | None = None,
+    ):
+        self.id = hook_id
+        self.name = name
+        self.priority = priority
+        self.depends_on = depends_on or []
+
+    @abstractmethod
+    async def execute(self, context: HookContext[T]) -> HookResult:
+        """Execute hook - must be implemented by subclasses."""
+        pass
+
+
+class HookExecutor:
+    """Executes hooks in configured order with proper error handling.
+
+    Manages hook execution with support for:
+    - Sequential execution with proper ordering
+    - Dependency resolution
+    - Error handling and recovery
+    - Execution context management
+    - Performance tracking
+
+    Example:
+        >>> executor = HookExecutor(registry=registry)
+        >>> await executor.execute_phase("pre_migration", context)
+    """
+
+    def __init__(self, registry: Any | None = None):
+        """Initialize hook executor.
+
+        Args:
+            registry: Hook registry with registered hooks (optional)
+        """
+        self.registry = registry
+        self._executed_hooks: set[str] = set()
+        self._hook_results: dict[str, HookResult] = {}
+
+    async def execute_phase(self, phase: str, context: Any) -> dict[str, HookResult]:
+        """Execute all hooks for a given phase.
+
+        Args:
+            phase: Phase name (e.g., "pre_migration", "post_migration")
+            context: Hook execution context with migration state
+
+        Returns:
+            Dictionary mapping hook IDs to their execution results
+
+        Raises:
+            HookError: If any hook fails during execution
+        """
+        if not self.registry:
+            logger.debug(f"No hook registry configured, skipping phase: {phase}")
+            return {}
+
+        try:
+            # Get hooks for this phase
+            hooks = self.registry.get_hooks(phase) if hasattr(self.registry, "get_hooks") else []
+
+            if not hooks:
+                logger.debug(f"No hooks registered for phase: {phase}")
+                return {}
+
+            # Sort hooks by priority (lower number = higher priority)
+            sorted_hooks = sorted(hooks, key=lambda h: getattr(h, "priority", 5))
+
+            # Execute hooks
+            for hook in sorted_hooks:
+                await self._execute_single_hook(hook, phase, context)
+
+            return self._hook_results
+
+        except HookError:
+            raise
+        except Exception as e:
+            raise HookError(
+                message=f"Unexpected error executing phase '{phase}'",
+                phase=phase,
+                cause=e,
+            ) from e
+
+    async def _execute_single_hook(self, hook: Any, phase: str, context: Any) -> None:
+        """Execute a single hook with error handling.
+
+        Args:
+            hook: Hook instance to execute
+            phase: Phase name
+            context: Hook execution context
+
+        Raises:
+            HookError: If hook execution fails
+        """
+        hook_id = getattr(hook, "id", "unknown")
+        hook_name = getattr(hook, "name", "unknown")
+
+        # Check dependencies
+        depends_on = getattr(hook, "depends_on", [])
+        if depends_on:
+            for dep_id in depends_on:
+                if dep_id not in self._executed_hooks:
+                    raise HookError(
+                        message=f"Dependency '{dep_id}' not executed",
+                        hook_id=hook_id,
+                        hook_name=hook_name,
+                        phase=phase,
+                    )
+
+        try:
+            logger.debug(f"Executing hook '{hook_name}' ({hook_id}) in phase '{phase}'")
+
+            # Execute the hook
+            if hasattr(hook, "execute"):
+                result = (
+                    await hook.execute(context)
+                    if hasattr(hook.execute, "__await__")
+                    else hook.execute(context)
+                )
+            else:
+                raise HookError(
+                    message="Hook does not have execute method",
+                    hook_id=hook_id,
+                    hook_name=hook_name,
+                    phase=phase,
+                )
+
+            # Store result
+            self._hook_results[hook_id] = result
+            self._executed_hooks.add(hook_id)
+
+            if not result.success:
+                error_msg = result.error or "Unknown error"
+                raise HookError(
+                    message=f"Hook execution failed: {error_msg}",
+                    hook_id=hook_id,
+                    hook_name=hook_name,
+                    phase=phase,
+                )
+
+            logger.debug(f"Hook '{hook_name}' completed successfully")
+
+        except HookError:
+            raise
+        except Exception as e:
+            raise HookError(
+                message=f"Exception during hook execution: {str(e)}",
+                hook_id=hook_id,
+                hook_name=hook_name,
+                phase=phase,
+                cause=e,
+            ) from e

confiture/core/hooks/context.py

@@ -0,0 +1,146 @@
+"""Type-safe hook contexts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Generic, TypeVar
+from uuid import UUID, uuid4
+
+T = TypeVar("T")
+
+
+@dataclass
+class Schema:
+    """Basic schema representation."""
+
+    name: str
+    tables: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SchemaDifference:
+    """Represents a difference between schemas."""
+
+    type: str  # e.g., "added_table", "dropped_column", "type_change"
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RiskAssessment:
+    """Risk assessment for a migration."""
+
+    level: str  # "LOW", "MEDIUM", "HIGH", "CRITICAL"
+    score: float  # 0.0-1.0
+    factors: dict[str, float] = field(default_factory=dict)
+
+
+@dataclass
+class MigrationStep:
+    """Individual migration step."""
+
+    id: str
+    description: str
+    estimated_duration_ms: int
+    query: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SchemaAnalysisContext:
+    """Context available in before/after_analyze_schema hooks."""
+
+    source_schema: Schema
+    target_schema: Schema
+    analysis_time_ms: int
+    tables_analyzed: int
+    columns_analyzed: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SchemaDiffContext:
+    """Context available in before/after_diff_schemas hooks."""
+
+    source_schema: Schema
+    target_schema: Schema
+    differences: list[SchemaDifference] = field(default_factory=list)
+    diff_time_ms: int = 0
+    breaking_changes: list[str] = field(default_factory=list)
+    safe_changes: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MigrationPlanContext:
+    """Context available in before/after_plan_migration hooks."""
+
+    migration_steps: list[MigrationStep] = field(default_factory=list)
+    estimated_duration_ms: int = 0
+    estimated_downtime_ms: int = 0
+    risk_assessment: RiskAssessment | None = None
+    affected_tables: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ExecutionContext:
+    """Context available during before/after_execute."""
+
+    current_step: MigrationStep | None = None
+    steps_completed: int = 0
+    total_steps: int = 0
+    elapsed_time_ms: int = 0
+    rows_affected: int = 0
+    current_connections: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RollbackContext:
+    """Context available during before/after_rollback."""
+
+    rollback_reason: str
+    steps_to_rollback: list[MigrationStep] = field(default_factory=list)
+    original_error: Exception | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ValidationContext:
+    """Context available during before/after_validate."""
+
+    validation_results: list[dict[str, Any]] = field(default_factory=list)
+    passed: bool = True
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class HookContext(Generic[T]):
+    """Type-safe hook context with phase-specific information."""
+
+    def __init__(
+        self,
+        phase: Any,  # HookPhase | HookEvent | HookAlert
+        data: T,
+        execution_id: UUID | None = None,
+        hook_id: str | None = None,
+    ):
+        self.phase = phase
+        self.data: T = data  # Type-safe data
+        self.execution_id = execution_id or uuid4()  # Correlation ID for tracing
+        self.hook_id = hook_id or "unknown"
+        self.timestamp = datetime.now(UTC)
+        self.parent_execution_id: UUID | None = None  # For nested hooks
+
+    def get_data(self) -> T:
+        """Get phase-specific data (type-safe)."""
+        return self.data
+
+    def add_metadata(self, key: str, value: Any) -> None:
+        """Add metadata for observability."""
+        if hasattr(self.data, "metadata") and isinstance(self.data.metadata, dict):
+            metadata: dict[str, Any] = self.data.metadata  # type: ignore[union-attr]
+            metadata[key] = value

confiture/core/hooks/execution_strategies.py

@@ -0,0 +1,57 @@
+"""Hook execution strategies and configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class HookExecutionStrategy(Enum):
+    """Defines how hooks execute within a phase."""
+
+    SEQUENTIAL = "sequential"  # One by one, in priority order
+    PARALLEL = "parallel"  # All simultaneously via asyncio.gather()
+    PARALLEL_WITH_DEPS = "parallel_with_deps"  # DAG execution respecting dependencies
+
+
+class HookErrorStrategy(Enum):
+    """What happens when a hook fails."""
+
+    FAIL_FAST = "fail_fast"  # Stop execution, fail migration
+    FAIL_SAFE = "fail_safe"  # Log error, continue migration
+    RETRY = "retry"  # Retry with exponential backoff
+    ALERT_ONLY = "alert_only"  # Alert but continue
+
+
+class HookContextMutationPolicy(Enum):
+    """Whether downstream hooks can see upstream modifications."""
+
+    IMMUTABLE = "immutable"  # Context is read-only
+    MUTABLE = "mutable"  # Hooks can modify for downstream
+    COPY_ON_WRITE = "copy_on_write"  # Each hook gets modified copy
+
+
+@dataclass
+class RetryConfig:
+    """Retry strategy for RETRY error handling."""
+
+    max_attempts: int = 3
+    initial_delay_ms: int = 100
+    max_delay_ms: int = 30000
+    backoff_multiplier: float = 2.0
+
+
+@dataclass
+class HookPhaseConfig:
+    """Configuration for hook execution in a specific phase."""
+
+    phase: Any  # HookPhase | HookEvent | HookAlert
+    execution_strategy: HookExecutionStrategy = HookExecutionStrategy.SEQUENTIAL
+    error_strategy: HookErrorStrategy = HookErrorStrategy.FAIL_FAST
+    context_mutation_policy: HookContextMutationPolicy = HookContextMutationPolicy.IMMUTABLE
+    timeout_per_hook_ms: int = 30000  # 30 seconds per hook
+    timeout_per_phase_ms: int = 300000  # 5 minutes per phase
+    max_parallel_hooks: int = 4  # Limit concurrent execution
+    retry_config: RetryConfig | None = None  # For RETRY strategy
+    circuit_breaker_enabled: bool = True  # Prevent cascading failures

confiture/core/hooks/observability.py

@@ -0,0 +1,220 @@
+"""Observability and tracing infrastructure for hooks."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+logger = logging.getLogger(__name__)
+
+
+class HookExecutionStatus(Enum):
+    """Status of hook execution."""
+
+    PENDING = "pending"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    TIMEOUT = "timeout"
+    SKIPPED = "skipped"
+
+
+class CircuitBreakerState(Enum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Blocking requests
+    HALF_OPEN = "half_open"  # Testing recovery
+
+
+@dataclass
+class HookExecutionEvent:
+    """Record of a single hook execution."""
+
+    execution_id: UUID  # Trace correlation ID
+    hook_id: str
+    phase: str
+    status: HookExecutionStatus
+    duration_ms: int
+    rows_affected: int = 0
+    error: str | None = None
+    reason: str | None = None
+    stats: dict[str, Any] | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+@dataclass
+class HookExecutionResult:
+    """Result of executing all hooks in a phase."""
+
+    phase: str
+    hooks_executed: int
+    results: list[HookExecutionEvent] | None = None
+    total_duration_ms: int = 0
+    failed_count: int = 0
+    timeout_count: int = 0
+
+
+@dataclass
+class ExecutionDAG:
+    """Directed acyclic graph of hook dependencies."""
+
+    execution_id: UUID
+    hooks: list[str] = field(default_factory=list)
+    edges: list[tuple[str, str]] = field(default_factory=list)  # (from, to) pairs
+
+
+@dataclass
+class PerformanceTrace:
+    """Detailed performance trace of hook execution."""
+
+    execution_id: UUID
+    total_duration_ms: int
+    hook_events: list[HookExecutionEvent] = field(default_factory=list)
+    critical_path: list[str] = field(default_factory=list)
+
+
+class CircuitBreaker:
+    """Prevent cascading failures from failing hooks."""
+
+    def __init__(
+        self,
+        hook_id: str,
+        failure_threshold: int = 5,
+        recovery_timeout_ms: int = 60000,
+    ):
+        self.hook_id = hook_id
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout_ms = recovery_timeout_ms
+        self.failure_count = 0
+        self.last_failure_time = None
+        self.state = CircuitBreakerState.CLOSED
+
+    @property
+    def is_open(self) -> bool:
+        """Is circuit breaker open (blocking requests)?"""
+        if self.state == CircuitBreakerState.OPEN:
+            # Check if recovery timeout has elapsed
+            if (
+                self.last_failure_time
+                and (datetime.now(UTC) - self.last_failure_time).total_seconds() * 1000
+                > self.recovery_timeout_ms
+            ):
+                self.state = CircuitBreakerState.HALF_OPEN
+                self.failure_count = 0
+                return False
+            return True
+        return False
+
+    def record_success(self) -> None:
+        """Record successful hook execution."""
+        if self.state == CircuitBreakerState.HALF_OPEN:
+            self.state = CircuitBreakerState.CLOSED
+            self.failure_count = 0
+
+    def record_failure(self) -> None:
+        """Record failed hook execution."""
+        self.failure_count += 1
+        self.last_failure_time = datetime.now(UTC)
+
+        if self.failure_count >= self.failure_threshold:
+            self.state = CircuitBreakerState.OPEN
+            logger.warning(
+                f"Circuit breaker opened for hook {self.hook_id} after "
+                f"{self.failure_count} failures"
+            )
+
+
+class HookExecutionTracer:
+    """Track and trace hook execution for debugging."""
+
+    def __init__(self):
+        self.execution_log: list[HookExecutionEvent] = []
+        self.execution_graphs: dict[UUID, ExecutionDAG] = {}
+
+    def record_execution(self, event: HookExecutionEvent) -> None:
+        """Record hook execution event."""
+        self.execution_log.append(event)
+        logger.info(
+            f"Hook {event.hook_id} in {event.phase}: {event.status.value} ({event.duration_ms}ms)"
+        )
+
+    def get_execution_log(
+        self,
+        execution_id: UUID | None = None,
+        phase: str | None = None,
+    ) -> list[HookExecutionEvent]:
+        """Get execution log with optional filtering."""
+        log = self.execution_log
+
+        if execution_id:
+            log = [e for e in log if e.execution_id == execution_id]
+
+        if phase:
+            log = [e for e in log if e.phase == phase]
+
+        return log
+
+    def get_execution_dag(self, execution_id: UUID) -> ExecutionDAG | None:
+        """Get execution DAG showing hook dependencies."""
+        return self.execution_graphs.get(execution_id)
+
+    def get_performance_trace(self, execution_id: UUID) -> PerformanceTrace:
+        """Get detailed performance trace."""
+        events = self.get_execution_log(execution_id=execution_id)
+
+        return PerformanceTrace(
+            execution_id=execution_id,
+            total_duration_ms=sum(e.duration_ms for e in events),
+            hook_events=events,
+            critical_path=self._compute_critical_path(events),
+        )
+
+    def _compute_critical_path(self, events: list[HookExecutionEvent]) -> list[str]:
+        """Compute critical path - hooks that contributed most to total duration.
+
+        Algorithm:
+        1. Sort events by timestamp (execution order)
+        2. Identify sequential execution blocks (no overlap)
+        3. Return hooks in the longest duration chain
+
+        Note: This assumes sequential execution. For parallel execution,
+        a full DAG analysis with explicit dependencies would be needed.
+        """
+        if not events:
+            return []
+
+        if len(events) == 1:
+            return [events[0].hook_id]
+
+        # Sort events by timestamp and end time
+        sorted_events = sorted(events, key=lambda e: e.timestamp)
+
+        # Find hooks that form a critical path (non-overlapping sequential chain)
+        critical_path = []
+        max_end_time = None
+
+        for event in sorted_events:
+            # Only include events that start after the previous one ended
+            # (indicating sequential dependency)
+            if max_end_time is None or event.timestamp >= max_end_time:
+                critical_path.append(event.hook_id)
+                # Update end time (approximated as timestamp + duration)
+                end_timestamp = event.timestamp.timestamp() + (event.duration_ms / 1000)
+                max_end_time = datetime.fromtimestamp(end_timestamp, tz=UTC)
+
+        # If we got no sequential chain, return the longest single execution
+        if not critical_path:
+            longest = max(sorted_events, key=lambda e: e.duration_ms)
+            return [longest.hook_id]
+
+        return critical_path
+
+
+class HookExecutionError(Exception):
+    """Exception raised when hook execution fails."""
+
+    pass