wappa 0.1.0__py3-none-any.whl

wappa/persistence/redis/redis_manager.py

@@ -0,0 +1,189 @@
+"""
+Redis Manager for Wappa application lifecycle management.
+
+Wraps the Wappa RedisClient with application-specific initialization and cleanup.
+Provides a clean interface for applications to manage Redis connections.
+"""
+
+import logging
+from typing import Any
+
+from ...core.config.settings import settings
+from .redis_client import POOL_DB_MAPPING, PoolAlias, RedisClient
+
+logger = logging.getLogger(__name__)
+
+
+class RedisManager:
+    """
+    Application-level wrapper around the Wappa RedisClient.
+
+    Handles lifecycle management, health monitoring, and provides
+    a clean interface for applications to manage Redis connections.
+
+    This manager follows the same patterns as the reference implementation
+    but uses Wappa's own RedisClient instead of external dependencies.
+    """
+
+    _initialized: bool = False
+
+    @classmethod
+    async def initialize(
+        cls, redis_url: str | None = None, max_connections: int | None = None
+    ) -> None:
+        """
+        Initialize Redis pools with enhanced logging.
+
+        Uses the existing multi-pool setup with proper configuration
+        from application settings or provided parameters.
+
+        Args:
+            redis_url: Redis connection URL (defaults to settings.redis_url)
+            max_connections: Max connections per pool (defaults to settings.redis_max_connections)
+        """
+        if cls._initialized:
+            logger.info("Redis pools already initialized - skipping")
+            return
+
+        try:
+            # Enhanced initialization logging
+            url = redis_url or settings.redis_url
+            connections = max_connections or settings.redis_max_connections
+
+            logger.info(f"Setting up Redis pools from {url} (max_connections: {connections})")
+
+            # Use Wappa's RedisClient.setup_single_url
+            RedisClient.setup_single_url(
+                base_url=url,
+                max_connections=connections,
+            )
+
+            # Verify all pools with detailed logging
+            logger.info("Verifying Redis pool health...")
+            await cls._verify_pools()
+
+            cls._initialized = True
+
+            # Success confirmation with pool details
+            pool_count = len(POOL_DB_MAPPING)
+            pool_details = ", ".join(f"{alias}:db{db}" for alias, db in POOL_DB_MAPPING.items())
+            logger.info(f"✅ Redis pools ready: {pool_count} pools ({pool_details})")
+
+        except Exception as e:
+            logger.error(f"❌ Redis pool initialization failed: {e}", exc_info=True)
+            raise
+
+    @classmethod
+    async def _verify_pools(cls) -> None:
+        """
+        Health check all Redis pools with detailed logging.
+
+        Ensures all expected pools are accessible and responding.
+        """
+        failed_pools = []
+        successful_pools = []
+
+        for alias in POOL_DB_MAPPING:
+            pool_alias: PoolAlias = alias  # type: ignore
+            try:
+                redis = await RedisClient.get(pool_alias)
+                await redis.ping()
+                successful_pools.append(f"{alias}:db{POOL_DB_MAPPING[alias]}")
+                logger.debug(f"✅ Redis pool '{alias}' (db{POOL_DB_MAPPING[alias]}) health check passed")
+            except Exception as e:
+                failed_pools.append(f"{alias}:db{POOL_DB_MAPPING[alias]}")
+                logger.error(f"❌ Redis pool '{alias}' (db{POOL_DB_MAPPING[alias]}) health check failed: {e}")
+
+        if failed_pools:
+            raise ConnectionError(f"Failed Redis pools: {', '.join(failed_pools)}")
+
+        logger.info(f"✅ All Redis pools healthy: {', '.join(successful_pools)}")
+
+    @classmethod
+    async def get_health_status(cls) -> dict[str, Any]:
+        """
+        Get health status of all Redis pools.
+
+        Returns detailed health information for monitoring.
+
+        Returns:
+            Dictionary containing initialization status and per-pool health info
+        """
+        health_status = {"initialized": cls._initialized, "pools": {}}
+
+        if not cls._initialized:
+            health_status["message"] = "Redis not initialized"
+            return health_status
+
+        for alias in POOL_DB_MAPPING:
+            pool_alias: PoolAlias = alias  # type: ignore
+            try:
+                redis = await RedisClient.get(pool_alias)
+                await redis.ping()
+                health_status["pools"][alias] = {
+                    "status": "healthy",
+                    "database": POOL_DB_MAPPING[alias],
+                    "error": None,
+                }
+            except Exception as e:
+                health_status["pools"][alias] = {
+                    "status": "unhealthy",
+                    "database": POOL_DB_MAPPING[alias],
+                    "error": str(e),
+                }
+
+        return health_status
+
+    @classmethod
+    async def get_client(cls, alias: PoolAlias = "users"):
+        """
+        Get Redis client for specified pool.
+
+        Args:
+            alias: Pool alias ("users", "state_handler", "table")
+
+        Returns:
+            Redis client instance
+
+        Raises:
+            RuntimeError: If Redis not initialized
+        """
+        if not cls._initialized:
+            raise RuntimeError("RedisManager not initialized. Call initialize() first.")
+
+        return await RedisClient.get(alias)
+
+    @classmethod
+    async def cleanup(cls) -> None:
+        """
+        Clean shutdown of all Redis pools.
+
+        Should be called during application shutdown.
+        """
+        if not cls._initialized:
+            logger.info("Redis pools not initialized, skipping cleanup")
+            return
+
+        try:
+            logger.info("Shutting down Redis pools...")
+            await RedisClient.close()
+            cls._initialized = False
+            logger.info("Redis pools shut down successfully")
+        except Exception as e:
+            logger.error(f"Error during Redis cleanup: {e}", exc_info=True)
+            raise
+
+    @classmethod
+    def is_initialized(cls) -> bool:
+        """Check if Redis pools are initialized."""
+        return cls._initialized
+
+    @classmethod
+    def get_pool_info(cls) -> dict[str, int]:
+        """
+        Get information about available Redis pools.
+
+        Returns:
+            Dictionary mapping pool aliases to database numbers
+        """
+        return POOL_DB_MAPPING.copy()

wappa/processors/__init__.py

@@ -0,0 +1,6 @@
+"""
+Webhook processor infrastructure for the Mimeia AI Agent Platform.
+
+This module provides platform-agnostic webhook processing capabilities
+with specialized processors for different messaging platforms.
+"""

wappa/processors/base_processor.py

@@ -0,0 +1,262 @@
+"""
+Base processor abstraction for platform-agnostic webhook processing.
+
+This module defines the abstract base classes that all platform-specific
+webhook processors must inherit from to ensure consistent interfaces.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+from wappa.core.logging.logger import get_logger
+from wappa.schemas.core.base_message import BaseMessage
+from wappa.schemas.core.base_status import BaseMessageStatus
+from wappa.schemas.core.base_webhook import BaseWebhook
+from wappa.schemas.core.types import ErrorCode, MessageType, PlatformType
+
+# Legacy ProcessingResult class removed - Universal Webhook Interface is now the ONLY way
+# Use processor.create_universal_webhook() method instead for type-safe webhook handling
+
+
+class ProcessorCapabilities:
+    """
+    Represents the capabilities of a platform processor.
+
+    This allows the system to understand what each processor can handle
+    and route webhooks appropriately.
+    """
+
+    def __init__(
+        self,
+        platform: PlatformType,
+        supported_message_types: set[MessageType],
+        supports_status_updates: bool = True,
+        supports_signature_validation: bool = True,
+        supports_error_webhooks: bool = True,
+        max_payload_size: int | None = None,
+        rate_limit_per_minute: int | None = None,
+    ):
+        self.platform = platform
+        self.supported_message_types = supported_message_types
+        self.supports_status_updates = supports_status_updates
+        self.supports_signature_validation = supports_signature_validation
+        self.supports_error_webhooks = supports_error_webhooks
+        self.max_payload_size = max_payload_size
+        self.rate_limit_per_minute = rate_limit_per_minute
+
+    def can_handle_message_type(self, message_type: MessageType) -> bool:
+        """Check if processor can handle a specific message type."""
+        return message_type in self.supported_message_types
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert capabilities to dictionary."""
+        return {
+            "platform": self.platform.value,
+            "supported_message_types": [
+                mt.value for mt in self.supported_message_types
+            ],
+            "supports_status_updates": self.supports_status_updates,
+            "supports_signature_validation": self.supports_signature_validation,
+            "supports_error_webhooks": self.supports_error_webhooks,
+            "max_payload_size": self.max_payload_size,
+            "rate_limit_per_minute": self.rate_limit_per_minute,
+        }
+
+
+class BaseWebhookProcessor(ABC):
+    """
+    Platform-agnostic webhook processor base class.
+
+    All platform-specific processors must inherit from this class
+    to provide a consistent interface for webhook processing.
+    """
+
+    def __init__(self):
+        self.logger = get_logger(__name__)
+
+        # Message type handlers - subclasses should populate this
+        self._message_type_handlers: dict[str, callable] = {}
+
+        # Processing statistics
+        self._processed_count = 0
+        self._error_count = 0
+        self._last_processed = None
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform this processor handles."""
+        pass
+
+    @property
+    @abstractmethod
+    def capabilities(self) -> ProcessorCapabilities:
+        """Get the capabilities of this processor."""
+        pass
+
+    # Legacy process_webhook abstract method removed - Universal Webhook Interface is the ONLY way
+    # All processors must implement create_universal_webhook() method instead
+
+    @abstractmethod
+    def validate_webhook_signature(
+        self, payload: bytes, signature: str, **kwargs
+    ) -> bool:
+        """
+        Validate webhook signature for security.
+
+        Args:
+            payload: Raw webhook payload bytes
+            signature: Platform-specific signature header
+            **kwargs: Additional validation parameters
+
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def parse_webhook_container(self, payload: dict[str, Any], **kwargs) -> BaseWebhook:
+        """
+        Parse the top-level webhook structure.
+
+        Args:
+            payload: Raw webhook payload
+            **kwargs: Additional parsing parameters
+
+        Returns:
+            Parsed webhook container with universal interface
+
+        Raises:
+            ValidationError: If webhook structure is invalid
+        """
+        pass
+
+    @abstractmethod
+    def get_supported_message_types(self) -> set[MessageType]:
+        """Get the set of message types this processor supports."""
+        pass
+
+    @abstractmethod
+    def create_message_from_data(
+        self, message_data: dict[str, Any], message_type: MessageType, **kwargs
+    ) -> BaseMessage:
+        """
+        Create a message instance from raw data.
+
+        Args:
+            message_data: Raw message data from webhook
+            message_type: The type of message to create
+            **kwargs: Additional creation parameters
+
+        Returns:
+            Parsed message with universal interface
+
+        Raises:
+            ValidationError: If message data is invalid
+            UnsupportedMessageType: If message type is not supported
+        """
+        pass
+
+    @abstractmethod
+    def create_status_from_data(
+        self, status_data: dict[str, Any], **kwargs
+    ) -> BaseMessageStatus:
+        """
+        Create a status instance from raw data.
+
+        Args:
+            status_data: Raw status data from webhook
+            **kwargs: Additional creation parameters
+
+        Returns:
+            Parsed status with universal interface
+
+        Raises:
+            ValidationError: If status data is invalid
+        """
+        pass
+
+    def is_supported_platform(self, platform: str) -> bool:
+        """Check if the platform string matches this processor."""
+        return platform.lower() == self.platform.value.lower()
+
+    def register_message_handler(self, message_type: str, handler: Callable) -> None:
+        """Register a handler for a specific message type."""
+        self._message_type_handlers[message_type] = handler
+
+    def get_message_handler(self, message_type: str) -> Callable | None:
+        """Get the handler for a specific message type."""
+        return self._message_type_handlers.get(message_type)
+
+    # Legacy _process_incoming_messages method removed - Universal Webhook Interface handles this via IncomingMessageWebhook
+
+    # Legacy _process_status_updates method removed - Universal Webhook Interface handles this via StatusWebhook
+
+    def get_processing_stats(self) -> dict[str, Any]:
+        """
+        Get processing statistics for monitoring and analysis.
+
+        Returns:
+            Dictionary with processing statistics
+        """
+        return {
+            "platform": self.platform.value,
+            "capabilities": self.capabilities.to_dict(),
+            "processed_count": self._processed_count,
+            "error_count": self._error_count,
+            "error_rate": self._error_count / max(self._processed_count, 1),
+            "last_processed": self._last_processed.isoformat()
+            if self._last_processed
+            else None,
+            "supported_message_types": [
+                mt.value for mt in self.get_supported_message_types()
+            ],
+        }
+
+    # Legacy create_error_result method removed - Universal Webhook Interface handles errors via ErrorWebhook
+
+    def __str__(self) -> str:
+        """String representation of the processor."""
+        return f"{self.__class__.__name__}(platform={self.platform.value})"
+
+    def __repr__(self) -> str:
+        """Detailed string representation of the processor."""
+        return (
+            f"{self.__class__.__name__}("
+            f"platform={self.platform.value}, "
+            f"processed={self._processed_count}, "
+            f"errors={self._error_count})"
+        )
+
+
+class ProcessorError(Exception):
+    """Base exception for processor-related errors."""
+
+    def __init__(self, message: str, error_code: ErrorCode, platform: PlatformType):
+        self.message = message
+        self.error_code = error_code
+        self.platform = platform
+        super().__init__(message)
+
+
+class UnsupportedMessageTypeError(ProcessorError):
+    """Raised when a processor encounters an unsupported message type."""
+
+    def __init__(self, message_type: str, platform: PlatformType):
+        super().__init__(
+            f"Message type '{message_type}' not supported by {platform.value} processor",
+            ErrorCode.UNKNOWN_MESSAGE_TYPE,
+            platform,
+        )
+
+
+class SignatureValidationError(ProcessorError):
+    """Raised when webhook signature validation fails."""
+
+    def __init__(self, platform: PlatformType):
+        super().__init__(
+            f"Webhook signature validation failed for {platform.value}",
+            ErrorCode.SIGNATURE_VALIDATION_FAILED,
+            platform,
+        )