django-cfg 1.4.48__py3-none-any.whl → 1.5.7__py3-none-any.whl

django_cfg/apps/integrations/centrifugo/services/client/config.py

@@ -0,0 +1,236 @@
+"""
+Centrifugo Client Configuration.
+
+Pydantic 2 configuration model for Centrifugo integration.
+Follows django-cfg patterns for modular configuration.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class DjangoCfgCentrifugoConfig(BaseModel):
+    """
+    Django-CFG Centrifugo Client configuration module.
+
+    Configures Centrifugo pub/sub communication between Django and
+    Centrifugo WebSocket server via Python Wrapper.
+
+    Example:
+        >>> from django_cfg import DjangoConfig
+        >>> from django_cfg.apps.integrations.centrifugo import DjangoCfgCentrifugoConfig
+        >>>
+        >>> config = DjangoConfig(
+        ...     centrifugo=DjangoCfgCentrifugoConfig(
+        ...         enabled=True,
+        ...         wrapper_url="http://localhost:8080",
+        ...         default_timeout=30
+        ...     )
+        ... )
+    """
+
+    # Module metadata
+    module_name: str = Field(
+        default="centrifugo",
+        frozen=True,
+        description="Module name for django-cfg integration",
+    )
+
+    enabled: bool = Field(
+        default=False,
+        description="Enable Centrifugo integration",
+    )
+
+    # Wrapper configuration
+    wrapper_url: str = Field(
+        default="http://localhost:8080",
+        description="Python Wrapper HTTP API URL",
+        examples=[
+            "http://localhost:8080",
+            "http://centrifugo-wrapper:8080",
+            "https://wrapper.example.com",
+        ],
+    )
+
+    wrapper_api_key: str | None = Field(
+        default=None,
+        description="Optional API key for wrapper authentication",
+    )
+
+    # Centrifugo settings
+    centrifugo_url: str = Field(
+        default="ws://localhost:8002/connection/websocket",
+        description="Centrifugo WebSocket URL for browser clients",
+        examples=[
+            "ws://localhost:8002/connection/websocket",
+            "wss://centrifugo.example.com/connection/websocket",
+        ],
+    )
+
+    centrifugo_api_url: str = Field(
+        default="http://localhost:8002/api",
+        description="Centrifugo HTTP API URL for server-to-server calls",
+        examples=[
+            "http://localhost:8002/api",
+            "https://centrifugo.example.com/api",
+        ],
+    )
+
+    centrifugo_api_key: str | None = Field(
+        default=None,
+        description="Centrifugo API key for server-to-server authentication",
+    )
+
+    centrifugo_token_hmac_secret: str | None = Field(
+        default=None,
+        description="HMAC secret for JWT token generation (if None, uses Django SECRET_KEY)",
+    )
+
+    # Timeout settings
+    default_timeout: int = Field(
+        default=30,
+        ge=5,
+        le=300,
+        description="Default publish timeout (seconds)",
+    )
+
+    ack_timeout: int = Field(
+        default=10,
+        ge=1,
+        le=60,
+        description="Default ACK timeout for delivery confirmation (seconds)",
+    )
+
+    http_timeout: int = Field(
+        default=35,
+        ge=5,
+        le=300,
+        description="HTTP request timeout to wrapper (seconds)",
+    )
+
+    # Retry settings
+    max_retries: int = Field(
+        default=3,
+        ge=0,
+        le=10,
+        description="Maximum retry attempts for failed publishes",
+    )
+
+    retry_delay: float = Field(
+        default=1.0,
+        ge=0.1,
+        le=10.0,
+        description="Delay between retries (seconds)",
+    )
+
+    # SSL settings
+    verify_ssl: bool = Field(
+        default=False,
+        description="Verify SSL certificates for HTTPS connections (default: False for self-signed certs)",
+    )
+
+    # Logging settings
+    log_all_calls: bool = Field(
+        default=False,
+        description="Log all publish calls to database (verbose)",
+    )
+
+    log_only_with_ack: bool = Field(
+        default=True,
+        description="Only log calls that wait for ACK",
+    )
+
+    log_level: str = Field(
+        default="INFO",
+        pattern=r"^(DEBUG|INFO|WARNING|ERROR|CRITICAL)$",
+        description="Log level for Centrifugo module",
+    )
+
+    @field_validator("wrapper_url", "centrifugo_url")
+    @classmethod
+    def validate_urls(cls, v: str) -> str:
+        """
+        Validate URL formats.
+
+        Allows environment variable templates like ${VAR:-default}.
+
+        Args:
+            v: URL to validate
+
+        Returns:
+            Validated URL
+
+        Raises:
+            ValueError: If URL format is invalid
+        """
+        # Skip validation for environment variable templates
+        if v.startswith("${") and "}" in v:
+            return v
+
+        # Validate actual URLs
+        if not any(v.startswith(proto) for proto in ["http://", "https://", "ws://", "wss://"]):
+            raise ValueError(
+                f"URL must start with http://, https://, ws://, or wss:// (got: {v})"
+            )
+
+        return v
+
+    def to_django_settings(self) -> dict:
+        """
+        Generate Django settings dictionary.
+
+        Returns:
+            Dictionary with DJANGO_CFG_CENTRIFUGO settings
+
+        Example:
+            >>> config = DjangoCfgCentrifugoConfig(enabled=True)
+            >>> settings_dict = config.to_django_settings()
+            >>> print(settings_dict["DJANGO_CFG_CENTRIFUGO"]["WRAPPER_URL"])
+        """
+        if not self.enabled:
+            return {}
+
+        return {
+            "DJANGO_CFG_CENTRIFUGO": {
+                "ENABLED": self.enabled,
+                "WRAPPER_URL": self.wrapper_url,
+                "WRAPPER_API_KEY": self.wrapper_api_key,
+                "CENTRIFUGO_URL": self.centrifugo_url,
+                "CENTRIFUGO_API_URL": self.centrifugo_api_url,
+                "CENTRIFUGO_API_KEY": self.centrifugo_api_key,
+                "CENTRIFUGO_TOKEN_HMAC_SECRET": self.centrifugo_token_hmac_secret,
+                "DEFAULT_TIMEOUT": self.default_timeout,
+                "ACK_TIMEOUT": self.ack_timeout,
+                "HTTP_TIMEOUT": self.http_timeout,
+                "MAX_RETRIES": self.max_retries,
+                "RETRY_DELAY": self.retry_delay,
+                "VERIFY_SSL": self.verify_ssl,
+                "LOG_ALL_CALLS": self.log_all_calls,
+                "LOG_ONLY_WITH_ACK": self.log_only_with_ack,
+                "LOG_LEVEL": self.log_level,
+            }
+        }
+
+    def get_client_config(self) -> dict:
+        """
+        Get client configuration dictionary.
+
+        Returns:
+            Dictionary with client connection options
+
+        Example:
+            >>> config = DjangoCfgCentrifugoConfig()
+            >>> client_config = config.get_client_config()
+        """
+        return {
+            "wrapper_url": self.wrapper_url,
+            "wrapper_api_key": self.wrapper_api_key,
+            "default_timeout": self.default_timeout,
+            "ack_timeout": self.ack_timeout,
+            "http_timeout": self.http_timeout,
+            "max_retries": self.max_retries,
+            "retry_delay": self.retry_delay,
+            "verify_ssl": self.verify_ssl,
+        }
+
+
+__all__ = ["DjangoCfgCentrifugoConfig"]

django_cfg/apps/integrations/centrifugo/services/client/exceptions.py

@@ -0,0 +1,212 @@
+"""
+Custom Exceptions for Centrifugo Client.
+
+Provides specific exception types for better error handling and debugging.
+Mirrors legacy WebSocket solution exception patterns for easy migration.
+"""
+
+from typing import Optional
+
+
+class CentrifugoBaseException(Exception):
+    """
+    Base exception for all Centrifugo-related errors.
+
+    All custom Centrifugo exceptions inherit from this class.
+    """
+
+    def __init__(self, message: str):
+        """
+        Initialize base Centrifugo exception.
+
+        Args:
+            message: Error message
+        """
+        self.message = message
+        super().__init__(message)
+
+
+class CentrifugoTimeoutError(CentrifugoBaseException):
+    """
+    Publish call timed out waiting for ACK.
+
+    Raised when ACK timeout is exceeded.
+
+    Example:
+        >>> try:
+        ...     result = client.publish_with_ack(
+        ...         channel="user#123",
+        ...         data={"msg": "test"},
+        ...         ack_timeout=5
+        ...     )
+        ... except CentrifugoTimeoutError as e:
+        ...     print(f"Timeout: {e.message}")
+        ...     print(f"Channel: {e.channel}")
+    """
+
+    def __init__(self, message: str, channel: str, timeout_seconds: int):
+        """
+        Initialize timeout error.
+
+        Args:
+            message: Error message
+            channel: Channel that timed out
+            timeout_seconds: Timeout duration that was exceeded
+        """
+        super().__init__(message)
+        self.channel = channel
+        self.timeout_seconds = timeout_seconds
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"Centrifugo timeout on channel '{self.channel}' after {self.timeout_seconds}s: {self.message}"
+
+
+class CentrifugoPublishError(CentrifugoBaseException):
+    """
+    Failed to publish message to Centrifugo.
+
+    Raised when wrapper returns error or HTTP request fails.
+
+    Example:
+        >>> try:
+        ...     result = client.publish(channel="test", data={})
+        ... except CentrifugoPublishError as e:
+        ...     print(f"Publish failed: {e.message}")
+        ...     print(f"Status code: {e.status_code}")
+    """
+
+    def __init__(
+        self,
+        message: str,
+        channel: Optional[str] = None,
+        status_code: Optional[int] = None,
+        response_data: Optional[dict] = None,
+    ):
+        """
+        Initialize publish error.
+
+        Args:
+            message: Error message
+            channel: Channel that failed
+            status_code: HTTP status code from wrapper
+            response_data: Response data from wrapper
+        """
+        super().__init__(message)
+        self.channel = channel
+        self.status_code = status_code
+        self.response_data = response_data
+
+    def __str__(self) -> str:
+        """String representation."""
+        parts = [f"Centrifugo publish error: {self.message}"]
+        if self.channel:
+            parts.append(f"(channel: {self.channel})")
+        if self.status_code:
+            parts.append(f"(HTTP {self.status_code})")
+        return " ".join(parts)
+
+
+class CentrifugoConnectionError(CentrifugoBaseException):
+    """
+    Failed to connect to wrapper.
+
+    Raised when HTTP connection to wrapper fails.
+
+    Example:
+        >>> try:
+        ...     client = CentrifugoClient(wrapper_url="http://invalid:8080")
+        ...     client.health_check()
+        ... except CentrifugoConnectionError as e:
+        ...     print(f"Connection failed: {e.message}")
+    """
+
+    def __init__(self, message: str, wrapper_url: Optional[str] = None):
+        """
+        Initialize connection error.
+
+        Args:
+            message: Error message
+            wrapper_url: Wrapper URL that failed to connect
+        """
+        super().__init__(message)
+        self.wrapper_url = wrapper_url
+
+    def __str__(self) -> str:
+        """String representation."""
+        if self.wrapper_url:
+            return f"Centrifugo connection error to {self.wrapper_url}: {self.message}"
+        return f"Centrifugo connection error: {self.message}"
+
+
+class CentrifugoConfigurationError(CentrifugoBaseException):
+    """
+    Centrifugo configuration error.
+
+    Raised when Centrifugo client is misconfigured.
+
+    Example:
+        >>> try:
+        ...     client = get_centrifugo_client()  # No config in settings
+        ... except CentrifugoConfigurationError as e:
+        ...     print(f"Configuration error: {e.message}")
+    """
+
+    def __init__(self, message: str, config_key: Optional[str] = None):
+        """
+        Initialize configuration error.
+
+        Args:
+            message: Error message
+            config_key: Configuration key that is missing/invalid
+        """
+        super().__init__(message)
+        self.config_key = config_key
+
+    def __str__(self) -> str:
+        """String representation."""
+        if self.config_key:
+            return f"Centrifugo configuration error (key: {self.config_key}): {self.message}"
+        return f"Centrifugo configuration error: {self.message}"
+
+
+class CentrifugoValidationError(CentrifugoBaseException):
+    """
+    Data validation error.
+
+    Raised when Pydantic model validation fails.
+
+    Example:
+        >>> try:
+        ...     client.publish(channel="test", data="invalid")
+        ... except CentrifugoValidationError as e:
+        ...     print(f"Validation failed: {e.message}")
+    """
+
+    def __init__(self, message: str, validation_errors: Optional[list] = None):
+        """
+        Initialize validation error.
+
+        Args:
+            message: Error message
+            validation_errors: List of validation errors from Pydantic
+        """
+        super().__init__(message)
+        self.validation_errors = validation_errors or []
+
+    def __str__(self) -> str:
+        """String representation."""
+        if self.validation_errors:
+            errors_str = "; ".join(str(e) for e in self.validation_errors)
+            return f"Centrifugo validation error: {self.message} ({errors_str})"
+        return f"Centrifugo validation error: {self.message}"
+
+
+__all__ = [
+    "CentrifugoBaseException",
+    "CentrifugoTimeoutError",
+    "CentrifugoPublishError",
+    "CentrifugoConnectionError",
+    "CentrifugoConfigurationError",
+    "CentrifugoValidationError",
+]

django_cfg/apps/integrations/centrifugo/services/config_helper.py

@@ -0,0 +1,63 @@
+"""
+Centrifugo Config Helper.
+
+Utility functions for accessing Centrifugo configuration from django-cfg.
+"""
+
+from typing import Optional
+
+from django_cfg.modules.django_logging import get_logger
+
+logger = get_logger("centrifugo.config")
+
+
+def get_centrifugo_config():
+    """
+    Get Centrifugo configuration from django-cfg global state.
+
+    Returns:
+        DjangoCfgCentrifugoConfig instance or None if not configured
+
+    Example:
+        >>> config = get_centrifugo_config()
+        >>> if config:
+        ...     print(config.wrapper_url)
+    """
+    from django_cfg.core import get_current_config
+
+    # Try to get config from django-cfg global state
+    django_cfg_config = get_current_config()
+
+    if django_cfg_config and hasattr(django_cfg_config, "centrifugo") and django_cfg_config.centrifugo:
+        return django_cfg_config.centrifugo
+
+    return None
+
+
+def get_centrifugo_config_or_default():
+    """
+    Get Centrifugo configuration from django-cfg or return default.
+
+    Returns:
+        DjangoCfgCentrifugoConfig instance (always)
+
+    Example:
+        >>> config = get_centrifugo_config_or_default()
+        >>> print(config.wrapper_url)  # Always works, fallback to default
+    """
+    config = get_centrifugo_config()
+
+    if config:
+        return config
+
+    # Fallback to default config
+    from ..client.config import DjangoCfgCentrifugoConfig
+
+    logger.warning("Django-CFG centrifugo config not found, using default config")
+    return DjangoCfgCentrifugoConfig()
+
+
+__all__ = [
+    "get_centrifugo_config",
+    "get_centrifugo_config_or_default",
+]

django_cfg/apps/integrations/centrifugo/services/dashboard_notifier.py

@@ -0,0 +1,157 @@
+"""
+Dashboard Real-time Notifications.
+
+Publishes updates to dashboard WebSocket channel when events occur.
+"""
+
+from typing import Any
+from django_cfg.modules.django_logging import get_logger
+
+logger = get_logger("centrifugo")
+
+# Dashboard channel for real-time updates
+DASHBOARD_CHANNEL = "centrifugo#dashboard"
+
+# Centrifugo Wrapper API endpoints
+WRAPPER_PUBLISH_ENDPOINT = "/api/publish"
+
+
+class DashboardNotifier:
+    """
+    Service for publishing real-time updates to Centrifugo dashboard.
+
+    Publishes notifications when:
+    - New publish is created
+    - Publish status changes (success/failure/timeout)
+    - Statistics need to be refreshed
+    """
+
+    @staticmethod
+    async def notify_new_publish(log_entry: Any) -> None:
+        """
+        Notify dashboard about new publish.
+
+        Args:
+            log_entry: CentrifugoLog instance
+        """
+        if not log_entry:
+            return
+
+        try:
+            import httpx
+            from .config_helper import get_centrifugo_config
+
+            config = get_centrifugo_config()
+            if not config or not config.enabled:
+                return
+
+            data = {
+                "type": "new_publish",
+                "publish": {
+                    "message_id": log_entry.message_id,
+                    "channel": log_entry.channel,
+                    "status": log_entry.status,
+                    "wait_for_ack": log_entry.wait_for_ack,
+                    "created_at": log_entry.created_at.isoformat(),
+                }
+            }
+
+            # Direct wrapper call WITHOUT logging to avoid recursion
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                await client.post(
+                    f"{config.wrapper_url}{WRAPPER_PUBLISH_ENDPOINT}",
+                    json={
+                        "channel": DASHBOARD_CHANNEL,
+                        "data": data,
+                        "wait_for_ack": False,
+                        "ack_timeout": 0,
+                    }
+                )
+
+            logger.debug(f"📊 Dashboard notified: new publish {log_entry.message_id}")
+
+        except Exception as e:
+            logger.debug(f"Dashboard notification failed: {e}")
+
+    @staticmethod
+    async def notify_status_change(log_entry: Any, old_status: str = None) -> None:
+        """
+        Notify dashboard about publish status change.
+
+        Args:
+            log_entry: CentrifugoLog instance
+            old_status: Previous status (optional)
+        """
+        if not log_entry:
+            return
+
+        try:
+            import httpx
+            from .config_helper import get_centrifugo_config
+
+            config = get_centrifugo_config()
+            if not config or not config.enabled:
+                return
+
+            data = {
+                "type": "status_change",
+                "publish": {
+                    "message_id": log_entry.message_id,
+                    "channel": log_entry.channel,
+                    "status": log_entry.status,
+                    "old_status": old_status,
+                    "acks_received": log_entry.acks_received,
+                    "duration_ms": log_entry.duration_ms,
+                    "completed_at": log_entry.completed_at.isoformat() if log_entry.completed_at else None,
+                }
+            }
+
+            # Direct wrapper call WITHOUT logging to avoid recursion
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                await client.post(
+                    f"{config.wrapper_url}{WRAPPER_PUBLISH_ENDPOINT}",
+                    json={
+                        "channel": DASHBOARD_CHANNEL,
+                        "data": data,
+                        "wait_for_ack": False,
+                        "ack_timeout": 0,
+                    }
+                )
+
+            logger.debug(f"📊 Dashboard notified: status change {log_entry.message_id} -> {log_entry.status}")
+
+        except Exception as e:
+            logger.debug(f"Dashboard notification failed: {e}")
+
+    @staticmethod
+    async def notify_stats_update() -> None:
+        """
+        Notify dashboard to refresh statistics.
+
+        Triggers a full stats refresh on the dashboard.
+        """
+        try:
+            from .client import CentrifugoClient
+
+            client = CentrifugoClient()
+
+            data = {
+                "type": "stats_update",
+                "action": "refresh",
+            }
+
+            await client.publish(
+                channel=DASHBOARD_CHANNEL,
+                data=data,
+            )
+
+            logger.debug("📊 Dashboard notified: refresh stats")
+
+        except Exception as e:
+            logger.warning(f"Failed to notify dashboard about stats update: {e}")
+
+
+__all__ = [
+    "DashboardNotifier",
+    "DASHBOARD_CHANNEL",
+]