django-cfg 1.4.62__py3-none-any.whl → 1.4.64__py3-none-any.whl

django_cfg/apps/centrifugo/management/commands/generate_centrifugo_clients.py

@@ -0,0 +1,254 @@
+"""Django management command to generate Centrifugo WebSocket RPC clients.
+
+Usage:
+    python manage.py generate_centrifugo_clients --output ./clients --python --typescript --go
+    python manage.py generate_centrifugo_clients -o ./clients --all
+    python manage.py generate_centrifugo_clients -o ./clients --python --verbose
+"""
+
+import logging
+from pathlib import Path
+from typing import List
+
+from django.core.management.base import BaseCommand, CommandError
+from django.utils.termcolors import colorize
+
+from django_cfg.apps.centrifugo.codegen.discovery import discover_rpc_methods_from_router
+from django_cfg.apps.centrifugo.codegen.generators.python_thin import PythonThinGenerator
+from django_cfg.apps.centrifugo.codegen.generators.typescript_thin import TypeScriptThinGenerator
+from django_cfg.apps.centrifugo.codegen.generators.go_thin import GoThinGenerator
+from django_cfg.apps.centrifugo.router import get_global_router
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+    """Generate type-safe client SDKs for Centrifugo WebSocket RPC."""
+
+    help = "Generate type-safe client SDKs for Centrifugo WebSocket RPC from @websocket_rpc handlers"
+
+    def add_arguments(self, parser):
+        """Add command arguments."""
+        parser.add_argument(
+            "-o",
+            "--output",
+            type=str,
+            required=True,
+            help="Output directory for generated clients",
+        )
+        parser.add_argument(
+            "--python",
+            action="store_true",
+            help="Generate Python client",
+        )
+        parser.add_argument(
+            "--typescript",
+            action="store_true",
+            help="Generate TypeScript client",
+        )
+        parser.add_argument(
+            "--go",
+            action="store_true",
+            help="Generate Go client",
+        )
+        parser.add_argument(
+            "--all",
+            action="store_true",
+            help="Generate all clients (Python, TypeScript, Go)",
+        )
+        parser.add_argument(
+            "--router-path",
+            type=str,
+            default=None,
+            help="Python import path to custom MessageRouter (default: uses global router)",
+        )
+        parser.add_argument(
+            "--verbose",
+            action="store_true",
+            help="Verbose output (use Django's -v for verbosity level)",
+        )
+
+    def handle(self, *args, **options):
+        """Execute the command."""
+        output_dir = Path(options["output"]).resolve()
+        verbose = options["verbose"]
+
+        # Configure logging
+        if verbose:
+            logging.basicConfig(level=logging.DEBUG)
+        else:
+            logging.basicConfig(level=logging.INFO)
+
+        # Determine which clients to generate
+        generate_python = options["python"] or options["all"]
+        generate_typescript = options["typescript"] or options["all"]
+        generate_go = options["go"] or options["all"]
+
+        if not (generate_python or generate_typescript or generate_go):
+            raise CommandError(
+                "No client languages specified. Use --python, --typescript, --go, or --all"
+            )
+
+        self.stdout.write(
+            colorize("Centrifugo Client Code Generation", fg="cyan", opts=["bold"])
+        )
+        self.stdout.write("=" * 60)
+
+        # Get the MessageRouter
+        try:
+            if options["router_path"]:
+                router = self._load_custom_router(options["router_path"])
+                self.stdout.write(f"Using custom router: {options['router_path']}")
+            else:
+                router = get_global_router()
+                self.stdout.write("Using global MessageRouter")
+        except Exception as e:
+            raise CommandError(f"Failed to load router: {e}")
+
+        # Discover RPC methods
+        self.stdout.write("\nDiscovering RPC methods...")
+        try:
+            methods = discover_rpc_methods_from_router(router)
+            self.stdout.write(
+                colorize(f"Found {len(methods)} RPC methods", fg="green")
+            )
+
+            if verbose:
+                for method in methods:
+                    param_type = (
+                        method.param_type.__name__ if method.param_type else "None"
+                    )
+                    return_type = (
+                        method.return_type.__name__ if method.return_type else "None"
+                    )
+                    self.stdout.write(
+                        f"  - {method.name}: {param_type} -> {return_type}"
+                    )
+
+        except Exception as e:
+            raise CommandError(f"Failed to discover RPC methods: {e}")
+
+        if not methods:
+            self.stdout.write(
+                colorize(
+                    "No RPC methods found. Did you register handlers with @websocket_rpc?",
+                    fg="yellow",
+                )
+            )
+            return
+
+        # Create output directory
+        output_dir.mkdir(parents=True, exist_ok=True)
+        self.stdout.write(f"\nOutput directory: {output_dir}")
+
+        # Generate clients
+        generated: List[str] = []
+
+        if generate_python:
+            self.stdout.write("\nGenerating Python client...")
+            try:
+                python_dir = output_dir / "python"
+                # Extract all unique models from methods
+                models = set()
+                for method in methods:
+                    if method.param_type:
+                        models.add(method.param_type)
+                    if method.return_type:
+                        models.add(method.return_type)
+
+                generator = PythonThinGenerator(methods, list(models), python_dir)
+                generator.generate()
+                generated.append("Python")
+                self.stdout.write(
+                    colorize(f"  ✓ Generated at: {python_dir}", fg="green")
+                )
+            except Exception as e:
+                self.stdout.write(colorize(f"  ✗ Failed: {e}", fg="red"))
+                if verbose:
+                    logger.exception("Python generation failed")
+
+        if generate_typescript:
+            self.stdout.write("\nGenerating TypeScript client...")
+            try:
+                ts_dir = output_dir / "typescript"
+                # Extract all unique models from methods
+                models = set()
+                for method in methods:
+                    if method.param_type:
+                        models.add(method.param_type)
+                    if method.return_type:
+                        models.add(method.return_type)
+
+                generator = TypeScriptThinGenerator(methods, list(models), ts_dir)
+                generator.generate()
+                generated.append("TypeScript")
+                self.stdout.write(colorize(f"  ✓ Generated at: {ts_dir}", fg="green"))
+            except Exception as e:
+                self.stdout.write(colorize(f"  ✗ Failed: {e}", fg="red"))
+                if verbose:
+                    logger.exception("TypeScript generation failed")
+
+        if generate_go:
+            self.stdout.write("\nGenerating Go client...")
+            try:
+                go_dir = output_dir / "go"
+                # Extract all unique models from methods
+                models = set()
+                for method in methods:
+                    if method.param_type:
+                        models.add(method.param_type)
+                    if method.return_type:
+                        models.add(method.return_type)
+
+                generator = GoThinGenerator(methods, list(models), go_dir)
+                generator.generate()
+                generated.append("Go")
+                self.stdout.write(colorize(f"  ✓ Generated at: {go_dir}", fg="green"))
+            except Exception as e:
+                self.stdout.write(colorize(f"  ✗ Failed: {e}", fg="red"))
+                if verbose:
+                    logger.exception("Go generation failed")
+
+        # Summary
+        self.stdout.write("\n" + "=" * 60)
+        if generated:
+            self.stdout.write(
+                colorize(
+                    f"Successfully generated {len(generated)} client(s): {', '.join(generated)}",
+                    fg="green",
+                    opts=["bold"],
+                )
+            )
+            self.stdout.write("\nNext steps:")
+            if "Python" in generated:
+                self.stdout.write(f"  cd {output_dir}/python && pip install -r requirements.txt")
+            if "TypeScript" in generated:
+                self.stdout.write(f"  cd {output_dir}/typescript && npm install")
+            if "Go" in generated:
+                self.stdout.write(f"  cd {output_dir}/go && go mod tidy")
+        else:
+            self.stdout.write(
+                colorize("No clients were generated", fg="red", opts=["bold"])
+            )
+
+    def _load_custom_router(self, router_path: str):
+        """Load a custom MessageRouter from a Python import path.
+
+        Args:
+            router_path: Python import path like 'myapp.routers.my_router'
+
+        Returns:
+            MessageRouter instance
+
+        Raises:
+            CommandError: If router cannot be loaded
+        """
+        try:
+            from importlib import import_module
+
+            module_path, attr_name = router_path.rsplit(".", 1)
+            module = import_module(module_path)
+            router = getattr(module, attr_name)
+            return router
+        except (ValueError, ImportError, AttributeError) as e:
+            raise CommandError(f"Failed to import router from '{router_path}': {e}")

django_cfg/apps/centrifugo/managers/__init__.py

@@ -0,0 +1,12 @@
+"""
+Centrifugo Managers.
+
+Custom QuerySets and Managers for Centrifugo models.
+"""
+
+from .centrifugo_log import CentrifugoLogManager, CentrifugoLogQuerySet
+
+__all__ = [
+    "CentrifugoLogManager",
+    "CentrifugoLogQuerySet",
+]

django_cfg/apps/centrifugo/managers/centrifugo_log.py

@@ -0,0 +1,264 @@
+"""
+CentrifugoLog Manager.
+
+Custom QuerySet and Manager for CentrifugoLog model.
+"""
+
+from django.db import models
+from django.utils import timezone
+
+
+class CentrifugoLogQuerySet(models.QuerySet):
+    """Custom QuerySet for CentrifugoLog with filtering helpers."""
+
+    def pending(self):
+        """Get all pending logs."""
+        return self.filter(status="pending")
+
+    def successful(self):
+        """Get all successful logs."""
+        return self.filter(status="success")
+
+    def failed(self):
+        """Get all failed logs."""
+        return self.filter(status="failed")
+
+    def timeout(self):
+        """Get all timeout logs."""
+        return self.filter(status="timeout")
+
+    def with_ack(self):
+        """Get logs that waited for ACK."""
+        return self.filter(wait_for_ack=True)
+
+    def for_channel(self, channel: str):
+        """Get logs for specific channel."""
+        return self.filter(channel=channel)
+
+    def for_user(self, user):
+        """Get logs for specific user."""
+        return self.filter(user=user)
+
+    def recent(self, hours: int = 24):
+        """Get logs from recent hours."""
+        cutoff = timezone.now() - timezone.timedelta(hours=hours)
+        return self.filter(created_at__gte=cutoff)
+
+    def completed(self):
+        """Get all completed logs (success, failed, timeout, partial)."""
+        return self.exclude(status="pending")
+
+    def by_performance(self):
+        """Order by duration (fastest first)."""
+        return self.filter(duration_ms__isnull=False).order_by("duration_ms")
+
+
+class CentrifugoLogManager(models.Manager):
+    """Custom Manager for CentrifugoLog."""
+
+    def get_queryset(self):
+        """Return custom QuerySet."""
+        return CentrifugoLogQuerySet(self.model, using=self._db)
+
+    def pending(self):
+        """Get pending logs."""
+        return self.get_queryset().pending()
+
+    def successful(self):
+        """Get successful logs."""
+        return self.get_queryset().successful()
+
+    def failed(self):
+        """Get failed logs."""
+        return self.get_queryset().failed()
+
+    def timeout(self):
+        """Get timeout logs."""
+        return self.get_queryset().timeout()
+
+    def with_ack(self):
+        """Get logs with ACK tracking."""
+        return self.get_queryset().with_ack()
+
+    def for_channel(self, channel: str):
+        """Get logs for channel."""
+        return self.get_queryset().for_channel(channel)
+
+    def for_user(self, user):
+        """Get logs for user."""
+        return self.get_queryset().for_user(user)
+
+    def recent(self, hours: int = 24):
+        """Get recent logs."""
+        return self.get_queryset().recent(hours)
+
+    def get_statistics(self, hours: int = 24):
+        """
+        Get publish statistics for recent period.
+
+        Args:
+            hours: Number of hours to analyze
+
+        Returns:
+            Dictionary with statistics
+        """
+        # Get all recent logs (not just with_ack) to include fire-and-forget publishes
+        recent_logs = self.recent(hours)
+
+        total = recent_logs.count()
+        successful = recent_logs.successful().count()
+        failed = recent_logs.failed().count()
+        timeout_count = recent_logs.timeout().count()
+
+        success_rate = (successful / total * 100) if total > 0 else 0
+
+        avg_duration = recent_logs.filter(
+            duration_ms__isnull=False
+        ).aggregate(
+            models.Avg("duration_ms")
+        )["duration_ms__avg"] or 0
+
+        avg_acks = recent_logs.aggregate(
+            models.Avg("acks_received")
+        )["acks_received__avg"] or 0
+
+        return {
+            "total": total,
+            "successful": successful,
+            "failed": failed,
+            "timeout": timeout_count,
+            "success_rate": round(success_rate, 2),
+            "avg_duration_ms": round(avg_duration, 2),
+            "avg_acks_received": round(avg_acks, 2),
+        }
+
+    def mark_success(self, log_instance, acks_received: int = 0, duration_ms: int | None = None):
+        """
+        Mark publish as successful.
+
+        Args:
+            log_instance: CentrifugoLog instance
+            acks_received: Number of ACKs received
+            duration_ms: Duration in milliseconds
+        """
+        from ..models import CentrifugoLog
+
+        log_instance.status = CentrifugoLog.StatusChoices.SUCCESS
+        log_instance.acks_received = acks_received
+        log_instance.completed_at = timezone.now()
+
+        if duration_ms is not None:
+            log_instance.duration_ms = duration_ms
+
+        log_instance.save(update_fields=["status", "acks_received", "completed_at", "duration_ms"])
+
+    def mark_partial(
+        self,
+        log_instance,
+        acks_received: int,
+        acks_expected: int,
+        duration_ms: int | None = None,
+    ):
+        """
+        Mark publish as partially delivered.
+
+        Args:
+            log_instance: CentrifugoLog instance
+            acks_received: Number of ACKs received
+            acks_expected: Number of ACKs expected
+            duration_ms: Duration in milliseconds
+        """
+        from ..models import CentrifugoLog
+
+        log_instance.status = CentrifugoLog.StatusChoices.PARTIAL
+        log_instance.acks_received = acks_received
+        log_instance.acks_expected = acks_expected
+        log_instance.completed_at = timezone.now()
+
+        if duration_ms is not None:
+            log_instance.duration_ms = duration_ms
+
+        log_instance.save(
+            update_fields=[
+                "status",
+                "acks_received",
+                "acks_expected",
+                "completed_at",
+                "duration_ms",
+            ]
+        )
+
+    def mark_failed(
+        self,
+        log_instance,
+        error_code: str,
+        error_message: str,
+        duration_ms: int | None = None,
+    ):
+        """
+        Mark publish as failed.
+
+        Args:
+            log_instance: CentrifugoLog instance
+            error_code: Error code
+            error_message: Error message
+            duration_ms: Duration in milliseconds
+        """
+        from ..models import CentrifugoLog
+
+        log_instance.status = CentrifugoLog.StatusChoices.FAILED
+        log_instance.error_code = error_code
+        log_instance.error_message = error_message
+        log_instance.completed_at = timezone.now()
+
+        if duration_ms is not None:
+            log_instance.duration_ms = duration_ms
+
+        log_instance.save(
+            update_fields=[
+                "status",
+                "error_code",
+                "error_message",
+                "completed_at",
+                "duration_ms",
+            ]
+        )
+
+    def mark_timeout(
+        self,
+        log_instance,
+        acks_received: int = 0,
+        duration_ms: int | None = None,
+    ):
+        """
+        Mark publish as timed out.
+
+        Args:
+            log_instance: CentrifugoLog instance
+            acks_received: Number of ACKs received before timeout
+            duration_ms: Duration in milliseconds
+        """
+        from ..models import CentrifugoLog
+
+        log_instance.status = CentrifugoLog.StatusChoices.TIMEOUT
+        log_instance.acks_received = acks_received
+        log_instance.error_code = "timeout"
+        log_instance.error_message = f"Timeout after {log_instance.ack_timeout}s"
+        log_instance.completed_at = timezone.now()
+
+        if duration_ms is not None:
+            log_instance.duration_ms = duration_ms
+
+        log_instance.save(
+            update_fields=[
+                "status",
+                "acks_received",
+                "error_code",
+                "error_message",
+                "completed_at",
+                "duration_ms",
+            ]
+        )
+
+
+__all__ = ["CentrifugoLogManager", "CentrifugoLogQuerySet"]

django_cfg/apps/centrifugo/migrations/0001_initial.py

@@ -0,0 +1,164 @@
+# Generated by Django 5.2.7 on 2025-10-24 12:55
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="CentrifugoLog",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+                    ),
+                ),
+                (
+                    "message_id",
+                    models.CharField(
+                        db_index=True,
+                        help_text="Unique message identifier (UUID)",
+                        max_length=100,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "channel",
+                    models.CharField(
+                        db_index=True,
+                        help_text="Centrifugo channel (e.g., user#123, broadcast)",
+                        max_length=200,
+                    ),
+                ),
+                ("data", models.JSONField(help_text="Published data (JSON payload)")),
+                (
+                    "wait_for_ack",
+                    models.BooleanField(
+                        db_index=True,
+                        default=False,
+                        help_text="Whether this publish waited for ACK",
+                    ),
+                ),
+                (
+                    "ack_timeout",
+                    models.IntegerField(blank=True, help_text="ACK timeout in seconds", null=True),
+                ),
+                (
+                    "acks_received",
+                    models.IntegerField(default=0, help_text="Number of ACKs received"),
+                ),
+                (
+                    "acks_expected",
+                    models.IntegerField(
+                        blank=True, help_text="Number of ACKs expected (if known)", null=True
+                    ),
+                ),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("pending", "Pending"),
+                            ("success", "Success"),
+                            ("failed", "Failed"),
+                            ("timeout", "Timeout"),
+                            ("partial", "Partial Delivery"),
+                        ],
+                        db_index=True,
+                        default="pending",
+                        help_text="Current status of publish operation",
+                        max_length=20,
+                    ),
+                ),
+                (
+                    "error_code",
+                    models.CharField(
+                        blank=True, help_text="Error code if failed", max_length=100, null=True
+                    ),
+                ),
+                (
+                    "error_message",
+                    models.TextField(blank=True, help_text="Error message if failed", null=True),
+                ),
+                (
+                    "duration_ms",
+                    models.IntegerField(
+                        blank=True, help_text="Total duration in milliseconds", null=True
+                    ),
+                ),
+                (
+                    "is_notification",
+                    models.BooleanField(
+                        db_index=True,
+                        default=True,
+                        help_text="Whether this is a notification (vs other pub type)",
+                    ),
+                ),
+                (
+                    "caller_ip",
+                    models.GenericIPAddressField(
+                        blank=True, help_text="IP address of caller", null=True
+                    ),
+                ),
+                (
+                    "user_agent",
+                    models.TextField(blank=True, help_text="User agent of caller", null=True),
+                ),
+                (
+                    "created_at",
+                    models.DateTimeField(
+                        auto_now_add=True, db_index=True, help_text="When publish was initiated"
+                    ),
+                ),
+                (
+                    "completed_at",
+                    models.DateTimeField(
+                        blank=True,
+                        db_index=True,
+                        help_text="When publish completed (success/failure/timeout)",
+                        null=True,
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        blank=True,
+                        help_text="User who triggered the publish (if applicable)",
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="centrifugo_logs",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Centrifugo Log",
+                "verbose_name_plural": "Centrifugo Logs",
+                "db_table": "django_cfg_centrifugo_log",
+                "ordering": ["-created_at"],
+                "indexes": [
+                    models.Index(
+                        fields=["channel", "-created_at"], name="django_cfg__channel_ee539b_idx"
+                    ),
+                    models.Index(
+                        fields=["status", "-created_at"], name="django_cfg__status_73b0b0_idx"
+                    ),
+                    models.Index(
+                        fields=["wait_for_ack", "status"], name="django_cfg__wait_fo_59bb80_idx"
+                    ),
+                    models.Index(
+                        fields=["user", "-created_at"], name="django_cfg__user_id_5e0c7d_idx"
+                    ),
+                ],
+            },
+        ),
+    ]

django_cfg/apps/centrifugo/migrations/__init__.py

@@ -0,0 +1,3 @@
+"""
+Centrifugo Migrations.
+"""