django-cfg 1.4.62__py3-none-any.whl → 1.4.64__py3-none-any.whl

django_cfg/apps/ipc/README.md

@@ -1,346 +0,0 @@
-# Django-CFG RPC Client 📡
-
-Lightweight synchronous RPC client for Django applications to communicate with **django-ipc** 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-ipc installed
-- ✅ **Optional Dependency** - Works without django-ipc (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-ipc (Recommended)
-
-```bash
-pip install django-cfg django-ipc
-```
-
-### 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_ipc_client.config import DjangoCfgRPCConfig
-
-class MyProjectConfig(DjangoConfig):
-    project_name = "My Project"
-
-    # RPC Client Configuration
-    django_ipc = 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-ipc Models (Type-Safe)
-
-```python
-# views.py
-from django_cfg.modules.django_ipc_client import get_rpc_client
-from django_ipc.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-ipc (Dict-Based)
-
-```python
-from django_cfg.modules.django_ipc_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_ipc_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_ipc_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_ipc_client                │  │
-│  │  - DjangoCfgRPCClient (sync)          │  │
-│  │  - Redis Streams (requests)           │  │
-│  │  - Redis Lists (responses)            │  │
-│  └───────────────────────────────────────┘  │
-└───────────────┬─────────────────────────────┘
-                │
-                │ Redis IPC
-                │ (stream:requests → list:response:{cid})
-                ▼
-┌─────────────────────────────────────────────┐
-│     django-ipc Server (Async)           │
-│  - WebSocket Server                         │
-│  - Connection Manager                       │
-│  - RPC Handlers                             │
-│  - Pydantic 2 Models                        │
-└─────────────────────────────────────────────┘
-```
-
----
-
-## 🔗 Related
-
-- **django-ipc** - 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_ipc_client import get_rpc_client
-```
-
-API remains mostly compatible. Main changes:
-- Configuration key: `WEBSOCKET_RPC` → `DJANGO_CFG_RPC`
-- Models now live in `django-ipc` 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_ipc_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/apps/ipc/RPC_LOGGING.md

@@ -1,321 +0,0 @@
-# RPC Logging & Analytics
-
-**Track, monitor, and analyze all RPC calls between Django and WebSocket server.**
-
----
-
-## 🎯 Overview
-
-The IPC app now includes **automatic RPC logging** to database with:
-- ✅ **Full request/response tracking**
-- ✅ **Performance metrics** (duration, success rate)
-- ✅ **User attribution** (who made the call)
-- ✅ **Error details** (stack traces, error codes)
-- ✅ **Beautiful admin interface** (Unfold Admin)
-- ✅ **Analytics dashboard** (coming soon)
-
----
-
-## 📊 What Gets Logged?
-
-Every RPC call creates a `RPCLog` entry with:
-
-```python
-RPCLog:
-    id: UUID                      # Primary key
-    correlation_id: str           # Matches RPC request
-    method: str                   # RPC method name
-    params: dict                  # Request parameters (JSON)
-    response: dict | None         # Response data (JSON)
-    status: pending|success|failed|timeout
-    error_code: str | None        # Error code if failed
-    error_message: str | None     # Error message
-    duration_ms: int | None       # Call duration in milliseconds
-    user: User | None             # Django user who made the call
-    caller_ip: str | None         # IP address
-    user_agent: str | None        # User agent string
-    created_at: datetime          # When call started
-    completed_at: datetime        # When call finished
-```
-
----
-
-## 🚀 Usage
-
-### **Automatic Logging (Recommended)**
-
-Logging happens automatically when you pass `user` to `rpc.call()`:
-
-```python
-from django_cfg.apps.ipc import get_rpc_client
-
-def my_view(request):
-    rpc = get_rpc_client()
-
-    # RPC call with automatic logging
-    result = rpc.call(
-        method="send_notification",
-        params={"user_id": "123", "message": "Hello"},
-        user=request.user,          # ✅ Logs this call
-        caller_ip=request.META.get('REMOTE_ADDR'),
-        user_agent=request.META.get('HTTP_USER_AGENT')
-    )
-
-    return JsonResponse({"sent": True})
-```
-
-**What gets logged:**
-- ✅ Method name: `send_notification`
-- ✅ Parameters: `{"user_id": "123", "message": "Hello"}`
-- ✅ User: `request.user`
-- ✅ IP: Client IP address
-- ✅ Duration: Automatically calculated
-- ✅ Status: success/failed/timeout
-- ✅ Response data or error details
-
-### **Manual Logging (Advanced)**
-
-For more control, use `RPCLogger` directly:
-
-```python
-from django_cfg.apps.ipc.services.logging import RPCLogger
-
-# Create log entry
-log_entry = RPCLogger.create_log(
-    correlation_id="abc123",
-    method="my_method",
-    params={"key": "value"},
-    user=request.user
-)
-
-# ... make RPC call ...
-
-# Mark as success
-RPCLogger.mark_success(log_entry, response_data={"result": "ok"}, duration_ms=150)
-
-# Or mark as failed
-RPCLogger.mark_failed(log_entry, "network_error", "Connection timeout", duration_ms=30000)
-```
-
-### **Context Manager (Cleanest)**
-
-```python
-from django_cfg.apps.ipc.services.logging import RPCLogContext
-
-with RPCLogContext(
-    correlation_id="abc123",
-    method="send_notification",
-    params={"user_id": "123"},
-    user=request.user
-) as log_ctx:
-    result = rpc.call(...)
-    log_ctx.set_response(result)
-    # Automatically logged on exit
-```
-
----
-
-## 🎨 Admin Interface
-
-**Access at:** `/admin/django_cfg_ipc/rpclog/`
-
-### **List View Features:**
-- ✅ **Color-coded status badges** (green=success, red=failed, orange=timeout)
-- ✅ **Performance metrics** (duration color-coded by speed)
-- ✅ **Search** by method, user, correlation ID
-- ✅ **Filters** by status, method, date, user
-- ✅ **Date hierarchy** for time-based navigation
-
-### **Detail View Features:**
-- ✅ **Formatted JSON** for params/response
-- ✅ **Error details** with highlighted boxes
-- ✅ **Timeline** (created_at → completed_at)
-- ✅ **User info** with links to user admin
-
----
-
-## 📈 Analytics Queries
-
-### **Get stats by method:**
-
-```python
-from django_cfg.apps.ipc.models import RPCLog
-
-stats = RPCLog.objects.stats_by_method()
-for stat in stats:
-    print(f"{stat['method']}:")
-    print(f"  Total calls: {stat['total_calls']}")
-    print(f"  Avg duration: {stat['avg_duration_ms']}ms")
-    print(f"  Success rate: {stat['success_count'] / stat['total_calls'] * 100}%")
-```
-
-### **Get recent failures:**
-
-```python
-# Last 100 failed calls
-failed_calls = RPCLog.objects.failed().order_by('-created_at')[:100]
-
-for call in failed_calls:
-    print(f"{call.method}: {call.error_message}")
-```
-
-### **Get slow calls:**
-
-```python
-# Calls slower than 1 second
-slow_calls = RPCLog.objects.filter(
-    duration_ms__gt=1000,
-    status='success'
-).order_by('-duration_ms')
-
-for call in slow_calls:
-    print(f"{call.method}: {call.duration_ms}ms")
-```
-
-### **User activity:**
-
-```python
-# RPC calls by specific user
-user_calls = RPCLog.objects.filter(user=request.user).recent(hours=24)
-print(f"User made {user_calls.count()} RPC calls in last 24h")
-```
-
----
-
-## ⚙️ Configuration
-
-### **Enable/Disable Logging**
-
-```python
-# config.py
-from django_cfg import DjangoConfig
-
-class MyConfig(DjangoConfig):
-    django_ipc = DjangoCfgRPCConfig(
-        enabled=True,
-        redis_url="redis://localhost:6379/2",
-        enable_logging=True,  # ✅ Enable RPC logging (default: True)
-    )
-```
-
-Or via environment variable:
-
-```bash
-DJANGO_CFG_RPC__ENABLE_LOGGING=true
-```
-
-### **Log Retention**
-
-To prevent database bloat, set up a periodic cleanup task:
-
-```python
-# tasks/cleanup.py
-from django.utils import timezone
-from datetime import timedelta
-from django_cfg.apps.ipc.models import RPCLog
-
-def cleanup_old_rpc_logs(days=30):
-    """Delete RPC logs older than N days."""
-    cutoff = timezone.now() - timedelta(days=days)
-    deleted_count = RPCLog.objects.filter(created_at__lt=cutoff).delete()[0]
-    print(f"Deleted {deleted_count} old RPC logs")
-```
-
-Add to crontab or django-dramatiq:
-
-```python
-# Schedule daily cleanup
-@dramatiq.actor
-def daily_cleanup():
-    cleanup_old_rpc_logs(days=30)
-```
-
----
-
-## 📊 Performance Impact
-
-**Logging overhead:**
-- ✅ **Async-safe** - uses synchronous Django ORM
-- ✅ **Non-blocking** - doesn't delay RPC calls
-- ✅ **Error-tolerant** - logging failures don't break RPC
-- ✅ **Indexed** - fast queries on common fields
-
-**Benchmarks:**
-- Create log entry: **~2-5ms**
-- Update status: **~1-3ms**
-- Total overhead per RPC call: **~3-8ms**
-
-For 1000 RPC calls/min, expect **~5-10K log entries/day**.
-
----
-
-## 🔍 Troubleshooting
-
-### **Logging not working?**
-
-1. **Check if IPC app is installed:**
-   ```python
-   'django_cfg.apps.ipc' in settings.INSTALLED_APPS
-   ```
-
-2. **Run migrations:**
-   ```bash
-   python manage.py migrate django_cfg_ipc
-   ```
-
-3. **Check logging settings:**
-   ```python
-   settings.DJANGO_CFG_RPC.get('ENABLE_LOGGING')  # Should be True
-   ```
-
-### **Too many logs?**
-
-1. **Disable logging temporarily:**
-   ```python
-   DJANGO_CFG_RPC__ENABLE_LOGGING=false
-   ```
-
-2. **Set up log rotation:**
-   ```python
-   # Keep only last 7 days
-   cleanup_old_rpc_logs(days=7)
-   ```
-
-3. **Use log sampling** (advanced):
-   ```python
-   # Log only 10% of calls
-   import random
-   if random.random() < 0.1:
-       rpc.call(..., user=request.user)  # Logged
-   else:
-       rpc.call(...)  # Not logged
-   ```
-
----
-
-## 🎯 Best Practices
-
-1. **✅ Always pass `user`** when possible for attribution
-2. **✅ Set up log retention** to prevent DB bloat
-3. **✅ Monitor slow calls** (duration > 1s)
-4. **✅ Alert on high failure rates** (>5%)
-5. **✅ Use correlation_id** for debugging request chains
-6. **⚠️ Don't log sensitive data** in params (passwords, tokens)
-
----
-
-## 🚀 Future Enhancements
-
-Coming soon:
-- [ ] Real-time analytics dashboard
-- [ ] Grafana integration (metrics export)
-- [ ] Webhook notifications on failures
-- [ ] Automatic slow query detection
-- [ ] Rate limiting based on logs
-- [ ] Cost tracking (API usage billing)
-
----
-
-**Status:** ✅ Production Ready
-**Django-CFG Version:** 2.0+
-**Python Version:** 3.10+