django-cfg 1.4.46__py3-none-any.whl → 1.5.181__py3-none-any.whl

django_cfg/apps/system/frontend/setup.py

@@ -0,0 +1,105 @@
+"""
+Frontend App Setup Helpers
+
+Provides utilities to automatically configure Django to serve Next.js static builds.
+"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from django.conf import Settings
+
+
+def setup_frontend_serving(settings: 'Settings' = None) -> dict:
+    """
+    Configure Django to serve Next.js static builds.
+
+    This function returns configuration that should be added to Django settings.
+
+    Usage in settings.py:
+    ```python
+    from django_cfg.apps.system.frontend.setup import setup_frontend_serving
+
+    # Apply frontend configuration
+    frontend_config = setup_frontend_serving()
+    INSTALLED_APPS += frontend_config['INSTALLED_APPS']
+    ```
+
+    Args:
+        settings: Django settings module (optional)
+
+    Returns:
+        dict: Configuration to merge into settings
+    """
+    import django_cfg
+
+    config = {
+        'INSTALLED_APPS': [
+            'django_cfg.apps.system.frontend',
+        ],
+    }
+
+    return config
+
+
+def get_frontend_path(app_name: str = 'admin') -> Path:
+    """
+    Get the path to a frontend app's static build.
+
+    Args:
+        app_name: Name of the frontend app (e.g., 'admin')
+
+    Returns:
+        Path: Absolute path to the frontend build directory
+
+    Example:
+        >>> from django_cfg.apps.system.frontend.setup import get_frontend_path
+        >>> admin_path = get_frontend_path('admin')
+        >>> print(admin_path)
+        /path/to/django_cfg/static/frontend/admin
+    """
+    import django_cfg
+    return Path(django_cfg.__file__).parent / 'static' / 'frontend' / app_name
+
+
+def is_frontend_built(app_name: str = 'admin') -> bool:
+    """
+    Check if a frontend app has been built.
+
+    Args:
+        app_name: Name of the frontend app
+
+    Returns:
+        bool: True if the build exists, False otherwise
+    """
+    path = get_frontend_path(app_name)
+    index_html = path / 'index.html'
+    return index_html.exists()
+
+
+def get_frontend_urls():
+    """
+    Get URL patterns for frontend apps.
+
+    Usage in urls.py:
+    ```python
+    from django_cfg.apps.system.frontend.setup import get_frontend_urls
+
+    urlpatterns = [
+        # Your URLs here
+        ...
+    ]
+
+    # Add frontend URLs
+    urlpatterns += get_frontend_urls()
+    ```
+
+    Returns:
+        list: URL patterns for frontend apps
+    """
+    from django.urls import path, include
+
+    return [
+        path('', include('django_cfg.apps.system.frontend.urls', namespace='frontend')),
+    ]

django_cfg/apps/system/frontend/templates/frontend/404.html

@@ -0,0 +1,23 @@
+{% extends 'django_tailwind/simple.html' %}
+{% load django_cfg %}
+
+{% block title %}404 - Page Not Found{% endblock %}
+
+{% block icon %}🔍{% endblock %}
+
+{% block heading %}Page Not Found{% endblock %}
+
+{% block message %}
+The page you're looking for doesn't exist or has been moved.
+{% endblock %}
+
+{% block actions %}
+<a href="/cfg/admin/"
+   class="inline-flex items-center justify-center px-6 py-3 border border-transparent rounded-lg shadow-sm text-base font-medium text-white bg-primary-600 hover:bg-primary-700 dark:bg-primary-500 dark:hover:bg-primary-600 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary-500 transition-colors">
+    Go to Admin
+</a>
+<a href="/"
+   class="inline-flex items-center justify-center px-6 py-3 border border-base-300 dark:border-base-600 rounded-lg shadow-sm text-base font-medium text-font-default-light dark:text-font-default-dark bg-white dark:bg-base-800 hover:bg-base-50 dark:hover:bg-base-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary-500 transition-colors">
+    Go Home
+</a>
+{% endblock %}

django_cfg/apps/system/frontend/templates/frontend/route_not_found.html

@@ -0,0 +1,33 @@
+{% extends 'django_tailwind/simple.html' %}
+{% load django_cfg %}
+
+{% block title %}Route Not Available{% endblock %}
+
+{% block theme_toggle %}{% endblock %}
+
+{% block icon %}<span class="material-icons text-6xl text-amber-500">warning</span>{% endblock %}
+
+{% block heading %}Route Not Available{% endblock %}
+
+{% block message %}
+<span class="block mb-2">
+    The route <code class="bg-amber-100 dark:bg-amber-900/50 text-amber-800 dark:text-amber-200 px-2 py-0.5 rounded text-sm font-mono">{{ path }}</code> is not available in static export mode.
+</span>
+<span class="text-sm text-gray-500 dark:text-gray-400">
+    This page requires <code class="text-xs">generateStaticParams()</code> or development server.
+</span>
+{% endblock %}
+
+{% block actions %}
+<a href="/cfg/admin/"
+   class="inline-flex items-center justify-center px-5 py-2.5 border border-transparent rounded-lg shadow-sm text-sm font-medium text-white bg-indigo-600 hover:bg-indigo-700 dark:bg-indigo-500 dark:hover:bg-indigo-600 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 transition-colors">
+    <span class="material-icons text-lg mr-2">home</span>
+    Admin Dashboard
+</a>
+<a href="https://djangocfg.com/docs/guides/nextjs-admin-setup/troubleshooting"
+   target="_blank"
+   class="inline-flex items-center justify-center px-5 py-2.5 border border-gray-300 dark:border-gray-600 rounded-lg shadow-sm text-sm font-medium text-gray-700 dark:text-gray-200 bg-white dark:bg-gray-800 hover:bg-gray-50 dark:hover:bg-gray-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 transition-colors">
+    <span class="material-icons text-lg mr-2">menu_book</span>
+    Documentation
+</a>
+{% endblock %}

django_cfg/apps/system/frontend/test_routing.py

@@ -0,0 +1,134 @@
+"""
+Test script for SPA routing logic.
+
+Run this to verify that URL paths resolve correctly to static files.
+"""
+
+from pathlib import Path
+import django_cfg
+
+
+def test_resolve_spa_path():
+    """Test the SPA path resolution logic."""
+
+    # Simulate the base directory
+    base_dir = Path(django_cfg.__file__).parent / 'static' / 'frontend' / 'admin'
+
+    print(f"Base directory: {base_dir}")
+    print(f"Base directory exists: {base_dir.exists()}\n")
+
+    # Test cases
+    test_cases = [
+        # (input_path, expected_output_path, description)
+        ('', 'index.html', 'Root path'),
+        ('/', 'index.html', 'Root path with slash'),
+        ('private/centrifugo', 'private/centrifugo/index.html', 'Nested route without trailing slash'),
+        ('private/centrifugo/', 'private/centrifugo/index.html', 'Nested route with trailing slash'),
+        ('private', 'private.html', 'Single segment route'),
+        ('private/', 'private/index.html', 'Single segment with trailing slash'),
+        ('_next/static/chunks/app.js', '_next/static/chunks/app.js', 'Static asset (exact match)'),
+        ('favicon.ico', 'favicon.ico', 'Favicon (exact match)'),
+        ('unknown/route', 'index.html', 'Unknown route (SPA fallback)'),
+    ]
+
+    def resolve_spa_path(base_dir, path):
+        """
+        Exact copy of the view's _resolve_spa_path method.
+
+        This should match the logic in views.py exactly.
+        """
+        # Handle empty path (done in view before calling this method)
+        if not path or path == '/':
+            path = 'index.html'
+            return path
+
+        file_path = base_dir / path
+        path_normalized = path.rstrip('/')
+
+        # Strategy 1: Exact file match (for static assets like JS, CSS, images)
+        if file_path.exists() and file_path.is_file():
+            return path
+
+        # Strategy 2: Try path/index.html (most common for SPA routes)
+        index_in_dir = base_dir / path_normalized / 'index.html'
+        if index_in_dir.exists():
+            resolved_path = f"{path_normalized}/index.html"
+            return resolved_path
+
+        # Strategy 3: Try with trailing slash + index.html
+        if path.endswith('/'):
+            index_path = path + 'index.html'
+            if (base_dir / index_path).exists():
+                return index_path
+
+        # Strategy 4: Try path.html (Next.js static export behavior)
+        html_file = base_dir / (path_normalized + '.html')
+        if html_file.exists():
+            resolved_path = path_normalized + '.html'
+            return resolved_path
+
+        # Strategy 5: Check if it's a directory without index.html
+        if file_path.exists() and file_path.is_dir():
+            # Try index.html in that directory
+            index_in_existing_dir = file_path / 'index.html'
+            if index_in_existing_dir.exists():
+                resolved_path = f"{path_normalized}/index.html"
+                return resolved_path
+
+        # Strategy 6: SPA fallback - serve root index.html
+        # This allows client-side routing to handle unknown routes
+        root_index = base_dir / 'index.html'
+        if root_index.exists():
+            return 'index.html'
+
+        # Strategy 7: Nothing found - return original path (will 404)
+        return path
+
+    print("=" * 80)
+    print("SPA ROUTING TEST RESULTS")
+    print("=" * 80)
+
+    passed = 0
+    failed = 0
+
+    for input_path, expected, description in test_cases:
+        result = resolve_spa_path(base_dir, input_path)
+
+        # Check if file exists
+        resolved_file = base_dir / result
+        file_exists = resolved_file.exists() and resolved_file.is_file()
+
+        # Determine test status
+        if result == expected:
+            status = "✅ PASS"
+            passed += 1
+        else:
+            status = "❌ FAIL"
+            failed += 1
+
+        print(f"\n{status} - {description}")
+        print(f"  Input:    '{input_path}'")
+        print(f"  Expected: '{expected}'")
+        print(f"  Got:      '{result}'")
+        print(f"  File exists: {file_exists}")
+
+        if result != expected:
+            print(f"  ⚠️  Mismatch detected!")
+
+    print("\n" + "=" * 80)
+    print(f"TEST SUMMARY: {passed} passed, {failed} failed out of {len(test_cases)} tests")
+    print("=" * 80)
+
+    # Additional info
+    print("\n📁 File structure check:")
+    if base_dir.exists():
+        print(f"  - index.html: {(base_dir / 'index.html').exists()}")
+        print(f"  - private.html: {(base_dir / 'private.html').exists()}")
+        print(f"  - private/index.html: {(base_dir / 'private' / 'index.html').exists()}")
+        print(f"  - private/centrifugo/index.html: {(base_dir / 'private' / 'centrifugo' / 'index.html').exists()}")
+    else:
+        print(f"  ⚠️  Base directory does not exist!")
+
+
+if __name__ == '__main__':
+    test_resolve_spa_path()

django_cfg/apps/system/frontend/urls.py

@@ -0,0 +1,12 @@
+"""URL Configuration for Frontend Apps."""
+
+from django.urls import re_path
+from .views import AdminView
+
+
+app_name = 'frontend'
+
+urlpatterns = [
+    # Next.js Admin Panel - catch all routes for client-side routing
+    re_path(r'^(?P<path>.*)$', AdminView.as_view(), name='admin'),
+]

django_cfg/apps/system/frontend/utils/__init__.py

@@ -0,0 +1,24 @@
+"""
+Frontend utilities for Next.js static build processing.
+"""
+
+from .html_link_fixer import get_base_path_for_app, fix_html_links_after_extraction
+from .spa_path_resolver import resolve_spa_path
+from .compression import find_precompressed_file
+from .jwt_injection import should_inject_jwt, inject_jwt_tokens, convert_file_response_to_http_response
+from .downloader import download_frontend_asset, ensure_frontend_asset, get_asset_path
+
+__all__ = [
+    'get_base_path_for_app',
+    'fix_html_links_after_extraction',
+    'resolve_spa_path',
+    'find_precompressed_file',
+    'should_inject_jwt',
+    'inject_jwt_tokens',
+    'convert_file_response_to_http_response',
+    # Downloader
+    'download_frontend_asset',
+    'ensure_frontend_asset',
+    'get_asset_path',
+]
+

django_cfg/apps/system/frontend/utils/compression.py

@@ -0,0 +1,75 @@
+"""
+Compression Utility
+
+Handles detection and serving of precompressed files (.br, .gz).
+"""
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def find_precompressed_file(base_dir: Path, path: str, accept_encoding: str) -> tuple[str | None, str | None]:
+    """
+    Find and return precompressed file (.br or .gz) if available and supported by browser.
+    
+    Brotli (.br) is preferred over Gzip (.gz) as it provides better compression.
+    
+    Args:
+        base_dir: Base directory for static files
+        path: Requested file path
+        accept_encoding: Accept-Encoding header value (e.g., 'br, gzip, deflate')
+        
+    Returns:
+        tuple: (compressed_path, encoding) if precompressed file found and supported,
+               (None, None) otherwise
+               
+    Examples:
+        >>> from pathlib import Path
+        >>> base_dir = Path('/path/to/static')
+        >>> find_precompressed_file(base_dir, '_app.js', 'br, gzip')
+        ('_app.js.br', 'br')
+        >>> find_precompressed_file(base_dir, '_app.js', 'gzip')
+        ('_app.js.gz', 'gzip')
+        >>> find_precompressed_file(base_dir, 'index.html', 'br, gzip')
+        (None, None)  # HTML files are never compressed
+    """
+    accept_encoding_lower = accept_encoding.lower()
+    
+    # Check if browser supports brotli (preferred) or gzip
+    supports_br = 'br' in accept_encoding_lower
+    supports_gzip = 'gzip' in accept_encoding_lower
+    
+    if not (supports_br or supports_gzip):
+        return None, None
+    
+    # Don't compress HTML files - we need to inject JWT tokens
+    # JWT injection requires modifying content, which is incompatible with compression
+    if path.endswith('.html'):
+        return None, None
+    
+    # Build full file path
+    file_path = base_dir / path
+    
+    # Check if original file exists (safety check)
+    if not file_path.exists() or not file_path.is_file():
+        return None, None
+    
+    # Try Brotli first (better compression, ~5-15% smaller than gzip)
+    if supports_br:
+        br_path = f"{path}.br"
+        br_file = base_dir / br_path
+        if br_file.exists() and br_file.is_file():
+            return br_path, 'br'
+    
+    # Fallback to Gzip
+    if supports_gzip:
+        gz_path = f"{path}.gz"
+        gz_file = base_dir / gz_path
+        if gz_file.exists() and gz_file.is_file():
+            return gz_path, 'gzip'
+    
+    # No precompressed file found or not supported
+    return None, None
+