django-cfg 1.5.14__py3-none-any.whl → 1.5.29__py3-none-any.whl

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

@@ -0,0 +1,282 @@
+"""
+Direct Centrifugo Client.
+
+Lightweight client for internal Django-to-Centrifugo communication.
+Bypasses wrapper and connects directly to Centrifugo HTTP API.
+
+Use this for:
+- Internal gRPC events
+- Demo/test events
+- Background tasks
+- Any server-side publishing
+
+Use CentrifugoClient (with wrapper) for:
+- External API calls (from Next.js frontend)
+- When you need Django authorization
+- When you need wrapper-level logging
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+import httpx
+from django_cfg.modules.django_logging import get_logger
+
+from .exceptions import (
+    CentrifugoConfigurationError,
+    CentrifugoConnectionError,
+    CentrifugoPublishError,
+)
+
+logger = get_logger("centrifugo.direct_client")
+
+
+class PublishResponse:
+    """Response from direct publish operation."""
+
+    def __init__(self, message_id: str, published: bool):
+        self.message_id = message_id
+        self.published = published
+        self.delivered = published  # For compatibility
+
+
+class DirectCentrifugoClient:
+    """
+    Direct Centrifugo HTTP API client.
+
+    Connects directly to Centrifugo without going through Django wrapper.
+    Uses Centrifugo JSON-RPC format: POST /api with {method, params}.
+
+    Features:
+    - No database logging (lightweight)
+    - No wrapper overhead
+    - Direct API key authentication
+    - Minimal latency for internal calls
+
+    Example:
+        >>> from django_cfg.apps.integrations.centrifugo.services.client import DirectCentrifugoClient
+        >>>
+        >>> client = DirectCentrifugoClient(
+        ...     api_url="http://localhost:7120/api",
+        ...     api_key="your-api-key"
+        ... )
+        >>>
+        >>> result = await client.publish(
+        ...     channel="grpc#bot#123",
+        ...     data={"status": "running"}
+        ... )
+    """
+
+    def __init__(
+        self,
+        api_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        http_timeout: int = 10,
+        max_retries: int = 3,
+        retry_delay: float = 0.5,
+        verify_ssl: bool = False,
+    ):
+        """
+        Initialize direct Centrifugo client.
+
+        Args:
+            api_url: Centrifugo HTTP API URL (e.g., "http://localhost:8000/api")
+            api_key: Centrifugo API key for authentication
+            http_timeout: HTTP request timeout (seconds)
+            max_retries: Maximum retry attempts
+            retry_delay: Delay between retries (seconds)
+            verify_ssl: Whether to verify SSL certificates
+        """
+        self.api_url = api_url or self._get_api_url_from_settings()
+        self.api_key = api_key or self._get_api_key_from_settings()
+        self.http_timeout = http_timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.verify_ssl = verify_ssl
+
+        # Create HTTP client
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"apikey {self.api_key}"
+
+        self._http_client = httpx.AsyncClient(
+            base_url=self.api_url.rstrip("/api"),  # Remove /api from base
+            headers=headers,
+            timeout=httpx.Timeout(self.http_timeout),
+            limits=httpx.Limits(max_keepalive_connections=10, max_connections=20),
+            verify=self.verify_ssl,
+        )
+
+        logger.info(f"DirectCentrifugoClient initialized: {self.api_url}")
+
+    def _get_api_url_from_settings(self) -> str:
+        """Get Centrifugo API URL from django-cfg config."""
+        from ..config_helper import get_centrifugo_config
+
+        config = get_centrifugo_config()
+
+        if config and config.centrifugo_api_url:
+            return config.centrifugo_api_url
+
+        raise CentrifugoConfigurationError(
+            "Centrifugo API URL not configured",
+            config_key="centrifugo.centrifugo_api_url",
+        )
+
+    def _get_api_key_from_settings(self) -> str:
+        """Get Centrifugo API key from django-cfg config."""
+        from ..config_helper import get_centrifugo_config
+
+        config = get_centrifugo_config()
+
+        if config and config.centrifugo_api_key:
+            return config.centrifugo_api_key
+
+        raise CentrifugoConfigurationError(
+            "Centrifugo API key not configured",
+            config_key="centrifugo.centrifugo_api_key",
+        )
+
+    async def publish(
+        self,
+        channel: str,
+        data: Dict[str, Any],
+    ) -> PublishResponse:
+        """
+        Publish message to Centrifugo channel.
+
+        Args:
+            channel: Centrifugo channel name
+            data: Message data dict
+
+        Returns:
+            PublishResponse with result
+
+        Raises:
+            CentrifugoPublishError: If publish fails
+            CentrifugoConnectionError: If connection fails
+
+        Example:
+            >>> result = await client.publish(
+            ...     channel="grpc#bot#123#status",
+            ...     data={"status": "running", "timestamp": "2025-11-05T09:00:00Z"}
+            ... )
+        """
+        message_id = str(uuid4())
+        start_time = time.time()
+
+        # Centrifugo JSON-RPC format
+        payload = {
+            "method": "publish",
+            "params": {
+                "channel": channel,
+                "data": data,
+            },
+        }
+
+        last_error = None
+
+        for attempt in range(self.max_retries):
+            try:
+                response = await self._http_client.post("/api", json=payload)
+
+                if response.status_code == 200:
+                    result = response.json()
+
+                    # Check for Centrifugo error
+                    if "error" in result and result["error"]:
+                        error_msg = result["error"].get("message", "Unknown error")
+                        raise CentrifugoPublishError(
+                            f"Centrifugo API error: {error_msg}",
+                            channel=channel,
+                        )
+
+                    duration_ms = int((time.time() - start_time) * 1000)
+                    logger.debug(
+                        f"Published to {channel} (message_id={message_id}, {duration_ms}ms)"
+                    )
+
+                    return PublishResponse(message_id=message_id, published=True)
+
+                else:
+                    raise CentrifugoPublishError(
+                        f"HTTP {response.status_code}: {response.text}",
+                        channel=channel,
+                    )
+
+            except httpx.ConnectError as e:
+                last_error = CentrifugoConnectionError(
+                    f"Failed to connect to Centrifugo: {e}",
+                    url=self.api_url,
+                )
+                logger.warning(
+                    f"Connection attempt {attempt + 1}/{self.max_retries} failed: {e}"
+                )
+
+            except Exception as e:
+                last_error = CentrifugoPublishError(
+                    f"Publish failed: {e}",
+                    channel=channel,
+                )
+                logger.error(f"Publish attempt {attempt + 1}/{self.max_retries} failed: {e}")
+
+            # Retry delay
+            if attempt < self.max_retries - 1:
+                import asyncio
+                await asyncio.sleep(self.retry_delay)
+
+        # All retries failed
+        if last_error:
+            raise last_error
+        else:
+            raise CentrifugoPublishError(
+                f"Failed to publish after {self.max_retries} attempts",
+                channel=channel,
+            )
+
+    async def close(self):
+        """Close HTTP client connection."""
+        await self._http_client.aclose()
+        logger.debug("DirectCentrifugoClient closed")
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+
+# Singleton instance
+_direct_client_instance: Optional[DirectCentrifugoClient] = None
+
+
+def get_direct_centrifugo_client() -> DirectCentrifugoClient:
+    """
+    Get singleton DirectCentrifugoClient instance.
+
+    Returns:
+        DirectCentrifugoClient instance
+
+    Example:
+        >>> from django_cfg.apps.integrations.centrifugo.services.client import get_direct_centrifugo_client
+        >>> client = get_direct_centrifugo_client()
+        >>> await client.publish(channel="test", data={"foo": "bar"})
+    """
+    global _direct_client_instance
+
+    if _direct_client_instance is None:
+        _direct_client_instance = DirectCentrifugoClient()
+
+    return _direct_client_instance
+
+
+__all__ = [
+    "DirectCentrifugoClient",
+    "get_direct_centrifugo_client",
+    "PublishResponse",
+]

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

@@ -400,6 +400,53 @@ class CentrifugoLogger:
                 extra={"message_id": getattr(log_entry, "message_id", "unknown")},
             )
 
+    @staticmethod
+    async def mark_failed_async(
+        log_entry: Any,
+        error_code: str,
+        error_message: str,
+        duration_ms: int | None = None,
+    ) -> None:
+        """
+        Mark publish operation as failed (async version).
+
+        Args:
+            log_entry: CentrifugoLog instance
+            error_code: Error code
+            error_message: Error message
+            duration_ms: Duration in milliseconds
+        """
+        if log_entry is None:
+            return
+
+        try:
+            from asgiref.sync import sync_to_async
+            from ..models import CentrifugoLog
+
+            await sync_to_async(CentrifugoLog.objects.mark_failed)(
+                log_instance=log_entry,
+                error_code=error_code,
+                error_message=error_message,
+                duration_ms=duration_ms,
+            )
+
+            logger.error(
+                f"Centrifugo publish failed: {log_entry.message_id}",
+                extra={
+                    "message_id": log_entry.message_id,
+                    "channel": log_entry.channel,
+                    "error_code": error_code,
+                    "error_message": error_message,
+                    "duration_ms": duration_ms,
+                },
+            )
+
+        except Exception as e:
+            logger.error(
+                f"Failed to mark Centrifugo log as failed: {e}",
+                extra={"message_id": getattr(log_entry, "message_id", "unknown")},
+            )
+
     @staticmethod
     async def mark_timeout_async(
         log_entry: Any,

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

@@ -0,0 +1,371 @@
+"""
+Centrifugo Publishing Service.
+
+Unified high-level API for publishing events to Centrifugo.
+Abstracts away CentrifugoClient details and provides domain-specific methods.
+
+Usage:
+    >>> from django_cfg.apps.integrations.centrifugo.services import CentrifugoPublisher
+    >>>
+    >>> publisher = CentrifugoPublisher()
+    >>>
+    >>> # Publish gRPC event
+    >>> await publisher.publish_grpc_event(
+    ...     channel="grpc#bot#123#status",
+    ...     method="/bot.BotService/Start",
+    ...     status="OK",
+    ...     duration_ms=150
+    ... )
+    >>>
+    >>> # Publish demo event
+    >>> await publisher.publish_demo_event(
+    ...     channel="grpc#demo#test",
+    ...     metadata={"test": True}
+    ... )
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone as tz
+from typing import Any, Dict, Optional
+
+from django_cfg.modules.django_logging import get_logger
+
+from ..services.client import (
+    CentrifugoClient,
+    DirectCentrifugoClient,
+    PublishResponse,
+    get_centrifugo_client,
+    get_direct_centrifugo_client,
+)
+
+logger = get_logger("centrifugo.publisher")
+
+
+class CentrifugoPublisher:
+    """
+    High-level publishing service for Centrifugo events.
+
+    Provides domain-specific methods that abstract away low-level client details.
+    All methods are async and handle errors gracefully.
+
+    Features:
+    - Unified API for all Centrifugo publishing
+    - Automatic timestamp injection
+    - Type-safe event metadata
+    - Error handling and logging
+    - Easy to mock for testing
+    """
+
+    def __init__(
+        self,
+        client: Optional[CentrifugoClient | DirectCentrifugoClient] = None,
+        use_direct: bool = True,
+    ):
+        """
+        Initialize publisher.
+
+        Args:
+            client: Optional client instance (CentrifugoClient or DirectCentrifugoClient)
+            use_direct: Use DirectCentrifugoClient (bypass wrapper, default=True)
+        """
+        if client:
+            self._client = client
+            logger.debug("CentrifugoPublisher initialized with custom client")
+        elif use_direct:
+            # Use direct client (no wrapper, no DB logging)
+            self._client = get_direct_centrifugo_client()
+            logger.debug("CentrifugoPublisher initialized with DirectCentrifugoClient")
+        else:
+            # Use wrapper client (with auth & DB logging)
+            self._client = get_centrifugo_client()
+            logger.debug("CentrifugoPublisher initialized with CentrifugoClient (wrapper)")
+
+    @property
+    def client(self) -> CentrifugoClient | DirectCentrifugoClient:
+        """Get underlying client instance."""
+        return self._client
+
+    async def publish_grpc_event(
+        self,
+        channel: str,
+        method: str,
+        status: str = "OK",
+        duration_ms: float = 0.0,
+        peer: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **extra: Any,
+    ) -> PublishResponse:
+        """
+        Publish gRPC event (interceptor-style metadata).
+
+        Args:
+            channel: Centrifugo channel (e.g., "grpc#bot#123#status")
+            method: Full gRPC method name (e.g., "/bot.BotService/Start")
+            status: RPC status code (default: "OK")
+            duration_ms: RPC duration in milliseconds
+            peer: Client peer address
+            metadata: Additional metadata dict
+            **extra: Additional fields
+
+        Returns:
+            PublishResponse with result
+
+        Example:
+            >>> await publisher.publish_grpc_event(
+            ...     channel="grpc#bot#123#status",
+            ...     method="/bot.BotService/Start",
+            ...     status="OK",
+            ...     duration_ms=150,
+            ...     peer="127.0.0.1:50051"
+            ... )
+        """
+        # Parse method name
+        service_name = None
+        method_name = None
+        if method.startswith("/") and "/" in method[1:]:
+            parts = method[1:].split("/")
+            service_name = parts[0]
+            method_name = parts[1]
+
+        # Build event data
+        event_data = {
+            "event_type": "grpc_event",
+            "method": method,
+            "status": status,
+            "timestamp": datetime.now(tz.utc).isoformat(),
+        }
+
+        if service_name:
+            event_data["service"] = service_name
+        if method_name:
+            event_data["method_name"] = method_name
+        if duration_ms:
+            event_data["duration_ms"] = duration_ms
+        if peer:
+            event_data["peer"] = peer
+        if metadata:
+            event_data.update(metadata)
+        if extra:
+            event_data.update(extra)
+
+        logger.debug(f"Publishing gRPC event: {channel} ({method})")
+
+        # DirectCentrifugoClient uses simpler API
+        if isinstance(self._client, DirectCentrifugoClient):
+            return await self._client.publish(channel=channel, data=event_data)
+        else:
+            return await self._client.publish(channel=channel, data=event_data)
+
+    async def publish_demo_event(
+        self,
+        channel: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        **extra: Any,
+    ) -> PublishResponse:
+        """
+        Publish demo/test event.
+
+        Args:
+            channel: Centrifugo channel
+            metadata: Event metadata
+            **extra: Additional fields
+
+        Returns:
+            PublishResponse with result
+
+        Example:
+            >>> await publisher.publish_demo_event(
+            ...     channel="grpc#demo#test",
+            ...     metadata={"test": True, "source": "demo.py"}
+            ... )
+        """
+        event_data = {
+            "event_type": "demo_event",
+            "timestamp": datetime.now(tz.utc).isoformat(),
+            "test_mode": True,
+        }
+
+        if metadata:
+            event_data.update(metadata)
+        if extra:
+            event_data.update(extra)
+
+        logger.debug(f"Publishing demo event: {channel}")
+
+        if isinstance(self._client, DirectCentrifugoClient):
+            return await self._client.publish(channel=channel, data=event_data)
+        else:
+            return await self._client.publish(channel=channel, data=event_data)
+
+    async def publish_notification(
+        self,
+        channel: str,
+        title: str,
+        message: str,
+        level: str = "info",
+        user: Optional[Any] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **extra: Any,
+    ) -> PublishResponse:
+        """
+        Publish user notification.
+
+        Args:
+            channel: Centrifugo channel (e.g., "notifications#user#123")
+            title: Notification title
+            message: Notification message
+            level: Notification level (info, warning, error, success)
+            user: Django User instance
+            metadata: Additional metadata
+            **extra: Additional fields
+
+        Returns:
+            PublishResponse with result
+
+        Example:
+            >>> await publisher.publish_notification(
+            ...     channel="notifications#user#123",
+            ...     title="Bot Started",
+            ...     message="Your bot has started successfully",
+            ...     level="success"
+            ... )
+        """
+        event_data = {
+            "event_type": "notification",
+            "title": title,
+            "message": message,
+            "level": level,
+            "timestamp": datetime.now(tz.utc).isoformat(),
+        }
+
+        if metadata:
+            event_data.update(metadata)
+        if extra:
+            event_data.update(extra)
+
+        logger.debug(f"Publishing notification: {channel} ({title})")
+
+        return await self._client.publish(channel=channel, data=event_data, user=user)
+
+    async def publish_status_change(
+        self,
+        channel: str,
+        old_status: str,
+        new_status: str,
+        reason: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **extra: Any,
+    ) -> PublishResponse:
+        """
+        Publish status change event.
+
+        Args:
+            channel: Centrifugo channel
+            old_status: Previous status
+            new_status: New status
+            reason: Reason for status change
+            metadata: Additional metadata
+            **extra: Additional fields
+
+        Returns:
+            PublishResponse with result
+
+        Example:
+            >>> await publisher.publish_status_change(
+            ...     channel="bot#123#status",
+            ...     old_status="STOPPED",
+            ...     new_status="RUNNING",
+            ...     reason="User requested start"
+            ... )
+        """
+        event_data = {
+            "event_type": "status_change",
+            "old_status": old_status,
+            "new_status": new_status,
+            "timestamp": datetime.now(tz.utc).isoformat(),
+        }
+
+        if reason:
+            event_data["reason"] = reason
+        if metadata:
+            event_data.update(metadata)
+        if extra:
+            event_data.update(extra)
+
+        logger.debug(f"Publishing status change: {channel} ({old_status} → {new_status})")
+
+        return await self._client.publish(channel=channel, data=event_data)
+
+    async def publish_custom(
+        self,
+        channel: str,
+        event_type: str,
+        data: Dict[str, Any],
+        user: Optional[Any] = None,
+    ) -> PublishResponse:
+        """
+        Publish custom event with arbitrary data.
+
+        Args:
+            channel: Centrifugo channel
+            event_type: Custom event type
+            data: Event data dict
+            user: Django User instance
+
+        Returns:
+            PublishResponse with result
+
+        Example:
+            >>> await publisher.publish_custom(
+            ...     channel="custom#events",
+            ...     event_type="custom_event",
+            ...     data={"foo": "bar", "count": 42}
+            ... )
+        """
+        event_data = {
+            "event_type": event_type,
+            "timestamp": datetime.now(tz.utc).isoformat(),
+            **data,
+        }
+
+        logger.debug(f"Publishing custom event: {channel} ({event_type})")
+
+        return await self._client.publish(channel=channel, data=event_data, user=user)
+
+
+# Singleton instance
+_publisher_instance: Optional[CentrifugoPublisher] = None
+
+
+def get_centrifugo_publisher(client: Optional[CentrifugoClient] = None) -> CentrifugoPublisher:
+    """
+    Get singleton CentrifugoPublisher instance.
+
+    Args:
+        client: Optional CentrifugoClient (creates new publisher if provided)
+
+    Returns:
+        CentrifugoPublisher instance
+
+    Example:
+        >>> from django_cfg.apps.integrations.centrifugo.services import get_centrifugo_publisher
+        >>> publisher = get_centrifugo_publisher()
+        >>> await publisher.publish_demo_event(channel="test", metadata={"foo": "bar"})
+    """
+    global _publisher_instance
+
+    if client is not None:
+        # Create new instance with custom client
+        return CentrifugoPublisher(client=client)
+
+    if _publisher_instance is None:
+        _publisher_instance = CentrifugoPublisher()
+
+    return _publisher_instance
+
+
+__all__ = [
+    "CentrifugoPublisher",
+    "get_centrifugo_publisher",
+]