django-cfg 1.2.15__py3-none-any.whl → 1.2.16__py3-none-any.whl

django_cfg/__init__.py

@@ -32,7 +32,7 @@ Example:
 default_app_config = "django_cfg.apps.DjangoCfgConfig"
 
 # Version information
-__version__ = "1.2.15"
+__version__ = "1.2.16"
 __license__ = "MIT"
 
 # Import registry for organized lazy loading

django_cfg/apps/maintenance/README.md

@@ -0,0 +1,305 @@
+# 🔧 Django-CFG Maintenance Application
+
+**Multi-site maintenance mode management with Cloudflare integration**
+
+## 🎯 Overview
+
+The Django-CFG Maintenance application provides a comprehensive solution for managing maintenance mode across multiple Cloudflare sites with an ORM-like interface and zero-configuration setup.
+
+### Key Features
+
+- ✅ **Zero-Configuration Setup** - Just provide API token and domain
+- ✅ **Multi-Site Management** - Manage hundreds of sites with ORM-like queries
+- ✅ **Bulk Operations** - Enable/disable maintenance for multiple sites at once
+- ✅ **External Monitoring** - Automatic maintenance triggers on health check failures
+- ✅ **Rich Admin Interface** - Full Django admin integration with bulk actions
+- ✅ **CLI Management** - Powerful management commands for automation
+- ✅ **Audit Trail** - Complete logging and event tracking
+
+## 🚀 Quick Start
+
+### 1. Enable in Configuration
+
+```python
+# settings.py or your DjangoConfig
+class MyProjectConfig(DjangoConfig):
+    project_name = "My Project"
+    enable_maintenance = True  # Enable maintenance app
+    
+    # Optional: Zero-config Cloudflare setup
+    # Set these environment variables:
+    # CLOUDFLARE_API_TOKEN=your_token
+    # CLOUDFLARE_DOMAIN=example.com
+```
+
+### 2. Run Migrations
+
+```bash
+python manage.py migrate
+```
+
+### 3. Basic Usage
+
+#### ORM-like Interface
+
+```python
+from django_cfg.apps.maintenance.services import multi_site_manager
+
+# Get sites for user
+sites = multi_site_manager.sites(user)
+
+# Enable maintenance for all production sites
+await sites.production().enable_maintenance(
+    reason="Database migration",
+    message="We're upgrading our database. Back in 30 minutes!"
+)
+
+# Disable maintenance for specific project
+await sites.filter(project='ecommerce').disable_maintenance()
+
+# Complex filtering
+critical_sites = sites.filter(
+    environment='production',
+    tags__contains='critical'
+).exclude(project='legacy')
+
+await critical_sites.enable_maintenance(reason="Security patch")
+```
+
+#### CLI Management
+
+```bash
+# Enable maintenance for all production sites
+python manage.py maintenance enable --environment production --reason "Database upgrade"
+
+# Disable maintenance for specific project
+python manage.py maintenance disable --project myproject
+
+# Check status of all sites
+python manage.py maintenance status
+
+# Discover new sites from Cloudflare
+python manage.py maintenance discover --api-token your_token
+```
+
+#### Django Admin
+
+- Navigate to `/admin/maintenance/`
+- Use bulk actions to manage multiple sites
+- View comprehensive dashboard with statistics
+- Monitor maintenance events and logs
+
+## 📊 Models
+
+### CloudflareSite
+Individual Cloudflare site configuration with maintenance capabilities.
+
+### SiteGroup
+Logical grouping of sites for bulk operations.
+
+### MaintenanceEvent
+Tracks maintenance events with full audit trail.
+
+### MaintenanceLog
+Detailed logging for maintenance operations.
+
+### MonitoringTarget
+External monitoring configuration for automatic triggers.
+
+### CloudflareDeployment
+Tracks Cloudflare Worker deployments with rollback support.
+
+## 🔧 Services
+
+### CloudflareService
+Core Cloudflare API v4 integration with proper error handling and retries.
+
+### CloudflareAutoSetup
+Zero-configuration setup service that automatically discovers and configures Cloudflare resources.
+
+### MultiSiteManager
+ORM-like interface for multi-site management with bulk operations.
+
+### MonitoringService
+External health check monitoring with automatic maintenance triggers.
+
+## 🎛️ Admin Interface
+
+Rich Django admin interface with:
+
+- **Site Dashboard** - Overview of all sites with statistics
+- **Bulk Operations** - Enable/disable maintenance for multiple sites
+- **Status Monitoring** - Real-time site status checks
+- **Event Tracking** - Complete audit trail of maintenance events
+- **Log Viewing** - Detailed operation logs with filtering
+
+## 📱 Management Commands
+
+### `maintenance`
+
+Comprehensive CLI for maintenance management:
+
+```bash
+# Actions
+python manage.py maintenance enable|disable|status|list|discover
+
+# Filters
+--domain example.com
+--environment production|staging|development|testing
+--project myproject
+--tag critical
+--owner username
+
+# Options
+--reason "Custom reason"
+--message "Custom maintenance message"
+--dry-run  # Preview without executing
+--force    # Skip confirmation
+--verbose  # Detailed output
+```
+
+## 🔍 Monitoring
+
+### External Health Checks
+
+The monitoring system performs external health checks and automatically triggers maintenance mode when sites become unavailable:
+
+```python
+# Configure monitoring target
+target = MonitoringTarget.objects.create(
+    site=site,
+    check_url=f"https://{site.domain}/health/",
+    check_interval=60,  # seconds
+    failure_threshold=3,
+    recovery_threshold=2,
+    auto_enable_maintenance=True,
+    auto_disable_maintenance=True
+)
+```
+
+### Health Check Results
+
+All health check results are stored with detailed information:
+- Response time
+- Status code
+- Error messages
+- Success/failure tracking
+
+## 🌐 Zero-Configuration Setup
+
+The auto-setup service automatically configures:
+
+1. **Zone Discovery** - Finds Zone ID from domain name
+2. **Account Discovery** - Extracts Account ID from zone data
+3. **SSL Configuration** - Sets appropriate SSL/TLS mode
+4. **DNS Records** - Creates missing DNS records if needed
+5. **Worker Deployment** - Deploys maintenance mode Worker
+6. **Monitoring Setup** - Configures health checks
+
+```python
+from django_cfg.models.cloudflare import CloudflareConfig
+from django_cfg.apps.maintenance.services import CloudflareAutoSetup
+
+config = CloudflareConfig(
+    api_token="your_token",
+    domain="example.com"
+)
+
+setup = CloudflareAutoSetup(config)
+result = await setup.setup_complete_infrastructure()
+
+if result.success:
+    print(f"✅ Setup completed in {result.get_duration_seconds():.2f}s")
+else:
+    print(f"❌ Setup failed: {result.error_message}")
+```
+
+## 🔐 Security
+
+- **API Token Security** - Tokens stored securely with proper field types
+- **User Permissions** - Site-level access control with owner/shared model
+- **Audit Trail** - Complete logging of all maintenance operations
+- **Input Validation** - Comprehensive validation using Pydantic v2
+
+## 📈 Scalability
+
+- **Bulk Operations** - Handle hundreds of sites simultaneously
+- **Async Processing** - Non-blocking operations with proper error handling
+- **Rate Limiting** - Respects Cloudflare API rate limits
+- **Retry Logic** - Exponential backoff for failed operations
+- **Connection Pooling** - Efficient HTTP connection management
+
+## 🧪 Testing
+
+```bash
+# Run maintenance app tests
+python manage.py test django_cfg.apps.maintenance
+
+# Test with coverage
+coverage run --source='.' manage.py test django_cfg.apps.maintenance
+coverage report
+```
+
+## 📚 API Reference
+
+### Multi-Site Manager
+
+```python
+from django_cfg.apps.maintenance.services import multi_site_manager
+
+# Get sites queryset
+sites = multi_site_manager.sites(user)
+
+# Filtering methods
+sites.production()           # Production sites
+sites.staging()             # Staging sites  
+sites.active()              # Active sites
+sites.in_maintenance()      # Sites in maintenance
+sites.by_project('name')    # Filter by project
+sites.with_tag('tag')       # Filter by tag
+
+# Bulk operations
+await sites.enable_maintenance(reason, message, user, dry_run)
+await sites.disable_maintenance(user, dry_run)
+await sites.check_status()
+
+# Analysis
+sites.get_environment_summary()  # Count by environment
+sites.get_status_summary()       # Count by status
+sites.get_project_summary()      # Count by project
+```
+
+### Cloudflare Service
+
+```python
+from django_cfg.apps.maintenance.services import CloudflareService
+
+async with CloudflareService(api_token) as cf:
+    # Zone management
+    zones = await cf.get_zones()
+    zone = await cf.get_zone_by_name('example.com')
+    
+    # Worker management
+    result = await cf.deploy_worker(zone_id, worker_name, script_content)
+    success = await cf.delete_worker(zone_id, worker_name)
+    
+    # DNS management
+    record_id = await cf.create_dns_record(zone_id, 'A', 'www', '192.0.2.1')
+    records = await cf.list_dns_records(zone_id)
+    
+    # SSL management
+    settings = await cf.get_ssl_settings(zone_id)
+    success = await cf.update_ssl_setting(zone_id, 'flexible')
+```
+
+## 🤝 Contributing
+
+1. Follow CRITICAL_REQUIREMENTS.md for code standards
+2. Use proper type hints and Pydantic models
+3. Add comprehensive tests for new features
+4. Update documentation for API changes
+5. Follow django-cfg patterns and conventions
+
+## 📄 License
+
+Part of django-cfg package. See main package license.

django_cfg/apps/maintenance/__init__.py

@@ -0,0 +1,27 @@
+"""
+Django-CFG Maintenance Application
+
+Multi-site maintenance mode management with Cloudflare integration.
+Provides zero-configuration setup and ORM-like interface for managing
+maintenance mode across multiple sites.
+
+Key Features:
+- Zero-configuration Cloudflare setup
+- Multi-site management with ORM-like queries
+- External monitoring for automatic maintenance mode
+- Rich Django admin interface
+- Scheduled maintenance support
+- Full audit trail and logging
+
+Example Usage:
+    # Zero-config setup
+    CLOUDFLARE_API_TOKEN = "your_token"
+    CLOUDFLARE_DOMAIN = "example.com"
+    
+    # Multi-site management
+    sites = multi_site_manager.sites(user)
+    await sites.production().enable_maintenance()
+    await sites.filter(project='client-a').disable_maintenance()
+"""
+
+default_app_config = 'django_cfg.apps.maintenance.apps.MaintenanceConfig'

django_cfg/apps/maintenance/admin/__init__.py

@@ -0,0 +1,28 @@
+"""
+Maintenance admin interfaces.
+
+Rich Django admin interfaces for multi-site maintenance management.
+Following django-cfg patterns with Unfold optimization.
+"""
+
+# Import all admin classes to register them
+from .sites_admin import CloudflareSiteAdmin, SiteGroupAdmin
+from .events_admin import MaintenanceEventAdmin, MaintenanceLogAdmin
+from .monitoring_admin import MonitoringTargetAdmin
+from .deployments_admin import CloudflareDeploymentAdmin
+
+__all__ = [
+    # Site management
+    'CloudflareSiteAdmin',
+    'SiteGroupAdmin',
+    
+    # Maintenance tracking
+    'MaintenanceEventAdmin', 
+    'MaintenanceLogAdmin',
+    
+    # Monitoring
+    'MonitoringTargetAdmin',
+    
+    # Cloudflare integration
+    'CloudflareDeploymentAdmin',
+]

django_cfg/apps/maintenance/admin/deployments_admin.py

@@ -0,0 +1,251 @@
+"""
+Deployments admin interfaces with Unfold optimization.
+"""
+
+from django.contrib import admin
+from django.utils.html import format_html
+from django.urls import reverse
+from django.utils.safestring import mark_safe
+from django.db import models
+from django.db.models import Count, Q
+from django.contrib import messages
+from django.shortcuts import redirect
+from unfold.admin import ModelAdmin, TabularInline
+from unfold.decorators import display, action
+from unfold.enums import ActionVariant
+from unfold.contrib.filters.admin import AutocompleteSelectFilter
+from django_cfg import ImportExportModelAdmin, ExportMixin
+
+from ..models import CloudflareDeployment
+
+
+@admin.register(CloudflareDeployment)
+class CloudflareDeploymentAdmin(ModelAdmin, ImportExportModelAdmin):
+    """Admin for CloudflareDeployment with Unfold styling."""
+    
+    list_display = [
+        "deployment_with_icon",
+        "site_link",
+        "deployment_type_badge",
+        "status_badge",
+        "worker_name_display",
+        "created_at_display",
+        "deployed_at_display"
+    ]
+    list_display_links = ["deployment_with_icon"]
+    search_fields = ["site__name", "site__domain", "worker_name", "script_name"]
+    list_filter = [
+        "deployment_type",
+        "status",
+        "created_at",
+        "deployed_at",
+        ("site", AutocompleteSelectFilter),
+        ("maintenance_event", AutocompleteSelectFilter),
+    ]
+    ordering = ["-created_at"]
+    readonly_fields = [
+        "deployed_at", "created_at"
+    ]
+    
+    fieldsets = (
+        ("Deployment Information", {
+            "fields": ("site", "deployment_type", "maintenance_event")
+        }),
+        ("Worker Configuration", {
+            "fields": ("worker_name", "script_name", "script_content"),
+            "classes": ("collapse",)
+        }),
+        ("Cloudflare Details", {
+            "fields": ("worker_id", "script_id", "deployment_config"),
+            "classes": ("collapse",)
+        }),
+        ("Status & Logs", {
+            "fields": ("status", "deployed_at", "deployment_logs"),
+            "classes": ("collapse",)
+        }),
+        ("Timestamps", {
+            "fields": ("created_at", "updated_at"),
+            "classes": ("collapse",)
+        })
+    )
+    
+    # Unfold actions
+    actions_detail = ["deploy_worker", "undeploy_worker", "view_logs"]
+    
+    @display(description="Deployment", ordering="worker_name")
+    def deployment_with_icon(self, obj):
+        """Display deployment with status icon."""
+        icons = {
+            'pending': '⏳',
+            'deploying': '🚀',
+            'deployed': '✅',
+            'failed': '❌',
+            'undeployed': '🗑️'
+        }
+        icon = icons.get(obj.status, '📦')
+        name = obj.worker_name or obj.script_name or f"Deployment #{obj.id}"
+        return format_html('{} {}', icon, name)
+    
+    @display(description="Site")
+    def site_link(self, obj):
+        """Display site with link."""
+        return format_html(
+            '<a href="{}" class="text-decoration-none">🌐 {}</a>',
+            reverse('admin:django_cfg_maintenance_cloudflaresite_change', 
+                   args=[obj.site.id]),
+            obj.site.name
+        )
+    
+    @display(description="Type", ordering="deployment_type")
+    def deployment_type_badge(self, obj):
+        """Display deployment type with colored badge."""
+        colors = {
+            'maintenance_page': 'warning',
+            'redirect': 'info',
+            'custom_worker': 'primary',
+            'error_page': 'danger'
+        }
+        color = colors.get(obj.deployment_type, 'secondary')
+        return format_html(
+            '<span class="badge badge-{}">{}</span>',
+            color, obj.get_deployment_type_display()
+        )
+    
+    @display(description="Status", ordering="status")
+    def status_badge(self, obj):
+        """Display status with colored badge."""
+        colors = {
+            'pending': 'secondary',
+            'deploying': 'info',
+            'deployed': 'success',
+            'failed': 'danger',
+            'undeployed': 'warning'
+        }
+        color = colors.get(obj.status, 'secondary')
+        return format_html(
+            '<span class="badge badge-{}">{}</span>',
+            color, obj.get_status_display()
+        )
+    
+    @display(description="Worker")
+    def worker_name_display(self, obj):
+        """Display worker name or script name."""
+        if obj.worker_name:
+            return obj.worker_name
+        elif obj.script_name:
+            return format_html('<em>{}</em>', obj.script_name)
+        else:
+            return format_html('<span class="text-muted">Auto-generated</span>')
+    
+    @display(description="Created", ordering="created_at")
+    def created_at_display(self, obj):
+        """Display creation time."""
+        return obj.created_at.strftime("%Y-%m-%d %H:%M")
+    
+    @display(description="Deployed", ordering="deployed_at")
+    def deployed_at_display(self, obj):
+        """Display deployment time."""
+        if not obj.deployed_at:
+            return format_html('<span class="text-muted">Not deployed</span>')
+        
+        from django.utils import timezone
+        from datetime import timedelta
+        
+        now = timezone.now()
+        diff = now - obj.deployed_at
+        
+        if diff < timedelta(hours=1):
+            color = "success"
+        elif diff < timedelta(days=1):
+            color = "info"
+        else:
+            color = "secondary"
+        
+        return format_html(
+            '<span class="text-{}">{}</span>',
+            color, obj.deployed_at.strftime("%Y-%m-%d %H:%M")
+        )
+    
+    def get_queryset(self, request):
+        """Optimize queryset."""
+        return super().get_queryset(request).select_related(
+            'site', 'maintenance_event'
+        )
+    
+    @action(
+        description="🚀 Deploy Worker",
+        icon="rocket_launch",
+        variant=ActionVariant.SUCCESS
+    )
+    def deploy_worker(self, request, object_id):
+        """Deploy Cloudflare Worker."""
+        try:
+            deployment = CloudflareDeployment.objects.get(id=object_id)
+            
+            if deployment.status == 'deployed':
+                messages.warning(request, "Worker is already deployed")
+                return redirect(request.META.get('HTTP_REFERER', '/admin/'))
+            
+            # Deploy worker logic here (placeholder)
+            deployment.status = 'deploying'
+            deployment.save()
+            
+            messages.success(
+                request,
+                f"Deployment started for {deployment.site.name}"
+            )
+            
+        except Exception as e:
+            messages.error(request, f"Deployment failed: {str(e)}")
+        
+        return redirect(request.META.get('HTTP_REFERER', '/admin/'))
+    
+    @action(
+        description="🗑️ Undeploy Worker",
+        icon="delete",
+        variant=ActionVariant.DANGER
+    )
+    def undeploy_worker(self, request, object_id):
+        """Undeploy Cloudflare Worker."""
+        try:
+            deployment = CloudflareDeployment.objects.get(id=object_id)
+            
+            if deployment.status != 'deployed':
+                messages.warning(request, "Worker is not currently deployed")
+                return redirect(request.META.get('HTTP_REFERER', '/admin/'))
+            
+            # Undeploy worker logic here (placeholder)
+            deployment.status = 'undeployed'
+            deployment.save()
+            
+            messages.success(
+                request,
+                f"Worker undeployed for {deployment.site.name}"
+            )
+            
+        except Exception as e:
+            messages.error(request, f"Undeployment failed: {str(e)}")
+        
+        return redirect(request.META.get('HTTP_REFERER', '/admin/'))
+    
+    @action(
+        description="📋 View Logs",
+        icon="description",
+        variant=ActionVariant.INFO
+    )
+    def view_logs(self, request, object_id):
+        """View deployment logs."""
+        try:
+            deployment = CloudflareDeployment.objects.get(id=object_id)
+            
+            # This would typically redirect to a logs view
+            # For now, just show a message
+            messages.info(
+                request,
+                f"Logs for deployment {deployment.id} would be displayed here"
+            )
+            
+        except Exception as e:
+            messages.error(request, f"Failed to retrieve logs: {str(e)}")
+        
+        return redirect(request.META.get('HTTP_REFERER', '/admin/'))