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

django_cfg/apps/integrations/grpc/services/streaming/types.py

@@ -0,0 +1,367 @@
+"""
+Protocol type definitions for type-safe gRPC bidirectional streaming.
+
+This module defines Protocol types used for generic, reusable gRPC streaming components.
+All protocols are fully typed and support generic message/command types.
+
+**Design Goals**:
+- 100% type-safe callbacks
+- Zero runtime overhead (protocols are compile-time only)
+- Compatible with any protobuf message types
+- Enables IDE autocomplete and mypy validation
+
+**Usage Example**:
+```python
+# Define your processor
+async def process_signal_message(
+    client_id: str,
+    message: SignalCommand,
+    output_queue: asyncio.Queue[SignalMessage]
+) -> None:
+    # Your logic here
+    await output_queue.put(response)
+
+# Type checker validates signature matches MessageProcessor protocol
+service = BidirectionalStreamingService(
+    message_processor=process_signal_message,  # ✅ Type-safe
+    ...
+)
+```
+
+Created: 2025-11-07
+Status: %%PRODUCTION%%
+Phase: Phase 1 - Universal Components
+"""
+
+from typing import Protocol, TypeVar, Any
+import asyncio
+
+
+# ============================================================================
+# Generic Type Variables
+# ============================================================================
+
+TMessage = TypeVar('TMessage', contravariant=True)
+"""
+Generic type for incoming gRPC messages (commands from client).
+
+**Contravariant**: Allows passing more specific message types where generic is expected.
+
+Example:
+    - Protocol expects: Message (base)
+    - Can pass: SignalCommand (subclass)
+"""
+
+TCommand = TypeVar('TCommand', covariant=True)
+"""
+Generic type for outgoing gRPC commands (responses to client).
+
+**Covariant**: Allows returning more general command types where specific is expected.
+
+Example:
+    - Protocol returns: BotResponse (specific)
+    - Can be treated as: Message (base)
+"""
+
+
+# ============================================================================
+# Core Processing Protocols
+# ============================================================================
+
+class MessageProcessor(Protocol[TMessage, TCommand]):
+    """
+    Protocol for processing incoming gRPC messages and generating responses.
+
+    This is the core business logic handler that processes each message from the client
+    and optionally enqueues response commands.
+
+    **Type Parameters**:
+        TMessage: Type of incoming messages (e.g., SignalCommand, BotCommand)
+        TCommand: Type of outgoing commands (e.g., SignalMessage, BotResponse)
+
+    **Signature**:
+        async def(client_id: str, message: TMessage, output_queue: Queue[TCommand]) -> None
+
+    **Parameters**:
+        client_id: Unique identifier for the connected client
+        message: Incoming message from client (generic type TMessage)
+        output_queue: Queue to enqueue response commands (generic type TCommand)
+
+    **Example Implementation**:
+    ```python
+    async def process_bot_command(
+        client_id: str,
+        message: BotCommand,
+        output_queue: asyncio.Queue[BotResponse]
+    ) -> None:
+        logger.info(f"Processing command for {client_id}")
+
+        if message.command_type == CommandType.START:
+            response = BotResponse(status="started")
+            await output_queue.put(response)
+    ```
+    """
+    async def __call__(
+        self,
+        client_id: str,
+        message: TMessage,
+        output_queue: asyncio.Queue[TCommand]
+    ) -> None:
+        """Process incoming message and optionally enqueue responses."""
+        ...
+
+
+class ClientIdExtractor(Protocol[TMessage]):
+    """
+    Protocol for extracting client ID from incoming gRPC messages.
+
+    Different services may store client IDs in different message fields.
+    This protocol allows type-safe client ID extraction.
+
+    **Type Parameters**:
+        TMessage: Type of incoming messages
+
+    **Signature**:
+        def(message: TMessage) -> str
+
+    **Example Implementation**:
+    ```python
+    def extract_bot_client_id(message: BotCommand) -> str:
+        return str(message.bot_id)
+
+    def extract_signal_client_id(message: SignalCommand) -> str:
+        return message.client_id
+    ```
+    """
+    def __call__(self, message: TMessage) -> str:
+        """Extract client ID from message."""
+        ...
+
+
+class PingMessageCreator(Protocol[TCommand]):
+    """
+    Protocol for creating ping/keepalive messages.
+
+    Bidirectional streams need periodic ping messages to keep connections alive.
+    This protocol allows type-safe ping message creation.
+
+    **Type Parameters**:
+        TCommand: Type of outgoing commands
+
+    **Signature**:
+        def() -> TCommand
+
+    **Example Implementation**:
+    ```python
+    def create_bot_ping() -> BotResponse:
+        return BotResponse(
+            message_type=MessageType.PING,
+            timestamp=int(time.time())
+        )
+
+    def create_signal_ping() -> SignalMessage:
+        return SignalMessage(is_ping=True)
+    ```
+    """
+    def __call__(self) -> TCommand:
+        """Create a ping message."""
+        ...
+
+
+# ============================================================================
+# Connection Management Protocols
+# ============================================================================
+
+class ConnectionCallback(Protocol):
+    """
+    Protocol for connection lifecycle callbacks.
+
+    **Signature**:
+        async def(client_id: str) -> None
+
+    **Use Cases**:
+        - on_connect: Initialize resources, log connection
+        - on_disconnect: Cleanup resources, update database
+        - on_error: Handle connection errors
+
+    **Example Implementation**:
+    ```python
+    async def on_client_connected(client_id: str) -> None:
+        logger.info(f"Client {client_id} connected")
+        await db.mark_client_active(client_id)
+
+    async def on_client_disconnected(client_id: str) -> None:
+        logger.info(f"Client {client_id} disconnected")
+        await db.mark_client_inactive(client_id)
+    ```
+    """
+    async def __call__(self, client_id: str) -> None:
+        """Handle connection lifecycle event."""
+        ...
+
+
+class ErrorHandler(Protocol):
+    """
+    Protocol for handling errors during streaming.
+
+    **Signature**:
+        async def(client_id: str, error: Exception) -> None
+
+    **Example Implementation**:
+    ```python
+    async def handle_stream_error(client_id: str, error: Exception) -> None:
+        logger.error(f"Error for {client_id}: {error}")
+
+        if isinstance(error, asyncio.CancelledError):
+            # Normal cancellation, just log
+            pass
+        elif isinstance(error, grpc.RpcError):
+            # gRPC-specific error handling
+            await notify_admin(client_id, error)
+        else:
+            # Unexpected error, escalate
+            raise
+    ```
+    """
+    async def __call__(self, client_id: str, error: Exception) -> None:
+        """Handle streaming error."""
+        ...
+
+
+# ============================================================================
+# Type Aliases for Common Patterns
+# ============================================================================
+
+MessageProcessorType = MessageProcessor[Any, Any]
+"""Type alias for MessageProcessor without generic constraints."""
+
+ClientIdExtractorType = ClientIdExtractor[Any]
+"""Type alias for ClientIdExtractor without generic constraints."""
+
+PingMessageCreatorType = PingMessageCreator[Any]
+"""Type alias for PingMessageCreator without generic constraints."""
+
+
+# ============================================================================
+# Type Guards and Validation
+# ============================================================================
+
+def is_valid_message_processor(func: Any) -> bool:
+    """
+    Runtime check if function matches MessageProcessor protocol.
+
+    **Parameters**:
+        func: Function to validate
+
+    **Returns**:
+        True if function signature matches protocol
+
+    **Example**:
+    ```python
+    async def my_processor(client_id: str, msg: Command, queue: Queue) -> None:
+        pass
+
+    assert is_valid_message_processor(my_processor)  # ✅
+    ```
+    """
+    if not callable(func):
+        return False
+
+    import inspect
+    sig = inspect.signature(func)
+    params = list(sig.parameters.values())
+
+    return (
+        len(params) == 3 and
+        params[0].annotation in (str, inspect.Parameter.empty) and
+        inspect.iscoroutinefunction(func)
+    )
+
+
+def is_valid_client_id_extractor(func: Any) -> bool:
+    """
+    Runtime check if function matches ClientIdExtractor protocol.
+
+    **Parameters**:
+        func: Function to validate
+
+    **Returns**:
+        True if function signature matches protocol
+
+    **Example**:
+    ```python
+    def extract_id(msg: Command) -> str:
+        return msg.client_id
+
+    assert is_valid_client_id_extractor(extract_id)  # ✅
+    ```
+    """
+    if not callable(func):
+        return False
+
+    import inspect
+    sig = inspect.signature(func)
+    params = list(sig.parameters.values())
+
+    return (
+        len(params) == 1 and
+        sig.return_annotation in (str, inspect.Parameter.empty)
+    )
+
+
+def is_valid_ping_creator(func: Any) -> bool:
+    """
+    Runtime check if function matches PingMessageCreator protocol.
+
+    **Parameters**:
+        func: Function to validate
+
+    **Returns**:
+        True if function signature matches protocol
+
+    **Example**:
+    ```python
+    def create_ping() -> Message:
+        return Message(is_ping=True)
+
+    assert is_valid_ping_creator(create_ping)  # ✅
+    ```
+    """
+    if not callable(func):
+        return False
+
+    import inspect
+    sig = inspect.signature(func)
+    params = list(sig.parameters.values())
+
+    return len(params) == 0
+
+
+# ============================================================================
+# Exports
+# ============================================================================
+
+__all__ = [
+    # Type variables
+    'TMessage',
+    'TCommand',
+
+    # Core protocols
+    'MessageProcessor',
+    'ClientIdExtractor',
+    'PingMessageCreator',
+
+    # Connection protocols
+    'ConnectionCallback',
+    'ErrorHandler',
+
+    # Type aliases
+    'MessageProcessorType',
+    'ClientIdExtractorType',
+    'PingMessageCreatorType',
+
+    # Validation
+    'is_valid_message_processor',
+    'is_valid_client_id_extractor',
+    'is_valid_ping_creator',
+]

django_cfg/apps/integrations/grpc/utils/SERVER_LOGGING.md

@@ -0,0 +1,164 @@
+# Server Lifecycle Logging Utilities
+
+Reusable functions for logging server startup and shutdown with timestamps and uptime tracking.
+
+**Uses Rich** for beautiful output with panels, tables, and colors! 🎨
+
+## 📦 Functions
+
+### `log_server_start()`
+
+Logs server startup with timestamp and configuration.
+
+```python
+from django_cfg.apps.integrations.grpc.utils import log_server_start
+
+start_time = log_server_start(
+    logger,
+    server_type="gRPC Server",       # Server type
+    mode="Development",               # Production/Development
+    hotreload_enabled=True,           # Is hotreload enabled?
+    host="0.0.0.0",                   # Additional parameters
+    port=50051
+)
+```
+
+**Output (Rich Panel):**
+```
+╭────────────── 🚀 gRPC Server Starting ───────────────╮
+│                                                      │
+│  ⏰ Started at    2025-11-05 14:30:15               │
+│  Mode            Development                        │
+│  Hotreload       Enabled ⚡                          │
+│  Host            0.0.0.0                            │
+│  Port            50051                              │
+│                                                      │
+╰──────────────────────────────────────────────────────╯
+⚠️  Hotreload active - connections may be dropped on code changes
+```
+(with green border and colors!)
+
+**Returns:** `datetime` object of start time (for use in `log_server_shutdown`)
+
+---
+
+### `log_server_shutdown()`
+
+Logs server shutdown with uptime calculation.
+
+```python
+from django_cfg.apps.integrations.grpc.utils import log_server_shutdown
+
+log_server_shutdown(
+    logger,
+    start_time,                       # datetime from log_server_start()
+    server_type="gRPC Server",
+    reason="Hotreload triggered",     # Shutdown reason
+    active_connections=5              # Additional parameters
+)
+```
+
+**Output (Rich Panel):**
+```
+╭───────────── 🧹 Shutting down gRPC Server ──────────────╮
+│                                                          │
+│  📋 Reason            Hotreload triggered               │
+│  ⏱️  Uptime            0h 2m 35s                         │
+│  🕐 Stopped at        2025-11-05 14:32:50               │
+│  Active Connections  5                                  │
+│                                                          │
+╰──────────────────────────────────────────────────────────╯
+✅ Server shutdown complete
+```
+(with red border and colors!)
+
+---
+
+## 🎯 Complete Usage Example
+
+```python
+from django_cfg.apps.integrations.grpc.utils import (
+    setup_streaming_logger,
+    log_server_start,
+    log_server_shutdown,
+)
+
+# Create logger
+logger = setup_streaming_logger('my_server')
+
+# Log server start
+start_time = log_server_start(
+    logger,
+    server_type="WebSocket Server",
+    mode="Production",
+    hotreload_enabled=False,
+    host="0.0.0.0",
+    port=8000
+)
+
+try:
+    # Server work...
+    await server.serve_forever()
+    shutdown_reason = "Normal termination"
+except KeyboardInterrupt:
+    shutdown_reason = "Keyboard interrupt"
+finally:
+    # Log server shutdown
+    log_server_shutdown(
+        logger,
+        start_time,
+        server_type="WebSocket Server",
+        reason=shutdown_reason,
+        total_connections=1250
+    )
+```
+
+---
+
+## 📊 Used in:
+
+- ✅ `rungrpc` - gRPC server command
+- ✅ Can be used for any servers (WebSocket, HTTP, etc.)
+
+---
+
+## 🔧 Parameters
+
+### `log_server_start()`
+
+| Parameter | Type | Required | Description |
+|----------|-----|----------|-------------|
+| `logger` | `logging.Logger` | ✅ Yes | Logger instance |
+| `server_type` | `str` | ❌ No | Server type (default: "Server") |
+| `mode` | `str` | ❌ No | Running mode (default: "Development") |
+| `hotreload_enabled` | `bool` | ❌ No | Is hotreload enabled (default: False) |
+| `use_rich` | `bool` | ❌ No | Use Rich for output (default: True) |
+| `**extra_info` | `dict` | ❌ No | Additional key-value pairs to log |
+
+### `log_server_shutdown()`
+
+| Parameter | Type | Required | Description |
+|----------|-----|----------|-------------|
+| `logger` | `logging.Logger` | ✅ Yes | Logger instance |
+| `start_time` | `datetime` | ✅ Yes | Start time from `log_server_start()` |
+| `server_type` | `str` | ❌ No | Server type (default: "Server") |
+| `reason` | `str` | ❌ No | Shutdown reason |
+| `use_rich` | `bool` | ❌ No | Use Rich for output (default: True) |
+| `**extra_info` | `dict` | ❌ No | Additional key-value pairs to log |
+
+---
+
+## 💡 Benefits
+
+1. ✅ **DRY** - single code for all servers
+2. ✅ **Consistency** - uniform log format
+3. ✅ **Rich UI** - beautiful panels, tables, colors 🎨
+4. ✅ **Uptime tracking** - automatic time calculation
+5. ✅ **Flexible** - can add arbitrary parameters via `**extra_info`
+6. ✅ **Hotreload aware** - special warning for hotreload mode
+7. ✅ **Fallback** - works without Rich (if `use_rich=False`)
+
+---
+
+**Author:** django-cfg team
+**Date:** 2025-11-05

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

@@ -2,8 +2,65 @@
 Utilities for gRPC Integration.
 
 Reusable utilities for gRPC services in django-cfg.
+
+**Available Modules**:
+- streaming_logger: Rich logging for gRPC streams
+- converters: Protobuf ↔ Python conversions (Pydantic configured)
+- handlers: gRPC handler factory utilities
+
+**Quick Imports**:
+```python
+from django_cfg.apps.integrations.grpc.utils import (
+    # Logging
+    setup_streaming_logger,
+    get_streaming_logger,
+
+    # Converters
+    ProtobufConverterMixin,
+    ConverterConfig,
+
+    # Handlers
+    create_grpc_handler,
+)
+```
 """
 
 from .streaming_logger import setup_streaming_logger, get_streaming_logger
+from .converters import (
+    ConverterConfig,
+    ProtobufConverterMixin,
+    datetime_to_timestamp,
+    timestamp_to_datetime,
+    dict_to_struct,
+    struct_to_dict,
+)
+from .handlers import (
+    create_grpc_handler,
+    create_multiple_grpc_handlers,
+    validate_grpc_handler,
+    validate_grpc_handlers,
+)
+
+__all__ = [
+    # Logging
+    "setup_streaming_logger",
+    "get_streaming_logger",
+
+    # Converters - Config
+    "ConverterConfig",
+
+    # Converters - Mixin
+    "ProtobufConverterMixin",
+
+    # Converters - Standalone functions
+    "datetime_to_timestamp",
+    "timestamp_to_datetime",
+    "dict_to_struct",
+    "struct_to_dict",
 
-__all__ = ["setup_streaming_logger", "get_streaming_logger"]
+    # Handlers
+    "create_grpc_handler",
+    "create_multiple_grpc_handlers",
+    "validate_grpc_handler",
+    "validate_grpc_handlers",
+]