django-cfg 1.5.8__py3-none-any.whl → 1.5.20__py3-none-any.whl

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",
+]

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

@@ -0,0 +1,122 @@
+"""
+Centrifugo Token Generator Service.
+
+Provides utilities for generating Centrifugo JWT tokens with user permissions.
+"""
+
+import time
+import jwt
+from datetime import datetime, timezone
+from typing import List, Dict, Any, Optional
+
+from .config_helper import get_centrifugo_config
+
+
+def get_user_channels(user) -> List[str]:
+    """
+    Get list of Centrifugo channels user is allowed to subscribe to.
+
+    Args:
+        user: Django user instance
+
+    Returns:
+        List of channel names user can access
+
+    Channel naming convention:
+        - user#{user_id} - Personal channel for RPC responses
+        - notifications#user#{user_id} - Personal notifications
+        - centrifugo#dashboard - Admin dashboard events
+        - admin#notifications - Admin notifications
+        - grpc#* - All gRPC bot events (admin only)
+        - broadcast - Global broadcast channel
+    """
+    channels = []
+
+    # Personal channel for RPC responses
+    channels.append(f"user#{user.id}")
+
+    # Notifications channel
+    channels.append(f"notifications#user#{user.id}")
+
+    # Admin channels
+    if user.is_staff or user.is_superuser:
+        channels.append("centrifugo#dashboard")
+        channels.append("admin#notifications")
+        # Allow admins to see all gRPC bot events
+        channels.append("grpc#*")
+
+    # Broadcast channel for all users
+    channels.append("broadcast")
+
+    return channels
+
+
+def generate_centrifugo_token(
+    user,
+    exp_seconds: int = 3600,
+    additional_channels: Optional[List[str]] = None
+) -> Dict[str, Any]:
+    """
+    Generate Centrifugo JWT token with user's allowed channels.
+
+    Args:
+        user: Django user instance
+        exp_seconds: Token expiration time in seconds (default: 1 hour)
+        additional_channels: Optional additional channels to include
+
+    Returns:
+        Dictionary with:
+            - token: JWT token string
+            - centrifugo_url: Centrifugo WebSocket URL
+            - expires_at: Token expiration datetime
+            - channels: List of allowed channels
+
+    Raises:
+        ValueError: If Centrifugo is not configured or disabled
+    """
+    config = get_centrifugo_config()
+    if not config or not config.enabled:
+        raise ValueError("Centrifugo not configured or disabled")
+
+    # Get user's allowed channels
+    channels = get_user_channels(user)
+
+    # Add additional channels if provided
+    if additional_channels:
+        channels.extend(additional_channels)
+        # Remove duplicates while preserving order
+        channels = list(dict.fromkeys(channels))
+
+    # Generate JWT token
+    now = int(time.time())
+    exp = now + exp_seconds
+
+    payload = {
+        "sub": str(user.id),        # User ID
+        "exp": exp,                  # Expiration time
+        "iat": now,                  # Issued at
+        "channels": channels,        # Allowed channels
+    }
+
+    # Sign token with HMAC secret
+    token = jwt.encode(
+        payload,
+        config.centrifugo_token_hmac_secret,
+        algorithm="HS256"
+    )
+
+    # Use timezone-aware datetime for proper ISO 8601 format
+    expires_at = datetime.fromtimestamp(exp, tz=timezone.utc)
+
+    return {
+        "token": token,
+        "centrifugo_url": config.centrifugo_url,
+        "expires_at": expires_at,
+        "channels": channels,
+    }
+
+
+__all__ = [
+    "get_user_channels",
+    "generate_centrifugo_token",
+]

django_cfg/apps/integrations/centrifugo/urls.py

@@ -10,6 +10,8 @@ from rest_framework import routers
 from .views.admin_api import CentrifugoAdminAPIViewSet
 from .views.monitoring import CentrifugoMonitorViewSet
 from .views.testing_api import CentrifugoTestingAPIViewSet
+from .views.token_api import CentrifugoTokenViewSet
+from .views.wrapper import PublishWrapperView
 
 app_name = 'django_cfg_centrifugo'
 
@@ -25,7 +27,13 @@ router.register(r'server', CentrifugoAdminAPIViewSet, basename='server')
 # Testing API endpoints (live testing from dashboard)
 router.register(r'testing', CentrifugoTestingAPIViewSet, basename='testing')
 
+# Token API endpoints (JWT token generation for client connections)
+router.register(r'auth', CentrifugoTokenViewSet, basename='auth')
+
 urlpatterns = [
+    # Wrapper API endpoint (for CentrifugoClient)
+    path('api/publish', PublishWrapperView.as_view(), name='wrapper_publish'),
+
     # Include router URLs
     path('', include(router.urls)),
 ]

django_cfg/apps/integrations/centrifugo/views/__init__.py

@@ -5,9 +5,11 @@ Views for Centrifugo module.
 from .admin_api import CentrifugoAdminAPIViewSet
 from .monitoring import CentrifugoMonitorViewSet
 from .testing_api import CentrifugoTestingAPIViewSet
+from .wrapper import PublishWrapperView
 
 __all__ = [
     'CentrifugoMonitorViewSet',
     'CentrifugoAdminAPIViewSet',
     'CentrifugoTestingAPIViewSet',
+    'PublishWrapperView',
 ]

django_cfg/apps/integrations/centrifugo/views/monitoring.py

@@ -23,6 +23,7 @@ from ..serializers import (
     ChannelListSerializer,
     ChannelStatsSerializer,
     HealthCheckSerializer,
+    PublishSerializer,
     RecentPublishesSerializer,
 )
 from ..services import get_centrifugo_config
@@ -30,18 +31,20 @@ from ..services import get_centrifugo_config
 logger = get_logger("centrifugo.monitoring")
 
 
-class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.ViewSet):
+class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.GenericViewSet):
     """
     ViewSet for Centrifugo monitoring and statistics.
 
     Provides comprehensive monitoring data for Centrifugo publishes including:
     - Health checks
     - Overview statistics
-    - Recent publishes
+    - Recent publishes (with DRF pagination)
     - Channel-level statistics
     Requires admin authentication (JWT, Session, or Basic Auth).
     """
 
+    serializer_class = PublishSerializer
+
     @extend_schema(
         tags=["Centrifugo Monitoring"],
         summary="Get Centrifugo health status",
@@ -126,13 +129,20 @@ class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.ViewSet):
     @extend_schema(
         tags=["Centrifugo Monitoring"],
         summary="Get recent publishes",
-        description="Returns a list of recent Centrifugo publishes with their details.",
+        description="Returns a paginated list of recent Centrifugo publishes with their details. Uses standard DRF pagination.",
         parameters=[
             OpenApiParameter(
-                name="count",
+                name="page",
                 type=OpenApiTypes.INT,
                 location=OpenApiParameter.QUERY,
-                description="Number of publishes to return (default: 50, max: 200)",
+                description="Page number",
+                required=False,
+            ),
+            OpenApiParameter(
+                name="page_size",
+                type=OpenApiTypes.INT,
+                location=OpenApiParameter.QUERY,
+                description="Items per page (default: 10, max: 100)",
                 required=False,
             ),
             OpenApiParameter(
@@ -149,16 +159,9 @@ class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.ViewSet):
                 description="Filter by status (success, failed, timeout, pending, partial)",
                 required=False,
             ),
-            OpenApiParameter(
-                name="offset",
-                type=OpenApiTypes.INT,
-                location=OpenApiParameter.QUERY,
-                description="Offset for pagination (default: 0)",
-                required=False,
-            ),
         ],
         responses={
-            200: RecentPublishesSerializer,
+            200: PublishSerializer(many=True),
             400: {"description": "Invalid parameters"},
         },
     )
@@ -166,28 +169,23 @@ class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.ViewSet):
     def publishes(self, request):
         """Get recent Centrifugo publishes."""
         try:
-            count = int(request.GET.get("count", 50))
-            count = min(count, 200)  # Max 200
-
             channel = request.GET.get("channel")
-            status_filter = request.GET.get("status")  # NEW: status filter
-            offset = int(request.GET.get("offset", 0))  # NEW: offset for pagination
+            status_filter = request.GET.get("status")
 
             queryset = CentrifugoLog.objects.all()
 
             if channel:
                 queryset = queryset.filter(channel=channel)
 
-            # NEW: Filter by status
+            # Filter by status
             if status_filter and status_filter in ["success", "failed", "timeout", "pending", "partial"]:
                 queryset = queryset.filter(status=status_filter)
 
-            # Get total count before slicing
-            total = queryset.count()
+            queryset = queryset.order_by("-created_at")
 
-            # NEW: Apply offset and limit
+            # Convert queryset to list of dicts for serialization
             publishes_list = list(
-                queryset.order_by("-created_at")[offset:offset + count].values(
+                queryset.values(
                     "message_id",
                     "channel",
                     "status",
@@ -202,23 +200,10 @@ class CentrifugoMonitorViewSet(AdminAPIMixin, viewsets.ViewSet):
                 )
             )
 
-            # Convert datetime to ISO format
-            for pub in publishes_list:
-                if pub["created_at"]:
-                    pub["created_at"] = pub["created_at"].isoformat()
-                if pub["completed_at"]:
-                    pub["completed_at"] = pub["completed_at"].isoformat()
-
-            response_data = {
-                "publishes": publishes_list,
-                "count": len(publishes_list),
-                "total_available": total,
-                "offset": offset,  # NEW: for pagination
-                "has_more": (offset + count) < total,  # NEW: pagination helper
-            }
-
-            serializer = RecentPublishesSerializer(**response_data)
-            return Response(serializer.model_dump())
+            # Use DRF pagination
+            page = self.paginate_queryset(publishes_list)
+            serializer = PublishSerializer(page, many=True)
+            return self.get_paginated_response(serializer.data)
 
         except ValueError as e:
             logger.warning(f"Recent publishes validation error: {e}")