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

django_cfg/middleware/pool_cleanup.py

@@ -0,0 +1,261 @@
+"""
+Connection Pool Cleanup Middleware.
+
+Ensures database connections are properly returned to the pool after each
+request, including error cases. Prevents connection leaks in production.
+
+Usage:
+    Add to MIDDLEWARE in settings.py:
+    MIDDLEWARE = [
+        # ... other middleware ...
+        'django_cfg.middleware.pool_cleanup.ConnectionPoolCleanupMiddleware',
+    ]
+
+Note:
+    This middleware should be placed AFTER all other middleware to ensure
+    cleanup happens regardless of what other middleware does.
+"""
+
+import logging
+import time
+from typing import Callable
+
+from django.db import connection, connections, transaction
+from django.http import HttpRequest, HttpResponse
+from django.utils.deprecation import MiddlewareMixin
+
+logger = logging.getLogger('django_cfg.middleware.pool_cleanup')
+
+
+class ConnectionPoolCleanupMiddleware(MiddlewareMixin):
+    """
+    Middleware to ensure database connections are cleaned up after each request.
+
+    Features:
+    - Closes connections after successful responses
+    - Closes connections after exceptions
+    - Rolls back uncommitted transactions on errors
+    - Works with both sync and async views
+    - Minimal performance overhead (<1ms)
+
+    This middleware is critical when using connection pooling with
+    ATOMIC_REQUESTS=False, as it ensures connections don't leak.
+    """
+
+    def __init__(self, get_response: Callable):
+        """
+        Initialize middleware.
+
+        Args:
+            get_response: The next middleware or view to call
+        """
+        super().__init__(get_response)
+        self.get_response = get_response
+        self._enable_logging = False  # Set to True for debug logging
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        """
+        Process request through middleware chain.
+
+        Args:
+            request: The HTTP request
+
+        Returns:
+            HttpResponse from view or next middleware
+        """
+        start_time = time.time() if self._enable_logging else None
+
+        try:
+            response = self.get_response(request)
+            return response
+        finally:
+            # Cleanup happens in finally block to ensure it runs
+            self._cleanup_connections(request, rollback_on_error=False)
+
+            if self._enable_logging and start_time:
+                duration_ms = (time.time() - start_time) * 1000
+                logger.debug(f"Pool cleanup overhead: {duration_ms:.2f}ms")
+
+    def process_response(self, request: HttpRequest, response: HttpResponse) -> HttpResponse:
+        """
+        Process response before returning to client.
+
+        Called after view execution for successful responses.
+
+        Args:
+            request: The HTTP request
+            response: The HTTP response from view
+
+        Returns:
+            The HTTP response (unchanged)
+        """
+        # Cleanup handled in __call__ finally block
+        return response
+
+    def process_exception(self, request: HttpRequest, exception: Exception) -> None:
+        """
+        Process exception raised during request handling.
+
+        Called when view raises an exception. Rolls back any pending
+        transactions and closes connections.
+
+        Args:
+            request: The HTTP request
+            exception: The exception that was raised
+
+        Returns:
+            None (allows exception to propagate)
+        """
+        logger.warning(
+            f"Exception in request, rolling back transactions: {exception.__class__.__name__}",
+            extra={
+                'path': request.path,
+                'method': request.method,
+                'exception': str(exception),
+            }
+        )
+
+        # Rollback all open transactions
+        self._cleanup_connections(request, rollback_on_error=True)
+
+        # Return None to allow exception to propagate
+        return None
+
+    def _cleanup_connections(self, request: HttpRequest, rollback_on_error: bool = False) -> None:
+        """
+        Clean up all database connections.
+
+        Args:
+            request: The HTTP request
+            rollback_on_error: If True, rollback uncommitted transactions
+        """
+        for db_alias in connections:
+            try:
+                conn = connections[db_alias]
+
+                # Check if connection is open
+                if conn.connection is None:
+                    continue
+
+                # Rollback uncommitted transactions if requested
+                if rollback_on_error:
+                    self._rollback_transaction(conn, db_alias)
+
+                # Close the connection to return it to pool
+                # Django's close() is safe to call multiple times
+                conn.close()
+
+            except Exception as e:
+                logger.error(
+                    f"Error cleaning up connection '{db_alias}': {e}",
+                    exc_info=True,
+                    extra={
+                        'database': db_alias,
+                        'path': request.path,
+                    }
+                )
+
+    def _rollback_transaction(self, conn, db_alias: str) -> None:
+        """
+        Rollback any uncommitted transaction on a connection.
+
+        Args:
+            conn: Database connection
+            db_alias: Database alias for logging
+        """
+        try:
+            # Check if there's an open transaction
+            if conn.in_atomic_block:
+                logger.debug(f"Rolling back transaction for database '{db_alias}'")
+                conn.rollback()
+        except Exception as e:
+            logger.error(
+                f"Error rolling back transaction for '{db_alias}': {e}",
+                exc_info=True
+            )
+
+
+class AsyncConnectionPoolCleanupMiddleware:
+    """
+    Async version of ConnectionPoolCleanupMiddleware.
+
+    Use this middleware in ASGI deployments for better async compatibility.
+
+    Usage:
+        MIDDLEWARE = [
+            'django_cfg.middleware.pool_cleanup.AsyncConnectionPoolCleanupMiddleware',
+        ]
+    """
+
+    def __init__(self, get_response: Callable):
+        """
+        Initialize async middleware.
+
+        Args:
+            get_response: The next middleware or view to call
+        """
+        self.get_response = get_response
+        self._enable_logging = False
+
+    async def __call__(self, request: HttpRequest) -> HttpResponse:
+        """
+        Process request through middleware chain (async).
+
+        Args:
+            request: The HTTP request
+
+        Returns:
+            HttpResponse from view or next middleware
+        """
+        start_time = time.time() if self._enable_logging else None
+
+        try:
+            response = await self.get_response(request)
+            return response
+        except Exception as e:
+            # Rollback on exception
+            logger.warning(
+                f"Exception in async request, rolling back: {e.__class__.__name__}",
+                extra={'path': request.path, 'exception': str(e)}
+            )
+            self._cleanup_connections(request, rollback_on_error=True)
+            raise
+        finally:
+            # Always cleanup connections
+            self._cleanup_connections(request, rollback_on_error=False)
+
+            if self._enable_logging and start_time:
+                duration_ms = (time.time() - start_time) * 1000
+                logger.debug(f"Async pool cleanup overhead: {duration_ms:.2f}ms")
+
+    def _cleanup_connections(self, request: HttpRequest, rollback_on_error: bool = False) -> None:
+        """
+        Clean up all database connections (sync code in async middleware).
+
+        Args:
+            request: The HTTP request
+            rollback_on_error: If True, rollback uncommitted transactions
+        """
+        for db_alias in connections:
+            try:
+                conn = connections[db_alias]
+
+                if conn.connection is None:
+                    continue
+
+                if rollback_on_error and conn.in_atomic_block:
+                    logger.debug(f"Rolling back async transaction for '{db_alias}'")
+                    conn.rollback()
+
+                conn.close()
+
+            except Exception as e:
+                logger.error(
+                    f"Error cleaning up async connection '{db_alias}': {e}",
+                    exc_info=True,
+                    extra={'database': db_alias, 'path': request.path}
+                )
+
+
+# Default export - use sync middleware
+__all__ = ['ConnectionPoolCleanupMiddleware', 'AsyncConnectionPoolCleanupMiddleware']

django_cfg/models/api/grpc/config.py

@@ -370,9 +370,9 @@ class GRPCConfig(BaseConfig):
         description="Proto generation configuration (optional, use flatten fields above for common settings)",
     )
 
-    handlers_hook: str = Field(
+    handlers_hook: str | List[str] = Field(
         default="",
-        description="Import path to grpc_handlers function (optional, e.g., '{ROOT_URLCONF}.grpc_handlers')",
+        description="Import path(s) to grpc_handlers function (optional, e.g., '{ROOT_URLCONF}.grpc_handlers' or list of paths)",
     )
 
     auto_register_apps: bool = Field(

django_cfg/models/infrastructure/database/config.py

@@ -81,6 +81,18 @@ class DatabaseConfig(BaseModel):
         description="Additional database-specific options",
     )
 
+    # Connection pooling options (CRITICAL for preventing connection exhaustion)
+    conn_max_age: int = Field(
+        default=0,  # 0 disables persistent connections when using connection pooling
+        description="Maximum age of database connections in seconds. Must be 0 when using connection pooling.",
+        ge=0,
+    )
+
+    conn_health_checks: bool = Field(
+        default=True,
+        description="Enable database connection health checks",
+    )
+
     # Database routing configuration
     apps: List[str] = Field(
         default_factory=list,
@@ -223,6 +235,8 @@ class DatabaseConfig(BaseModel):
         apps: Optional[List[str]] = None,
         operations: Optional[List[Literal["read", "write", "migrate"]]] = None,
         routing_description: str = "",
+        conn_max_age: int = 0,  # 0 disables persistent connections when using connection pooling
+        conn_health_checks: bool = True,
         **kwargs
     ) -> "DatabaseConfig":
         """
@@ -254,6 +268,8 @@ class DatabaseConfig(BaseModel):
             apps=apps or [],
             operations=operations or ["read", "write", "migrate"],
             routing_description=routing_description,
+            conn_max_age=conn_max_age,
+            conn_health_checks=conn_health_checks,
             **kwargs
         )
 

django_cfg/models/infrastructure/database/converters.py

@@ -25,6 +25,8 @@ def to_django_config(config: "DatabaseConfig") -> Dict[str, Any]:  # type: ignor
         django_config = {
             "ENGINE": config.engine,
             "OPTIONS": {**config.options},
+            "CONN_MAX_AGE": config.conn_max_age,
+            "CONN_HEALTH_CHECKS": config.conn_health_checks,
         }
 
         # Add database-specific options

django_cfg/modules/django_admin/utils/html/composition.py

@@ -28,7 +28,8 @@ class CompositionElements:
 
     @staticmethod
     def icon_text(icon_or_text: Union[str, Any], text: Any = None,
-                  icon_size: str = "xs", separator: str = " ") -> SafeString:
+                  icon_size: str = "xs", separator: str = " ", 
+                  color: str = None) -> SafeString:
         """
         Render icon with text or emoji with text.
 
@@ -37,28 +38,35 @@ class CompositionElements:
             text: Optional text to display after icon
             icon_size: Icon size (xs, sm, base, lg, xl)
             separator: Separator between icon and text
+            color: Optional color (success, warning, danger, info, secondary, primary)
 
         Usage:
             html.icon_text(Icons.EDIT, 5)  # Icon with number
-            html.icon_text("📝", 5)  # Emoji with number
             html.icon_text("Active")  # Just text
+            html.icon_text(Icons.CHECK, "Yes", color="success")  # Icon with color
         """
+        # Color mapping to Tailwind/Unfold classes
+        color_classes = {
+            'success': 'text-green-600 dark:text-green-400',
+            'warning': 'text-yellow-600 dark:text-yellow-400',
+            'danger': 'text-red-600 dark:text-red-400',
+            'error': 'text-red-600 dark:text-red-400',
+            'info': 'text-blue-600 dark:text-blue-400',
+            'secondary': 'text-gray-600 dark:text-gray-400',
+            'primary': 'text-indigo-600 dark:text-indigo-400',
+        }
+        
+        color_class = color_classes.get(color, '') if color else ''
+        
         if text is None:
             # Just text
+            if color_class:
+                return format_html('<span class="{}">{}</span>', color_class, escape(str(icon_or_text)))
             return format_html('<span>{}</span>', escape(str(icon_or_text)))
 
-        # Check if it's a Material Icon (from Icons class) or emoji
+        # Render icon (Material Icon from Icons class)
         icon_str = str(icon_or_text)
-
-        # Detect if it's emoji by checking for non-ASCII characters
-        is_emoji = any(ord(c) > 127 for c in icon_str)
-
-        if is_emoji or icon_str in ['📝', '💬', '🛒', '👤', '📧', '🔔', '⚙️', '🔧', '📊', '🎯']:
-            # Emoji
-            icon_html = escape(icon_str)
-        else:
-            # Material Icon
-            icon_html = CompositionElements.icon(icon_str, size=icon_size)
+        icon_html = CompositionElements.icon(icon_str, size=icon_size)
 
         # DON'T escape SafeString - it's already safe HTML!
         from django.utils.safestring import SafeString
@@ -67,8 +75,44 @@ class CompositionElements:
         else:
             text_html = escape(str(text))
 
+        # Wrap in span with color class if provided
+        if color_class:
+            return format_html('<span class="{}">{}{}<span>{}</span></span>', 
+                             color_class, icon_html, separator, text_html)
+
         return format_html('{}{}<span>{}</span>', icon_html, separator, text_html)
 
+    @staticmethod
+    def colored_text(text: Any, color: str = None) -> SafeString:
+        """
+        Render colored text.
+
+        Args:
+            text: Text to display
+            color: Color (success, warning, danger, info, secondary, primary)
+
+        Usage:
+            html.colored_text("Active", "success")
+            html.colored_text("5 minutes ago", "warning")
+        """
+        # Color mapping to Tailwind/Unfold classes
+        color_classes = {
+            'success': 'text-green-600 dark:text-green-400',
+            'warning': 'text-yellow-600 dark:text-yellow-400',
+            'danger': 'text-red-600 dark:text-red-400',
+            'error': 'text-red-600 dark:text-red-400',
+            'info': 'text-blue-600 dark:text-blue-400',
+            'secondary': 'text-gray-600 dark:text-gray-400',
+            'primary': 'text-indigo-600 dark:text-indigo-400',
+        }
+        
+        color_class = color_classes.get(color, '') if color else ''
+        
+        if color_class:
+            return format_html('<span class="{}">{}</span>', color_class, escape(str(text)))
+        
+        return format_html('<span>{}</span>', escape(str(text)))
+
     @staticmethod
     def inline(*items, separator: str = " | ",
                size: str = "small", css_class: str = "") -> SafeString:

django_cfg/modules/django_admin/utils/html_builder.py

@@ -45,6 +45,7 @@ class HtmlBuilder:
     # === CompositionElements ===
     inline = staticmethod(CompositionElements.inline)
     icon_text = staticmethod(CompositionElements.icon_text)
+    colored_text = staticmethod(CompositionElements.colored_text)
     header = staticmethod(CompositionElements.header)
 
     # === FormattingElements ===

django_cfg/modules/django_client/core/generator/typescript/files_generator.py

@@ -143,6 +143,18 @@ class FilesGenerator:
             description="Retry utilities with p-retry",
         )
 
+    def generate_validation_events_file(self):
+        """Generate validation-events.ts with browser CustomEvent integration."""
+
+        template = self.jinja_env.get_template('utils/validation-events.ts.jinja')
+        content = template.render()
+
+        return GeneratedFile(
+            path="validation-events.ts",
+            content=content,
+            description="Zod validation error events for browser integration",
+        )
+
     def generate_api_instance_file(self):
         """Generate api-instance.ts with global singleton."""
 

django_cfg/modules/django_client/core/generator/typescript/generator.py

@@ -98,6 +98,10 @@ class TypeScriptGenerator(BaseGenerator):
             # Generate retry.ts with p-retry
             files.append(self.files_gen.generate_retry_file())
 
+            # Generate validation-events.ts (browser CustomEvent for Zod errors)
+            if self.generate_zod_schemas:
+                files.append(self.files_gen.generate_validation_events_file())
+
             # Generate api-instance.ts singleton (needed for fetchers/hooks)
             if self.generate_fetchers:
                 files.append(self.files_gen.generate_api_instance_file())
@@ -146,6 +150,10 @@ class TypeScriptGenerator(BaseGenerator):
             # Generate retry.ts with p-retry
             files.append(self.files_gen.generate_retry_file())
 
+            # Generate validation-events.ts (browser CustomEvent for Zod errors)
+            if self.generate_zod_schemas:
+                files.append(self.files_gen.generate_validation_events_file())
+
             # Generate api-instance.ts singleton (needed for fetchers/hooks)
             if self.generate_fetchers:
                 files.append(self.files_gen.generate_api_instance_file())

django_cfg/modules/django_client/core/generator/typescript/templates/fetchers/function.ts.jinja

@@ -43,6 +43,28 @@ export async function {{ func_name }}(
 
     consola.error('Response data:', response);
 
+    // Dispatch browser CustomEvent (only if window is defined)
+    if (typeof window !== 'undefined' && error instanceof Error && 'issues' in error) {
+      try {
+        const event = new CustomEvent('zod-validation-error', {
+          detail: {
+            operation: '{{ func_name }}',
+            path: '{{ operation.path }}',
+            method: '{{ operation.http_method }}',
+            error: error,
+            response: response,
+            timestamp: new Date(),
+          },
+          bubbles: true,
+          cancelable: false,
+        });
+        window.dispatchEvent(event);
+      } catch (eventError) {
+        // Silently fail - event dispatch should never crash the app
+        consola.warn('Failed to dispatch validation error event:', eventError);
+      }
+    }
+
     // Re-throw the error
     throw error;
   }

django_cfg/modules/django_client/core/generator/typescript/templates/main_index.ts.jinja

@@ -55,6 +55,10 @@ export * as Enums from "./enums";
 
 // Re-export Zod schemas for runtime validation
 export * as Schemas from "./_utils/schemas";
+
+// Re-export Zod validation events for browser integration
+export type { ValidationErrorDetail, ValidationErrorEvent } from "./validation-events";
+export { dispatchValidationError, onValidationError, formatZodError } from "./validation-events";
 {% endif %}
 {% if generate_fetchers %}
 

django_cfg/modules/django_client/core/generator/typescript/templates/utils/validation-events.ts.jinja

@@ -0,0 +1,133 @@
+/**
+ * Zod Validation Events - Browser CustomEvent integration
+ *
+ * Dispatches browser CustomEvents when Zod validation fails, allowing
+ * React/frontend apps to listen and handle validation errors globally.
+ *
+ * @example
+ * ```typescript
+ * // In your React app
+ * window.addEventListener('zod-validation-error', (event) => {
+ *   const { operation, path, method, error, response } = event.detail;
+ *   console.error(`Validation failed for ${method} ${path}`, error);
+ *   // Show toast notification, log to Sentry, etc.
+ * });
+ * ```
+ */
+
+import type { ZodError } from 'zod'
+
+/**
+ * Validation error event detail
+ */
+export interface ValidationErrorDetail {
+  /** Operation/function name that failed validation */
+  operation: string
+  /** API endpoint path */
+  path: string
+  /** HTTP method */
+  method: string
+  /** Zod validation error */
+  error: ZodError
+  /** Raw response data that failed validation */
+  response: any
+  /** Timestamp of the error */
+  timestamp: Date
+}
+
+/**
+ * Custom event type for Zod validation errors
+ */
+export type ValidationErrorEvent = CustomEvent<ValidationErrorDetail>
+
+/**
+ * Dispatch a Zod validation error event.
+ *
+ * Only dispatches in browser environment (when window is defined).
+ * Safe to call in Node.js/SSR - will be a no-op.
+ *
+ * @param detail - Validation error details
+ */
+export function dispatchValidationError(detail: ValidationErrorDetail): void {
+  // Check if running in browser
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    const event = new CustomEvent<ValidationErrorDetail>('zod-validation-error', {
+      detail,
+      bubbles: true,
+      cancelable: false,
+    })
+
+    window.dispatchEvent(event)
+  } catch (error) {
+    // Silently fail - validation event dispatch should never crash the app
+    console.warn('Failed to dispatch validation error event:', error)
+  }
+}
+
+/**
+ * Add a global listener for Zod validation errors.
+ *
+ * @param callback - Function to call when validation error occurs
+ * @returns Cleanup function to remove the listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onValidationError(({ operation, error }) => {
+ *   toast.error(`Validation failed in ${operation}`);
+ *   logToSentry(error);
+ * });
+ *
+ * // Later, remove listener
+ * cleanup();
+ * ```
+ */
+export function onValidationError(
+  callback: (detail: ValidationErrorDetail) => void
+): () => void {
+  if (typeof window === 'undefined') {
+    // Return no-op cleanup function for SSR
+    return () => {}
+  }
+
+  const handler = (event: Event) => {
+    if (event instanceof CustomEvent) {
+      callback(event.detail)
+    }
+  }
+
+  window.addEventListener('zod-validation-error', handler)
+
+  // Return cleanup function
+  return () => {
+    window.removeEventListener('zod-validation-error', handler)
+  }
+}
+
+/**
+ * Format Zod error for logging/display.
+ *
+ * @param error - Zod validation error
+ * @returns Formatted error message
+ */
+export function formatZodError(error: ZodError): string {
+  const issues = error.issues.map((issue, index) => {
+    const path = issue.path.join('.') || 'root'
+    const parts = [`${index + 1}. ${path}: ${issue.message}`]
+
+    if ('expected' in issue && issue.expected) {
+      parts.push(`   Expected: ${issue.expected}`)
+    }
+
+    if ('received' in issue && issue.received) {
+      parts.push(`   Received: ${issue.received}`)
+    }
+
+    return parts.join('\n')
+  })
+
+  return issues.join('\n')
+}