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

django_cfg/apps/integrations/grpc/utils/handlers.py

@@ -0,0 +1,242 @@
+"""
+gRPC handler factory utilities.
+
+This module provides utilities for creating and registering gRPC servicers
+with proper error handling and logging.
+
+**Purpose**:
+Simplify the boilerplate code needed to register gRPC services with servers.
+
+**Usage Example**:
+```python
+from django_cfg.apps.integrations.grpc.utils.handlers import create_grpc_handler
+
+# Your servicer class
+class BotStreamingService(pb2_grpc.BotStreamingServiceServicer):
+    pass
+
+# Create handler tuple
+handlers = create_grpc_handler(
+    servicer_class=BotStreamingService,
+    add_servicer_func=pb2_grpc.add_BotStreamingServiceServicer_to_server,
+)
+
+# Use with django-cfg
+GRPC_HANDLERS = [handlers]
+```
+
+Created: 2025-11-07
+Status: %%PRODUCTION%%
+Phase: Phase 1 - Universal Components
+"""
+
+from typing import Callable, Tuple, Any, Optional, Type
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Handler Factory
+# ============================================================================
+
+def create_grpc_handler(
+    servicer_class: Type,
+    add_servicer_func: Callable[[Any, Any], None],
+    servicer_kwargs: Optional[dict] = None,
+) -> Tuple[Callable[[Any, Any], None], Type, dict]:
+    """
+    Create gRPC handler tuple for django-cfg GRPC_HANDLERS.
+
+    This factory creates the standardized tuple format expected by django-cfg's
+    gRPC server initialization:
+    ```python
+    (add_servicer_function, servicer_class, init_kwargs)
+    ```
+
+    Args:
+        servicer_class: gRPC servicer class (e.g., MyStreamingService)
+        add_servicer_func: Generated add_*_to_server function from pb2_grpc
+        servicer_kwargs: Optional kwargs to pass to servicer constructor
+
+    Returns:
+        Tuple of (add_func, servicer_class, kwargs) for GRPC_HANDLERS
+
+    Example:
+    ```python
+    from .generated import bot_streaming_service_pb2_grpc
+    from .services import BotStreamingService
+
+    handlers = create_grpc_handler(
+        servicer_class=BotStreamingService,
+        add_servicer_func=bot_streaming_service_pb2_grpc.add_BotStreamingServiceServicer_to_server,
+        servicer_kwargs={'config': my_config},
+    )
+
+    # In settings.py
+    GRPC_HANDLERS = [handlers]
+    ```
+
+    **django-cfg Integration**:
+    The tuple is used by django-cfg like this:
+    ```python
+    for add_func, servicer_class, kwargs in GRPC_HANDLERS:
+        servicer = servicer_class(**kwargs)
+        add_func(servicer, server)
+    ```
+    """
+    kwargs = servicer_kwargs or {}
+
+    logger.debug(
+        f"Created gRPC handler: {servicer_class.__name__} "
+        f"with {len(kwargs)} init kwargs"
+    )
+
+    return (add_servicer_func, servicer_class, kwargs)
+
+
+def create_multiple_grpc_handlers(
+    handlers_config: list[dict],
+) -> list[Tuple[Callable[[Any, Any], None], Type, dict]]:
+    """
+    Create multiple gRPC handlers from configuration list.
+
+    Convenience function for creating multiple handlers at once.
+
+    Args:
+        handlers_config: List of handler configurations, each with keys:
+            - servicer_class: Servicer class
+            - add_servicer_func: Add function
+            - servicer_kwargs: Optional init kwargs
+
+    Returns:
+        List of handler tuples for GRPC_HANDLERS
+
+    Example:
+    ```python
+    handlers = create_multiple_grpc_handlers([
+        {
+            'servicer_class': BotStreamingService,
+            'add_servicer_func': pb2_grpc.add_BotStreamingServiceServicer_to_server,
+        },
+        {
+            'servicer_class': SignalStreamingService,
+            'add_servicer_func': signal_pb2_grpc.add_SignalStreamingServiceServicer_to_server,
+            'servicer_kwargs': {'timeout': 30},
+        },
+    ])
+
+    # In settings.py
+    GRPC_HANDLERS = handlers
+    ```
+    """
+    handlers = []
+
+    for config in handlers_config:
+        handler = create_grpc_handler(
+            servicer_class=config['servicer_class'],
+            add_servicer_func=config['add_servicer_func'],
+            servicer_kwargs=config.get('servicer_kwargs'),
+        )
+        handlers.append(handler)
+
+    logger.info(f"Created {len(handlers)} gRPC handlers")
+
+    return handlers
+
+
+# ============================================================================
+# Validation Utilities
+# ============================================================================
+
+def validate_grpc_handler(
+    handler: Tuple[Callable, Type, dict],
+) -> bool:
+    """
+    Validate that handler tuple has correct structure.
+
+    Args:
+        handler: Handler tuple to validate
+
+    Returns:
+        True if valid, False otherwise
+
+    Example:
+    ```python
+    handler = create_grpc_handler(MyService, add_func)
+
+    if validate_grpc_handler(handler):
+        GRPC_HANDLERS.append(handler)
+    ```
+    """
+    if not isinstance(handler, tuple):
+        logger.error(f"Handler must be tuple, got {type(handler)}")
+        return False
+
+    if len(handler) != 3:
+        logger.error(f"Handler tuple must have 3 elements, got {len(handler)}")
+        return False
+
+    add_func, servicer_class, kwargs = handler
+
+    if not callable(add_func):
+        logger.error(f"First element (add_func) must be callable, got {type(add_func)}")
+        return False
+
+    if not isinstance(servicer_class, type):
+        logger.error(f"Second element (servicer_class) must be class, got {type(servicer_class)}")
+        return False
+
+    if not isinstance(kwargs, dict):
+        logger.error(f"Third element (kwargs) must be dict, got {type(kwargs)}")
+        return False
+
+    return True
+
+
+def validate_grpc_handlers(
+    handlers: list,
+) -> Tuple[bool, list[str]]:
+    """
+    Validate list of handlers.
+
+    Args:
+        handlers: List of handler tuples
+
+    Returns:
+        Tuple of (all_valid: bool, errors: list[str])
+
+    Example:
+    ```python
+    valid, errors = validate_grpc_handlers(GRPC_HANDLERS)
+
+    if not valid:
+        for error in errors:
+            logger.error(error)
+        raise ValueError("Invalid gRPC handlers")
+    ```
+    """
+    errors = []
+
+    if not isinstance(handlers, list):
+        errors.append(f"GRPC_HANDLERS must be list, got {type(handlers)}")
+        return False, errors
+
+    for i, handler in enumerate(handlers):
+        if not validate_grpc_handler(handler):
+            errors.append(f"Handler #{i} is invalid")
+
+    all_valid = len(errors) == 0
+    return all_valid, errors
+
+
+# ============================================================================
+# Exports
+# ============================================================================
+
+__all__ = [
+    'create_grpc_handler',
+    'create_multiple_grpc_handlers',
+    'validate_grpc_handler',
+    'validate_grpc_handlers',
+]

django_cfg/apps/integrations/grpc/utils/proto_gen.py

@@ -394,7 +394,7 @@ def generate_proto_for_app(app_label: str, output_dir: Optional[Path] = None) ->
         ```
     """
     # Get gRPC config from django-cfg (Pydantic)
-    from ..services.config_helper import get_grpc_config
+    from ..services.management.config_helper import get_grpc_config
 
     grpc_config = get_grpc_config()
     proto_config = grpc_config.proto if grpc_config else None

django_cfg/apps/integrations/grpc/utils/streaming_logger.py

@@ -19,6 +19,39 @@ from rich.table import Table
 from rich.text import Text
 
 
+# ========================================================================
+# Module-level debug mode caching (performance optimization)
+# ========================================================================
+
+_debug_mode: Optional[bool] = None  # Cached debug mode to avoid repeated config loads
+
+
+def _get_debug_mode() -> bool:
+    """
+    Get debug mode from config (cached at module level).
+
+    Loads config only once and caches the result to avoid repeated config loads.
+    This is a performance optimization - config loading can be expensive.
+
+    Returns:
+        True if debug mode is enabled, False otherwise
+    """
+    global _debug_mode
+
+    if _debug_mode is not None:
+        return _debug_mode
+
+    # Load config once and cache
+    try:
+        from django_cfg.core.state import get_current_config
+        config = get_current_config()
+        _debug_mode = config.debug if config and hasattr(config, 'debug') else False
+    except Exception:
+        _debug_mode = os.getenv('DEBUG', 'false').lower() in ('true', '1', 'yes')
+
+    return _debug_mode
+
+
 class AutoTracebackHandler(logging.Handler):
     """
     Custom handler that automatically adds exception info to ERROR and CRITICAL logs.
@@ -49,8 +82,8 @@ class AutoTracebackHandler(logging.Handler):
 def setup_streaming_logger(
     name: str = "grpc_streaming",
     logs_dir: Optional[Path] = None,
-    level: int = logging.DEBUG,
-    console_level: int = logging.INFO
+    level: Optional[int] = None,
+    console_level: Optional[int] = None
 ) -> logging.Logger:
     """
     Setup dedicated logger for gRPC streaming with file and console handlers.
@@ -58,14 +91,15 @@ def setup_streaming_logger(
     Follows django-cfg logging pattern:
     - Uses os.getcwd() / 'logs' / 'grpc_streaming' for log directory
     - Time-based log file names (streaming_YYYYMMDD_HHMMSS.log)
-    - Detailed file logging (DEBUG level by default)
-    - Concise console logging (INFO level by default)
+    - Auto-detects debug mode for appropriate logging levels
+    - In dev/debug: files=DEBUG+, console=DEBUG+
+    - In production: files=INFO+, console=WARNING+
 
     Args:
         name: Logger name (default: "grpc_streaming")
         logs_dir: Directory for log files (default: <cwd>/logs/grpc_streaming)
-        level: File logging level (default: DEBUG)
-        console_level: Console logging level (default: INFO)
+        level: File logging level (default: auto-detect from debug mode)
+        console_level: Console logging level (default: auto-detect from debug mode)
 
     Returns:
         Configured logger instance
@@ -74,14 +108,14 @@ def setup_streaming_logger(
         ```python
         from django_cfg.apps.integrations.grpc.utils import setup_streaming_logger
 
-        # Basic usage
+        # Basic usage (auto-detects debug mode)
         logger = setup_streaming_logger()
 
         # Custom configuration
         logger = setup_streaming_logger(
             name="my_streaming_service",
             logs_dir=Path("/var/log/grpc"),
-            level=logging.INFO
+            level=logging.INFO  # Override auto-detection
         )
 
         logger.info("Service started")
@@ -93,8 +127,21 @@ def setup_streaming_logger(
         - Time-based log file names
         - No duplicate logs (propagate=False)
         - UTF-8 encoding
+        - Debug mode auto-detection (cached for performance)
         - Reusable across all django-cfg gRPC projects
     """
+    # Auto-detect debug mode (cached - loaded once)
+    debug = _get_debug_mode()
+
+    # Auto-determine logging levels based on debug mode if not explicitly provided
+    if level is None:
+        # File handlers: DEBUG in dev, INFO in production
+        level = logging.DEBUG if debug else logging.INFO
+
+    if console_level is None:
+        # Console: DEBUG in dev (full visibility), WARNING in production (reduce noise)
+        console_level = logging.DEBUG if debug else logging.WARNING
+
     # Create logger
     streaming_logger = logging.getLogger(name)
     streaming_logger.setLevel(level)

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

@@ -22,7 +22,7 @@ from ..serializers.charts import (
     ServerUptimeChartSerializer,
     ServiceActivityChartSerializer,
 )
-from ..services.chart_generator import ChartGeneratorService
+from ..services.rendering.charts import ChartGeneratorService
 
 logger = get_logger("grpc.charts")
 

django_cfg/apps/integrations/grpc/views/config.py

@@ -16,7 +16,7 @@ from rest_framework.response import Response
 from ..models import GRPCRequestLog, GRPCServerStatus
 from ..serializers.config import GRPCConfigSerializer, GRPCServerInfoSerializer
 from ..services import ServiceDiscovery
-from ..services.config_helper import get_grpc_config, get_grpc_server_config
+from ..services.management.config_helper import get_grpc_config, get_grpc_server_config
 
 logger = get_logger("grpc.config")
 

django_cfg/core/base/config_model.py

@@ -221,6 +221,17 @@ class DjangoConfig(BaseModel):
         description="Database connections",
     )
 
+    enable_pool_cleanup: bool = Field(
+        default=False,
+        description=(
+            "Enable explicit connection pool cleanup middleware. "
+            "Django already closes connections automatically, but this middleware "
+            "adds explicit guarantees and rollback on errors. "
+            "Enable only if you experience connection leaks. "
+            "Note: Not needed with ATOMIC_REQUESTS=True (default)."
+        ),
+    )
+
     # === Cache Configuration ===
     # Redis URL - used for automatic cache configuration if cache_default is not set
     redis_url: Optional[str] = Field(

django_cfg/core/builders/middleware_builder.py

@@ -66,6 +66,11 @@ class MiddlewareBuilder:
         # Add custom user middleware
         middleware.extend(self.config.custom_middleware)
 
+        # Add connection pool cleanup middleware LAST (if enabled)
+        # This ensures connections are returned to pool after ALL other middleware
+        if self.config.enable_pool_cleanup:
+            middleware.append('django_cfg.middleware.pool_cleanup.ConnectionPoolCleanupMiddleware')
+
         return middleware
 
     def _get_feature_middleware(self) -> List[str]:

django_cfg/management/commands/pool_status.py

@@ -0,0 +1,153 @@
+"""
+Django management command to display connection pool status.
+
+Usage:
+    python manage.py pool_status
+    python manage.py pool_status --database=secondary
+    python manage.py pool_status --json
+"""
+
+import json
+
+from django.core.management.base import BaseCommand
+
+from django_cfg.utils.pool_monitor import PoolMonitor
+
+
+class Command(BaseCommand):
+    """Display database connection pool status."""
+
+    help = 'Display database connection pool status and health information'
+
+    def add_arguments(self, parser):
+        """Add command arguments."""
+        parser.add_argument(
+            '--database',
+            default='default',
+            help='Database alias to check (default: default)',
+        )
+        parser.add_argument(
+            '--json',
+            action='store_true',
+            help='Output in JSON format',
+        )
+
+    def handle(self, *args, **options):
+        """Execute command."""
+        database_alias = options['database']
+        json_output = options['json']
+
+        monitor = PoolMonitor(database_alias=database_alias)
+
+        if json_output:
+            self._handle_json_output(monitor)
+        else:
+            self._handle_pretty_output(monitor)
+
+    def _handle_json_output(self, monitor: PoolMonitor):
+        """Output pool status as JSON."""
+        info = monitor.get_pool_info_dict()
+        self.stdout.write(json.dumps(info, indent=2))
+
+    def _handle_pretty_output(self, monitor: PoolMonitor):
+        """Output pool status in pretty formatted text."""
+        stats = monitor.get_pool_stats()
+
+        if not stats:
+            self.stdout.write(self.style.WARNING('\n⚠️  Connection Pooling: Not Configured'))
+            self.stdout.write('')
+            self.stdout.write('Database is not using connection pooling.')
+            self.stdout.write('Consider enabling pooling for production environments.')
+            self.stdout.write('')
+            return
+
+        health = monitor.check_pool_health()
+
+        # Header
+        self.stdout.write('')
+        self.stdout.write(self.style.SUCCESS('=' * 70))
+        self.stdout.write(self.style.SUCCESS('         DATABASE CONNECTION POOL STATUS'))
+        self.stdout.write(self.style.SUCCESS('=' * 70))
+        self.stdout.write('')
+
+        # Deployment Information
+        mode = 'ASGI' if stats['is_asgi'] else 'WSGI'
+        mode_icon = '🚀' if stats['is_asgi'] else '🐍'
+
+        self.stdout.write(self.style.HTTP_INFO('Deployment Information:'))
+        self.stdout.write(f"  Mode:            {mode_icon} {mode}")
+        self.stdout.write(f"  Environment:     {stats['environment'].title()}")
+        self.stdout.write(f"  Database:        {monitor.database_alias}")
+        self.stdout.write(f"  Backend:         {stats['backend']}")
+        self.stdout.write('')
+
+        # Pool Configuration
+        self.stdout.write(self.style.HTTP_INFO('Pool Configuration:'))
+        self.stdout.write(f"  Min Size:        {stats['pool_min_size']:3d} connections")
+        self.stdout.write(f"  Max Size:        {stats['pool_max_size']:3d} connections")
+        self.stdout.write(f"  Timeout:         {stats['pool_timeout']:3d} seconds")
+        self.stdout.write(f"  Max Lifetime:    {stats['max_lifetime']:4d} seconds ({stats['max_lifetime'] // 60} min)")
+        self.stdout.write(f"  Max Idle:        {stats['max_idle']:4d} seconds ({stats['max_idle'] // 60} min)")
+        self.stdout.write('')
+
+        # Current Status (if available)
+        if stats['pool_size'] is not None:
+            self.stdout.write(self.style.HTTP_INFO('Current Status:'))
+            self.stdout.write(f"  Current Size:    {stats['pool_size']:3d} connections")
+            if stats['pool_available'] is not None:
+                self.stdout.write(f"  Available:       {stats['pool_available']:3d} connections")
+            self.stdout.write(f"  Capacity:        {health['capacity_percent']:.1f}% used")
+            self.stdout.write('')
+        else:
+            self.stdout.write(self.style.WARNING('Current Status:     Not available (pool not active yet)'))
+            self.stdout.write('')
+
+        # Health Check
+        status_styles = {
+            'healthy': self.style.SUCCESS,
+            'warning': self.style.WARNING,
+            'critical': self.style.ERROR,
+            'unavailable': self.style.NOTICE,
+        }
+        status_icons = {
+            'healthy': '✅',
+            'warning': '⚠️',
+            'critical': '🔴',
+            'unavailable': '⚪',
+        }
+
+        status_style = status_styles.get(health['status'], self.style.NOTICE)
+        status_icon = status_icons.get(health['status'], '❓')
+        status_text = health['status'].upper()
+
+        self.stdout.write(self.style.HTTP_INFO('Health Check:'))
+        self.stdout.write(f"  Status:          {status_icon} " + status_style(status_text))
+
+        if health['issues']:
+            self.stdout.write('')
+            self.stdout.write(self.style.WARNING('  Issues Detected:'))
+            for issue in health['issues']:
+                self.stdout.write(self.style.WARNING(f"    • {issue}"))
+
+        if health['recommendations']:
+            self.stdout.write('')
+            self.stdout.write(self.style.NOTICE('  Recommendations:'))
+            for rec in health['recommendations']:
+                self.stdout.write(f"    • {rec}")
+
+        # Footer
+        self.stdout.write('')
+        self.stdout.write(self.style.SUCCESS('=' * 70))
+        self.stdout.write('')
+
+        # Overall summary
+        if health['healthy']:
+            self.stdout.write(self.style.SUCCESS('✅ Pool is healthy and operating normally'))
+        elif health['status'] == 'warning':
+            self.stdout.write(self.style.WARNING('⚠️  Pool is functional but requires attention'))
+        elif health['status'] == 'critical':
+            self.stdout.write(self.style.ERROR('🔴 Pool is in critical state - immediate action required'))
+        else:
+            self.stdout.write(self.style.NOTICE('ℹ️  Pool status check completed'))
+
+        self.stdout.write('')