wappa 0.1.0__py3-none-any.whl

wappa/core/plugins/rate_limit_plugin.py

@@ -0,0 +1,183 @@
+"""
+Rate Limit Plugin
+
+Plugin for adding rate limiting middleware to Wappa applications.
+Provides protection against abuse and DoS attacks.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from ...core.logging.logger import get_app_logger
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from ...core.factory.wappa_builder import WappaBuilder
+
+
+class RateLimitPlugin:
+    """
+    Rate limiting middleware plugin for Wappa applications.
+
+    Provides request rate limiting to protect against abuse and DoS attacks.
+    Can be configured with different strategies and backends.
+
+    Example:
+        # Basic rate limiting
+        rate_limit_plugin = RateLimitPlugin(
+            RateLimiterMiddleware,
+            max_requests=100,
+            window_seconds=60
+        )
+
+        # Redis-backed rate limiting
+        rate_limit_plugin = RateLimitPlugin(
+            RedisRateLimiterMiddleware,
+            max_requests=1000,
+            window_seconds=3600,
+            redis_url="redis://localhost:6379"
+        )
+    """
+
+    def __init__(
+        self,
+        rate_limit_middleware_class: type,
+        priority: int = 70,  # Medium-high priority
+        **middleware_kwargs: Any,
+    ):
+        """
+        Initialize rate limit plugin.
+
+        Args:
+            rate_limit_middleware_class: Rate limiting middleware class
+            priority: Middleware priority (lower runs first/outer)
+            **middleware_kwargs: Arguments for the middleware class
+        """
+        self.rate_limit_middleware_class = rate_limit_middleware_class
+        self.priority = priority
+        self.middleware_kwargs = middleware_kwargs
+
+    async def configure(self, builder: "WappaBuilder") -> None:
+        """
+        Configure rate limit plugin with WappaBuilder.
+
+        Adds the rate limiting middleware to the application.
+
+        Args:
+            builder: WappaBuilder instance
+        """
+        logger = get_app_logger()
+
+        # Add rate limiting middleware to builder
+        builder.add_middleware(
+            self.rate_limit_middleware_class,
+            priority=self.priority,
+            **self.middleware_kwargs,
+        )
+
+        logger.debug(
+            f"RateLimitPlugin configured with {self.rate_limit_middleware_class.__name__} "
+            f"(priority: {self.priority})"
+        )
+
+    async def startup(self, app: "FastAPI") -> None:
+        """
+        Rate limit plugin startup.
+
+        Can be used for rate limiter backend initialization.
+
+        Args:
+            app: FastAPI application instance
+        """
+        logger = get_app_logger()
+        logger.debug(
+            f"RateLimitPlugin startup - {self.rate_limit_middleware_class.__name__}"
+        )
+
+    async def shutdown(self, app: "FastAPI") -> None:
+        """
+        Rate limit plugin shutdown.
+
+        Can be used for cleaning up rate limiter resources.
+
+        Args:
+            app: FastAPI application instance
+        """
+        logger = get_app_logger()
+        logger.debug(
+            f"RateLimitPlugin shutdown - {self.rate_limit_middleware_class.__name__}"
+        )
+
+
+# Convenience functions for common rate limiting patterns
+
+
+def create_memory_rate_limit_plugin(
+    max_requests: int = 100, window_seconds: int = 60, **kwargs: Any
+) -> RateLimitPlugin:
+    """
+    Create an in-memory rate limiting plugin.
+
+    Note: This is a convenience function. You'll need to provide
+    an actual rate limiting middleware implementation.
+
+    Args:
+        max_requests: Maximum requests per window
+        window_seconds: Time window in seconds
+        **kwargs: Additional rate limiter arguments
+
+    Returns:
+        Configured RateLimitPlugin for in-memory rate limiting
+    """
+    try:
+        # This is a placeholder - you'd import your actual rate limiting middleware
+        from your_rate_limit_library import MemoryRateLimiterMiddleware
+
+        return RateLimitPlugin(
+            MemoryRateLimiterMiddleware,
+            max_requests=max_requests,
+            window_seconds=window_seconds,
+            **kwargs,
+        )
+    except ImportError:
+        raise ImportError(
+            "Rate limiting middleware not found. Please implement or install a rate limiting middleware library."
+        )
+
+
+def create_redis_rate_limit_plugin(
+    max_requests: int = 1000,
+    window_seconds: int = 3600,
+    redis_url: str = "redis://localhost:6379",
+    **kwargs: Any,
+) -> RateLimitPlugin:
+    """
+    Create a Redis-backed rate limiting plugin.
+
+    Note: This is a convenience function. You'll need to provide
+    an actual Redis rate limiting middleware implementation.
+
+    Args:
+        max_requests: Maximum requests per window
+        window_seconds: Time window in seconds
+        redis_url: Redis connection URL
+        **kwargs: Additional rate limiter arguments
+
+    Returns:
+        Configured RateLimitPlugin for Redis-backed rate limiting
+    """
+    try:
+        # This is a placeholder - you'd import your actual Redis rate limiting middleware
+        from your_rate_limit_library import RedisRateLimiterMiddleware
+
+        return RateLimitPlugin(
+            RedisRateLimiterMiddleware,
+            max_requests=max_requests,
+            window_seconds=window_seconds,
+            redis_url=redis_url,
+            **kwargs,
+        )
+    except ImportError:
+        raise ImportError(
+            "Redis rate limiting middleware not found. Please implement or install a Redis rate limiting middleware library."
+        )

wappa/core/plugins/redis_plugin.py

@@ -0,0 +1,224 @@
+"""
+Redis Plugin
+
+Plugin for integrating Redis caching functionality with the Wappa framework.
+Uses the Wappa library's own RedisManager for clean dependency management.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from ...core.logging.logger import get_app_logger
+from ...persistence.redis.redis_manager import RedisManager
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from ...core.factory.wappa_builder import WappaBuilder
+
+
+class RedisPlugin:
+    """
+    Redis plugin for Wappa applications.
+
+    This plugin integrates Redis caching functionality using Wappa's own
+    RedisManager and ICacheFactory pattern. It automatically uses settings.redis_url
+    and provides clean dependency injection through the event handler cache_factory.
+
+    Example:
+        # Basic usage (uses settings.redis_url automatically)
+        redis_plugin = RedisPlugin()
+
+        # With custom max connections
+        redis_plugin = RedisPlugin(max_connections=100)
+
+        builder.add_plugin(redis_plugin)
+
+        # Access in event handlers through ICacheFactory
+        user_cache = self.cache_factory.create_user_cache(tenant_id, user_id)
+        await user_cache.set('key', 'value')
+    """
+
+    def __init__(self, max_connections: int | None = None, **redis_config: Any):
+        """
+        Initialize Redis plugin.
+
+        Redis URL is automatically loaded from settings.redis_url.
+        The plugin uses hook-based architecture - Redis initialization
+        happens during the startup hook, not during plugin construction.
+
+        Args:
+            max_connections: Max Redis connections (defaults to settings.redis_max_connections)
+            **redis_config: Additional Redis configuration options
+        """
+        self.max_connections = max_connections
+        self.redis_config = redis_config
+
+    def configure(self, builder: "WappaBuilder") -> None:
+        """
+        Configure Redis plugin with WappaBuilder using hook-based architecture.
+
+        Registers Redis initialization and cleanup as hooks with the builder's
+        unified lifespan management system. This ensures Redis starts after
+        core Wappa functionality (logging) and shuts down before core cleanup.
+
+        Args:
+            builder: WappaBuilder instance to register hooks with
+        """
+        # Register Redis lifecycle hooks with appropriate priorities
+        # Priority 20: After core startup (10) but before user hooks (50)
+        builder.add_startup_hook(self._redis_startup, priority=20)
+        builder.add_shutdown_hook(self._redis_shutdown, priority=20)
+
+        logger = get_app_logger()
+        logger.debug("🔧 RedisPlugin configured - registered startup/shutdown hooks")
+
+    async def startup(self, app: "FastAPI") -> None:
+        """
+        Plugin startup method required by WappaPlugin protocol.
+
+        Delegates to _redis_startup hook method for actual implementation.
+        This maintains compatibility with both the plugin protocol and
+        the hook-based architecture.
+
+        Args:
+            app: FastAPI application instance
+        """
+        await self._redis_startup(app)
+
+    async def shutdown(self, app: "FastAPI") -> None:
+        """
+        Plugin shutdown method required by WappaPlugin protocol.
+
+        Delegates to _redis_shutdown hook method for actual implementation.
+        This maintains compatibility with both the plugin protocol and
+        the hook-based architecture.
+
+        Args:
+            app: FastAPI application instance
+        """
+        await self._redis_shutdown(app)
+
+    async def _redis_startup(self, app: "FastAPI") -> None:
+        """
+        Redis initialization hook - runs after core Wappa startup.
+
+        This hook is registered with priority 20, ensuring it runs after
+        core Wappa functionality (priority 10) has initialized logging
+        and other essential services.
+
+        Args:
+            app: FastAPI application instance
+        """
+        logger = get_app_logger()
+
+        try:
+            # Import settings for explicit configuration
+            from ...core.config.settings import settings
+
+            # Use explicit settings - more readable than None
+            redis_url = settings.redis_url
+            max_conn = self.max_connections or settings.redis_max_connections
+
+            logger.info("=== REDIS CACHE INITIALIZATION ===")
+            logger.info(
+                f"🔴 Redis URL: {redis_url} (max_connections: {max_conn})"
+            )
+
+            # Initialize Redis pools with explicit settings
+            await RedisManager.initialize(
+                redis_url=redis_url,  # Explicit, not None - more readable
+                max_connections=max_conn,
+            )
+
+            # Store RedisManager reference in app state for cache factory access
+            app.state.redis_manager = RedisManager
+
+            # Get detailed health status for confirmation
+            health_status = await RedisManager.get_health_status()
+            healthy_pools = [
+                alias
+                for alias, status in health_status.get("pools", {}).items()
+                if status.get("status") == "healthy"
+            ]
+
+            # Success confirmation with pool details
+            pool_info = RedisManager.get_pool_info()
+            logger.info(
+                f"✅ Redis startup completed! "
+                f"Healthy pools: {len(healthy_pools)}/{len(pool_info)} "
+                f"({', '.join(f'{alias}:db{db}' for alias, db in pool_info.items())})"
+            )
+            logger.info("===============================")
+
+            # Debug detailed pool information
+            logger.debug(f"Redis pool health details: {health_status}")
+
+        except Exception as e:
+            logger.error(f"❌ Redis startup hook failed: {e}", exc_info=True)
+            raise RuntimeError(f"RedisPlugin startup hook failed: {e}") from e
+
+    async def _redis_shutdown(self, app: "FastAPI") -> None:
+        """
+        Redis cleanup hook - runs before core Wappa shutdown.
+
+        This hook is registered with priority 20, ensuring it runs before
+        core Wappa cleanup (priority 90) to properly close Redis connections
+        while logging is still available.
+
+        Args:
+            app: FastAPI application instance
+        """
+        logger = get_app_logger()
+
+        try:
+            # Clean up Redis connections if initialized
+            if hasattr(app.state, "redis_manager") and RedisManager.is_initialized():
+                logger.info("=== REDIS CACHE SHUTDOWN ===")
+                logger.debug("🔴 Cleaning up Redis connections...")
+                await RedisManager.cleanup()
+                logger.info("✅ Redis shutdown completed")
+                logger.info("==============================")
+
+            # Clean up app state
+            if hasattr(app.state, "redis_manager"):
+                del app.state.redis_manager
+                logger.debug("🧹 Redis manager removed from app state")
+
+        except Exception as e:
+            # Don't re-raise in shutdown - log and continue
+            logger.error(f"❌ Error during Redis shutdown hook: {e}", exc_info=True)
+
+    async def get_health_status(self, app: "FastAPI") -> dict[str, Any]:
+        """
+        Get Redis health status for monitoring.
+
+        Uses the existing RedisManager.get_health_status() method
+        to provide consistent health reporting.
+
+        Args:
+            app: FastAPI application instance
+
+        Returns:
+            Dictionary with Redis health information
+        """
+        if not RedisManager.is_initialized():
+            return {
+                "healthy": False,
+                "error": "Redis manager not initialized",
+                "initialized": False,
+                "plugin": "RedisPlugin",
+            }
+
+        try:
+            health_status = await RedisManager.get_health_status()
+            return {
+                "healthy": health_status.get("initialized", False),
+                "plugin": "RedisPlugin",
+                **health_status,
+            }
+        except Exception as e:
+            return {
+                "healthy": False,
+                "error": str(e),
+                "plugin": "RedisPlugin",
+            }

wappa/core/plugins/wappa_core_plugin.py

@@ -0,0 +1,261 @@
+"""
+Wappa Core Plugin
+
+This plugin encapsulates all traditional Wappa functionality, providing the foundation
+for the Wappa framework through the plugin system. It includes logging, middleware,
+routes, and lifespan management that was previously hardcoded in the Wappa class.
+"""
+
+from typing import TYPE_CHECKING
+
+import aiohttp
+from fastapi import FastAPI
+
+from wappa.api.middleware.error_handler import ErrorHandlerMiddleware
+from wappa.api.middleware.owner import OwnerMiddleware
+from wappa.api.middleware.request_logging import RequestLoggingMiddleware
+from wappa.api.routes.health import router as health_router
+from wappa.api.routes.whatsapp_combined import whatsapp_router
+
+from ..config.settings import settings
+from ..logging.logger import get_app_logger, setup_app_logging
+from ..types import CacheType
+
+if TYPE_CHECKING:
+    from ..factory.wappa_builder import WappaBuilder
+
+
+class WappaCorePlugin:
+    """
+    Core Wappa functionality as a plugin.
+
+    This plugin provides all the essential Wappa framework functionality:
+    - Application logging setup
+    - HTTP session management
+    - Core middleware stack (Owner, ErrorHandler, RequestLogging)
+    - Core routes (Health, WhatsApp combined)
+    - Webhook URL generation and logging
+    - Cache type configuration
+
+    By implementing core functionality as a plugin, we achieve a unified
+    architecture where all Wappa applications use the same plugin-based
+    foundation, whether they use simple Wappa() or advanced WappaBuilder.
+    """
+
+    def __init__(self, cache_type: CacheType = CacheType.MEMORY):
+        """
+        Initialize Wappa core plugin.
+
+        Args:
+            cache_type: Cache backend to use for the application
+        """
+        self.cache_type = cache_type
+
+    def configure(self, builder: "WappaBuilder") -> None:
+        """
+        Configure core Wappa functionality with the builder.
+
+        Registers:
+        - Core middleware with appropriate priorities
+        - Core routes (health, whatsapp)
+        - Core startup/shutdown hooks
+
+        Args:
+            builder: WappaBuilder instance to configure
+        """
+        logger = get_app_logger()
+        logger.debug("🏗️ Configuring WappaCorePlugin...")
+
+        # Register core middleware with proper priorities
+        # Higher priority numbers run closer to routes (inner middleware)
+        builder.add_middleware(
+            OwnerMiddleware, priority=90
+        )  # Outer - tenant extraction
+        builder.add_middleware(ErrorHandlerMiddleware, priority=80)  # Error handling
+        builder.add_middleware(
+            RequestLoggingMiddleware, priority=70
+        )  # Request logging (inner)
+
+        # Register core routes
+        builder.add_router(health_router)
+        builder.add_router(whatsapp_router)
+
+        # Register core lifespan hooks with high priority (runs first/last)
+        builder.add_startup_hook(self._core_startup, priority=10)  # First to run
+        builder.add_shutdown_hook(self._core_shutdown, priority=90)  # Last to run
+
+        logger.debug(
+            f"✅ WappaCorePlugin configured - cache_type: {self.cache_type.value}, "
+            f"middleware: 3, routes: 2, hooks: 2"
+        )
+
+    async def startup(self, app: FastAPI) -> None:
+        """
+        Plugin startup method required by WappaPlugin protocol.
+
+        Delegates to _core_startup hook method for actual implementation.
+        This maintains compatibility with both the plugin protocol and
+        the hook-based architecture.
+
+        Args:
+            app: FastAPI application instance
+        """
+        await self._core_startup(app)
+
+    async def shutdown(self, app: FastAPI) -> None:
+        """
+        Plugin shutdown method required by WappaPlugin protocol.
+
+        Delegates to _core_shutdown hook method for actual implementation.
+        This maintains compatibility with both the plugin protocol and
+        the hook-based architecture.
+
+        Args:
+            app: FastAPI application instance
+        """
+        await self._core_shutdown(app)
+
+    async def _core_startup(self, app: FastAPI) -> None:
+        """
+        Core Wappa startup functionality.
+
+        This hook runs first (priority 10) to establish the foundation that
+        other plugins and hooks can depend on:
+        - Logging system initialization
+        - HTTP session for connection pooling
+        - Cache type configuration
+        - Webhook URL generation and display
+        - Development mode configuration
+
+        Args:
+            app: FastAPI application instance
+        """
+        logger = None
+        try:
+            # Initialize logging first - this is critical for all other operations
+            setup_app_logging()
+            logger = get_app_logger()
+
+            logger.info(f"🚀 Starting Wappa Framework v{settings.version}")
+            logger.info(f"📊 Environment: {settings.environment}")
+            logger.info(f"👤 Owner ID: {settings.owner_id}")
+            logger.info(f"📝 Log level: {settings.log_level}")
+            logger.info(f"💾 Cache type: {self.cache_type.value}")
+
+            if settings.is_development:
+                logger.info(f"🔧 Development mode - logs: {settings.log_dir}")
+
+            # Set cache type in app state for WebhookController detection
+            app.state.wappa_cache_type = self.cache_type.value
+            logger.debug(f"💾 Set app.state.wappa_cache_type = {self.cache_type.value}")
+
+            # Initialize HTTP session for connection pooling (correct scope for app lifecycle)
+            app.state.http_session = aiohttp.ClientSession()
+            logger.debug("🌐 HTTP session initialized for connection pooling")
+
+            # Log available endpoints
+            base_url = (
+                f"http://localhost:{settings.port}"
+                if settings.is_development
+                else "https://your-domain.com"
+            )
+            logger.info("=== AVAILABLE ENDPOINTS ===")
+            logger.info(f"🏥 Health Check: {base_url}/health")
+            logger.info(f"📊 Detailed Health: {base_url}/health/detailed")
+            logger.info(f"📱 WhatsApp API: {base_url}/api/whatsapp/...")
+            logger.info(
+                f"📖 API Documentation: {base_url}/docs"
+                if settings.is_development
+                else "📖 API docs disabled in production"
+            )
+            logger.info("============================")
+
+            # Generate and display WhatsApp webhook URL
+            await self._display_webhook_urls(logger, base_url)
+
+            logger.info("✅ Wappa core startup completed successfully")
+
+        except Exception as e:
+            if logger:
+                logger.error(f"❌ Error during Wappa core startup: {e}", exc_info=True)
+            else:
+                print(f"💥 Critical error during logging setup: {e}")
+            raise
+
+    async def _core_shutdown(self, app: FastAPI) -> None:
+        """
+        Core Wappa shutdown functionality.
+
+        This hook runs last (priority 90) to clean up core resources after
+        all other plugins have shut down:
+        - Close HTTP session
+        - Final logging
+
+        Args:
+            app: FastAPI application instance
+        """
+        logger = get_app_logger()
+        logger.info("🛑 Starting Wappa core shutdown...")
+
+        try:
+            # Close HTTP session if it exists
+            if hasattr(app.state, "http_session"):
+                await app.state.http_session.close()
+                logger.debug("🌐 HTTP session closed")
+
+            # Clear cache type from app state
+            if hasattr(app.state, "wappa_cache_type"):
+                del app.state.wappa_cache_type
+                logger.debug("💾 Cache type cleared from app state")
+
+            logger.info("✅ Wappa core shutdown completed")
+
+        except Exception as e:
+            logger.error(f"❌ Error during Wappa core shutdown: {e}", exc_info=True)
+
+    async def _display_webhook_urls(self, logger, base_url: str) -> None:
+        """
+        Generate and display WhatsApp webhook URLs for user convenience.
+
+        Args:
+            logger: Logger instance
+            base_url: Base URL for the application
+        """
+        try:
+            # Import here to avoid circular imports during startup
+            from ..events.webhook_factory import webhook_url_factory
+
+            whatsapp_webhook_url = webhook_url_factory.generate_whatsapp_webhook_url()
+
+            logger.info("=== WHATSAPP WEBHOOK URL ===")
+            logger.info(f"📍 Primary Webhook URL: {whatsapp_webhook_url}")
+            logger.info("   • Use this single URL in WhatsApp Business settings")
+            logger.info("   • Handles both verification (GET) and webhooks (POST)")
+            logger.info("   • Auto-configured with your WP_PHONE_ID from .env")
+            logger.info("=============================")
+            logger.info("")
+
+        except Exception as e:
+            logger.warning(f"⚠️ Could not generate webhook URL: {e}")
+
+    def get_cache_type(self) -> CacheType:
+        """
+        Get the configured cache type.
+
+        Returns:
+            CacheType enum value
+        """
+        return self.cache_type
+
+    def set_cache_type(self, cache_type: CacheType) -> None:
+        """
+        Update the cache type configuration.
+
+        Args:
+            cache_type: New cache type to use
+
+        Note:
+            This should be called before the application starts, as the
+            cache type is set in app state during startup.
+        """
+        self.cache_type = cache_type