kailash 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

kailash/runtime/validation/connection_context.py

@@ -0,0 +1,119 @@
+"""
+Connection context tracking for enhanced error messages.
+
+Provides detailed information about connection sources and targets
+to enable precise error message generation with connection paths.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class ConnectionContext:
+    """Context information for a specific parameter connection.
+
+    Tracks the source and target of a connection to enable detailed
+    error message generation with connection path reconstruction.
+    """
+
+    source_node: str
+    """Source node ID in the workflow"""
+
+    source_port: Optional[str]
+    """Output port/parameter from source node (e.g., 'result.data')"""
+
+    target_node: str
+    """Target node ID in the workflow"""
+
+    target_port: str
+    """Input parameter on target node"""
+
+    parameter_value: Any
+    """The actual parameter value being passed through connection"""
+
+    validation_mode: str
+    """Validation mode: 'off', 'warn', or 'strict'"""
+
+    def get_connection_path(self) -> str:
+        """Generate human-readable connection path string.
+
+        Returns:
+            Connection path in format: source_node.source_port → target_node.target_port
+        """
+        source_part = self.source_node
+        if self.source_port:
+            source_part = f"{self.source_node}.{self.source_port}"
+
+        target_part = f"{self.target_node}.{self.target_port}"
+
+        return f"{source_part} → {target_part}"
+
+    def get_sanitized_value(self) -> str:
+        """Get sanitized representation of parameter value for error messages.
+
+        Sanitizes sensitive information like SQL injection attempts, passwords, etc.
+
+        Returns:
+            Safe string representation of the parameter value
+        """
+        if self.parameter_value is None:
+            return "None"
+
+        value_str = str(self.parameter_value)
+
+        # Detect and sanitize potential security issues
+        security_patterns = [
+            "drop table",
+            "delete from",
+            "insert into",
+            "update set",
+            "union select",
+            "exec(",
+            "eval(",
+            "script>",
+            "password",
+            "secret",
+            "token",
+            "key",
+        ]
+
+        for pattern in security_patterns:
+            if pattern.lower() in value_str.lower():
+                return "**SANITIZED**"
+
+        # Truncate very long values
+        if len(value_str) > 100:
+            return f"{value_str[:97]}..."
+
+        return value_str
+
+    def is_security_sensitive(self) -> bool:
+        """Check if the parameter value contains security-sensitive data.
+
+        Returns:
+            True if the value appears to contain sensitive information
+        """
+        if self.parameter_value is None:
+            return False
+
+        value_str = str(self.parameter_value).lower()
+
+        sensitive_indicators = [
+            "password",
+            "secret",
+            "token",
+            "key",
+            "auth",
+            "drop",
+            "delete",
+            "insert",
+            "update",
+            "exec",
+            "union",
+            "select",
+            "script",
+            "eval",
+        ]
+
+        return any(indicator in value_str for indicator in sensitive_indicators)

kailash/runtime/validation/enhanced_error_formatter.py

@@ -0,0 +1,202 @@
+"""
+Enhanced error message formatting for connection validation errors.
+
+Formats validation errors into structured, readable messages with
+connection paths, categorization, suggestions, and examples.
+"""
+
+from typing import Optional
+
+from .connection_context import ConnectionContext
+from .error_categorizer import ErrorCategorizer, ErrorCategory
+from .suggestion_engine import ValidationSuggestion
+
+
+class EnhancedErrorFormatter:
+    """Formats validation errors into enhanced, actionable error messages."""
+
+    def __init__(self):
+        self.categorizer = ErrorCategorizer()
+
+    def format_enhanced_error(
+        self,
+        original_error: str,
+        error_category: ErrorCategory,
+        connection_context: ConnectionContext,
+        suggestion: Optional[ValidationSuggestion] = None,
+    ) -> str:
+        """Format a comprehensive error message with all enhancement details.
+
+        Args:
+            original_error: Original validation error message
+            error_category: Categorized error type
+            connection_context: Context about the failing connection
+            suggestion: Optional actionable suggestion
+
+        Returns:
+            Formatted error message with structured sections
+        """
+        sections = []
+
+        # Header with error category
+        category_desc = self.categorizer.get_category_description(error_category)
+        severity = self.categorizer.get_severity_level(error_category)
+
+        sections.append(f"🚨 Connection Validation Error: {category_desc} [{severity}]")
+        sections.append("=" * 60)
+
+        # Problem section
+        sections.append("\n📋 Problem:")
+        sections.append(f"    {original_error}")
+
+        # Connection path section
+        sections.append("\n🔗 Connection:")
+        connection_path = connection_context.get_connection_path()
+        sections.append(f"    {connection_path}")
+
+        # Parameter details (sanitized)
+        if not connection_context.is_security_sensitive():
+            value_repr = connection_context.get_sanitized_value()
+            sections.append(f"    Value: {value_repr}")
+        else:
+            sections.append("    Value: **REDACTED** (security-sensitive)")
+
+        sections.append(f"    Validation Mode: {connection_context.validation_mode}")
+
+        # Suggestion section
+        if suggestion:
+            sections.append("\n💡 Suggestion:")
+            sections.append(f"    {suggestion.message}")
+
+            # Code example
+            if suggestion.code_example:
+                sections.append("\n📝 Example:")
+                example_lines = suggestion.code_example.split("\n")
+                for line in example_lines:
+                    sections.append(f"    {line}")
+
+            # Alternative approaches
+            if suggestion.alternative_approaches:
+                sections.append("\n🔄 Alternatives:")
+                for i, alt in enumerate(suggestion.alternative_approaches, 1):
+                    sections.append(f"    {i}. {alt}")
+
+            # Documentation link
+            if suggestion.documentation_link:
+                sections.append("\n📚 Documentation:")
+                sections.append(f"    {suggestion.documentation_link}")
+        else:
+            sections.append("\n💡 Suggestion:")
+            sections.append("    Check node documentation for parameter requirements.")
+            sections.append("    Verify data types and connection mapping.")
+
+        # Troubleshooting tips
+        sections.append("\n🛠️  Quick Troubleshooting:")
+        sections.append("    1. Check the source node output format")
+        sections.append("    2. Verify target node parameter requirements")
+        sections.append("    3. Test with simplified data first")
+        sections.append(
+            "    4. Review connection syntax: workflow.add_connection(source, source_port, target, target_port)"
+        )
+
+        return "\n".join(sections)
+
+    def format_simple_error(
+        self, original_error: str, connection_context: ConnectionContext
+    ) -> str:
+        """Format a simple enhanced error message for warn mode.
+
+        Args:
+            original_error: Original validation error message
+            connection_context: Context about the failing connection
+
+        Returns:
+            Simple formatted error message
+        """
+        connection_path = connection_context.get_connection_path()
+        return f"Connection validation warning: {connection_path} - {original_error}"
+
+    def format_security_error(
+        self,
+        original_error: str,
+        connection_context: ConnectionContext,
+        suggestion: Optional[ValidationSuggestion] = None,
+    ) -> str:
+        """Format security-specific error message with appropriate warnings.
+
+        Args:
+            original_error: Original security error message
+            connection_context: Context about the failing connection
+            suggestion: Optional security-specific suggestion
+
+        Returns:
+            Security-focused error message
+        """
+        sections = []
+
+        sections.append("🔒 SECURITY ALERT: Potential Security Vulnerability")
+        sections.append("=" * 60)
+
+        sections.append("\n⚠️  Security Issue:")
+        sections.append(f"    {original_error}")
+
+        sections.append("\n🔗 Affected Connection:")
+        connection_path = connection_context.get_connection_path()
+        sections.append(f"    {connection_path}")
+
+        # Always redact security-sensitive values
+        sections.append("    Value: **REDACTED** (potential security risk)")
+
+        if suggestion:
+            sections.append("\n🛡️  Security Recommendation:")
+            sections.append(f"    {suggestion.message}")
+
+            if suggestion.code_example:
+                sections.append("\n🔐 Secure Example:")
+                example_lines = suggestion.code_example.split("\n")
+                for line in example_lines:
+                    sections.append(f"    {line}")
+
+        sections.append("\n🚨 Immediate Actions:")
+        sections.append("    1. Review the data source for potential attacks")
+        sections.append("    2. Implement input validation and sanitization")
+        sections.append("    3. Use parameterized queries for database operations")
+        sections.append("    4. Consider implementing rate limiting")
+
+        sections.append("\n📋 Security Checklist:")
+        sections.append("    □ Input validation implemented")
+        sections.append("    □ Output encoding applied")
+        sections.append("    □ Parameterized queries used")
+        sections.append("    □ Access controls verified")
+
+        return "\n".join(sections)
+
+    def get_error_summary(
+        self, error_category: ErrorCategory, connection_context: ConnectionContext
+    ) -> str:
+        """Get a brief summary of the error for logging.
+
+        Args:
+            error_category: Categorized error type
+            connection_context: Context about the failing connection
+
+        Returns:
+            Brief error summary
+        """
+        category_desc = self.categorizer.get_category_description(error_category)
+        connection_path = connection_context.get_connection_path()
+
+        return f"{category_desc}: {connection_path}"
+
+    def _indent_lines(self, text: str, indent: str = "    ") -> str:
+        """Indent all lines in text with the given prefix.
+
+        Args:
+            text: Text to indent
+            indent: Indentation string
+
+        Returns:
+            Indented text
+        """
+        lines = text.split("\n")
+        return "\n".join(f"{indent}{line}" for line in lines)

kailash/runtime/validation/error_categorizer.py

@@ -0,0 +1,164 @@
+"""
+Error categorization for connection validation failures.
+
+Classifies validation errors into specific categories to enable
+targeted suggestion generation and better error handling.
+"""
+
+import re
+from enum import Enum
+from typing import Any, Optional
+
+
+class ErrorCategory(Enum):
+    """Categories of connection validation errors."""
+
+    TYPE_MISMATCH = "type_mismatch"
+    """Parameter type doesn't match expected type"""
+
+    MISSING_PARAMETER = "missing_parameter"
+    """Required parameter is missing or None"""
+
+    CONSTRAINT_VIOLATION = "constraint_violation"
+    """Parameter violates validation constraints (range, format, etc.)"""
+
+    SECURITY_VIOLATION = "security_violation"
+    """Parameter contains potential security issues (injection, etc.)"""
+
+    UNKNOWN = "unknown"
+    """Error category could not be determined"""
+
+
+class ErrorCategorizer:
+    """Categorizes validation errors for enhanced error message generation."""
+
+    # Error patterns for categorization
+    TYPE_ERROR_PATTERNS = [
+        r"expected .+ but got .+",
+        r"object of type .+ has no attribute",
+        r"unsupported operand type",
+        r"can't convert .+ to .+",
+        r"'[^']+' object .+ not .+",
+        r"argument must be .+, not .+",
+    ]
+
+    MISSING_PARAMETER_PATTERNS = [
+        r"missing required parameter",
+        r"required argument .+ is missing",
+        r"takes .+ arguments but .+ were given",
+        r"missing .+ required",
+        r"parameter .+ is required",
+    ]
+
+    CONSTRAINT_VIOLATION_PATTERNS = [
+        r"must be positive",
+        r"must be greater than",
+        r"must be less than",
+        r"invalid value",
+        r"out of range",
+        r"violates constraint",
+        r"exceeds maximum",
+        r"below minimum",
+    ]
+
+    SECURITY_VIOLATION_PATTERNS = [
+        r"sql injection",
+        r"injection detected",
+        r"security violation",
+        r"potential attack",
+        r"malicious",
+        r"dangerous",
+        r"unsafe",
+        r"script injection",
+    ]
+
+    def categorize_error(
+        self, error: Exception, node_type: Optional[str] = None
+    ) -> ErrorCategory:
+        """Categorize a validation error based on error message and context.
+
+        Args:
+            error: The validation error exception
+            node_type: Optional node type for additional context
+
+        Returns:
+            ErrorCategory enum value indicating the error type
+        """
+        error_message = str(error).lower()
+        error_type = type(error).__name__
+
+        # Check for security violations first (highest priority)
+        if self._matches_patterns(error_message, self.SECURITY_VIOLATION_PATTERNS):
+            return ErrorCategory.SECURITY_VIOLATION
+
+        # Check for type errors
+        if error_type in ["TypeError", "AttributeError"] or self._matches_patterns(
+            error_message, self.TYPE_ERROR_PATTERNS
+        ):
+            return ErrorCategory.TYPE_MISMATCH
+
+        # Check for missing parameter errors
+        if error_type in ["ValueError", "TypeError"] and self._matches_patterns(
+            error_message, self.MISSING_PARAMETER_PATTERNS
+        ):
+            return ErrorCategory.MISSING_PARAMETER
+
+        # Check for constraint violations
+        if error_type == "ValueError" and self._matches_patterns(
+            error_message, self.CONSTRAINT_VIOLATION_PATTERNS
+        ):
+            return ErrorCategory.CONSTRAINT_VIOLATION
+
+        # Default to unknown if no pattern matches
+        return ErrorCategory.UNKNOWN
+
+    def _matches_patterns(self, text: str, patterns: list[str]) -> bool:
+        """Check if text matches any of the given regex patterns.
+
+        Args:
+            text: Text to check
+            patterns: List of regex patterns
+
+        Returns:
+            True if text matches any pattern
+        """
+        for pattern in patterns:
+            if re.search(pattern, text, re.IGNORECASE):
+                return True
+        return False
+
+    def get_category_description(self, category: ErrorCategory) -> str:
+        """Get human-readable description of error category.
+
+        Args:
+            category: Error category enum
+
+        Returns:
+            Human-readable description
+        """
+        descriptions = {
+            ErrorCategory.TYPE_MISMATCH: "Type Mismatch",
+            ErrorCategory.MISSING_PARAMETER: "Missing Required Parameter",
+            ErrorCategory.CONSTRAINT_VIOLATION: "Parameter Constraint Violation",
+            ErrorCategory.SECURITY_VIOLATION: "Security Violation",
+            ErrorCategory.UNKNOWN: "Unknown Validation Error",
+        }
+        return descriptions.get(category, "Unknown Error")
+
+    def get_severity_level(self, category: ErrorCategory) -> str:
+        """Get severity level for error category.
+
+        Args:
+            category: Error category enum
+
+        Returns:
+            Severity level: 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW'
+        """
+        severity_map = {
+            ErrorCategory.SECURITY_VIOLATION: "CRITICAL",
+            ErrorCategory.MISSING_PARAMETER: "HIGH",
+            ErrorCategory.TYPE_MISMATCH: "MEDIUM",
+            ErrorCategory.CONSTRAINT_VIOLATION: "MEDIUM",
+            ErrorCategory.UNKNOWN: "LOW",
+        }
+        return severity_map.get(category, "LOW")