aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/hooks.py

@@ -0,0 +1,144 @@
+# app/components/backend/hooks.py
+"""
+Backend-specific hook management system for drop-in extensibility.
+
+This system automatically discovers and registers:
+- Middleware from app/components/backend/middleware/
+- Startup hooks from app/components/backend/startup/
+- Shutdown hooks from app/components/backend/shutdown/
+
+Just drop files in the appropriate folders - no central registration required.
+"""
+
+import importlib
+import inspect
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from app.core.log import logger
+from fastapi import FastAPI
+
+
+class BackendHooks:
+    """Backend-specific hook management system."""
+
+    def __init__(self) -> None:
+        self.startup_hooks: list[Callable[[], Any]] = []
+        self.shutdown_hooks: list[Callable[[], Any]] = []
+
+    def discover_and_register_middleware(self, app: FastAPI) -> None:
+        """
+        Auto-discover and register middleware. This must be called
+        before the application starts.
+        """
+        middleware_dir = Path(__file__).parent / "middleware"
+        if not middleware_dir.exists():
+            return
+
+        for middleware_file in middleware_dir.glob("*.py"):
+            if middleware_file.name.startswith("_"):
+                continue
+
+            module_name = f"app.components.backend.middleware.{middleware_file.stem}"
+            try:
+                module = importlib.import_module(module_name)
+                if hasattr(module, "register_middleware"):
+                    logger.info(f"Registering middleware from {module_name}")
+                    # Middleware registration is synchronous
+                    module.register_middleware(app)
+            except Exception as e:
+                logger.error(f"Failed to load middleware {module_name}: {e}")
+
+    async def discover_lifespan_hooks(self) -> None:
+        """Discover startup and shutdown hooks for the lifespan event."""
+        await self._discover_startup_hooks()
+        await self._discover_shutdown_hooks()
+
+    async def _discover_startup_hooks(self) -> None:
+        """Auto-discover startup hooks from app/components/backend/startup/."""
+        startup_dir = Path(__file__).parent / "startup"
+        if not startup_dir.exists():
+            logger.info("No backend startup directory found")
+            return
+
+        for startup_file in startup_dir.glob("*.py"):
+            if startup_file.name.startswith("_"):
+                continue
+
+            module_name = f"app.components.backend.startup.{startup_file.stem}"
+            try:
+                module = importlib.import_module(module_name)
+
+                # Look for startup_hook function
+                if hasattr(module, "startup_hook"):
+                    # Prevent duplicate registration
+                    if module.startup_hook not in self.startup_hooks:
+                        logger.info(f"Registered startup hook from {module_name}")
+                        self.startup_hooks.append(module.startup_hook)
+                    else:
+                        logger.debug(
+                            f"Startup hook from {module_name} already registered"
+                        )
+
+            except Exception as e:
+                logger.error(f"Failed to load startup hook {module_name}: {e}")
+
+    async def _discover_shutdown_hooks(self) -> None:
+        """Auto-discover shutdown hooks from app/components/backend/shutdown/."""
+        shutdown_dir = Path(__file__).parent / "shutdown"
+        if not shutdown_dir.exists():
+            logger.info("No backend shutdown directory found")
+            return
+
+        for shutdown_file in shutdown_dir.glob("*.py"):
+            if shutdown_file.name.startswith("_"):
+                continue
+
+            module_name = f"app.components.backend.shutdown.{shutdown_file.stem}"
+            try:
+                module = importlib.import_module(module_name)
+
+                # Look for shutdown_hook function
+                if hasattr(module, "shutdown_hook"):
+                    # Prevent duplicate registration
+                    if module.shutdown_hook not in self.shutdown_hooks:
+                        logger.info(f"Registered shutdown hook from {module_name}")
+                        self.shutdown_hooks.append(module.shutdown_hook)
+                    else:
+                        logger.debug(
+                            f"Shutdown hook from {module_name} already registered"
+                        )
+
+            except Exception as e:
+                logger.error(f"Failed to load shutdown hook {module_name}: {e}")
+
+    async def execute_startup_hooks(self) -> None:
+        """Execute all discovered startup hooks."""
+        logger.info(f"Executing {len(self.startup_hooks)} backend startup hooks")
+        for hook in self.startup_hooks:
+            try:
+                if inspect.iscoroutinefunction(hook):
+                    await hook()
+                else:
+                    hook()
+            except Exception as e:
+                logger.error(f"Startup hook failed: {e}")
+                raise
+
+    async def execute_shutdown_hooks(self) -> None:
+        """Execute all discovered shutdown hooks in reverse order."""
+        logger.info(f"Executing {len(self.shutdown_hooks)} backend shutdown hooks")
+        for hook in reversed(self.shutdown_hooks):
+            try:
+                if inspect.iscoroutinefunction(hook):
+                    await hook()
+                else:
+                    hook()
+            except Exception as e:
+                logger.error(f"Shutdown hook failed: {e}")
+                # Continue with other shutdown hooks even if one fails
+
+
+# Global backend hooks instance
+backend_hooks = BackendHooks()

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/main.py

@@ -0,0 +1,31 @@
+from app.components.backend.api.routing import include_routers
+from app.components.backend.hooks import backend_hooks
+from fastapi import FastAPI
+
+# Store the configured FastAPI app instance for introspection
+_configured_app: FastAPI | None = None
+
+
+def create_backend_app(app: FastAPI) -> FastAPI:
+    """Configure FastAPI app with all backend concerns"""
+    global _configured_app
+
+    # Store the app instance for later introspection
+    _configured_app = app
+
+    # Auto-discover and register middleware
+    backend_hooks.discover_and_register_middleware(app)
+
+    # Include all routes
+    include_routers(app)
+
+    return app
+
+
+def get_configured_app() -> FastAPI | None:
+    """
+    Get the configured backend FastAPI app instance.
+    Returns:
+        The configured FastAPI app instance, or None if not yet configured.
+    """
+    return _configured_app

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/middleware/__init__.py

@@ -0,0 +1 @@
+# Backend middleware

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/middleware/cors.py

@@ -0,0 +1,20 @@
+# app/components/backend/middleware/cors.py
+"""
+Auto-discovered CORS middleware for development.
+
+This middleware is automatically registered with FastAPI when the backend starts.
+"""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+
+def register_middleware(app: FastAPI) -> None:
+    """Auto-discovered middleware registration."""
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost:3000", "http://localhost:8080"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/shutdown/__init__.py

@@ -0,0 +1 @@
+# Backend shutdown hooks

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/shutdown/cleanup.py

@@ -0,0 +1,14 @@
+# app/components/backend/shutdown/cleanup.py
+"""
+Auto-discovered cleanup shutdown hook.
+
+This hook performs cleanup when the backend shuts down.
+"""
+
+from app.core.log import logger
+
+
+async def shutdown_hook() -> None:
+    """Auto-discovered shutdown hook for cleanup."""
+    logger.info("🧹 Running backend cleanup...")
+    logger.info("✅ Backend shutdown cleanup complete")

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/startup/__init__.py

@@ -0,0 +1 @@
+# Backend startup hooks

aegis/templates/copier-aegis-project/{{ project_slug }}/app/components/backend/startup/component_health.py.jinja

@@ -0,0 +1,418 @@
+"""
+Component health registration startup hook.
+
+Automatically detects available components and registers their health checks
+with the system health service using Python's import system.
+"""
+
+from app.core.log import logger
+from app.services.system.health import register_health_check
+from app.services.system.models import ComponentStatus, ComponentStatusType
+from app.components.backend.main import get_configured_app
+from app.services.backend.route_inspector import get_fastapi_route_metadata, RouteMetadata
+from app.services.backend.middleware_inspector import get_fastapi_middleware_metadata, MiddlewareMetadata
+
+# Cache for route metadata - initialized once at startup
+_cached_route_metadata: RouteMetadata | None = None
+# Cache for middleware metadata - initialized once at startup  
+_cached_middleware_metadata: MiddlewareMetadata | None = None
+
+
+def _initialize_route_metadata_cache() -> None:
+    """
+    Initialize route and middleware metadata caches using the configured FastAPI app.
+    Called once during startup to avoid recreating the app on every health check.
+    """
+    global _cached_route_metadata, _cached_middleware_metadata
+    
+    if _cached_route_metadata is not None and _cached_middleware_metadata is not None:
+        return  # Already initialized
+    
+    try:
+        app = get_configured_app()
+        if app is not None:
+            # Cache route metadata
+            if _cached_route_metadata is None:
+                _cached_route_metadata = get_fastapi_route_metadata(app)
+                logger.info(
+                    f"Route metadata cached: "
+                    f"{_cached_route_metadata.total_routes} routes, "
+                    f"{_cached_route_metadata.total_endpoints} endpoints"
+                )
+            
+            # Cache middleware metadata
+            if _cached_middleware_metadata is None:
+                _cached_middleware_metadata = get_fastapi_middleware_metadata(app)
+                logger.info(
+                    f"Middleware metadata cached: "
+                    f"{_cached_middleware_metadata.total_middleware} middleware, "
+                    f"{_cached_middleware_metadata.security_count} security layers"
+                )
+        else:
+            logger.warning(
+                "FastAPI app not yet configured - route and middleware metadata "
+                "cache will be initialized later"
+            )
+    except Exception as e:
+        logger.error(f"Failed to initialize route and middleware metadata cache: {e}")
+
+
+async def _backend_component_health() -> ComponentStatus:
+    """
+    FastAPI backend health check with route and middleware introspection.
+
+    In test environment, reports as healthy since the app is loaded.
+    In production, uses internal check to avoid circular dependency.
+    Includes comprehensive route and middleware metadata for dashboard display.
+    """
+    import os
+    global _cached_route_metadata, _cached_middleware_metadata
+
+    # Check if we're in test environment
+    if os.getenv("PYTEST_CURRENT_TEST") or "pytest" in os.getenv("_", ""):
+        # Even in test mode, try to get route and middleware information if possible
+        try:
+            
+            # Initialize cache if not already done (might happen in tests)
+            if _cached_route_metadata is None or _cached_middleware_metadata is None:
+                _initialize_route_metadata_cache()
+            
+            route_metadata = _cached_route_metadata
+            middleware_metadata = _cached_middleware_metadata
+            
+            # Handle case where metadata is not available in test mode
+            if route_metadata is None or middleware_metadata is None:
+                return ComponentStatus(
+                    name="backend",
+                    status=ComponentStatusType.HEALTHY,
+                    message="FastAPI backend available (test mode)",
+                    response_time_ms=None,
+                    metadata={
+                        "type": "component_check",
+                        "environment": "test",
+                        "note": "Backend component loaded successfully",
+                        "route_introspection": "unavailable",
+                        "middleware_introspection": "unavailable",
+                    },
+                )
+            
+            # Create message with both route and middleware info
+            message_parts = [f"{route_metadata.total_routes} routes"]
+            if middleware_metadata.security_count > 0:
+                message_parts.append(
+                    f"{middleware_metadata.security_count} security layers"
+                )
+            
+            return ComponentStatus(
+                name="backend",
+                status=ComponentStatusType.HEALTHY,
+                message=(
+                    f"FastAPI backend available (test mode): "
+                    f"{', '.join(message_parts)}"
+                ),
+                response_time_ms=None,
+                metadata={
+                    "type": "component_check",
+                    "environment": "test",
+                    "note": "Backend component loaded successfully",
+                    **route_metadata.model_dump_for_metadata(),
+                    **middleware_metadata.model_dump_for_metadata(),
+                },
+            )
+        except Exception as e:
+            logger.warning(
+                f"Could not get route and middleware metadata in test mode: {e}"
+            )
+            return ComponentStatus(
+                name="backend",
+                status=ComponentStatusType.HEALTHY,
+                message="FastAPI backend available (test mode)",
+                response_time_ms=None,
+                metadata={
+                    "type": "component_check",
+                    "environment": "test",
+                    "note": "Backend component loaded successfully",
+                    "route_introspection_error": str(e),
+                    "middleware_introspection_error": str(e),
+                },
+            )
+
+    # In production, use cached route and middleware information
+    try:
+        # Initialize cache if not already done (fallback safety)
+        if _cached_route_metadata is None or _cached_middleware_metadata is None:
+            logger.warning(
+                "Route and middleware metadata cache not initialized at startup, "
+                "initializing now..."
+            )
+            _initialize_route_metadata_cache()
+        
+        route_metadata = _cached_route_metadata
+        middleware_metadata = _cached_middleware_metadata
+        
+        # Handle case where metadata is still not available
+        if route_metadata is None or middleware_metadata is None:
+            return ComponentStatus(
+                name="backend",
+                status=ComponentStatusType.HEALTHY,
+                message=(
+                    "FastAPI backend active (introspection unavailable)"
+                ),
+                response_time_ms=None,
+                metadata={
+                    "type": "internal_component_check",
+                    "note": (
+                        "Backend is running but route/middleware metadata unavailable"
+                    ),
+                    "check_method": "internal_execution",
+                },
+            )
+        
+        # Create descriptive message based on route and middleware data
+        total_routes = route_metadata.total_routes
+        total_endpoints = route_metadata.total_endpoints
+        method_counts = route_metadata.method_counts
+        security_count = middleware_metadata.security_count
+        
+        # Format method summary (e.g., "12 GET, 5 POST")
+        method_summary = ", ".join([
+            f"{count} {method}" 
+            for method, count in sorted(method_counts.items())
+        ])
+        
+        message_parts = [f"{total_routes} routes"]
+        if total_endpoints != total_routes:
+            message_parts.append(f"{total_endpoints} endpoints")
+        if security_count > 0:
+            message_parts.append(f"{security_count} security layers")
+        if method_summary:
+            message_parts.append(f"({method_summary})")
+        
+        message = f"FastAPI backend active: {', '.join(message_parts)}"
+        
+        return ComponentStatus(
+            name="backend",
+            status=ComponentStatusType.HEALTHY,
+            message=message,
+            response_time_ms=None,
+            metadata={
+                "type": "internal_component_check",
+                "note": (
+                    "Backend is running since this health check executed"
+                ),
+                "check_method": "internal_execution",
+                **route_metadata.model_dump_for_metadata(),
+                **middleware_metadata.model_dump_for_metadata(),
+            },
+        )
+    except Exception as e:
+        return ComponentStatus(
+            name="backend",
+            status=ComponentStatusType.UNHEALTHY,
+            message=f"Backend component check failed: {str(e)}",
+            response_time_ms=None,
+            metadata={
+                "type": "internal_component_check",
+                "error": "import_or_execution_error",
+                "error_details": str(e),
+            },
+        )
+
+
+async def _frontend_component_health() -> ComponentStatus:
+    """
+    Flet frontend health check.
+
+    Since the frontend runs in the same process as the backend,
+    we check if the frontend component is properly initialized.
+    """
+    try:
+        # Check if frontend component is available
+        from app.components.frontend.main import create_frontend_app
+
+        # Verify the frontend app factory function works
+        create_frontend_app()
+
+        return ComponentStatus(
+            name="frontend",
+            status=ComponentStatusType.HEALTHY,
+            message="Flet frontend component available",
+            response_time_ms=None,
+            metadata={
+                "type": "component_check",
+                "framework": "flet",
+                "note": "Frontend integrated with FastAPI",
+            },
+        )
+
+    except ImportError as e:
+        return ComponentStatus(
+            name="frontend",
+            status=ComponentStatusType.UNHEALTHY,
+            message="Frontend component not found",
+            response_time_ms=None,
+            metadata={
+                "type": "component_check",
+                "error": "import_error",
+                "error_details": str(e),
+            },
+        )
+    except Exception as e:
+        return ComponentStatus(
+            name="frontend",
+            status=ComponentStatusType.UNHEALTHY,
+            message=f"Frontend component error: {str(e)}",
+            response_time_ms=None,
+            metadata={
+                "type": "component_check",
+                "error": "unexpected_error",
+                "error_details": str(e),
+            },
+        )
+
+{%- if include_scheduler %}
+
+
+async def _scheduler_component_health() -> ComponentStatus:
+    """
+    Check scheduler component health from backend.
+{%- if scheduler_backend != "memory" %}
+
+    With persistence: Gets real task data from database
+{%- else %}
+
+    Without persistence: Shows component as activated only
+{%- endif %}
+    """
+    {% if scheduler_backend != "memory" %}
+    try:
+        from app.services.scheduler.task_monitor import TaskHealthMonitor
+        monitor = TaskHealthMonitor()
+        # No scheduler instance available in backend
+        health_data = await monitor.get_health_metadata(None)
+        
+        # Format message based on task data
+        total_tasks = health_data.total_tasks
+        if total_tasks > 0:
+            message = f"Scheduler running with {total_tasks} tasks"
+        else:
+            message = "Scheduler running (no tasks)"
+        
+        return ComponentStatus(
+            name="scheduler",
+            status=ComponentStatusType.HEALTHY,
+            message=message,
+            response_time_ms=None,
+            metadata=health_data.model_dump(),
+        )
+    except Exception as e:
+        logger.error("Failed to get scheduler health data", error=str(e))
+        # Fallback to basic status
+        return ComponentStatus(
+            name="scheduler",
+            status=ComponentStatusType.WARNING,
+            message="Scheduler enabled, health data unavailable",
+            response_time_ms=None,
+            metadata={
+                "type": "component_status",
+                "error": "health_check_failed",
+                "error_details": str(e),
+            },
+        )
+    {% else %}
+    return ComponentStatus(
+        name="scheduler",
+        status=ComponentStatusType.HEALTHY,
+        message="Scheduler component activated",
+        response_time_ms=None,
+        metadata={
+            "type": "component_status",
+            "deployment": "separate_container",
+            "status": "activated",
+            "note": "Memory-only mode - no cross-container health monitoring",
+        },
+    )
+    {% endif %}
+{%- endif %}
+
+
+async def startup_hook() -> None:
+    """
+    Auto-detect available components and register their health checks.
+
+    Always registers core components (backend, frontend) and detects
+    optional components using Python's import system.
+    """
+    logger.info("Registering component health checks...")
+
+    # Initialize route metadata cache once at startup
+    _initialize_route_metadata_cache()
+
+    # Always register core components
+    register_health_check("backend", _backend_component_health)
+    logger.info("Backend component health check registered")
+
+    register_health_check("frontend", _frontend_component_health)
+    logger.info("️Frontend component health check registered")
+
+    {%- if include_scheduler %}
+    # Register scheduler component health check
+    register_health_check("scheduler", _scheduler_component_health)
+    {% if scheduler_backend != "memory" %}
+    logger.info("Scheduler component health check registered (with task data)")
+    {% else %}
+    logger.info("Scheduler component enabled (shows as activated)")
+    {% endif %}
+    {%- endif %}
+
+    {%- if include_worker %}
+    # Register worker health check (shows queue status and job metrics)
+    from app.services.system.health import check_worker_health
+    register_health_check("worker", check_worker_health)
+    logger.info("Worker component health check registered")
+    {%- endif %}
+
+    {%- if include_redis %}
+    # Register cache health check (Redis connectivity and operations)
+    from app.services.system.health import check_cache_health
+    register_health_check("cache", check_cache_health)
+    logger.info("Cache component health check registered")
+    {%- endif %}
+
+    {%- if include_database %}
+    # Register database health check (SQLite connectivity and basic operations)
+    from app.services.system.health import check_database_health
+    register_health_check("database", check_database_health)
+    logger.info("Database component health check registered")
+    {% endif %}
+
+    logger.info("✅ Component health detection complete")
+
+    # ==========================================
+    # Service Health Checks Registration
+    # ==========================================
+
+    from app.services.system.health import register_service_health_check
+
+    logger.info("🔧 Registering service health checks...")
+
+    {%- if include_auth %}
+    # Register auth service health check
+    from app.services.auth.health import check_auth_service_health
+    register_service_health_check("auth", check_auth_service_health)
+    logger.info("Auth service health check registered")
+    {%- endif %}
+
+    {%- if include_ai %}
+    # Register AI service health check
+    from app.services.ai.health import check_ai_service_health
+    register_service_health_check("ai", check_ai_service_health)
+    logger.info("AI service health check registered")
+    {%- endif %}
+
+    # Future services will be registered here:
+    # Example:
+    #     from app.services.payment.health import check_payment_service_health
+    #     register_service_health_check("payment", check_payment_service_health)
+
+    logger.info("✅ Service health detection complete")