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

django_cfg/apps/integrations/grpc/services/commands/__init__.py

@@ -0,0 +1,93 @@
+"""
+Universal Streaming Commands
+
+Provides reusable command client architecture for bidirectional gRPC streaming services.
+
+Quick Start:
+    1. Create your command client:
+        from django_cfg.apps.integrations.grpc.services.commands.base import StreamingCommandClient
+        from your_app.grpc import service_pb2 as pb2
+
+        class MyCommandClient(StreamingCommandClient[pb2.Command]):
+            async def _send_via_grpc(self, command):
+                # Implement gRPC call
+                async with grpc.aio.insecure_channel(self.get_grpc_address()) as channel:
+                    stub = service_pb2_grpc.YourServiceStub(channel)
+                    request = pb2.SendCommandRequest(client_id=self.client_id, command=command)
+                    response = await stub.SendCommandToClient(request)
+                    return response.success
+
+    2. Register your streaming service:
+        from django_cfg.apps.integrations.grpc.services.commands.registry import register_streaming_service
+
+        def grpc_handlers(server):
+            servicer = YourService()
+            register_streaming_service("your_service", servicer._streaming_service)
+            # ...
+
+    3. Use the client:
+        # Cross-process mode
+        client = MyCommandClient(client_id="123", grpc_port=50051)
+        await client.send_command(command)
+
+        # Same-process mode
+        from django_cfg.apps.integrations.grpc.services.commands.registry import get_streaming_service
+        service = get_streaming_service("your_service")
+        client = MyCommandClient(client_id="123", streaming_service=service)
+        await client.send_command(command)
+
+Documentation:
+    See @commands/ directory for complete documentation:
+    - README.md: Overview and quick start
+    - ARCHITECTURE.md: System design
+    - EXAMPLES.md: Code examples
+    - INDEX.md: Navigation hub
+
+Version: 1.0.0
+"""
+
+from .base import (
+    StreamingCommandClient,
+    CommandClientConfig,
+    CommandError,
+    CommandTimeoutError,
+    ClientNotConnectedError,
+    TCommand,
+)
+from .registry import (
+    register_streaming_service,
+    get_streaming_service,
+    unregister_streaming_service,
+    list_streaming_services,
+    is_registered,
+    clear_registry,
+    set_streaming_service,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Base classes
+    'StreamingCommandClient',
+    'CommandClientConfig',
+
+    # Exceptions
+    'CommandError',
+    'CommandTimeoutError',
+    'ClientNotConnectedError',
+
+    # Registry functions
+    'register_streaming_service',
+    'get_streaming_service',
+    'unregister_streaming_service',
+    'list_streaming_services',
+    'is_registered',
+    'clear_registry',
+    'set_streaming_service',
+
+    # Type variables
+    'TCommand',
+
+    # Version
+    '__version__',
+]

django_cfg/apps/integrations/grpc/services/commands/base.py

@@ -0,0 +1,243 @@
+"""
+Universal Streaming Command Client - Base Implementation
+
+This module provides a generic, reusable command client for bidirectional gRPC streaming services.
+
+Key Features:
+- Dual-mode: Same-process (direct queue) or Cross-process (gRPC RPC)
+- Type-safe: Generic[TCommand] for different protobuf types
+- Auto-detection: Automatically chooses the right mode
+- Minimal coupling: Works with any BidirectionalStreamingService
+
+Usage:
+    from your_app.grpc.commands.base import StreamingCommandClient
+    from your_app.grpc import your_service_pb2 as pb2
+
+    class YourCommandClient(StreamingCommandClient[pb2.Command]):
+        pass
+
+Documentation: See @commands/README.md for complete guide
+"""
+
+import asyncio
+import logging
+from abc import ABC
+from dataclasses import dataclass
+from typing import Generic, Optional, TypeVar, Any
+
+try:
+    import grpc
+    GRPC_AVAILABLE = True
+except ImportError:
+    GRPC_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+# Generic type for protobuf command messages
+TCommand = TypeVar('TCommand')
+
+
+@dataclass
+class CommandClientConfig:
+    """Configuration for command client behavior."""
+
+    # Queue timeout for same-process mode (seconds)
+    queue_timeout: float = 5.0
+
+    # gRPC connection timeout for cross-process mode (seconds)
+    connect_timeout: float = 3.0
+
+    # gRPC call timeout (seconds)
+    call_timeout: float = 5.0
+
+    # Default gRPC server address
+    grpc_host: str = "localhost"
+
+    # Default gRPC server port (can be overridden)
+    grpc_port: Optional[int] = None
+
+
+class StreamingCommandClient(Generic[TCommand], ABC):
+    """
+    Universal command client for bidirectional streaming services.
+
+    Supports two modes:
+    1. Same-process: Direct queue access when streaming_service is provided
+    2. Cross-process: gRPC RPC call when streaming_service is None
+
+    Type Parameters:
+        TCommand: The protobuf message type for commands
+
+    Example:
+        # Same-process mode
+        from your_app.grpc.services.registry import get_streaming_service
+
+        service = get_streaming_service("your_service")
+        client = YourCommandClient(
+            client_id="client-123",
+            streaming_service=service
+        )
+
+        # Cross-process mode
+        client = YourCommandClient(
+            client_id="client-123",
+            grpc_port=50051
+        )
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        streaming_service: Optional[Any] = None,
+        config: Optional[CommandClientConfig] = None,
+        grpc_port: Optional[int] = None,
+        grpc_host: Optional[str] = None,
+    ):
+        """
+        Initialize command client.
+
+        Args:
+            client_id: Unique identifier for the client
+            streaming_service: BidirectionalStreamingService instance for same-process mode
+            config: Configuration object (uses defaults if not provided)
+            grpc_port: Override gRPC port for cross-process mode
+            grpc_host: Override gRPC host for cross-process mode
+        """
+        self.client_id = client_id
+        self._streaming_service = streaming_service
+        self.config = config or CommandClientConfig()
+
+        # Override config with provided values
+        if grpc_port is not None:
+            self.config.grpc_port = grpc_port
+        if grpc_host is not None:
+            self.config.grpc_host = grpc_host
+
+        # Determine mode
+        self._is_same_process = streaming_service is not None
+
+        logger.debug(
+            f"Initialized {self.__class__.__name__} for client_id={client_id}, "
+            f"mode={'same-process' if self._is_same_process else 'cross-process'}"
+        )
+
+    async def _send_command(self, command: TCommand) -> bool:
+        """
+        Send command to client (auto-detects mode).
+
+        Args:
+            command: Protobuf command message
+
+        Returns:
+            True if command was sent successfully, False otherwise
+
+        Raises:
+            RuntimeError: If gRPC is not available in cross-process mode
+        """
+        if self._is_same_process:
+            return await self._send_direct(command)
+        else:
+            return await self._send_via_grpc(command)
+
+    async def _send_direct(self, command: TCommand) -> bool:
+        """
+        Send command directly via queue (same-process mode).
+
+        Args:
+            command: Protobuf command message
+
+        Returns:
+            True if command was queued, False if client not connected
+        """
+        try:
+            success = await self._streaming_service.send_to_client(
+                client_id=self.client_id,
+                command=command,
+                timeout=self.config.queue_timeout
+            )
+
+            if success:
+                logger.debug(f"Command sent to {self.client_id} (same-process)")
+            else:
+                logger.warning(f"Client {self.client_id} not connected")
+
+            return success
+
+        except asyncio.TimeoutError:
+            logger.error(
+                f"Timeout sending command to {self.client_id} "
+                f"(timeout={self.config.queue_timeout}s)"
+            )
+            return False
+        except Exception as e:
+            logger.error(
+                f"Error sending command to {self.client_id}: {e}",
+                exc_info=True
+            )
+            return False
+
+    async def _send_via_grpc(self, command: TCommand) -> bool:
+        """
+        Send command via gRPC RPC (cross-process mode).
+
+        This method should be overridden in subclasses to implement
+        the actual gRPC call with service-specific stub and request.
+
+        Args:
+            command: Protobuf command message
+
+        Returns:
+            True if RPC succeeded, False otherwise
+
+        Raises:
+            NotImplementedError: Must be implemented in subclass
+            RuntimeError: If gRPC is not available
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement _send_via_grpc() "
+            "for cross-process communication. See EXAMPLES.md for reference."
+        )
+
+    def is_same_process(self) -> bool:
+        """Check if running in same-process mode."""
+        return self._is_same_process
+
+    def get_grpc_address(self) -> str:
+        """Get gRPC server address for cross-process mode."""
+        if self.config.grpc_port is None:
+            # Try to auto-detect from django-cfg config
+            try:
+                from django_cfg.core.config import get_current_config
+                self.config.grpc_port = get_current_config().grpc.port
+                logger.debug(f"Auto-detected gRPC port: {self.config.grpc_port}")
+            except Exception as e:
+                raise ValueError(
+                    f"grpc_port not configured and auto-detection failed: {e}. "
+                    "Either set it in config or pass to __init__"
+                )
+        return f"{self.config.grpc_host}:{self.config.grpc_port}"
+
+
+class CommandError(Exception):
+    """Base exception for command-related errors."""
+    pass
+
+
+class CommandTimeoutError(CommandError):
+    """Raised when command send times out."""
+    pass
+
+
+class ClientNotConnectedError(CommandError):
+    """Raised when client is not connected."""
+    pass
+
+
+__all__ = [
+    'StreamingCommandClient',
+    'CommandClientConfig',
+    'CommandError',
+    'CommandTimeoutError',
+    'ClientNotConnectedError',
+    'TCommand',
+]

django_cfg/apps/integrations/grpc/services/commands/examples/__init__.py

@@ -0,0 +1,22 @@
+"""
+Example Command Implementations
+
+This package contains example command implementations that demonstrate
+the universal streaming command pattern.
+
+These examples show:
+- How to decompose commands into separate modules
+- How to use Protocol for type-safe model operations
+- How to implement Django async ORM updates
+- How to build a wrapper client class
+
+To use these examples in your project:
+1. Copy the pattern from base_client.py
+2. Adapt command functions (start.py, stop.py, config.py) to your needs
+3. Create a wrapper client class (client.py)
+4. Update protobuf imports to match your service
+
+See @commands/EXAMPLES.md for detailed documentation.
+"""
+
+__all__ = []

django_cfg/apps/integrations/grpc/services/commands/examples/base_client.py

@@ -0,0 +1,228 @@
+"""
+Example: Base Command Client Implementation
+
+This example shows how to extend StreamingCommandClient for a specific gRPC service.
+It implements the _send_via_grpc method for cross-process communication.
+
+Copy this pattern and adapt it to your service:
+1. Update protobuf imports (your_service_pb2, your_service_pb2_grpc)
+2. Update Command type to match your proto
+3. Update stub class name
+4. Update SendCommandRequest message structure
+5. Optionally add model type hints using Protocol
+
+Usage:
+    # Import your extended client
+    from your_app.grpc.commands.base_client import ExampleCommandClient
+
+    # Cross-process mode
+    client = ExampleCommandClient(client_id="123", grpc_port=50051)
+
+    # Same-process mode
+    from django_cfg.apps.integrations.grpc.services.commands.registry import get_streaming_service
+    service = get_streaming_service("example")
+    client = ExampleCommandClient(client_id="123", streaming_service=service)
+"""
+
+import logging
+from typing import Any, Optional, Protocol, runtime_checkable
+
+from django_cfg.apps.integrations.grpc.services.commands.base import (
+    StreamingCommandClient,
+    CommandClientConfig,
+)
+
+# IMPORTANT: Update these imports to match your protobuf files
+# Example assumes you have:
+# - your_service_pb2.py (generated from your_service.proto)
+# - your_service_pb2_grpc.py (generated gRPC stub)
+#
+# from your_app.grpc.generated import your_service_pb2 as pb2
+# from your_app.grpc.generated import your_service_pb2_grpc as pb2_grpc
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Protocol for Type-Safe Model Operations
+# ============================================================================
+
+@runtime_checkable
+class HasStatus(Protocol):
+    """
+    Protocol for models that have a status field.
+
+    This allows type-safe operations on Django models without tight coupling.
+    Any model with these attributes/methods will pass type checking.
+
+    Example Django model:
+        class YourModel(models.Model):
+            status = models.CharField(max_length=20)
+
+            # Django 5.2+ async save
+            async def asave(self, update_fields=None):
+                ...
+    """
+    status: str
+
+    async def asave(self, update_fields: Optional[list[str]] = None) -> None:
+        """Django async save method (Django 5.2+)."""
+        ...
+
+
+@runtime_checkable
+class HasConfig(Protocol):
+    """
+    Protocol for models that have configuration.
+
+    Example Django model:
+        class YourModel(models.Model):
+            config = models.JSONField(default=dict)
+
+            async def asave(self, update_fields=None):
+                ...
+    """
+    config: dict
+
+    async def asave(self, update_fields: Optional[list[str]] = None) -> None:
+        """Django async save method."""
+        ...
+
+
+# ============================================================================
+# Example Command Client
+# ============================================================================
+
+class ExampleCommandClient(StreamingCommandClient):  # [pb2.Command]
+    """
+    Example implementation of universal command client.
+
+    This shows how to extend StreamingCommandClient with gRPC implementation.
+
+    Type Parameters:
+        TCommand: Should be your protobuf Command type (e.g., pb2.Command)
+
+    Note: The type parameter is commented out because protobuf imports
+    are not available in this example. In your implementation, use:
+
+        class YourCommandClient(StreamingCommandClient[pb2.Command]):
+            ...
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        model: Optional[Any] = None,
+        streaming_service: Optional[Any] = None,
+        config: Optional[CommandClientConfig] = None,
+        grpc_port: Optional[int] = None,
+        grpc_host: Optional[str] = None,
+    ):
+        """
+        Initialize example command client.
+
+        Args:
+            client_id: Unique identifier for the client
+            model: Optional Django model instance (for callbacks)
+            streaming_service: BidirectionalStreamingService for same-process mode
+            config: Client configuration
+            grpc_port: gRPC port for cross-process mode
+            grpc_host: gRPC host for cross-process mode
+        """
+        super().__init__(
+            client_id=client_id,
+            streaming_service=streaming_service,
+            config=config,
+            grpc_port=grpc_port,
+            grpc_host=grpc_host,
+        )
+        self.model = model
+
+    async def _send_via_grpc(self, command) -> bool:  # command: pb2.Command
+        """
+        Send command via gRPC RPC (cross-process mode).
+
+        This implements the abstract method from StreamingCommandClient.
+
+        Args:
+            command: Protobuf command message (pb2.Command)
+
+        Returns:
+            True if RPC succeeded, False otherwise
+
+        Implementation guide:
+            1. Import grpc and your stubs at the top of the file:
+               import grpc
+               from your_app.grpc.generated import your_service_pb2_grpc as pb2_grpc
+               from your_app.grpc.generated import your_service_pb2 as pb2
+
+            2. Create gRPC channel
+            3. Create stub instance
+            4. Create request message with client_id and command
+            5. Call SendCommandToClient RPC
+            6. Return response.success
+        """
+        # This is a template - you need to implement with your actual protobuf types
+
+        logger.warning(
+            "Example implementation: _send_via_grpc is not implemented. "
+            "Please copy this file and implement with your actual protobuf types."
+        )
+
+        # Example implementation (uncomment and adapt):
+        #
+        # try:
+        #     import grpc
+        #
+        #     async with grpc.aio.insecure_channel(
+        #         self.get_grpc_address(),
+        #         options=[
+        #             ('grpc.keepalive_time_ms', 10000),
+        #             ('grpc.keepalive_timeout_ms', 5000),
+        #         ]
+        #     ) as channel:
+        #         stub = pb2_grpc.YourServiceStub(channel)
+        #
+        #         # Create request with your service's message structure
+        #         request = pb2.SendCommandRequest(
+        #             client_id=self.client_id,
+        #             command=command,
+        #         )
+        #
+        #         # Call your service's SendCommandToClient RPC
+        #         response = await stub.SendCommandToClient(
+        #             request,
+        #             timeout=self.config.call_timeout
+        #         )
+        #
+        #         if response.success:
+        #             logger.debug(f"Command sent to {self.client_id} via gRPC")
+        #             return True
+        #         else:
+        #             logger.warning(
+        #                 f"Command failed for {self.client_id}: {response.message}"
+        #             )
+        #             return False
+        #
+        # except grpc.RpcError as e:
+        #     logger.error(
+        #         f"gRPC error sending command to {self.client_id}: "
+        #         f"{e.code()} - {e.details()}",
+        #         exc_info=True
+        #     )
+        #     return False
+        # except Exception as e:
+        #     logger.error(
+        #         f"Error sending command to {self.client_id}: {e}",
+        #         exc_info=True
+        #     )
+        #     return False
+
+        return False
+
+
+__all__ = [
+    'ExampleCommandClient',
+    'HasStatus',
+    'HasConfig',
+]