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

django_cfg/apps/integrations/grpc/auth/api_key_auth.py

@@ -0,0 +1,320 @@
+"""
+API Key Authentication Interceptor for gRPC.
+
+Handles API key verification and Django user authentication for gRPC requests.
+Simple, secure, and manageable through Django admin.
+"""
+
+import asyncio
+import contextvars
+import logging
+from typing import Callable, Optional
+
+import grpc
+import grpc.aio
+from django.conf import settings
+from django.contrib.auth import get_user_model
+
+logger = logging.getLogger(__name__)
+
+User = get_user_model()
+
+# Context variables for passing user/api_key between async interceptors
+_grpc_user_var: contextvars.ContextVar = contextvars.ContextVar('grpc_user', default=None)
+_grpc_api_key_var: contextvars.ContextVar = contextvars.ContextVar('grpc_api_key', default=None)
+
+
+class ApiKeyAuthInterceptor(grpc.aio.ServerInterceptor):
+    """
+    gRPC interceptor for API key authentication.
+
+    Features:
+    - Validates API keys from database (GrpcApiKey model)
+    - Accepts Django SECRET_KEY for development/internal use
+    - Loads Django user from API key
+    - Sets user on request context
+    - Supports public methods whitelist
+    - Tracks API key usage
+    - Handles authentication errors gracefully
+
+    Example:
+        ```python
+        # In Django settings (auto-configured by django-cfg)
+        GRPC_FRAMEWORK = {
+            "SERVER_INTERCEPTORS": [
+                "django_cfg.apps.integrations.grpc.auth.ApiKeyAuthInterceptor",
+            ]
+        }
+        ```
+
+    API Key Format:
+        x-api-key: <api_key_string>
+
+    Or for SECRET_KEY:
+        x-api-key: <Django SECRET_KEY>
+    """
+
+    def __init__(self):
+        """Initialize API key authentication interceptor."""
+        self.grpc_auth_config = getattr(settings, "GRPC_AUTH", {})
+        self.enabled = self.grpc_auth_config.get("enabled", True)
+        self.require_auth = self.grpc_auth_config.get("require_auth", False)
+
+        # API Key settings
+        self.api_key_header = self.grpc_auth_config.get("api_key_header", "x-api-key")
+        self.accept_django_secret_key = self.grpc_auth_config.get(
+            "accept_django_secret_key", True
+        )
+
+        # Public methods (don't require auth)
+        self.public_methods = self.grpc_auth_config.get("public_methods", [
+            "/grpc.health.v1.Health/Check",
+            "/grpc.health.v1.Health/Watch",
+            "/grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo",
+        ])
+
+    async def intercept_service(
+        self,
+        continuation: Callable,
+        handler_call_details: grpc.HandlerCallDetails
+    ) -> grpc.RpcMethodHandler:
+        """
+        Intercept gRPC service call for authentication (async).
+
+        Args:
+            continuation: Function to invoke the next interceptor or handler
+            handler_call_details: Details about the RPC call
+
+        Returns:
+            RPC method handler (possibly wrapped with auth)
+        """
+        # Skip if auth is disabled
+        if not self.enabled:
+            return await continuation(handler_call_details)
+
+        # Check if method is public
+        method_name = handler_call_details.method
+        if method_name in self.public_methods:
+            logger.debug(f"Public method accessed: {method_name}")
+            return await continuation(handler_call_details)
+
+        # Extract API key from metadata
+        api_key = self._extract_api_key(handler_call_details.invocation_metadata)
+
+        # If no API key provided
+        if not api_key:
+            if self.require_auth:
+                logger.warning(f"Missing API key for {method_name}")
+                return self._abort_unauthenticated("API key is required")
+            else:
+                # Allow anonymous access (no user/api_key in context)
+                logger.debug(f"No API key provided for {method_name}, allowing anonymous access")
+                return await continuation(handler_call_details)
+
+        # Verify API key and get user + api_key instance (async)
+        user, api_key_instance = await self._verify_api_key(api_key)
+
+        # If API key is valid, ALWAYS set user and api_key in context (even if require_auth=False)
+        if user:
+            logger.debug(f"Authenticated user {user.id} ({user.username}) for {method_name}")
+            return await self._continue_with_user(continuation, handler_call_details, user, api_key_instance)
+
+        # API key provided but invalid
+        if self.require_auth:
+            logger.warning(f"Invalid API key for {method_name}")
+            return self._abort_unauthenticated("Invalid or expired API key")
+        else:
+            # Allow anonymous access even with invalid key
+            logger.debug(f"Invalid API key for {method_name}, allowing anonymous access")
+            return await continuation(handler_call_details)
+
+    def _extract_api_key(self, metadata: tuple) -> Optional[str]:
+        """
+        Extract API key from gRPC metadata.
+
+        Args:
+            metadata: gRPC invocation metadata
+
+        Returns:
+            API key string or None
+        """
+        if not metadata:
+            return None
+
+        # Convert metadata to dict (case-insensitive lookup)
+        metadata_dict = dict(metadata)
+
+        # Get API key header (case-insensitive)
+        for key, value in metadata_dict.items():
+            if key.lower() == self.api_key_header.lower():
+                return value
+
+        return None
+
+    async def _verify_api_key(self, api_key: str) -> tuple[Optional[User], Optional["GrpcApiKey"]]:
+        """
+        Verify API key and return user and api_key instance (async).
+
+        Checks:
+        1. Django SECRET_KEY (if enabled)
+        2. GrpcApiKey model in database
+
+        Args:
+            api_key: API key string
+
+        Returns:
+            Tuple of (Django User instance or None, GrpcApiKey instance or None)
+        """
+        # Check if it's Django SECRET_KEY
+        if self.accept_django_secret_key and api_key == settings.SECRET_KEY:
+            logger.debug("API key matches Django SECRET_KEY")
+            # For SECRET_KEY, return first superuser or None (no api_key instance)
+            try:
+                # Wrap Django ORM in asyncio.to_thread()
+                superuser = await asyncio.to_thread(
+                    lambda: User.objects.filter(is_superuser=True, is_active=True).first()
+                )
+                if superuser:
+                    return superuser, None
+                else:
+                    logger.warning("No active superuser found for SECRET_KEY authentication")
+                    return None, None
+            except Exception as e:
+                logger.error(f"Error loading superuser for SECRET_KEY: {e}")
+                return None, None
+
+        # Check API key in database
+        try:
+            from django_cfg.apps.integrations.grpc.models import GrpcApiKey
+
+            # Wrap Django ORM in asyncio.to_thread()
+            api_key_obj = await asyncio.to_thread(
+                lambda: GrpcApiKey.objects.filter(key=api_key, is_active=True).first()
+            )
+
+            if api_key_obj and api_key_obj.is_valid:
+                # Update usage tracking (also wrapped in to_thread)
+                await asyncio.to_thread(api_key_obj.mark_used)
+                logger.debug(f"Valid API key for user {api_key_obj.user.id} ({api_key_obj.user.username})")
+                return api_key_obj.user, api_key_obj
+            else:
+                logger.debug("API key not found or invalid in database")
+                return None, None
+
+        except Exception as e:
+            logger.error(f"Error validating API key: {e}")
+            return None, None
+
+    async def _continue_with_user(
+        self,
+        continuation: Callable,
+        handler_call_details: grpc.HandlerCallDetails,
+        user: User,
+        api_key_instance: Optional["GrpcApiKey"] = None,
+    ) -> grpc.RpcMethodHandler:
+        """
+        Continue RPC with authenticated user and api_key in context (async).
+
+        Args:
+            continuation: Function to invoke next interceptor or handler
+            handler_call_details: Details about the RPC call
+            user: Authenticated Django user
+            api_key_instance: GrpcApiKey instance used for authentication (if applicable)
+
+        Returns:
+            RPC method handler with user and api_key context
+        """
+        # Get the handler (await because continuation is async)
+        handler = await continuation(handler_call_details)
+
+        if handler is None:
+            return None
+
+        # Wrap the handler to inject user and api_key into contextvars (not context directly)
+        # All wrappers must be async for grpc.aio
+        async def wrapped_unary_unary(request, context):
+            # Set context variables for async context
+            _grpc_user_var.set(user)
+            _grpc_api_key_var.set(api_key_instance)
+            logger.info(f"[Auth] Set contextvar api_key = {api_key_instance} (user={user})")
+            return await handler.unary_unary(request, context)
+
+        async def wrapped_unary_stream(request, context):
+            # Set context variables for async context
+            _grpc_user_var.set(user)
+            _grpc_api_key_var.set(api_key_instance)
+            logger.info(f"[Auth] Set contextvar api_key = {api_key_instance} (user={user})")
+            async for response in handler.unary_stream(request, context):
+                yield response
+
+        async def wrapped_stream_unary(request_iterator, context):
+            # Set context variables for async context
+            _grpc_user_var.set(user)
+            _grpc_api_key_var.set(api_key_instance)
+            return await handler.stream_unary(request_iterator, context)
+
+        async def wrapped_stream_stream(request_iterator, context):
+            # Set context variables for async context
+            _grpc_user_var.set(user)
+            _grpc_api_key_var.set(api_key_instance)
+            async for response in handler.stream_stream(request_iterator, context):
+                yield response
+
+        # Return wrapped handler based on type
+        return grpc.unary_unary_rpc_method_handler(
+            wrapped_unary_unary,
+            request_deserializer=handler.request_deserializer,
+            response_serializer=handler.response_serializer,
+        ) if handler.unary_unary else (
+            grpc.unary_stream_rpc_method_handler(
+                wrapped_unary_stream,
+                request_deserializer=handler.request_deserializer,
+                response_serializer=handler.response_serializer,
+            ) if handler.unary_stream else (
+                grpc.stream_unary_rpc_method_handler(
+                    wrapped_stream_unary,
+                    request_deserializer=handler.request_deserializer,
+                    response_serializer=handler.response_serializer,
+                ) if handler.stream_unary else (
+                    grpc.stream_stream_rpc_method_handler(
+                        wrapped_stream_stream,
+                        request_deserializer=handler.request_deserializer,
+                        response_serializer=handler.response_serializer,
+                    ) if handler.stream_stream else None
+                )
+            )
+        )
+
+    def _abort_unauthenticated(self, message: str) -> grpc.RpcMethodHandler:
+        """
+        Return handler that aborts with UNAUTHENTICATED status.
+
+        Args:
+            message: Error message
+
+        Returns:
+            RPC method handler that aborts
+        """
+        def abort(*args, **kwargs):
+            context = args[1] if len(args) > 1 else None
+            if context:
+                context.abort(grpc.StatusCode.UNAUTHENTICATED, message)
+
+        return grpc.unary_unary_rpc_method_handler(
+            abort,
+            request_deserializer=lambda x: x,
+            response_serializer=lambda x: x,
+        )
+
+
+__all__ = ["ApiKeyAuthInterceptor", "get_current_grpc_user", "get_current_grpc_api_key"]
+
+
+def get_current_grpc_user():
+    """Get current gRPC user from context variables (async-safe)."""
+    return _grpc_user_var.get()
+
+
+def get_current_grpc_api_key():
+    """Get current gRPC API key from context variables (async-safe)."""
+    return _grpc_api_key_var.get()

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

@@ -0,0 +1,29 @@
+"""
+gRPC → Centrifugo Integration.
+
+Mixin and configuration for bridging gRPC streaming events to Centrifugo WebSocket.
+"""
+
+from .bridge import CentrifugoBridgeMixin
+from .config import ChannelConfig, CentrifugoChannels
+from .demo import (
+    DemoChannels,
+    DemoBridgeService,
+    test_complete_integration,
+    test_demo_service,
+    send_demo_event,
+)
+
+__all__ = [
+    # Core components
+    "CentrifugoBridgeMixin",
+    "ChannelConfig",
+    "CentrifugoChannels",
+
+    # Demo/testing
+    "DemoChannels",
+    "DemoBridgeService",
+    "test_complete_integration",
+    "test_demo_service",
+    "send_demo_event",
+]

django_cfg/apps/integrations/grpc/centrifugo/bridge.py

@@ -0,0 +1,277 @@
+"""
+Centrifugo Bridge Mixin for gRPC Services.
+
+Universal mixin that enables automatic publishing of gRPC stream events
+to Centrifugo WebSocket channels using Pydantic configuration.
+"""
+
+import logging
+import time
+from datetime import datetime, timezone as tz
+from typing import Dict, Optional, Any, TYPE_CHECKING
+
+from .config import CentrifugoChannels, ChannelConfig
+from .transformers import transform_protobuf_to_dict
+
+if TYPE_CHECKING:
+    from django_cfg.apps.integrations.centrifugo import CentrifugoClient
+
+logger = logging.getLogger(__name__)
+
+
+class CentrifugoBridgeMixin:
+    """
+    Universal mixin for publishing gRPC stream events to Centrifugo.
+
+    Uses Pydantic models for type-safe, validated configuration.
+
+    Features:
+    - Type-safe Pydantic configuration
+    - Automatic event publishing to WebSocket channels
+    - Built-in protobuf → JSON transformation
+    - Graceful degradation if Centrifugo unavailable
+    - Custom transform functions support
+    - Template-based channel naming
+    - Per-channel rate limiting
+    - Critical event bypassing
+
+    Usage:
+        ```python
+        from django_cfg.apps.integrations.grpc.mixins import (
+            CentrifugoBridgeMixin,
+            CentrifugoChannels,
+            ChannelConfig,
+        )
+
+        class BotChannels(CentrifugoChannels):
+            heartbeat: ChannelConfig = ChannelConfig(
+                template='bot#{bot_id}#heartbeat',
+                rate_limit=0.1
+            )
+            status: ChannelConfig = ChannelConfig(
+                template='bot#{bot_id}#status',
+                critical=True
+            )
+
+        class BotStreamingService(
+            bot_streaming_service_pb2_grpc.BotStreamingServiceServicer,
+            CentrifugoBridgeMixin
+        ):
+            centrifugo_channels = BotChannels()
+
+            async def ConnectBot(self, request_iterator, context):
+                async for message in request_iterator:
+                    # Your business logic
+                    await self._handle_message(bot_id, message)
+
+                    # Auto-publish to Centrifugo (1 line!)
+                    await self._notify_centrifugo(message, bot_id=bot_id)
+        ```
+    """
+
+    # Class-level Pydantic config (optional, can be set in __init__)
+    centrifugo_channels: Optional[CentrifugoChannels] = None
+
+    def __init__(self):
+        """Initialize Centrifugo bridge from Pydantic configuration."""
+        super().__init__()
+
+        # Instance attributes
+        self._centrifugo_enabled: bool = False
+        self._centrifugo_graceful: bool = True
+        self._centrifugo_client: Optional['CentrifugoClient'] = None
+        self._centrifugo_mappings: Dict[str, Dict[str, Any]] = {}
+        self._centrifugo_last_publish: Dict[str, float] = {}
+
+        # Auto-setup if config exists
+        if self.centrifugo_channels:
+            self._setup_from_pydantic_config(self.centrifugo_channels)
+
+    def _setup_from_pydantic_config(self, config: CentrifugoChannels):
+        """
+        Setup Centrifugo bridge from Pydantic configuration.
+
+        Args:
+            config: CentrifugoChannels instance with channel mappings
+        """
+        self._centrifugo_enabled = config.enabled
+        self._centrifugo_graceful = config.graceful_degradation
+
+        # Extract channel mappings
+        for field_name, channel_config in config.get_channel_mappings().items():
+            if channel_config.enabled:
+                self._centrifugo_mappings[field_name] = {
+                    'template': channel_config.template,
+                    'rate_limit': channel_config.rate_limit or config.default_rate_limit,
+                    'critical': channel_config.critical,
+                    'transform': channel_config.transform,
+                    'metadata': channel_config.metadata,
+                }
+
+        # Initialize client if enabled
+        if self._centrifugo_enabled and self._centrifugo_mappings:
+            self._initialize_centrifugo_client()
+
+    def _initialize_centrifugo_client(self):
+        """Lazy initialize Centrifugo client."""
+        try:
+            from django_cfg.apps.integrations.centrifugo import get_centrifugo_client
+            self._centrifugo_client = get_centrifugo_client()
+            logger.info(
+                f"✅ Centrifugo bridge enabled with {len(self._centrifugo_mappings)} channels"
+            )
+        except Exception as e:
+            logger.warning(f"⚠️ Centrifugo client not available: {e}")
+            if not self._centrifugo_graceful:
+                raise
+            self._centrifugo_enabled = False
+
+    async def _notify_centrifugo(
+        self,
+        message: Any,  # Protobuf message
+        **context: Any  # Template variables for channel rendering
+    ) -> bool:
+        """
+        Publish protobuf message to Centrifugo based on configured mappings.
+
+        Automatically detects which field is set in the message and publishes
+        to the corresponding channel.
+
+        Args:
+            message: Protobuf message (e.g., BotMessage with heartbeat/status/etc.)
+            **context: Template variables for channel name rendering
+                Example: bot_id='123', user_id='456'
+
+        Returns:
+            True if published successfully, False otherwise
+
+        Example:
+            ```python
+            # message = BotMessage with heartbeat field set
+            await self._notify_centrifugo(message, bot_id='bot-123')
+            # → Publishes to channel: bot#bot-123#heartbeat
+            ```
+        """
+        if not self._centrifugo_enabled or not self._centrifugo_client:
+            return False
+
+        # Check each mapped field
+        for field_name, mapping in self._centrifugo_mappings.items():
+            if message.HasField(field_name):
+                return await self._publish_field(
+                    field_name,
+                    message,
+                    mapping,
+                    context
+                )
+
+        return False
+
+    async def _publish_field(
+        self,
+        field_name: str,
+        message: Any,
+        mapping: Dict[str, Any],
+        context: dict
+    ) -> bool:
+        """
+        Publish specific message field to Centrifugo.
+
+        Args:
+            field_name: Name of the protobuf field
+            message: Full protobuf message
+            mapping: Channel mapping configuration
+            context: Template variables
+
+        Returns:
+            True if published successfully
+        """
+        try:
+            # Render channel from template
+            channel = mapping['template'].format(**context)
+
+            # Rate limiting check (unless critical)
+            if not mapping['critical'] and mapping['rate_limit']:
+                now = time.time()
+                last = self._centrifugo_last_publish.get(channel, 0)
+                if now - last < mapping['rate_limit']:
+                    logger.debug(f"⏱️ Rate limit: skipping {field_name} for {channel}")
+                    return False
+                self._centrifugo_last_publish[channel] = now
+
+            # Get field value
+            field_value = getattr(message, field_name)
+
+            # Transform to dict
+            data = self._transform_field(field_name, field_value, mapping, context)
+
+            # Publish to Centrifugo
+            await self._centrifugo_client.publish(
+                channel=channel,
+                data=data
+            )
+
+            logger.debug(f"✅ Published {field_name} to {channel}")
+            return True
+
+        except KeyError as e:
+            logger.error(
+                f"❌ Missing template variable in channel: {e}. "
+                f"Template: {mapping['template']}, Context: {context}"
+            )
+            return False
+
+        except Exception as e:
+            logger.error(
+                f"❌ Failed to publish {field_name} to Centrifugo: {e}",
+                exc_info=True
+            )
+            if not self._centrifugo_graceful:
+                raise
+            return False
+
+    def _transform_field(
+        self,
+        field_name: str,
+        field_value: Any,
+        mapping: Dict[str, Any],
+        context: dict
+    ) -> dict:
+        """
+        Transform protobuf field to JSON-serializable dict.
+
+        Args:
+            field_name: Field name
+            field_value: Protobuf message field value
+            mapping: Channel mapping with optional transform function
+            context: Template context variables
+
+        Returns:
+            JSON-serializable dictionary
+        """
+        # Use custom transform if provided
+        if mapping['transform']:
+            data = mapping['transform'](field_name, field_value)
+        else:
+            # Default protobuf → dict transform
+            data = transform_protobuf_to_dict(field_value)
+
+        # Add metadata
+        data['type'] = field_name
+        data['timestamp'] = datetime.now(tz.utc).isoformat()
+
+        # Merge channel metadata
+        if mapping['metadata']:
+            for key, value in mapping['metadata'].items():
+                if key not in data:
+                    data[key] = value
+
+        # Add context variables (bot_id, user_id, etc.)
+        for key, value in context.items():
+            if key not in data:
+                data[key] = value
+
+        return data
+
+
+__all__ = ["CentrifugoBridgeMixin"]