django-cfg 1.3.13__py3-none-any.whl → 1.4.0__py3-none-any.whl

django_cfg/modules/django_cfg_rpc_client/README.md

@@ -0,0 +1,346 @@
+# Django-CFG RPC Client 📡
+
+Lightweight synchronous RPC client for Django applications to communicate with **django-cfg-rpc** WebSocket servers via Redis.
+
+**NEW**: ✨ Built-in RPC Dashboard for real-time monitoring! See [Dashboard README](./dashboard/README.md)
+
+## 🎯 Key Features
+
+- ✅ **100% Synchronous** - No async/await in Django, works with WSGI
+- ✅ **Type-Safe** - Full Pydantic 2 support when django-cfg-rpc installed
+- ✅ **Optional Dependency** - Works without django-cfg-rpc (dict-based fallback)
+- ✅ **Redis IPC** - Reliable communication via Streams + Lists
+- ✅ **Connection Pooling** - Automatic Redis connection management
+- ✅ **Singleton Pattern** - Single client instance across Django app
+
+---
+
+## 📦 Installation
+
+### Option 1: With django-cfg-rpc (Recommended)
+
+```bash
+pip install django-cfg django-cfg-rpc
+```
+
+### Option 2: Standalone (Basic)
+
+```bash
+pip install django-cfg redis
+```
+
+---
+
+## ⚙️ Configuration
+
+### Django Settings (via django-cfg)
+
+```python
+# config.py
+from django_cfg import DjangoConfig
+from django_cfg.modules.django_cfg_rpc_client.config import DjangoCfgRPCConfig
+
+class MyProjectConfig(DjangoConfig):
+    project_name = "My Project"
+
+    # RPC Client Configuration
+    django_cfg_rpc = DjangoCfgRPCConfig(
+        enabled=True,
+        redis_url="redis://localhost:6379/2",
+        rpc_timeout=30,
+    )
+
+config = MyProjectConfig()
+
+# settings.py
+from config import config
+
+# Settings are automatically generated by django-cfg orchestrator
+# DJANGO_CFG_RPC settings will be available in Django settings
+globals().update(config.get_all_settings())
+```
+
+**✨ Automatic Integration:**
+- ✅ `DJANGO_CFG_RPC` settings are auto-generated
+- ✅ Dashboard app auto-added to `INSTALLED_APPS`
+- ✅ Dashboard URLs auto-registered at `/admin/rpc/`
+- ✅ RPC tracked in `DJANGO_CFG_INTEGRATIONS` list
+
+### Environment Variables
+
+```bash
+DJANGO_CFG_RPC__ENABLED=true
+DJANGO_CFG_RPC__REDIS_URL=redis://localhost:6379/2
+DJANGO_CFG_RPC__RPC_TIMEOUT=30
+```
+
+---
+
+## 🚀 Usage
+
+### With django-cfg-rpc Models (Type-Safe)
+
+```python
+# views.py
+from django_cfg.modules.django_cfg_rpc_client import get_rpc_client
+from django_cfg_rpc.models import NotificationRequest, NotificationResponse
+
+rpc = get_rpc_client()
+
+def notify_user(request, user_id):
+    """Send notification to user via WebSocket."""
+
+    result: NotificationResponse = rpc.call(
+        method="send_notification",
+        params=NotificationRequest(
+            user_id=user_id,
+            type="order_update",
+            title="Order Confirmed",
+            message="Your order #12345 has been confirmed",
+            priority="high",
+        ),
+        result_model=NotificationResponse,
+        timeout=10,
+    )
+
+    return JsonResponse({
+        "delivered": result.delivered,
+        "connections": result.connections,
+    })
+```
+
+### Without django-cfg-rpc (Dict-Based)
+
+```python
+from django_cfg.modules.django_cfg_rpc_client import get_rpc_client
+
+rpc = get_rpc_client()
+
+def notify_user(request, user_id):
+    """Send notification using dict params."""
+
+    result = rpc.call_dict(
+        method="send_notification",
+        params={
+            "user_id": user_id,
+            "type": "order_update",
+            "title": "Order Confirmed",
+            "message": "Your order #12345 has been confirmed",
+        },
+        timeout=10,
+    )
+
+    return JsonResponse({
+        "delivered": result.get("delivered", False),
+    })
+```
+
+### Fire-and-Forget (No Response Wait)
+
+```python
+# For operations where you don't need the result
+rpc.fire_and_forget(
+    method="log_event",
+    params={"event": "user_login", "user_id": "123"}
+)
+```
+
+---
+
+## 🔧 API Reference
+
+### `get_rpc_client(force_new=False)`
+
+Get singleton RPC client instance.
+
+**Args:**
+- `force_new` (bool): Force create new instance (for testing)
+
+**Returns:**
+- `DjangoCfgRPCClient` instance
+
+---
+
+### `DjangoCfgRPCClient.call(method, params, result_model=None, timeout=None)`
+
+Make synchronous RPC call.
+
+**Args:**
+- `method` (str): RPC method name
+- `params` (BaseModel | dict): Parameters (Pydantic model or dict)
+- `result_model` (Type[BaseModel], optional): Expected result model class
+- `timeout` (int, optional): Timeout override in seconds
+
+**Returns:**
+- Pydantic model instance (if `result_model` provided) or dict
+
+**Raises:**
+- `RPCTimeoutError`: If timeout exceeded
+- `RPCRemoteError`: If remote execution failed
+
+---
+
+### `DjangoCfgRPCClient.call_dict(method, params, timeout=None)`
+
+Make RPC call with dict params (no Pydantic).
+
+**Args:**
+- `method` (str): RPC method name
+- `params` (dict): Dictionary with parameters
+- `timeout` (int, optional): Timeout override in seconds
+
+**Returns:**
+- Dictionary with result
+
+---
+
+### `DjangoCfgRPCClient.fire_and_forget(method, params)`
+
+Send RPC request without waiting for response.
+
+**Args:**
+- `method` (str): RPC method name
+- `params` (BaseModel | dict): Parameters
+
+**Returns:**
+- str: Message ID from Redis Stream
+
+---
+
+### `DjangoCfgRPCClient.health_check(timeout=5)`
+
+Check if RPC system is healthy.
+
+**Args:**
+- `timeout` (int): Health check timeout in seconds
+
+**Returns:**
+- bool: True if healthy, False otherwise
+
+---
+
+## ⚠️ Error Handling
+
+### Timeout Handling
+
+```python
+from django_cfg.modules.django_cfg_rpc_client import get_rpc_client, RPCTimeoutError
+
+rpc = get_rpc_client()
+
+try:
+    result = rpc.call(method="slow_operation", params={...}, timeout=5)
+except RPCTimeoutError as e:
+    logger.warning(f"RPC timeout: {e.method} after {e.timeout_seconds}s")
+    # Handle timeout (retry, fallback, etc.)
+```
+
+### Remote Error Handling
+
+```python
+from django_cfg.modules.django_cfg_rpc_client import RPCRemoteError
+
+try:
+    result = rpc.call(method="...", params={...})
+except RPCRemoteError as e:
+    logger.error(f"Remote error [{e.error.code}]: {e.error.message}")
+
+    if e.is_retryable:
+        # Retry after delay
+        import time
+        time.sleep(e.retry_after or 5)
+        result = rpc.call(...)  # Retry
+    else:
+        # Non-retryable error
+        raise
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│       Django Application (WSGI/Sync)        │
+│  ┌───────────────────────────────────────┐  │
+│  │  django_cfg_rpc_client                │  │
+│  │  - DjangoCfgRPCClient (sync)          │  │
+│  │  - Redis Streams (requests)           │  │
+│  │  - Redis Lists (responses)            │  │
+│  └───────────────────────────────────────┘  │
+└───────────────┬─────────────────────────────┘
+                │
+                │ Redis IPC
+                │ (stream:requests → list:response:{cid})
+                ▼
+┌─────────────────────────────────────────────┐
+│     django-cfg-rpc Server (Async)           │
+│  - WebSocket Server                         │
+│  - Connection Manager                       │
+│  - RPC Handlers                             │
+│  - Pydantic 2 Models                        │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 🔗 Related
+
+- **django-cfg-rpc** - WebSocket RPC server package
+- **Old Module** - `django_rpc_old` (deprecated, kept for reference)
+
+---
+
+## 📝 Migration from django_rpc_old
+
+```python
+# Old (deprecated)
+from django_cfg.modules.django_rpc import get_rpc_client
+
+# New (current)
+from django_cfg.modules.django_cfg_rpc_client import get_rpc_client
+```
+
+API remains mostly compatible. Main changes:
+- Configuration key: `WEBSOCKET_RPC` → `DJANGO_CFG_RPC`
+- Models now live in `django-cfg-rpc` package (optional dependency)
+- Better error handling with specific exception types
+
+---
+
+**Status:** ✅ Production Ready
+**Django-CFG Version:** 2.0+
+**Python Version:** 3.10+
+
+
+---
+
+## 📊 RPC Dashboard (NEW!)
+
+### Quick Start
+
+Add dashboard to your Django URLs:
+
+```python
+# urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # ... other URLs
+    path('admin/rpc/', include('django_cfg.modules.django_cfg_rpc_client.dashboard.urls')),
+]
+```
+
+Access at: **http://localhost:8000/admin/rpc/** (requires staff login)
+
+### Features
+
+- ✅ **Real-time monitoring** - Updates every 5 seconds
+- ✅ **Request tracking** - View recent RPC calls
+- ✅ **Notification stats** - Track sent notifications  
+- ✅ **Method analytics** - See which methods are called
+- ✅ **Health checks** - Monitor Redis and streams
+- ✅ **Beautiful UI** - Tailwind CSS dark mode
+
+See [Dashboard README](./dashboard/README.md) for full documentation.
+

django_cfg/modules/django_cfg_rpc_client/__init__.py

@@ -0,0 +1,51 @@
+"""
+Django-CFG RPC Client Module.
+
+Lightweight synchronous RPC client for Django applications to communicate
+with django-cfg-rpc WebSocket servers via Redis.
+
+Key Features:
+- ✅ 100% synchronous (no async/await in Django)
+- ✅ Type-safe with Pydantic 2 models from django-cfg-rpc
+- ✅ Automatic connection pooling
+- ✅ Optional dependency on django-cfg-rpc
+- ✅ Graceful fallback if django-cfg-rpc not installed
+
+Example:
+    >>> from django_cfg.modules.django_cfg_rpc_client import get_rpc_client
+    >>> from django_cfg_rpc.models import NotificationRequest, NotificationResponse
+    >>>
+    >>> rpc = get_rpc_client()
+    >>> result: NotificationResponse = rpc.call(
+    ...     method="send_notification",
+    ...     params=NotificationRequest(
+    ...         user_id="123",
+    ...         type="order_update",
+    ...         title="Order Confirmed",
+    ...         message="Your order has been confirmed"
+    ...     ),
+    ...     result_model=NotificationResponse
+    ... )
+"""
+
+from .client import DjangoCfgRPCClient, get_rpc_client
+from .config import DjangoCfgRPCConfig
+from .exceptions import (
+    RPCTimeoutError,
+    RPCRemoteError,
+    RPCConnectionError,
+    RPCConfigurationError,
+)
+
+__all__ = [
+    # Client
+    "DjangoCfgRPCClient",
+    "get_rpc_client",
+    # Configuration
+    "DjangoCfgRPCConfig",
+    # Exceptions
+    "RPCTimeoutError",
+    "RPCRemoteError",
+    "RPCConnectionError",
+    "RPCConfigurationError",
+]