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

django_cfg/modules/django_ipc_client/config.py

@@ -0,0 +1,207 @@
+"""
+Django-CFG RPC Client Configuration.
+
+Pydantic 2 configuration model for RPC client integration.
+Follows django-cfg patterns for modular configuration.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class DjangoCfgRPCConfig(BaseModel):
+    """
+    Django-CFG RPC Client configuration module.
+
+    Configures Redis-based RPC communication between Django and
+    django-cfg-rpc WebSocket servers.
+
+    Example:
+        >>> from django_cfg import DjangoConfig
+        >>> from django_cfg.modules.django_ipc_client import DjangoCfgRPCConfig
+        >>>
+        >>> config = DjangoConfig(
+        ...     django_ipc=DjangoCfgRPCConfig(
+        ...         enabled=True,
+        ...         redis_url="redis://localhost:6379/2",
+        ...         rpc_timeout=30
+        ...     )
+        ... )
+    """
+
+    # Module metadata
+    module_name: str = Field(
+        default="django_ipc_client",
+        frozen=True,
+        description="Module name for django-cfg integration",
+    )
+
+    enabled: bool = Field(
+        default=False,
+        description="Enable Django-CFG RPC client",
+    )
+
+    # Redis configuration
+    redis_url: str = Field(
+        default="redis://localhost:6379/2",
+        description="Redis URL for RPC communication (dedicated database recommended)",
+        examples=[
+            "redis://localhost:6379/2",
+            "redis://:password@localhost:6379/2",
+            "redis://redis-server:6379/2",
+        ],
+    )
+
+    redis_max_connections: int = Field(
+        default=50,
+        ge=10,
+        le=500,
+        description="Maximum Redis connection pool size",
+    )
+
+    # RPC settings
+    rpc_timeout: int = Field(
+        default=30,
+        ge=5,
+        le=300,
+        description="Default RPC call timeout (seconds)",
+    )
+
+    request_stream: str = Field(
+        default="stream:requests",
+        min_length=1,
+        max_length=100,
+        description="Redis Stream name for RPC requests",
+    )
+
+    consumer_group: str = Field(
+        default="rpc_group",
+        min_length=1,
+        max_length=100,
+        description="Redis Streams consumer group name (on server side)",
+    )
+
+    stream_maxlen: int = Field(
+        default=10000,
+        ge=1000,
+        le=100000,
+        description="Maximum stream length (XADD MAXLEN)",
+    )
+
+    # Response settings
+    response_key_prefix: str = Field(
+        default="list:response:",
+        min_length=1,
+        max_length=50,
+        description="Prefix for response list keys",
+    )
+
+    response_key_ttl: int = Field(
+        default=60,
+        ge=10,
+        le=3600,
+        description="Response key TTL (seconds) for auto-cleanup",
+    )
+
+    # Performance settings
+    enable_connection_pooling: bool = Field(
+        default=True,
+        description="Enable Redis connection pooling",
+    )
+
+    socket_keepalive: bool = Field(
+        default=True,
+        description="Enable TCP keepalive for Redis connections",
+    )
+
+    # Logging settings
+    log_rpc_calls: bool = Field(
+        default=False,
+        description="Log all RPC calls (verbose, use for debugging)",
+    )
+
+    log_level: str = Field(
+        default="INFO",
+        pattern=r"^(DEBUG|INFO|WARNING|ERROR|CRITICAL)$",
+        description="Log level for RPC module",
+    )
+
+    @field_validator("redis_url")
+    @classmethod
+    def validate_redis_url(cls, v: str) -> str:
+        """
+        Validate Redis URL format.
+
+        Args:
+            v: Redis URL to validate
+
+        Returns:
+            Validated Redis URL
+
+        Raises:
+            ValueError: If URL format is invalid
+        """
+        if not v.startswith("redis://") and not v.startswith("rediss://"):
+            raise ValueError(
+                "redis_url must start with 'redis://' or 'rediss://' "
+                f"(got: {v})"
+            )
+
+        return v
+
+    def to_django_settings(self) -> dict:
+        """
+        Generate Django settings dictionary.
+
+        Returns:
+            Dictionary with DJANGO_CFG_RPC settings
+
+        Example:
+            >>> config = DjangoCfgRPCConfig(enabled=True)
+            >>> settings_dict = config.to_django_settings()
+            >>> print(settings_dict["DJANGO_CFG_RPC"]["REDIS_URL"])
+        """
+        if not self.enabled:
+            return {}
+
+        return {
+            "DJANGO_CFG_RPC": {
+                "ENABLED": self.enabled,
+                "REDIS_URL": self.redis_url,
+                "REDIS_MAX_CONNECTIONS": self.redis_max_connections,
+                "RPC_TIMEOUT": self.rpc_timeout,
+                "REQUEST_STREAM": self.request_stream,
+                "CONSUMER_GROUP": self.consumer_group,
+                "STREAM_MAXLEN": self.stream_maxlen,
+                "RESPONSE_KEY_PREFIX": self.response_key_prefix,
+                "RESPONSE_KEY_TTL": self.response_key_ttl,
+                "LOG_RPC_CALLS": self.log_rpc_calls,
+                "LOG_LEVEL": self.log_level,
+            }
+        }
+
+    def get_redis_config(self) -> dict:
+        """
+        Get Redis connection configuration.
+
+        Returns:
+            Dictionary with Redis connection options
+
+        Example:
+            >>> config = DjangoCfgRPCConfig()
+            >>> redis_config = config.get_redis_config()
+            >>> import redis
+            >>> redis_client = redis.Redis.from_url(**redis_config)
+        """
+        config = {
+            "url": self.redis_url,
+            "max_connections": self.redis_max_connections,
+            "decode_responses": False,  # We handle JSON ourselves
+        }
+
+        if self.socket_keepalive:
+            config["socket_keepalive"] = True
+
+        return config
+
+
+__all__ = ["DjangoCfgRPCConfig"]

django_cfg/modules/django_ipc_client/dashboard/README.md

@@ -0,0 +1,517 @@
+# RPC Dashboard 📊
+
+**Real-time WebSocket & RPC Activity Monitor**
+
+Built-in dashboard for monitoring RPC requests, notifications, and WebSocket activity.
+
+---
+
+## ✨ Features
+
+- ✅ **Real-time Monitoring** - Live updates every 5 seconds
+- ✅ **Request Tracking** - View recent RPC calls with details
+- ✅ **Notification Stats** - Track sent notifications by type
+- ✅ **Method Analytics** - See which RPC methods are called most
+- ✅ **Health Checks** - Monitor Redis and stream status
+- ✅ **Tailwind CSS** - Beautiful dark mode UI
+- ✅ **Zero Config** - Works out of the box
+- ✅ **Django Cache** - 3-second cache reduces Redis load
+- ✅ **XSS Protection** - Secure against injection attacks
+- ✅ **Stream Validation** - Whitelist prevents Redis key injection
+- ✅ **Error Handling** - Specific HTTP codes (400, 503, 500)
+
+---
+
+## 🚀 Quick Start
+
+### ✨ Automatic Integration (Recommended)
+
+Simply enable RPC in your django-cfg configuration:
+
+```python
+# config.py
+from django_cfg import DjangoConfig
+from django_cfg.modules.django_ipc_client.config import DjangoCfgRPCConfig
+
+class MyProjectConfig(DjangoConfig):
+    # Enable RPC Client
+    django_ipc = DjangoCfgRPCConfig(
+        enabled=True,
+        redis_url="redis://localhost:6379/2",
+    )
+
+config = MyProjectConfig()
+```
+
+**That's it!** Django-cfg automatically:
+- ✅ Adds dashboard app to `INSTALLED_APPS`
+- ✅ Registers URL at `/admin/rpc/`
+- ✅ Adds "Operations" section to Unfold navigation
+- ✅ Generates `DJANGO_CFG_RPC` settings
+
+### Access Dashboard
+
+Navigate to: **http://localhost:8000/admin/rpc/**
+
+(Requires staff user login - `is_staff=True`)
+
+---
+
+### Manual Integration (Advanced)
+
+If not using django-cfg's automatic integration:
+
+```python
+# urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # RPC Dashboard (requires staff login)
+    path('admin/rpc/', include('django_cfg.modules.django_ipc_client.dashboard.urls')),
+]
+```
+
+For Unfold navigation customization, see [UNFOLD_INTEGRATION.md](./UNFOLD_INTEGRATION.md)
+
+---
+
+## 📊 Dashboard Tabs
+
+### Overview Tab
+
+Shows key metrics:
+- Total requests today
+- Active RPC methods
+- Average response time
+- Success rate
+
+### Recent Requests Tab
+
+Live stream of RPC calls:
+- Timestamp
+- Method name
+- Correlation ID
+- Request parameters (expandable)
+
+### Notifications Tab
+
+Notification statistics:
+- Total sent
+- Delivery rate
+- Breakdown by type
+- Recent notifications
+
+### Methods Tab
+
+Analytics by RPC method:
+- Call count
+- Percentage of total
+- Average response time
+
+---
+
+## 🔧 Configuration
+
+### Default Settings
+
+```python
+# In your Django settings.py (auto-configured)
+DJANGO_CFG_RPC = {
+    'redis_url': 'redis://localhost:6379/2',  # RPC database
+    'request_stream': 'stream:requests',
+    # ... other settings
+}
+```
+
+### URL Customization
+
+Mount at custom path:
+
+```python
+urlpatterns = [
+    path('my/custom/path/', include('django_cfg.modules.django_ipc_client.dashboard.urls')),
+]
+```
+
+---
+
+## 🧪 Testing
+
+### Run Tests
+
+```bash
+# Run all dashboard tests
+pytest django_cfg/modules/django_ipc_client/tests/
+
+# Run monitor tests
+pytest django_cfg/modules/django_ipc_client/tests/test_monitor.py -v
+
+# Run view tests
+pytest django_cfg/modules/django_ipc_client/tests/test_dashboard.py -v
+```
+
+### Test Coverage
+
+- ✅ **RPCMonitor**: 15 tests
+- ✅ **Dashboard Views**: 10 tests
+- ✅ **Integration Tests**: Fakeredis support
+
+---
+
+## 📡 API Endpoints
+
+Dashboard exposes JSON API endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/admin/rpc/api/overview/` | GET | Overview statistics |
+| `/admin/rpc/api/requests/?count=50` | GET | Recent RPC requests |
+| `/admin/rpc/api/notifications/` | GET | Notification stats |
+| `/admin/rpc/api/methods/` | GET | Method statistics |
+| `/admin/rpc/api/health/` | GET | Health check |
+
+All endpoints return JSON:
+
+```json
+{
+    "success": true,
+    "data": { ... }
+}
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+dashboard/
+├── monitor.py          # RPCMonitor class (reads Redis)
+├── views.py            # Django views + JSON API
+├── urls.py             # URL routing
+├── templates/          # Tailwind CSS templates
+│   └── django_ipc_dashboard/
+│       ├── base.html
+│       └── dashboard.html
+└── static/             # JavaScript
+    └── django_ipc_dashboard/
+        └── js/
+            └── dashboard.js
+```
+
+### Data Flow
+
+```
+Redis DB 2 (stream:requests)
+    ↓
+RPCMonitor.get_overview_stats()
+    ↓
+Django View (dashboard_view)
+    ↓
+Template (dashboard.html)
+    ↓
+JavaScript (auto-refresh every 5s)
+    ↓
+API Endpoints (/api/overview/, etc.)
+```
+
+---
+
+## 🎨 Customization
+
+### Disable Auto-Refresh
+
+Toggle "Auto-refresh" checkbox in dashboard header.
+
+### Change Refresh Interval
+
+Edit `dashboard.js`:
+
+```javascript
+class RPCDashboard {
+    constructor() {
+        this.refreshInterval = 10000; // 10 seconds instead of 5
+        // ...
+    }
+}
+```
+
+### Custom Styling
+
+Override Tailwind classes or add custom CSS to `base.html`.
+
+---
+
+## 🐛 Troubleshooting
+
+### Dashboard shows "Redis not connected"
+
+**Check:**
+1. Redis running: `redis-cli ping`
+2. Correct Redis URL in config
+3. Using DB 2 for RPC: `redis://localhost:6379/2`
+
+**Solution:**
+```bash
+# Check Redis is running
+redis-cli -h localhost -p 6379 ping  # Should return "PONG"
+
+# Check database 2 is accessible
+redis-cli -h localhost -p 6379 -n 2 ping
+```
+
+### No requests showing up
+
+**Check:**
+1. RPC client actually making requests
+2. Request stream exists: `redis-cli XLEN stream:requests`
+3. Recent activity (last 5 minutes)
+
+**Debug:**
+```bash
+# Check stream exists and has data
+redis-cli -n 2 XLEN stream:requests
+
+# View latest request
+redis-cli -n 2 XREVRANGE stream:requests + - COUNT 1
+```
+
+### Permission denied
+
+**Solution:** Dashboard requires staff user login (`is_staff=True`)
+
+```python
+user = User.objects.get(username='your_user')
+user.is_staff = True
+user.save()
+```
+
+### Dashboard is slow / High Redis load
+
+**Solution:** Dashboard uses 3-second cache. If still slow:
+
+1. Increase cache timeout in `monitor.py`:
+```python
+CACHE_TIMEOUT = 5  # Change from 3 to 5 seconds
+```
+
+2. Configure Django cache backend (default uses in-memory):
+```python
+# settings.py
+CACHES = {
+    'default': {
+        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
+        'LOCATION': 'redis://localhost:6379/0',
+    }
+}
+```
+
+3. Reduce stream read count in `monitor.py`:
+```python
+recent_requests = self._get_recent_stream_entries(count=500)  # Down from 1000
+```
+
+### API returns 503 "Service Unavailable"
+
+**Cause:** Redis connection lost or timeout
+
+**Solution:**
+```python
+# Check Redis connection settings
+config = DjangoCfgRPCConfig()
+print(config.redis_url)  # Should be redis://localhost:6379/2
+
+# Increase timeout in monitor.py _create_redis_client():
+client = redis.Redis(
+    socket_connect_timeout=10,  # Up from 5
+    socket_timeout=10,           # Up from 5
+)
+
+---
+
+## 📚 Related Documentation
+
+- [RPC Client README](../README.md)
+- [RPC Integration Guide](../../../../../../@docs/websocket2/RPC_DRAMATIQ_INTEGRATION.md)
+- [Redis Database Allocation](../../../../../../@docs/websocket2/REDIS_DATABASES.md)
+
+---
+
+## 🎯 Example Use Cases
+
+### 1. Monitor Notification Delivery
+
+Track how many notifications are sent to users:
+
+1. Go to "Notifications" tab
+2. See total sent + delivery rate
+3. Breakdown by notification type
+
+### 2. Debug RPC Issues
+
+When RPC calls fail:
+
+1. Go to "Recent Requests" tab
+2. Find failing request
+3. Expand "View" to see parameters
+4. Check correlation ID for tracing
+
+### 3. Analyze Performance
+
+Find slow RPC methods:
+
+1. Go to "Methods" tab
+2. Sort by "Avg Time"
+3. Identify bottlenecks
+
+---
+
+## ✅ Summary
+
+- **Location**: `django_cfg/modules/django_ipc_client/dashboard/`
+- **URL**: `/admin/rpc/` (customizable)
+- **Requirements**: Staff login, Redis DB 2
+- **Tech Stack**: Django, Tailwind CSS, Vanilla JS
+- **Tests**: 25+ tests with mocks + fakeredis
+
+**Production Ready**: ✅
+
+---
+
+## 🚀 Production Deployment Checklist
+
+### 1. Security
+- [ ] Verify all views use `@staff_member_required`
+- [ ] Configure HTTPS for dashboard URL
+- [ ] Enable CSRF protection (Django default)
+- [ ] Set strong `SECRET_KEY` in production
+
+### 2. Redis Configuration
+- [ ] Use dedicated Redis DB for RPC (DB 2)
+- [ ] Configure Redis persistence (AOF or RDB)
+- [ ] Set Redis `maxmemory-policy` to `allkeys-lru`
+- [ ] Enable Redis password authentication
+
+```python
+# Production config
+DJANGO_CFG_RPC = DjangoCfgRPCConfig(
+    redis_url="redis://:strong_password@redis-server:6379/2",
+    redis_max_connections=100,  # Increase for production
+)
+```
+
+### 3. Django Cache
+- [ ] Configure Redis cache backend (not in-memory)
+- [ ] Set cache timeout appropriately
+
+```python
+# settings.py
+CACHES = {
+    'default': {
+        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
+        'LOCATION': 'redis://localhost:6379/0',
+        'OPTIONS': {
+            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
+        }
+    }
+}
+```
+
+### 4. Static Files
+- [ ] Run `python manage.py collectstatic`
+- [ ] Configure static files serving (nginx/whitenoise)
+- [ ] Verify Tailwind CSS loads from CDN
+
+### 5. Performance
+- [ ] Monitor Redis memory usage
+- [ ] Set stream MAXLEN to prevent unbounded growth
+- [ ] Consider Redis eviction policy
+- [ ] Enable connection pooling (default: enabled)
+
+```bash
+# Monitor Redis memory
+redis-cli INFO memory
+
+# Trim old stream entries (if needed)
+redis-cli -n 2 XTRIM stream:requests MAXLEN 10000
+```
+
+### 6. Monitoring
+- [ ] Set up logging for dashboard errors
+- [ ] Monitor API endpoint response times
+- [ ] Track Redis connection errors
+- [ ] Set up alerts for 503 errors
+
+```python
+# settings.py - Enhanced logging
+LOGGING = {
+    'loggers': {
+        'django_cfg.modules.django_ipc_client.dashboard': {
+            'level': 'INFO',
+            'handlers': ['file', 'sentry'],  # Add Sentry for production
+        },
+    },
+}
+```
+
+### 7. Testing
+- [ ] Run all tests: `pytest django_cfg/modules/django_ipc_client/tests/`
+- [ ] Load test API endpoints
+- [ ] Verify dashboard loads with production data
+- [ ] Test with Redis connection failures
+
+### 8. Documentation
+- [ ] Document custom URL mounting path
+- [ ] Document Redis DB allocation
+- [ ] Document staff user creation process
+
+---
+
+## 🔧 Performance Optimization
+
+### Redis Stream Management
+
+Prevent unlimited stream growth:
+
+```bash
+# Add to cron (daily cleanup)
+redis-cli -n 2 XTRIM stream:requests MAXLEN 50000
+
+# Or use MAXLEN in stream writes (django-cfg-rpc server)
+XADD stream:requests MAXLEN ~ 10000 * payload {...}
+```
+
+### Cache Configuration
+
+Optimize cache for high traffic:
+
+```python
+# monitor.py - Adjust cache timeout based on traffic
+CACHE_TIMEOUT = 5  # Higher for production (less Redis load)
+
+# settings.py - Use connection pool
+CACHES = {
+    'default': {
+        'LOCATION': 'redis://localhost:6379/0',
+        'OPTIONS': {
+            'CONNECTION_POOL_KWARGS': {
+                'max_connections': 50
+            }
+        }
+    }
+}
+```
+
+---
+
+## 🔒 Security Notes
+
+1. **XSS Protection**: All user data sanitized via `textContent` (not `innerHTML`)
+2. **Stream Key Validation**: Whitelist prevents Redis key injection
+3. **Staff-Only Access**: All endpoints require `is_staff=True`
+4. **Error Messages**: Generic messages in production (no stack traces to clients)
+5. **CSRF**: Django CSRF protection enabled by default
+
+---
+
+**Last Updated**: 2025-10-03
+**Version**: 2.0 (Security Hardened)