django-bolt 0.1.0__cp310-abi3-win_amd64.whl

django_bolt/logging/config.py

@@ -0,0 +1,357 @@
+"""Logging configuration for Django-Bolt.
+
+Integrates with Django's logging configuration and provides structured logging
+for HTTP requests, responses, and exceptions.
+
+Adopts Litestar's queue-based logging approach so request logging stays
+non-blocking and fully controlled by application logging config.
+"""
+
+import sys
+import os
+import atexit
+from queue import Queue
+from logging.handlers import QueueHandler, QueueListener
+import logging
+import logging.config
+from abc import ABC, abstractmethod
+from typing import Callable, Optional, Set, List, Dict, Any
+from dataclasses import dataclass, field
+
+
+# Global flag to prevent multiple logging reconfigurations
+_LOGGING_CONFIGURED = False
+_QUEUE_LISTENER: Optional[QueueListener] = None
+_QUEUE: Optional[Queue] = None
+
+
+@dataclass
+class LoggingConfig:
+    """Configuration for request/response logging.
+
+    Integrates with Django's logging system and uses the configured logger.
+    """
+
+    # Logger name - defaults to Django's logger
+    logger_name: str = "django.server"
+
+    # Request logging fields
+    request_log_fields: Set[str] = field(default_factory=lambda: {
+        "method", "path", "status_code"
+    })
+
+    # Response logging fields
+    response_log_fields: Set[str] = field(default_factory=lambda: {
+        "status_code"
+    })
+
+    # Headers to obfuscate in logs (for security)
+    obfuscate_headers: Set[str] = field(default_factory=lambda: {
+        "authorization", "cookie", "x-api-key", "x-auth-token"
+    })
+
+    # Cookies to obfuscate in logs
+    obfuscate_cookies: Set[str] = field(default_factory=lambda: {
+        "sessionid", "csrftoken"
+    })
+
+    # Log request body (be careful with sensitive data)
+    log_request_body: bool = False
+
+    # Log response body (be careful with large responses)
+    log_response_body: bool = False
+
+    # Maximum body size to log (in bytes)
+    max_body_log_size: int = 1024
+
+    # Note: Individual log levels are determined automatically:
+    # - Requests: DEBUG
+    # - Successful responses (2xx/3xx): INFO
+    # - Client errors (4xx): WARNING
+    # - Server errors (5xx): ERROR
+    #
+    # To control which logs appear, configure Django's LOGGING in settings.py:
+    # LOGGING = {
+    #     "loggers": {
+    #         "django_bolt": {"level": "INFO"},  # Show INFO and above
+    #     }
+    # }
+
+    # Deprecated: log_level is no longer used (kept for backward compatibility)
+    log_level: str = "INFO"
+
+    # Log level for exceptions (used by log_exception method)
+    error_log_level: str = "ERROR"
+
+    # Custom exception logging handler
+    exception_logging_handler: Optional[Callable] = None
+
+    # Skip logging for specific paths (e.g., health checks)
+    skip_paths: Set[str] = field(default_factory=lambda: {
+        "/health", "/ready", "/metrics"
+    })
+
+    # Skip logging for specific status codes
+    skip_status_codes: Set[int] = field(default_factory=set)
+
+    # Optional sampling of logs (0.0-1.0). When set, successful responses (2xx/3xx)
+    # will only be logged with this probability. Errors (4xx/5xx) are not sampled.
+    sample_rate: Optional[float] = None
+
+    # Only log successful responses slower than this threshold (milliseconds).
+    # Errors (4xx/5xx) are not subject to the slow-only threshold.
+    min_duration_ms: Optional[int] = None
+
+    def get_logger(self) -> logging.Logger:
+        """Get the configured logger.
+
+        Uses Django's logging configuration if available.
+        """
+        return logging.getLogger(self.logger_name)
+
+    def should_log_request(self, path: str, status_code: Optional[int] = None) -> bool:
+        """Check if a request should be logged.
+
+        Args:
+            path: Request path
+            status_code: Response status code (optional)
+
+        Returns:
+            True if request should be logged
+        """
+        if path in self.skip_paths:
+            return False
+
+        if status_code and status_code in self.skip_status_codes:
+            return False
+
+        return True
+
+
+@dataclass
+class RequestLogFields:
+    """Available fields for request logging."""
+
+    # HTTP method (GET, POST, etc.)
+    method: str = "method"
+
+    # Request path
+    path: str = "path"
+
+    # Query string
+    query: str = "query"
+
+    # Request headers
+    headers: str = "headers"
+
+    # Request body
+    body: str = "body"
+
+    # Client IP address
+    client_ip: str = "client_ip"
+
+    # User agent
+    user_agent: str = "user_agent"
+
+    # Request ID (if available)
+    request_id: str = "request_id"
+
+
+@dataclass
+class ResponseLogFields:
+    """Available fields for response logging."""
+
+    # HTTP status code
+    status_code: str = "status_code"
+
+    # Response headers
+    headers: str = "headers"
+
+    # Response body
+    body: str = "body"
+
+    # Response time (in seconds)
+    duration: str = "duration"
+
+    # Response size (in bytes)
+    size: str = "size"
+
+
+def get_default_logging_config() -> LoggingConfig:
+    """Get default logging configuration.
+
+    Uses Django's DEBUG setting to determine log level.
+    """
+    log_level = "INFO"
+    debug = False
+    settings_level = None
+    settings_sample = None
+    settings_slow_ms = None
+    try:
+        from django.conf import settings
+        if settings.configured:
+            debug = settings.DEBUG
+            # Optional overrides from Django settings
+            settings_level = getattr(settings, "DJANGO_BOLT_LOG_LEVEL", None)
+            settings_sample = getattr(settings, "DJANGO_BOLT_LOG_SAMPLE", None)
+            settings_slow_ms = getattr(settings, "DJANGO_BOLT_LOG_SLOW_MS", None)
+            # Default base level by DEBUG
+            log_level = "DEBUG" if debug else "WARNING"
+    except (ImportError, AttributeError, Exception):
+        # Django not available or not configured, use default
+        pass
+
+    # Choose log level: Django settings override > default determined by DEBUG
+    if settings_level:
+        log_level = str(settings_level).upper()
+
+    sample_rate: Optional[float] = None
+    if settings_sample is not None:
+        try:
+            sr = float(settings_sample)
+            if 0.0 <= sr <= 1.0:
+                sample_rate = sr
+        except Exception:
+            sample_rate = None
+
+    min_duration_ms: Optional[int] = None
+    if settings_slow_ms is not None:
+        try:
+            min_duration_ms = max(0, int(settings_slow_ms))
+        except Exception:
+            min_duration_ms = None
+    else:
+        # Default to slow-only logging in production
+        if not debug:
+            min_duration_ms = 250
+
+    return LoggingConfig(
+        log_level=log_level,
+        sample_rate=sample_rate,
+        min_duration_ms=min_duration_ms,
+    )
+
+
+def _ensure_queue_logging(base_level: str) -> QueueHandler:
+    """Create or reuse a queue-based logging setup.
+
+    Returns a QueueHandler that enqueues log records. A singleton QueueListener
+    forwards records to a console StreamHandler in the background. Inspired by
+    Litestar's standard logging implementation.
+    """
+
+    global _QUEUE_LISTENER, _QUEUE  # noqa: PLW0603
+
+    if _QUEUE is None:
+        _QUEUE = Queue(-1)
+
+    queue_handler = QueueHandler(_QUEUE)
+    queue_handler.setLevel(logging.DEBUG)
+
+    if _QUEUE_LISTENER is None:
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(base_level)
+        console_handler.setFormatter(
+            logging.Formatter(
+                fmt="%(levelname)s - %(asctime)s - %(name)s - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+
+        listener = QueueListener(_QUEUE, console_handler)
+        listener.start()
+
+        # Only register atexit once for cleanup
+        def _cleanup_listener():
+            """Safely stop the listener, handling already-stopped case."""
+            try:
+                if _QUEUE_LISTENER is not None and hasattr(_QUEUE_LISTENER, '_thread'):
+                    if _QUEUE_LISTENER._thread is not None:
+                        _QUEUE_LISTENER.stop()
+            except Exception:
+                pass
+
+        atexit.register(_cleanup_listener)
+        _QUEUE_LISTENER = listener
+
+    return queue_handler
+
+
+def setup_django_logging(force: bool = False) -> None:
+    """Setup Django logging configuration with console output.
+
+    Configures Django's logging system to output to console/terminal.
+    Based on Litestar's logging configuration pattern.
+
+    This should be called once during application startup. Subsequent calls
+    are no-ops unless force=True.
+
+    Args:
+        force: If True, reconfigure even if already configured
+    """
+    global _LOGGING_CONFIGURED, _QUEUE_LISTENER, _QUEUE
+
+    # Guard against multiple reconfigurations (Litestar pattern)
+    if _LOGGING_CONFIGURED and not force:
+        return
+
+    if force and _QUEUE_LISTENER is not None:
+        try:
+            _QUEUE_LISTENER.stop()
+        except Exception:
+            pass
+        _QUEUE_LISTENER = None
+
+    try:
+        from django.conf import settings
+
+        # Check if Django is configured
+        if not settings.configured:
+            return
+
+        # Check if LOGGING is explicitly configured in Django settings
+        # Note: Django's default settings may have LOGGING, but we want to check
+        # if the user explicitly set it in their settings.py
+        has_explicit_logging = False
+        try:
+            # Try to import the actual settings module to check if LOGGING is defined
+            import importlib
+            settings_module = importlib.import_module(settings.SETTINGS_MODULE)
+            has_explicit_logging = hasattr(settings_module, 'LOGGING')
+        except (AttributeError, ImportError):
+            # Fall back to checking settings object
+            has_explicit_logging = hasattr(settings, 'LOGGING') and settings.LOGGING
+
+        if has_explicit_logging:
+            # User has explicitly configured logging, respect it
+            _LOGGING_CONFIGURED = True
+            return
+
+        # Get appropriate handlers for Python version
+        base_level = "DEBUG" if getattr(settings, "DEBUG", False) else "WARNING"
+
+        queue_handler = _ensure_queue_logging(base_level)
+
+        root_logger = logging.getLogger()
+        root_logger.handlers.clear()
+        root_logger.addHandler(queue_handler)
+        root_logger.setLevel(base_level)
+
+        for logger_name in ("django", "django.server", "django_bolt"):
+            logger = logging.getLogger(logger_name)
+            logger.handlers.clear()
+            logger.addHandler(queue_handler)
+            # App-level logging config remains source of truth; use base_level if unset
+            current_level = logger.level or logging.getLevelName(base_level)
+            logger.setLevel(current_level)
+            logger.propagate = logger_name == "django"
+
+        _LOGGING_CONFIGURED = True
+
+    except (ImportError, AttributeError, Exception) as e:
+        # If Django not available or configuration fails, use basic config
+        logging.basicConfig(
+            level=logging.INFO,
+            format='%(levelname)s - %(asctime)s - %(name)s - %(message)s',
+        )
+        _LOGGING_CONFIGURED = True

django_bolt/logging/middleware.py

@@ -0,0 +1,296 @@
+"""Logging middleware for Django-Bolt.
+
+Provides request/response logging with support for Django's logging configuration.
+"""
+
+import time
+import random
+import logging
+from typing import Dict, Any, Optional, Callable, Awaitable
+from .config import LoggingConfig
+
+
+class LoggingMiddleware:
+    """Middleware for logging HTTP requests and responses.
+
+    Integrates with Django's logging system and provides structured logging.
+    """
+
+    def __init__(self, config: Optional[LoggingConfig] = None):
+        """Initialize logging middleware.
+
+        Args:
+            config: Logging configuration (uses defaults if not provided)
+        """
+        if config is None:
+            from .config import get_default_logging_config
+            config = get_default_logging_config()
+
+        self.config = config
+        self.logger = config.get_logger()
+
+    def obfuscate_headers(self, headers: Dict[str, str]) -> Dict[str, str]:
+        """Obfuscate sensitive headers.
+
+        Args:
+            headers: Request/response headers
+
+        Returns:
+            Headers with sensitive values obfuscated
+        """
+        obfuscated = {}
+        for key, value in headers.items():
+            if key.lower() in self.config.obfuscate_headers:
+                obfuscated[key] = "***"
+            else:
+                obfuscated[key] = value
+        return obfuscated
+
+    def obfuscate_cookies(self, cookies: Dict[str, str]) -> Dict[str, str]:
+        """Obfuscate sensitive cookies.
+
+        Args:
+            cookies: Request cookies
+
+        Returns:
+            Cookies with sensitive values obfuscated
+        """
+        obfuscated = {}
+        for key, value in cookies.items():
+            if key in self.config.obfuscate_cookies:
+                obfuscated[key] = "***"
+            else:
+                obfuscated[key] = value
+        return obfuscated
+
+    def extract_request_data(self, request: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract request data for logging.
+
+        Args:
+            request: Request dictionary
+
+        Returns:
+            Dictionary of request data to log
+        """
+        data = {}
+
+        if "method" in self.config.request_log_fields:
+            data["method"] = request.get("method", "")
+
+        if "path" in self.config.request_log_fields:
+            data["path"] = request.get("path", "")
+
+        if "query" in self.config.request_log_fields:
+            query_params = request.get("query_params", {})
+            if query_params:
+                data["query"] = query_params
+
+        if "headers" in self.config.request_log_fields:
+            headers = request.get("headers", {})
+            if headers:
+                data["headers"] = self.obfuscate_headers(headers)
+
+        if "body" in self.config.request_log_fields and self.config.log_request_body:
+            body = request.get("body", b"")
+            if body and len(body) <= self.config.max_body_log_size:
+                try:
+                    data["body"] = body.decode("utf-8")
+                except UnicodeDecodeError:
+                    data["body"] = f"<binary data, {len(body)} bytes>"
+
+        if "client_ip" in self.config.request_log_fields:
+            # Try to get client IP from various headers
+            headers = request.get("headers", {})
+            client_ip = (
+                headers.get("x-forwarded-for", "").split(",")[0].strip()
+                or headers.get("x-real-ip", "")
+                or request.get("client", "")
+            )
+            if client_ip:
+                data["client_ip"] = client_ip
+
+        if "user_agent" in self.config.request_log_fields:
+            headers = request.get("headers", {})
+            user_agent = headers.get("user-agent", "")
+            if user_agent:
+                data["user_agent"] = user_agent
+
+        return data
+
+    def log_request(self, request: Dict[str, Any]) -> None:
+        """Log an HTTP request.
+
+        Args:
+            request: Request dictionary
+        """
+        path = request.get("path", "")
+        if not self.config.should_log_request(path):
+            return
+
+        # Requests are always DEBUG level. Short-circuit if disabled.
+        if not self.logger.isEnabledFor(logging.DEBUG):
+            return
+
+        data = self.extract_request_data(request)
+
+        # Build log message from configured fields only
+        message_parts = []
+        if "method" in self.config.request_log_fields and "method" in data:
+            message_parts.append(data["method"])
+        if "path" in self.config.request_log_fields and "path" in data:
+            message_parts.append(data["path"])
+
+        message = " ".join(message_parts) if message_parts else f"Request: {path}"
+
+        # Log requests at DEBUG level (less important than responses)
+        self.logger.log(logging.DEBUG, message, extra=data)
+
+    def log_response(
+        self,
+        request: Dict[str, Any],
+        status_code: int,
+        duration: float,
+        response_size: Optional[int] = None,
+    ) -> None:
+        """Log an HTTP response.
+
+        Args:
+            request: Request dictionary
+            status_code: HTTP status code
+            duration: Request duration in seconds
+            response_size: Response size in bytes (optional)
+        """
+        path = request.get("path", "")
+        if not self.config.should_log_request(path, status_code):
+            return
+
+        # Determine log level early and short-circuit if disabled for success path
+        if status_code >= 500:
+            log_level = logging.ERROR
+        elif status_code >= 400:
+            log_level = logging.WARNING
+        else:
+            log_level = logging.INFO
+
+        # For successful responses, apply gating: level check, sampling, and slow-only
+        if status_code < 400:
+            if not self.logger.isEnabledFor(log_level):
+                return
+            # Sampling gate
+            if self.config.sample_rate is not None:
+                try:
+                    if random.random() > float(self.config.sample_rate):
+                        return
+                except Exception:
+                    pass
+            # Slow-only gate
+            if self.config.min_duration_ms is not None:
+                duration_ms_check = (duration * 1000.0)
+                if duration_ms_check < float(self.config.min_duration_ms):
+                    return
+
+        data = {}
+        message_parts = []
+
+        # Only include method if configured
+        if "method" in self.config.request_log_fields:
+            method = request.get("method", "")
+            data["method"] = method
+            message_parts.append(method)
+
+        # Only include path if configured
+        if "path" in self.config.request_log_fields:
+            data["path"] = path
+            message_parts.append(path)
+
+        # Only include status_code if configured
+        if "status_code" in self.config.response_log_fields:
+            data["status_code"] = status_code
+            message_parts.append(f"{status_code}")
+
+        # Only include duration if configured
+        if "duration" in self.config.response_log_fields:
+            duration_ms = round(duration * 1000, 2)
+            data["duration_ms"] = duration_ms
+            message_parts.append(f"({duration_ms}ms)")
+
+        if "size" in self.config.response_log_fields and response_size is not None:
+            data["response_size"] = response_size
+
+        # Build log message from configured fields only
+        message = " ".join(message_parts) if message_parts else f"Response: {status_code}"
+
+        self.logger.log(log_level, message, extra=data)
+
+    def log_exception(
+        self,
+        request: Dict[str, Any],
+        exc: Exception,
+        exc_info: bool = True,
+    ) -> None:
+        """Log an exception that occurred during request handling.
+
+        Args:
+            request: Request dictionary
+            exc: Exception instance
+            exc_info: Whether to include exception traceback
+        """
+        path = request.get("path", "")
+
+        data = {
+            "method": request.get("method", ""),
+            "path": path,
+            "exception_type": type(exc).__name__,
+            "exception": str(exc),
+        }
+
+        message = f"Exception in {data['method']} {path}: {type(exc).__name__}: {str(exc)}"
+
+        # Use custom exception handler if provided
+        if self.config.exception_logging_handler:
+            self.config.exception_logging_handler(
+                self.logger, request, exc, exc_info
+            )
+        else:
+            # Default exception logging
+            log_level = getattr(logging, self.config.error_log_level.upper(), logging.ERROR)
+            self.logger.log(
+                log_level,
+                message,
+                extra=data,
+                exc_info=exc_info,
+            )
+
+
+# Convenience function to create logging middleware
+def create_logging_middleware(
+    logger_name: Optional[str] = None,
+    log_level: Optional[str] = None,
+    **kwargs
+) -> LoggingMiddleware:
+    """Create a logging middleware with custom configuration.
+
+    Args:
+        logger_name: Logger name (defaults to 'django.server')
+        log_level: Log level (defaults to DEBUG in DEBUG mode, INFO otherwise)
+        **kwargs: Additional configuration options
+
+    Returns:
+        LoggingMiddleware instance
+    """
+    from .config import get_default_logging_config
+
+    config = get_default_logging_config()
+
+    if logger_name:
+        config.logger_name = logger_name
+
+    if log_level:
+        config.log_level = log_level
+
+    # Update config with additional kwargs
+    for key, value in kwargs.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+
+    return LoggingMiddleware(config)

django_bolt/management/__init__.py

@@ -0,0 +1 @@
+# Django management commands package