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

django_cfg/apps/integrations/grpc/models/grpc_server_status.py

@@ -0,0 +1,305 @@
+"""
+gRPC Server Status Model.
+
+Tracks the lifecycle and status of gRPC server instances.
+Provides real-time monitoring of server availability and uptime.
+"""
+
+import os
+from datetime import datetime, timedelta
+
+from django.db import models
+from django.utils import timezone
+
+
+class GRPCServerStatus(models.Model):
+    """
+    Track gRPC server status and lifecycle.
+
+    Stores information about server instances including:
+    - Start/stop times
+    - Process ID
+    - Server address and configuration
+    - Health status and heartbeats
+
+    Example:
+        >>> # Server starts
+        >>> status = GRPCServerStatus.objects.start_server(
+        ...     host="[::]",
+        ...     port=50051,
+        ...     pid=12345
+        ... )
+        >>> status.is_running
+        True
+        >>> status.uptime_seconds
+        120
+
+        >>> # Server stops
+        >>> status.stop_server()
+        >>> status.is_running
+        False
+    """
+
+    # Custom manager
+    from ..managers.grpc_server_status import GRPCServerStatusManager
+
+    objects: GRPCServerStatusManager = GRPCServerStatusManager()
+
+    class StatusChoices(models.TextChoices):
+        """Server status choices."""
+
+        STARTING = "starting", "Starting"
+        RUNNING = "running", "Running"
+        STOPPING = "stopping", "Stopping"
+        STOPPED = "stopped", "Stopped"
+        ERROR = "error", "Error"
+
+    # Identity
+    instance_id = models.CharField(
+        max_length=100,
+        unique=True,
+        db_index=True,
+        help_text="Unique instance identifier (hostname:port:pid)",
+    )
+
+    # Server configuration
+    host = models.CharField(
+        max_length=200,
+        help_text="Server host address",
+    )
+
+    port = models.IntegerField(
+        help_text="Server port",
+    )
+
+    address = models.CharField(
+        max_length=200,
+        db_index=True,
+        help_text="Full server address (host:port)",
+    )
+
+    # Process information
+    pid = models.IntegerField(
+        help_text="Process ID of gRPC server",
+    )
+
+    hostname = models.CharField(
+        max_length=255,
+        help_text="Server hostname",
+    )
+
+    # Status tracking
+    status = models.CharField(
+        max_length=20,
+        choices=StatusChoices.choices,
+        default=StatusChoices.STARTING,
+        db_index=True,
+        help_text="Current server status",
+    )
+
+    # Lifecycle timestamps
+    started_at = models.DateTimeField(
+        auto_now_add=True,
+        db_index=True,
+        help_text="When server started",
+    )
+
+    last_heartbeat = models.DateTimeField(
+        auto_now=True,
+        db_index=True,
+        help_text="Last heartbeat timestamp",
+    )
+
+    stopped_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When server stopped",
+    )
+
+    # Configuration snapshot
+    max_workers = models.IntegerField(
+        default=10,
+        help_text="Maximum worker threads",
+    )
+
+    enable_reflection = models.BooleanField(
+        default=False,
+        help_text="Whether reflection is enabled",
+    )
+
+    # Registered services (stored as JSON)
+    registered_services = models.JSONField(
+        default=list,
+        blank=True,
+        help_text="List of registered service metadata (name, methods, etc.)",
+    )
+
+    enable_health_check = models.BooleanField(
+        default=True,
+        help_text="Whether health check is enabled",
+    )
+
+    # Error tracking
+    error_message = models.TextField(
+        null=True,
+        blank=True,
+        help_text="Error message if status is ERROR",
+    )
+
+    # Metadata
+    created_at = models.DateTimeField(
+        auto_now_add=True,
+        help_text="Record creation time",
+    )
+
+    updated_at = models.DateTimeField(
+        auto_now=True,
+        help_text="Record last update time",
+    )
+
+    class Meta:
+        db_table = "django_cfg_grpc_server_status"
+        ordering = ["-started_at"]
+        indexes = [
+            models.Index(fields=["status", "-started_at"]),
+            models.Index(fields=["address", "-started_at"]),
+            models.Index(fields=["pid", "-started_at"]),
+        ]
+        verbose_name = "gRPC Server Status"
+        verbose_name_plural = "gRPC Server Statuses"
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"gRPC Server {self.address} ({self.status}) - PID {self.pid}"
+
+    @property
+    def is_running(self) -> bool:
+        """
+        Check if server is currently running.
+
+        Uses environment-aware detection:
+        - Production: Assumes external server (Docker), relies on heartbeat only
+        - Development/Test: Checks local process + heartbeat
+        """
+        if self.status not in [self.StatusChoices.RUNNING, self.StatusChoices.STARTING]:
+            return False
+
+        # Check if process is still alive (auto-detects external servers)
+        if not self._is_process_alive():
+            return False
+
+        # Check heartbeat (consider dead if no heartbeat in 5 minutes)
+        if self.last_heartbeat:
+            time_since_heartbeat = timezone.now() - self.last_heartbeat
+            if time_since_heartbeat > timedelta(minutes=5):
+                return False
+
+        return True
+
+    @property
+    def uptime_seconds(self) -> int:
+        """Calculate server uptime in seconds."""
+        if not self.is_running or not self.started_at:
+            return 0
+
+        if self.stopped_at:
+            delta = self.stopped_at - self.started_at
+        else:
+            delta = timezone.now() - self.started_at
+
+        return int(delta.total_seconds())
+
+    @property
+    def uptime_display(self) -> str:
+        """Human-readable uptime."""
+        seconds = self.uptime_seconds
+        if seconds == 0:
+            return "Not running"
+
+        days, remainder = divmod(seconds, 86400)
+        hours, remainder = divmod(remainder, 3600)
+        minutes, seconds = divmod(remainder, 60)
+
+        parts = []
+        if days > 0:
+            parts.append(f"{days}d")
+        if hours > 0:
+            parts.append(f"{hours}h")
+        if minutes > 0:
+            parts.append(f"{minutes}m")
+        if seconds > 0 or not parts:
+            parts.append(f"{seconds}s")
+
+        return " ".join(parts)
+
+    def _is_process_alive(self) -> bool:
+        """
+        Check if the process is still running.
+
+        Uses environment-aware detection:
+        - Production mode: Skip PID check (assumes external server in Docker)
+        - Development/Test: Check PID with graceful fallback for containers
+        """
+        try:
+            from django_cfg.core import get_current_config
+
+            # Auto-detect based on env_mode
+            config = get_current_config()
+            if config and str(config.env_mode) == "production":
+                # Production = external server in separate container
+                # Don't check PID, rely on heartbeat only
+                return True
+
+        except Exception:
+            # Config not available, use fallback logic
+            pass
+
+        # Development/Test or fallback: check PID with graceful handling
+        try:
+            # Send signal 0 to check if process exists
+            os.kill(self.pid, 0)
+            return True
+        except ProcessLookupError:
+            # PID not found - could be different namespace (Docker)
+            # Don't mark as dead immediately, rely on heartbeat
+            return True
+        except PermissionError:
+            # Process exists but no permission to signal
+            return True
+        except OSError:
+            # Other OS error (e.g., process died)
+            return False
+
+    def mark_running(self):
+        """Mark server as running."""
+        self.status = self.StatusChoices.RUNNING
+        self.error_message = None
+        self.save(update_fields=["status", "error_message", "updated_at", "last_heartbeat"])
+
+    def mark_stopping(self):
+        """Mark server as stopping."""
+        self.status = self.StatusChoices.STOPPING
+        self.save(update_fields=["status", "updated_at", "last_heartbeat"])
+
+    def mark_stopped(self, error_message: str = None):
+        """Mark server as stopped."""
+        self.status = self.StatusChoices.STOPPED
+        self.stopped_at = timezone.now()
+        if error_message:
+            self.error_message = error_message
+        self.save(update_fields=["status", "stopped_at", "error_message", "updated_at"])
+
+    def mark_error(self, error_message: str):
+        """Mark server as error."""
+        self.status = self.StatusChoices.ERROR
+        self.error_message = error_message
+        self.stopped_at = timezone.now()
+        self.save(update_fields=["status", "error_message", "stopped_at", "updated_at"])
+
+    def heartbeat(self):
+        """Update heartbeat timestamp."""
+        self.last_heartbeat = timezone.now()
+        self.save(update_fields=["last_heartbeat", "updated_at"])
+
+
+__all__ = ["GRPCServerStatus"]

django_cfg/apps/integrations/grpc/serializers/__init__.py

@@ -0,0 +1,83 @@
+"""
+Pydantic serializers for gRPC monitoring API.
+"""
+
+from .api_keys import (
+    ApiKeyListSerializer,
+    ApiKeySerializer,
+    ApiKeyStatsSerializer,
+)
+from .proto_files import (
+    ProtoFileDetailSerializer,
+    ProtoFileListSerializer,
+    ProtoGenerateRequestSerializer,
+    ProtoGenerateResponseSerializer,
+)
+from .charts import (
+    DashboardChartsSerializer,
+    ErrorDistributionChartSerializer,
+    RequestVolumeChartSerializer,
+    ResponseTimeChartSerializer,
+    ServerLifecycleChartSerializer,
+    ServerUptimeChartSerializer,
+    ServiceActivityChartSerializer,
+)
+from .config import GRPCConfigSerializer, GRPCServerInfoSerializer
+from .health import GRPCHealthCheckSerializer
+from .requests import RecentRequestsSerializer
+from .service_registry import (
+    MethodDetailSerializer,
+    ServiceDetailSerializer,
+    ServiceListSerializer,
+    ServiceMethodsSerializer,
+)
+from .services import (
+    MethodListSerializer,
+    MethodStatsSerializer,
+)
+from .stats import GRPCOverviewStatsSerializer
+from .testing import (
+    GRPCCallRequestSerializer,
+    GRPCCallResponseSerializer,
+    GRPCExamplesListSerializer,
+    GRPCTestLogsSerializer,
+)
+
+__all__ = [
+    # Health & Stats
+    "GRPCHealthCheckSerializer",
+    "GRPCOverviewStatsSerializer",
+    "RecentRequestsSerializer",
+    "MethodStatsSerializer",
+    "MethodListSerializer",
+    # Config
+    "GRPCConfigSerializer",
+    "GRPCServerInfoSerializer",
+    # Service Registry
+    "ServiceListSerializer",
+    "ServiceDetailSerializer",
+    "ServiceMethodsSerializer",
+    "MethodDetailSerializer",
+    # Testing
+    "GRPCExamplesListSerializer",
+    "GRPCTestLogsSerializer",
+    "GRPCCallRequestSerializer",
+    "GRPCCallResponseSerializer",
+    # Charts
+    "ServerUptimeChartSerializer",
+    "RequestVolumeChartSerializer",
+    "ResponseTimeChartSerializer",
+    "ServiceActivityChartSerializer",
+    "ServerLifecycleChartSerializer",
+    "ErrorDistributionChartSerializer",
+    "DashboardChartsSerializer",
+    # API Keys
+    "ApiKeySerializer",
+    "ApiKeyListSerializer",
+    "ApiKeyStatsSerializer",
+    # Proto Files
+    "ProtoFileDetailSerializer",
+    "ProtoFileListSerializer",
+    "ProtoGenerateRequestSerializer",
+    "ProtoGenerateResponseSerializer",
+]

django_cfg/apps/integrations/grpc/serializers/api_keys.py

@@ -0,0 +1,63 @@
+"""
+DRF serializers for gRPC API Keys.
+
+Read-only serializers for listing and viewing API keys.
+Create/Update/Delete operations handled through Django Admin.
+"""
+
+from rest_framework import serializers
+
+
+class ApiKeySerializer(serializers.Serializer):
+    """API Key information (read-only)."""
+
+    id = serializers.IntegerField(help_text="Database ID")
+    name = serializers.CharField(help_text="Key name/description")
+    key_type = serializers.CharField(help_text="Type of API key")
+    masked_key = serializers.CharField(help_text="Masked API key (first 4 and last 4 chars)")
+    is_active = serializers.BooleanField(help_text="Whether key is active")
+    is_valid = serializers.BooleanField(help_text="Whether key is valid (active and not expired)")
+    user_id = serializers.IntegerField(help_text="User ID")
+    username = serializers.CharField(help_text="Username")
+    user_email = serializers.CharField(help_text="User email", allow_blank=True)
+    request_count = serializers.IntegerField(help_text="Total requests made with this key")
+    last_used_at = serializers.DateTimeField(
+        allow_null=True,
+        help_text="When key was last used"
+    )
+    expires_at = serializers.DateTimeField(
+        allow_null=True,
+        help_text="When key expires (null = never)"
+    )
+    created_at = serializers.DateTimeField(help_text="When key was created")
+    created_by = serializers.CharField(
+        allow_null=True,
+        help_text="User who created this key"
+    )
+
+
+class ApiKeyListSerializer(serializers.Serializer):
+    """List of API keys response."""
+
+    results = ApiKeySerializer(many=True, help_text="List of API keys")
+    count = serializers.IntegerField(help_text="Total number of API keys")
+
+
+class ApiKeyStatsSerializer(serializers.Serializer):
+    """API Key usage statistics."""
+
+    total_keys = serializers.IntegerField(help_text="Total API keys")
+    active_keys = serializers.IntegerField(help_text="Active API keys")
+    expired_keys = serializers.IntegerField(help_text="Expired API keys")
+    total_requests = serializers.IntegerField(help_text="Total requests across all keys")
+    keys_by_type = serializers.DictField(
+        child=serializers.IntegerField(),
+        help_text="Count of keys by type"
+    )
+
+
+__all__ = [
+    "ApiKeySerializer",
+    "ApiKeyListSerializer",
+    "ApiKeyStatsSerializer",
+]

django_cfg/apps/integrations/grpc/serializers/charts.py

@@ -0,0 +1,216 @@
+"""
+DRF serializers for gRPC charts and statistics data.
+
+These serializers define the structure for chart endpoints
+that provide time-series data for visualization.
+"""
+
+from rest_framework import serializers
+
+
+class TimeSeriesDataPoint(serializers.Serializer):
+    """Single data point in time series."""
+
+    timestamp = serializers.CharField(help_text="ISO timestamp")
+    value = serializers.FloatField(help_text="Value at this timestamp")
+    label = serializers.CharField(
+        required=False, allow_null=True, help_text="Optional label for this point"
+    )
+
+
+class ServerUptimeDataPoint(serializers.Serializer):
+    """Server uptime data point."""
+
+    timestamp = serializers.CharField(help_text="ISO timestamp")
+    server_count = serializers.IntegerField(help_text="Number of running servers")
+    servers = serializers.ListField(
+        child=serializers.CharField(), default=list, help_text="List of server addresses"
+    )
+
+
+class RequestVolumeDataPoint(serializers.Serializer):
+    """Request volume data point."""
+
+    timestamp = serializers.CharField(help_text="ISO timestamp")
+    total_requests = serializers.IntegerField(help_text="Total requests in period")
+    successful_requests = serializers.IntegerField(help_text="Successful requests")
+    failed_requests = serializers.IntegerField(help_text="Failed requests")
+    success_rate = serializers.FloatField(help_text="Success rate percentage")
+
+
+class ResponseTimeDataPoint(serializers.Serializer):
+    """Response time statistics data point."""
+
+    timestamp = serializers.CharField(help_text="ISO timestamp")
+    avg_duration_ms = serializers.FloatField(help_text="Average duration")
+    p50_duration_ms = serializers.FloatField(help_text="P50 percentile")
+    p95_duration_ms = serializers.FloatField(help_text="P95 percentile")
+    p99_duration_ms = serializers.FloatField(help_text="P99 percentile")
+    min_duration_ms = serializers.FloatField(help_text="Minimum duration")
+    max_duration_ms = serializers.FloatField(help_text="Maximum duration")
+
+
+class ServiceActivityDataPoint(serializers.Serializer):
+    """Service activity data point."""
+
+    service_name = serializers.CharField(help_text="Service name")
+    request_count = serializers.IntegerField(help_text="Number of requests")
+    success_rate = serializers.FloatField(help_text="Success rate percentage")
+    avg_duration_ms = serializers.FloatField(help_text="Average duration")
+
+
+class ServerLifecycleEvent(serializers.Serializer):
+    """Server lifecycle event."""
+
+    timestamp = serializers.CharField(help_text="Event timestamp")
+    event_type = serializers.CharField(
+        help_text="Event type (started, stopped, error)"
+    )
+    server_address = serializers.CharField(help_text="Server address")
+    server_pid = serializers.IntegerField(help_text="Server process ID")
+    uptime_seconds = serializers.IntegerField(
+        required=False,
+        allow_null=True,
+        help_text="Uptime at event time (for stop events)",
+    )
+    error_message = serializers.CharField(
+        required=False, allow_null=True, help_text="Error message if applicable"
+    )
+
+
+class TimeSeriesChartData(serializers.Serializer):
+    """Generic time series chart data."""
+
+    title = serializers.CharField(help_text="Chart title")
+    series_name = serializers.CharField(help_text="Series name")
+    data_points = TimeSeriesDataPoint(many=True, default=list, help_text="Data points")
+    period_hours = serializers.IntegerField(help_text="Period in hours")
+    granularity = serializers.CharField(help_text="Data granularity (hour, day, week)")
+
+
+class ServerUptimeChartSerializer(serializers.Serializer):
+    """Server uptime over time chart data."""
+
+    title = serializers.CharField(default="Server Uptime", help_text="Chart title")
+    data_points = ServerUptimeDataPoint(
+        many=True, default=list, help_text="Uptime data points"
+    )
+    period_hours = serializers.IntegerField(help_text="Period in hours")
+    granularity = serializers.CharField(help_text="Data granularity")
+    total_servers = serializers.IntegerField(
+        help_text="Total unique servers in period"
+    )
+    currently_running = serializers.IntegerField(help_text="Currently running servers")
+
+
+class RequestVolumeChartSerializer(serializers.Serializer):
+    """Request volume over time chart data."""
+
+    title = serializers.CharField(default="Request Volume", help_text="Chart title")
+    data_points = RequestVolumeDataPoint(
+        many=True, default=list, help_text="Volume data points"
+    )
+    period_hours = serializers.IntegerField(help_text="Period in hours")
+    granularity = serializers.CharField(help_text="Data granularity")
+    total_requests = serializers.IntegerField(help_text="Total requests in period")
+    avg_success_rate = serializers.FloatField(help_text="Average success rate")
+
+
+class ResponseTimeChartSerializer(serializers.Serializer):
+    """Response time over time chart data."""
+
+    title = serializers.CharField(default="Response Time", help_text="Chart title")
+    data_points = ResponseTimeDataPoint(
+        many=True, default=list, help_text="Response time data points"
+    )
+    period_hours = serializers.IntegerField(help_text="Period in hours")
+    granularity = serializers.CharField(help_text="Data granularity")
+    overall_avg_ms = serializers.FloatField(help_text="Overall average duration")
+    overall_p95_ms = serializers.FloatField(help_text="Overall P95 duration")
+
+
+class ServiceActivityChartSerializer(serializers.Serializer):
+    """Service activity comparison chart data."""
+
+    title = serializers.CharField(default="Service Activity", help_text="Chart title")
+    services = ServiceActivityDataPoint(
+        many=True, default=list, help_text="Service activity data"
+    )
+    period_hours = serializers.IntegerField(help_text="Period in hours")
+    total_services = serializers.IntegerField(help_text="Total number of services")
+    most_active_service = serializers.CharField(
+        required=False, allow_null=True, help_text="Most active service name"
+    )
+
+
+class ServerLifecycleChartSerializer(serializers.Serializer):
+    """Server lifecycle events timeline."""
+
+    title = serializers.CharField(default="Server Lifecycle", help_text="Chart title")
+    events = ServerLifecycleEvent(
+        many=True, default=list, help_text="Lifecycle events"
+    )
+    period_hours = serializers.IntegerField(help_text="Period in hours")
+    total_events = serializers.IntegerField(help_text="Total number of events")
+    restart_count = serializers.IntegerField(help_text="Number of server restarts")
+    error_count = serializers.IntegerField(help_text="Number of error events")
+
+
+class ErrorDistributionDataPoint(serializers.Serializer):
+    """Error distribution data point."""
+
+    error_code = serializers.CharField(help_text="gRPC status code")
+    count = serializers.IntegerField(help_text="Number of occurrences")
+    percentage = serializers.FloatField(help_text="Percentage of total errors")
+    service_name = serializers.CharField(
+        required=False, allow_null=True, help_text="Service name if filtered"
+    )
+
+
+class ErrorDistributionChartSerializer(serializers.Serializer):
+    """Error distribution chart data."""
+
+    title = serializers.CharField(default="Error Distribution", help_text="Chart title")
+    error_types = ErrorDistributionDataPoint(
+        many=True, default=list, help_text="Error distribution data"
+    )
+    period_hours = serializers.IntegerField(help_text="Period in hours")
+    total_errors = serializers.IntegerField(help_text="Total number of errors")
+    most_common_error = serializers.CharField(
+        required=False, allow_null=True, help_text="Most common error code"
+    )
+
+
+class DashboardChartsSerializer(serializers.Serializer):
+    """Combined dashboard charts data."""
+
+    server_uptime = ServerUptimeChartSerializer(help_text="Server uptime chart")
+    request_volume = RequestVolumeChartSerializer(help_text="Request volume chart")
+    response_time = ResponseTimeChartSerializer(help_text="Response time chart")
+    service_activity = ServiceActivityChartSerializer(help_text="Service activity chart")
+    error_distribution = ErrorDistributionChartSerializer(
+        help_text="Error distribution chart"
+    )
+    period_hours = serializers.IntegerField(
+        help_text="Period in hours for all charts"
+    )
+    generated_at = serializers.CharField(help_text="When data was generated")
+
+
+__all__ = [
+    "TimeSeriesDataPoint",
+    "ServerUptimeDataPoint",
+    "RequestVolumeDataPoint",
+    "ResponseTimeDataPoint",
+    "ServiceActivityDataPoint",
+    "ServerLifecycleEvent",
+    "TimeSeriesChartData",
+    "ServerUptimeChartSerializer",
+    "RequestVolumeChartSerializer",
+    "ResponseTimeChartSerializer",
+    "ServiceActivityChartSerializer",
+    "ServerLifecycleChartSerializer",
+    "ErrorDistributionDataPoint",
+    "ErrorDistributionChartSerializer",
+    "DashboardChartsSerializer",
+]