velocity-python 0.0.129__py3-none-any.whl → 0.0.132__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.129"
+__version__ = version = "0.0.132"
 
 from . import aws
 from . import db

velocity/aws/handlers/mixins/__init__.py

@@ -0,0 +1,16 @@
+"""
+Mixins for AWS Lambda handlers.
+
+This package provides reusable mixins for common Lambda handler functionality:
+- ActivityTracker: Standardized activity logging and tracking
+- ErrorHandler: Standardized error handling and notifications
+- StandardMixin: Combined mixin for most common use cases
+- LegacyMixin: Backward-compatible enhanced tracking for existing handlers
+"""
+
+from .activity_tracker import ActivityTracker
+from .error_handler import ErrorHandler
+from .standard_mixin import StandardMixin
+from .legacy_mixin import LegacyMixin
+
+__all__ = ['ActivityTracker', 'ErrorHandler', 'StandardMixin', 'LegacyMixin']

velocity/aws/handlers/mixins/activity_tracker.py

@@ -0,0 +1,142 @@
+"""
+Activity Tracker Mixin for Lambda Handlers.
+
+Provides standardized activity tracking and logging functionality
+for Lambda handlers using the aws_api_activity table.
+"""
+
+import copy
+import json
+import os
+import time
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+
+class ActivityTracker(ABC):
+    """
+    Mixin class providing standardized activity tracking for Lambda handlers.
+    
+    Tracks API calls to the aws_api_activity table with consistent data structure
+    and automatic duration calculation.
+    """
+    
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.activity_log_key = None
+        self.start_time = None
+        self.end_time = None
+        self.activity_data = {}
+    
+    def track_activity_start(self, tx, context):
+        """Start tracking activity for the current request"""
+        self.start_time = time.time()
+        
+        # Gather common activity data
+        postdata = context.postdata()
+        payload = context.payload()
+        
+        self.activity_data = {
+            "action": context.action(),
+            "args": json.dumps(context.args()),
+            "postdata": self._sanitize_postdata(postdata),
+            "handler_name": self.__class__.__name__,
+            "function_name": os.environ.get("AWS_LAMBDA_FUNCTION_NAME", "Unknown"),
+            "user_branch": os.environ.get("USER_BRANCH", "Unknown"),
+            "start_timestamp": self.start_time,
+        }
+        
+        # Add user information if available
+        user_info = self._extract_user_info(payload)
+        if user_info:
+            self.activity_data.update(user_info)
+            
+        # Add session information
+        session_data = context.session()
+        if session_data:
+            self.activity_data.update({k: v for k, v in session_data.items() 
+                                     if k not in ['cognito_user']})
+        
+        # Create the activity record
+        self.activity_log_key = tx.table("aws_api_activity").new(self.activity_data).pk
+        
+        return self.activity_log_key
+    
+    def track_activity_success(self, tx, context):
+        """Update activity record with success information"""
+        if not self.activity_log_key:
+            return
+            
+        self.end_time = time.time()
+        update_data = {
+            "end_timestamp": self.end_time,
+            "duration": self.end_time - self.start_time,
+            "status": "success"
+        }
+        
+        tx.table("aws_api_activity").update(update_data, self.activity_log_key)
+    
+    def track_activity_error(self, tx, context, exception, tb_string):
+        """Update activity record with error information"""
+        if not self.activity_log_key:
+            return
+            
+        self.end_time = time.time()
+        update_data = {
+            "end_timestamp": self.end_time,
+            "duration": self.end_time - self.start_time if self.start_time else 0,
+            "status": "error",
+            "exception_type": exception.__class__.__name__,
+            "exception_message": str(exception),
+            "traceback": tb_string,
+        }
+        
+        # Handle legacy field names for backward compatibility
+        update_data["exception"] = exception.__class__.__name__
+        
+        tx.table("aws_api_activity").update(update_data, self.activity_log_key)
+    
+    def _sanitize_postdata(self, postdata: Dict) -> str:
+        """Remove sensitive information from postdata before logging"""
+        if not postdata:
+            return "{}"
+            
+        sanitized = copy.deepcopy(postdata)
+        
+        # Remove cognito user data from payload if present
+        if "payload" in sanitized and isinstance(sanitized["payload"], dict):
+            sanitized["payload"].pop("cognito_user", None)
+            
+        # Remove other sensitive fields as needed
+        sensitive_fields = ["password", "token", "secret", "key", "auth", "cognito_user"]
+        self._recursive_sanitize(sanitized, sensitive_fields)
+        
+        return json.dumps(sanitized)
+    
+    def _recursive_sanitize(self, data: Any, sensitive_fields: list):
+        """Recursively remove sensitive fields from nested data structures"""
+        if isinstance(data, dict):
+            for key in list(data.keys()):
+                if any(field in key.lower() for field in sensitive_fields):
+                    data[key] = "[REDACTED]"
+                else:
+                    self._recursive_sanitize(data[key], sensitive_fields)
+        elif isinstance(data, list):
+            for item in data:
+                self._recursive_sanitize(item, sensitive_fields)
+    
+    def _extract_user_info(self, payload: Dict) -> Dict:
+        """Extract user information from payload"""
+        user_info = {}
+        
+        if payload and "cognito_user" in payload:
+            try:
+                attrs = payload["cognito_user"]["attributes"]
+                if "email" in attrs:
+                    user_info["email_address"] = attrs["email"].lower()
+                if "sub" in attrs:
+                    user_info["user_id"] = attrs["sub"]
+            except (KeyError, TypeError):
+                pass
+                
+        return user_info

velocity/aws/handlers/mixins/error_handler.py

@@ -0,0 +1,192 @@
+"""
+Error Handler Mixin for Lambda Handlers.
+
+Provides standardized error handling, logging, and notification functionality
+for Lambda handlers.
+"""
+
+import copy
+import os
+import pprint
+import time
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+
+class ErrorHandler(ABC):
+    """
+    Mixin class providing standardized error handling for Lambda handlers.
+    
+    Handles error logging to sys_log table, email notifications to administrators,
+    and error metrics collection.
+    """
+    
+    def handle_standard_error(self, tx, context, exception: Exception, tb_string: str):
+        """Handle errors with consistent logging and notification patterns"""
+        
+        # Log to sys_log for centralized logging
+        self.log_error_to_system(tx, context, exception, tb_string)
+        
+        # Determine if this error requires notification
+        if self._should_notify_error(exception):
+            self.send_error_notification(tx, context, exception, tb_string)
+        
+        # Log error metrics for monitoring
+        self.log_error_metrics(tx, context, exception)
+    
+    def log_error_to_system(self, tx, context, exception: Exception, tb_string: str):
+        """Log error to sys_log table"""
+        error_data = {
+            "level": "ERROR",
+            "message": str(exception),
+            "function": f"{self.__class__.__name__}.{context.action()}",
+            "traceback": tb_string,
+            "exception_type": exception.__class__.__name__,
+            "handler_name": self.__class__.__name__,
+            "action": context.action(),
+            "user_branch": os.environ.get("USER_BRANCH", "Unknown"),
+            "function_name": os.environ.get("AWS_LAMBDA_FUNCTION_NAME", "Unknown"),
+            "app_name": os.environ.get("ProjectName", "Unknown"),
+            "user_agent": "AWS Lambda",
+            "device_type": "Lambda",
+            "sys_modified_by": "Lambda",
+        }
+        
+        # Add user context if available
+        try:
+            if hasattr(self, 'current_user') and self.current_user:
+                error_data["user_email"] = self.current_user.get("email_address")
+        except:
+            pass
+            
+        tx.table("sys_log").insert(error_data)
+    
+    def send_error_notification(self, tx, context, exception: Exception, tb_string: str):
+        """Send error notification email to administrators"""
+        try:
+            # Import here to avoid circular dependency
+            from support.app import helpers
+            
+            environment = os.environ.get('USER_BRANCH', 'Unknown').title()
+            function_name = os.environ.get('AWS_LAMBDA_FUNCTION_NAME', 'Unknown')
+            
+            subject = f"{environment} Lambda Error - {function_name}"
+            
+            body = f"""
+Error Details:
+- Handler: {self.__class__.__name__}
+- Action: {context.action()}
+- Exception: {exception.__class__.__name__}
+- Message: {str(exception)}
+- Environment: {environment}
+- Function: {function_name}
+
+Full Traceback:
+{tb_string}
+
+Request Details:
+{self._get_error_context(context)}
+            """
+            
+            sender = self._get_error_notification_sender()
+            recipients = self._get_error_notification_recipients()
+            
+            helpers.sendmail(
+                tx,
+                subject=subject,
+                body=body,
+                html=None,
+                sender=sender,
+                recipient=recipients[0],
+                cc=recipients[1:] if len(recipients) > 1 else None,
+                bcc=None,
+                email_settings_id=1001,
+            )
+        except Exception as email_error:
+            print(f"Failed to send error notification email: {email_error}")
+    
+    def _should_notify_error(self, exception: Exception) -> bool:
+        """Determine if an error should trigger email notifications"""
+        # Don't notify for user authentication errors or validation errors
+        non_notification_types = [
+            "AuthenticationError", 
+            "ValidationError", 
+            "ValueError",
+            "AlertError"
+        ]
+        
+        exception_name = exception.__class__.__name__
+        
+        # Check for authentication-related exceptions
+        if "Authentication" in exception_name or "Auth" in exception_name:
+            return False
+            
+        return exception_name not in non_notification_types
+    
+    @abstractmethod
+    def _get_error_notification_recipients(self) -> list:
+        """
+        Get list of email recipients for error notifications.
+        
+        Must be implemented by the handler class.
+        
+        Returns:
+            List of email addresses to notify when errors occur
+            
+        Example:
+            return ["admin@company.com", "devops@company.com"]
+        """
+        pass
+    
+    @abstractmethod
+    def _get_error_notification_sender(self) -> str:
+        """
+        Get email sender for error notifications.
+        
+        Must be implemented by the handler class.
+        
+        Returns:
+            Email address to use as sender for error notifications
+            
+        Example:
+            return "no-reply@company.com"
+        """
+        pass
+    
+    def _get_error_context(self, context) -> str:
+        """Get sanitized request context for error reporting"""
+        try:
+            postdata = context.postdata()
+            sanitized = copy.deepcopy(postdata)
+            
+            # Remove sensitive data
+            if "payload" in sanitized and isinstance(sanitized["payload"], dict):
+                sanitized["payload"].pop("cognito_user", None)
+                
+            return pprint.pformat(sanitized)
+        except:
+            return "Unable to retrieve request context"
+    
+    def log_error_metrics(self, tx, context, exception: Exception):
+        """Log error metrics for monitoring and alerting"""
+        try:
+            metrics_data = {
+                "metric_type": "error_count",
+                "handler_name": self.__class__.__name__,
+                "action": context.action(),
+                "exception_type": exception.__class__.__name__,
+                "environment": os.environ.get("USER_BRANCH", "Unknown"),
+                "function_name": os.environ.get("AWS_LAMBDA_FUNCTION_NAME", "Unknown"),
+                "timestamp": time.time(),
+                "sys_modified_by": "Lambda"
+            }
+            
+            # Try to insert into metrics table if it exists
+            try:
+                tx.table("lambda_metrics").insert(metrics_data)
+            except:
+                # Metrics table might not exist yet, don't fail error handler
+                pass
+        except:
+            # Don't fail the error handler if metrics logging fails
+            pass

velocity/aws/handlers/mixins/legacy_mixin.py

@@ -0,0 +1,53 @@
+"""
+Legacy Mixin for backward compatibility.
+
+Provides enhanced activity tracking while maintaining existing 
+beforeAction/afterAction/onError implementations in handlers.
+"""
+
+import os
+from .activity_tracker import ActivityTracker
+from .error_handler import ErrorHandler
+
+
+class LegacyMixin(ActivityTracker, ErrorHandler):
+    """
+    Legacy-compatible mixin that enhances existing handlers without breaking them.
+    
+    This mixin adds standardized activity tracking and error handling
+    while preserving existing beforeAction/afterAction/onError implementations.
+    
+    Use this when migrating existing handlers that have complex custom logic
+    in their action methods.
+    """
+    
+    def _enhanced_before_action(self, tx, context):
+        """Enhanced beforeAction that adds activity tracking"""
+        # Start activity tracking
+        self.track_activity_start(tx, context)
+    
+    def _enhanced_after_action(self, tx, context):
+        """Enhanced afterAction that adds activity tracking"""
+        # Update activity tracking with success
+        self.track_activity_success(tx, context)
+    
+    def _enhanced_error_handler(self, tx, context, exc, tb):
+        """Enhanced onError that adds standardized error handling"""
+        # Convert exc to exception object if it's a string
+        if isinstance(exc, str):
+            exception = Exception(exc)
+        else:
+            exception = exc
+            
+        # Update activity tracking with error
+        self.track_activity_error(tx, context, exception, tb)
+        
+        # Handle error with standard patterns (but don't send duplicate emails)
+        self.log_error_to_system(tx, context, exception, tb)
+        self.log_error_metrics(tx, context, exception)
+        
+        # Only send notification if handler doesn't already handle it
+        # Check for a flag that handlers can set to indicate they handle their own notifications
+        if not getattr(self, '_handles_own_error_notifications', False):
+            if self._should_notify_error(exception):
+                self.send_error_notification(tx, context, exception, tb)

velocity/aws/handlers/mixins/standard_mixin.py

@@ -0,0 +1,73 @@
+"""
+Standard Mixin combining ActivityTracker and ErrorHandler.
+
+Provides a single mixin that includes both activity tracking and error handling
+with standardized beforeAction, afterAction, and onError implementations.
+"""
+
+import copy
+import pprint
+from abc import ABC, abstractmethod
+
+from .activity_tracker import ActivityTracker
+from .error_handler import ErrorHandler
+
+
+class StandardMixin(ActivityTracker, ErrorHandler):
+    """
+    Combined mixin providing both activity tracking and error handling.
+    Use this as the primary mixin for Lambda handlers.
+    
+    Provides standard implementations of:
+    - beforeAction: Starts activity tracking + custom logic
+    - afterAction: Records success + custom logic  
+    - onError: Records error + handles notifications + custom logic
+    """
+    
+    def beforeAction(self, tx, context):
+        """Standard beforeAction implementation"""
+        # Start activity tracking
+        self.track_activity_start(tx, context)
+        
+        # Call any custom beforeAction logic
+        self._custom_before_action(tx, context)
+    
+    def afterAction(self, tx, context):
+        """Standard afterAction implementation"""
+        # Update activity tracking with success
+        self.track_activity_success(tx, context)
+        
+        # Call any custom afterAction logic
+        self._custom_after_action(tx, context)
+    
+    def onError(self, tx, context, exc, tb):
+        """Standard onError implementation"""
+        # Convert exc to exception object if it's a string
+        if isinstance(exc, str):
+            exception = Exception(exc)
+        else:
+            exception = exc
+            
+        # Update activity tracking with error
+        self.track_activity_error(tx, context, exception, tb)
+        
+        # Handle error with standard patterns
+        self.handle_standard_error(tx, context, exception, tb)
+        
+        # Call any custom error handling
+        self._custom_error_handler(tx, context, exception, tb)
+    
+    @abstractmethod
+    def _custom_before_action(self, tx, context):
+        """Override this method for handler-specific beforeAction logic"""
+        pass
+    
+    @abstractmethod  
+    def _custom_after_action(self, tx, context):
+        """Override this method for handler-specific afterAction logic"""
+        pass
+    
+    @abstractmethod
+    def _custom_error_handler(self, tx, context, exception, tb):
+        """Override this method for handler-specific error handling"""
+        pass

velocity/db/servers/base/__init__.py

@@ -0,0 +1,9 @@
+"""
+Base abstract classes for database server implementations.
+"""
+from .sql import BaseSQLDialect
+from .types import BaseTypes
+from .operators import BaseOperators
+from .initializer import BaseInitializer
+
+__all__ = ["BaseSQLDialect", "BaseTypes", "BaseOperators", "BaseInitializer"]

velocity/db/servers/base/initializer.py

@@ -0,0 +1,69 @@
+"""
+Abstract base class for database initialization.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+from velocity.db.core import engine
+
+
+class BaseInitializer(ABC):
+    """
+    Abstract base class for database connection initialization.
+    
+    Each database implementation should provide a concrete implementation
+    of the initialize method to set up database connections properly.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def initialize(config: Optional[Dict[str, Any]] = None, **kwargs) -> engine.Engine:
+        """
+        Initialize a database engine with the appropriate driver and configuration.
+        
+        Args:
+            config: Configuration dictionary (can be None)
+            **kwargs: Additional configuration parameters
+            
+        Returns:
+            Configured Engine instance
+            
+        Raises:
+            ImportError: If required database driver is not available
+            ValueError: If configuration is invalid
+        """
+        pass
+
+    @staticmethod
+    def _merge_config(base_config: Dict[str, Any], config: Optional[Dict[str, Any]], **kwargs) -> Dict[str, Any]:
+        """
+        Helper method to merge configuration from multiple sources.
+        
+        Args:
+            base_config: Base configuration (e.g., from environment)
+            config: User-provided configuration
+            **kwargs: Additional keyword arguments
+            
+        Returns:
+            Merged configuration dictionary
+        """
+        final_config = base_config.copy()
+        if config:
+            final_config.update(config)
+        final_config.update(kwargs)
+        return final_config
+
+    @staticmethod
+    def _validate_required_config(config: Dict[str, Any], required_keys: list[str]) -> None:
+        """
+        Validate that required configuration keys are present.
+        
+        Args:
+            config: Configuration to validate
+            required_keys: List of required configuration keys
+            
+        Raises:
+            ValueError: If required keys are missing
+        """
+        missing_keys = [key for key in required_keys if key not in config]
+        if missing_keys:
+            raise ValueError(f"Missing required configuration keys: {missing_keys}")

velocity/db/servers/base/operators.py

@@ -0,0 +1,98 @@
+"""
+Abstract base class for database operator mapping implementations.
+"""
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class BaseOperators(ABC):
+    """
+    Abstract base class that defines the interface for database operator mappings.
+    
+    Each database implementation should provide concrete implementations of operator
+    mappings to handle conversion between Velocity.DB operators and SQL operators.
+    """
+
+    @classmethod
+    @abstractmethod
+    def get_operators(cls) -> Dict[str, str]:
+        """
+        Returns a dictionary mapping Velocity.DB operators to SQL operators.
+        
+        This method should return a complete mapping of all operators supported
+        by this database implementation.
+        
+        Returns:
+            Dictionary mapping operator symbols to SQL operators
+            
+        Examples:
+            {
+                "=": "=",
+                "!=": "<>",
+                "<>": "<>", 
+                "%": "LIKE",
+                "!%": "NOT LIKE",
+                "%%": "ILIKE",  # PostgreSQL case-insensitive
+                "!%%": "NOT ILIKE",
+                "><": "BETWEEN",
+                "!><": "NOT BETWEEN",
+                # ... etc
+            }
+        """
+        pass
+
+    @classmethod
+    def get_base_operators(cls) -> Dict[str, str]:
+        """
+        Returns common operators supported by most databases.
+        Subclasses can use this as a starting point and override specific operators.
+        
+        Returns:
+            Dictionary of common SQL operators
+        """
+        return {
+            "=": "=",
+            "==": "=",
+            "!=": "<>",
+            "<>": "<>",
+            "!": "<>",
+            "<": "<",
+            ">": ">", 
+            "<=": "<=",
+            ">=": ">=",
+            "%": "LIKE",
+            "!%": "NOT LIKE",
+            "><": "BETWEEN",
+            "!><": "NOT BETWEEN",
+            ">!<": "NOT BETWEEN",
+        }
+
+    @classmethod
+    def supports_case_insensitive_like(cls) -> bool:
+        """
+        Returns True if this database supports case-insensitive LIKE operations.
+        
+        Returns:
+            True if database supports ILIKE or similar
+        """
+        return False
+
+    @classmethod
+    def supports_regex(cls) -> bool:
+        """
+        Returns True if this database supports regular expressions.
+        
+        Returns:
+            True if database supports regex operators
+        """
+        return False
+
+    @classmethod
+    def get_regex_operators(cls) -> Dict[str, str]:
+        """
+        Returns regex operators if supported by this database.
+        
+        Returns:
+            Dictionary of regex operators or empty dict if not supported
+        """
+        return {}