django-cfg 1.4.61__py3-none-any.whl → 1.4.63__py3-none-any.whl

django_cfg/apps/centrifugo/models/__init__.py

@@ -0,0 +1,11 @@
+"""
+Centrifugo Models.
+
+Django models for tracking Centrifugo publish operations.
+"""
+
+from .centrifugo_log import CentrifugoLog
+
+__all__ = [
+    "CentrifugoLog",
+]

django_cfg/apps/centrifugo/models/centrifugo_log.py

@@ -0,0 +1,210 @@
+"""
+Centrifugo Log Model.
+
+Django model for tracking Centrifugo publish operations.
+Mirrors django-ipc RPCLog patterns for easy migration.
+"""
+
+from django.conf import settings
+from django.db import models
+from django.utils import timezone
+
+
+class CentrifugoLog(models.Model):
+    """
+    Log of Centrifugo publish operations.
+
+    Tracks all publish calls with ACK tracking, mirroring RPCLog functionality.
+    Provides observability for debugging and monitoring.
+
+    Fields mirror RPCLog for migration compatibility:
+    - correlation_id → message_id
+    - method → channel
+    - params → data
+    - status → status
+    - duration_ms → duration_ms
+    - is_event → is_notification
+
+    Example:
+        >>> log = CentrifugoLog.objects.create(
+        ...     message_id="abc123",
+        ...     channel="user#456",
+        ...     data={"title": "Hello", "message": "World"},
+        ...     wait_for_ack=True
+        ... )
+        >>> log.mark_success(acks_received=1, duration_ms=125)
+    """
+
+    # Custom manager
+    from ..managers.centrifugo_log import CentrifugoLogManager
+
+    objects: CentrifugoLogManager = CentrifugoLogManager()
+
+    class StatusChoices(models.TextChoices):
+        """Status of publish operation."""
+
+        PENDING = "pending", "Pending"
+        SUCCESS = "success", "Success"
+        FAILED = "failed", "Failed"
+        TIMEOUT = "timeout", "Timeout"
+        PARTIAL = "partial", "Partial Delivery"  # Some ACKs received, not all
+
+    # Identity
+    message_id = models.CharField(
+        max_length=100,
+        unique=True,
+        db_index=True,
+        help_text="Unique message identifier (UUID)",
+    )
+
+    # Publish details
+    channel = models.CharField(
+        max_length=200,
+        db_index=True,
+        help_text="Centrifugo channel (e.g., user#123, broadcast)",
+    )
+
+    data = models.JSONField(
+        help_text="Published data (JSON payload)",
+    )
+
+    # ACK tracking
+    wait_for_ack = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this publish waited for ACK",
+    )
+
+    ack_timeout = models.IntegerField(
+        null=True,
+        blank=True,
+        help_text="ACK timeout in seconds",
+    )
+
+    acks_received = models.IntegerField(
+        default=0,
+        help_text="Number of ACKs received",
+    )
+
+    acks_expected = models.IntegerField(
+        null=True,
+        blank=True,
+        help_text="Number of ACKs expected (if known)",
+    )
+
+    # Status tracking
+    status = models.CharField(
+        max_length=20,
+        choices=StatusChoices.choices,
+        default=StatusChoices.PENDING,
+        db_index=True,
+        help_text="Current status of publish operation",
+    )
+
+    error_code = models.CharField(
+        max_length=100,
+        null=True,
+        blank=True,
+        help_text="Error code if failed",
+    )
+
+    error_message = models.TextField(
+        null=True,
+        blank=True,
+        help_text="Error message if failed",
+    )
+
+    # Performance
+    duration_ms = models.IntegerField(
+        null=True,
+        blank=True,
+        help_text="Total duration in milliseconds",
+    )
+
+    # Metadata
+    is_notification = models.BooleanField(
+        default=True,
+        db_index=True,
+        help_text="Whether this is a notification (vs other pub type)",
+    )
+
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="centrifugo_logs",
+        help_text="User who triggered the publish (if applicable)",
+    )
+
+    caller_ip = models.GenericIPAddressField(
+        null=True,
+        blank=True,
+        help_text="IP address of caller",
+    )
+
+    user_agent = models.TextField(
+        null=True,
+        blank=True,
+        help_text="User agent of caller",
+    )
+
+    # Timestamps
+    created_at = models.DateTimeField(
+        auto_now_add=True,
+        db_index=True,
+        help_text="When publish was initiated",
+    )
+
+    completed_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="When publish completed (success/failure/timeout)",
+    )
+
+    class Meta:
+        db_table = "django_cfg_centrifugo_log"
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(fields=["channel", "-created_at"]),
+            models.Index(fields=["status", "-created_at"]),
+            models.Index(fields=["wait_for_ack", "status"]),
+            models.Index(fields=["user", "-created_at"]),
+        ]
+        verbose_name = "Centrifugo Log"
+        verbose_name_plural = "Centrifugo Logs"
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"{self.channel} ({self.message_id[:8]}...) - {self.status}"
+
+    @property
+    def is_completed(self) -> bool:
+        """Check if publish is completed (any terminal status)."""
+        return self.status in [
+            self.StatusChoices.SUCCESS,
+            self.StatusChoices.FAILED,
+            self.StatusChoices.TIMEOUT,
+            self.StatusChoices.PARTIAL,
+        ]
+
+    @property
+    def is_successful(self) -> bool:
+        """Check if publish was successful."""
+        return self.status == self.StatusChoices.SUCCESS
+
+    @property
+    def delivery_rate(self) -> float | None:
+        """
+        Calculate delivery rate (ACKs received / expected).
+
+        Returns:
+            Delivery rate (0.0 to 1.0) or None if unknown
+        """
+        if self.acks_expected and self.acks_expected > 0:
+            return self.acks_received / self.acks_expected
+        return None
+
+
+__all__ = ["CentrifugoLog"]

django_cfg/apps/centrifugo/registry.py

@@ -0,0 +1,106 @@
+"""
+Global registry for RPC handlers.
+
+Stores metadata about registered handlers for code generation.
+"""
+
+import logging
+from typing import Dict, List, Any, Callable, Optional, Type
+from pydantic import BaseModel
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RegisteredHandler:
+    """
+    Metadata about registered RPC handler.
+
+    Attributes:
+        name: RPC method name (e.g., "tasks.get_stats")
+        handler: Handler function
+        param_type: Pydantic model for parameters
+        return_type: Pydantic model for return value
+        docstring: Handler documentation
+    """
+    name: str
+    handler: Callable
+    param_type: Optional[Type[BaseModel]]
+    return_type: Optional[Type[BaseModel]]
+    docstring: Optional[str]
+
+
+class RPCRegistry:
+    """
+    Global registry for RPC handlers.
+
+    Used by @websocket_rpc decorator to register handlers
+    and by codegen to discover available methods.
+    """
+
+    def __init__(self):
+        self._handlers: Dict[str, RegisteredHandler] = {}
+
+    def register(
+        self,
+        name: str,
+        handler: Callable,
+        param_type: Optional[Type[BaseModel]] = None,
+        return_type: Optional[Type[BaseModel]] = None,
+        docstring: Optional[str] = None,
+    ) -> None:
+        """
+        Register RPC handler.
+
+        Args:
+            name: RPC method name (e.g., "tasks.get_stats")
+            handler: Handler function
+            param_type: Pydantic model for parameters
+            return_type: Pydantic model for return value
+            docstring: Handler documentation
+        """
+        if name in self._handlers:
+            logger.warning(f"Handler '{name}' already registered, overwriting")
+
+        self._handlers[name] = RegisteredHandler(
+            name=name,
+            handler=handler,
+            param_type=param_type,
+            return_type=return_type,
+            docstring=docstring,
+        )
+
+        logger.debug(f"Registered RPC handler: {name}")
+
+    def get_handler(self, name: str) -> Optional[RegisteredHandler]:
+        """Get handler by name."""
+        return self._handlers.get(name)
+
+    def get_all_handlers(self) -> List[RegisteredHandler]:
+        """Get all registered handlers."""
+        return list(self._handlers.values())
+
+    def list_methods(self) -> List[str]:
+        """List all registered method names."""
+        return list(self._handlers.keys())
+
+    def clear(self) -> None:
+        """Clear all registered handlers (for testing)."""
+        self._handlers.clear()
+
+
+# Global registry instance
+_global_registry = RPCRegistry()
+
+
+def get_global_registry() -> RPCRegistry:
+    """Get global RPC registry instance."""
+    return _global_registry
+
+
+__all__ = [
+    "RegisteredHandler",
+    "RPCRegistry",
+    "get_global_registry",
+]

django_cfg/apps/centrifugo/router.py

@@ -0,0 +1,125 @@
+"""
+MessageRouter for Centrifugo RPC handlers.
+
+Compatible with django-ipc's MessageRouter interface for code generation.
+"""
+
+import logging
+from typing import Dict, Callable, Any
+
+logger = logging.getLogger(__name__)
+
+
+class MessageRouter:
+    """
+    Message router for Centrifugo RPC handlers.
+
+    Provides django-ipc compatible interface for handler registration
+    and discovery by codegen system.
+    """
+
+    def __init__(self):
+        """Initialize message router."""
+        self._handlers: Dict[str, Callable] = {}
+
+    def register(self, method_name: str):
+        """
+        Decorator to register RPC handler.
+
+        Args:
+            method_name: RPC method name (e.g., "tasks.get_stats")
+
+        Returns:
+            Decorator function
+
+        Example:
+            >>> router = MessageRouter()
+            >>>
+            >>> @router.register("tasks.get_stats")
+            >>> async def handle_get_stats(conn, params: TaskStatsParams) -> TaskStatsResult:
+            ...     return TaskStatsResult(total=100, completed=50)
+        """
+        def decorator(handler_func: Callable) -> Callable:
+            if method_name in self._handlers:
+                logger.warning(f"Handler '{method_name}' already registered, overwriting")
+
+            self._handlers[method_name] = handler_func
+            logger.debug(f"Registered handler: {method_name}")
+
+            return handler_func
+
+        return decorator
+
+    def get_handler(self, method_name: str) -> Callable:
+        """
+        Get handler by method name.
+
+        Args:
+            method_name: RPC method name
+
+        Returns:
+            Handler function
+
+        Raises:
+            KeyError: If handler not found
+        """
+        return self._handlers[method_name]
+
+    def has_handler(self, method_name: str) -> bool:
+        """
+        Check if handler exists.
+
+        Args:
+            method_name: RPC method name
+
+        Returns:
+            True if handler registered
+        """
+        return method_name in self._handlers
+
+    def list_methods(self) -> list[str]:
+        """
+        List all registered method names.
+
+        Returns:
+            List of method names
+        """
+        return list(self._handlers.keys())
+
+    async def handle_message(self, method_name: str, params: Any, conn: Any = None) -> Any:
+        """
+        Handle RPC message.
+
+        Args:
+            method_name: RPC method name
+            params: Method parameters
+            conn: Connection object (optional)
+
+        Returns:
+            Handler result
+
+        Raises:
+            KeyError: If handler not found
+        """
+        handler = self.get_handler(method_name)
+
+        # Call handler with or without connection
+        if conn is not None:
+            return await handler(conn, params)
+        else:
+            return await handler(params)
+
+
+# Global router instance
+_global_router = MessageRouter()
+
+
+def get_global_router() -> MessageRouter:
+    """Get global MessageRouter instance."""
+    return _global_router
+
+
+__all__ = [
+    "MessageRouter",
+    "get_global_router",
+]

django_cfg/apps/centrifugo/serializers/__init__.py

@@ -0,0 +1,40 @@
+"""
+Serializers for Centrifugo module.
+"""
+
+from .admin_api import (
+    CentrifugoChannelsRequest,
+    CentrifugoChannelsResponse,
+    CentrifugoHistoryRequest,
+    CentrifugoHistoryResponse,
+    CentrifugoInfoRequest,
+    CentrifugoInfoResponse,
+    CentrifugoPresenceRequest,
+    CentrifugoPresenceResponse,
+    CentrifugoPresenceStatsRequest,
+    CentrifugoPresenceStatsResponse,
+)
+from .channels import ChannelListSerializer, ChannelStatsSerializer
+from .health import HealthCheckSerializer
+from .publishes import RecentPublishesSerializer
+from .stats import OverviewStatsSerializer
+
+__all__ = [
+    # Monitoring API (Django logs)
+    "HealthCheckSerializer",
+    "OverviewStatsSerializer",
+    "RecentPublishesSerializer",
+    "ChannelStatsSerializer",
+    "ChannelListSerializer",
+    # Admin API (Centrifugo server)
+    "CentrifugoInfoRequest",
+    "CentrifugoInfoResponse",
+    "CentrifugoChannelsRequest",
+    "CentrifugoChannelsResponse",
+    "CentrifugoPresenceRequest",
+    "CentrifugoPresenceResponse",
+    "CentrifugoPresenceStatsRequest",
+    "CentrifugoPresenceStatsResponse",
+    "CentrifugoHistoryRequest",
+    "CentrifugoHistoryResponse",
+]