aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/api/worker.py.j2

@@ -0,0 +1,478 @@
+{%- if cookiecutter.include_worker == "yes" %}
+"""Worker task API endpoints."""
+
+from datetime import datetime, timedelta
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from app.components.backend.api.models import (
+    LoadTestRequest,
+    TaskListResponse,
+    TaskRequest,
+    TaskResponse,
+    TaskResultResponse,
+    TaskStatusResponse,
+)
+from app.components.worker.constants import LoadTestTypes
+from app.components.worker.pools import get_queue_pool
+from app.components.worker.tasks import get_task_by_name, list_available_tasks
+from app.core.config import get_default_queue
+from app.core.log import logger
+
+router = APIRouter(prefix="/tasks", tags=["worker"])
+
+
+@router.get("/", response_model=TaskListResponse)
+async def list_tasks() -> TaskListResponse:
+    """Get list of all available background tasks."""
+    available_tasks = list_available_tasks()
+
+    from app.components.worker.tasks import get_queue_for_task
+    from app.core.config import get_available_queues
+
+    queues: dict[str, list[str]] = {
+        queue_type: [] for queue_type in get_available_queues()
+    }
+
+    for task in available_tasks:
+        queue_type = get_queue_for_task(task)
+        queues[queue_type].append(task)
+
+    return TaskListResponse(
+        available_tasks=available_tasks,
+        total_count=len(available_tasks),
+        queues=queues,
+    )
+
+
+@router.post("/enqueue", response_model=TaskResponse)
+async def enqueue_task(task_request: TaskRequest) -> TaskResponse:
+    """Enqueue a background task for processing."""
+    logger.info(
+        f"Enqueueing task: {task_request.task_name} (queue: {task_request.queue_type})"
+    )
+
+    task_func = get_task_by_name(task_request.task_name)
+    if not task_func:
+        available_tasks = list_available_tasks()
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "error": "invalid_task_name",
+                "message": f"Task '{task_request.task_name}' not found",
+                "available_tasks": available_tasks,
+            },
+        )
+
+    from app.core.config import is_valid_queue, get_available_queues
+
+    if not is_valid_queue(task_request.queue_type):
+        available_queues = get_available_queues()
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "error": "invalid_queue_type",
+                "message": f"Queue type must be one of: {available_queues}",
+            },
+        )
+
+    try:
+        pool, queue_name = await get_queue_pool(task_request.queue_type)
+
+        job = await pool.enqueue_job(
+            task_request.task_name,
+            *task_request.args,
+            _queue_name=queue_name,
+            _defer_by=task_request.delay_seconds,
+            **task_request.task_kwargs,
+        )
+
+        queued_at = datetime.now()
+        estimated_start = None
+        if task_request.delay_seconds:
+            estimated_start = queued_at + timedelta(seconds=task_request.delay_seconds)
+
+        await pool.aclose()
+
+        if job is None:
+            raise HTTPException(status_code=500, detail="Failed to enqueue task")
+
+        logger.info(f"✅ Task enqueued: {job.job_id} ({task_request.task_name})")
+
+        return TaskResponse(
+            task_id=job.job_id,
+            task_name=task_request.task_name,
+            queue_type=task_request.queue_type,
+            queued_at=queued_at,
+            estimated_start=estimated_start,
+            message=(
+                f"Task '{task_request.task_name}' enqueued to "
+                f"{task_request.queue_type} queue"
+            ),
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to enqueue task {task_request.task_name}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "error": "enqueue_failed",
+                "message": f"Failed to enqueue task: {str(e)}",
+            },
+        )
+
+
+@router.get("/status/{task_id}", response_model=TaskStatusResponse)
+async def get_task_status(task_id: str) -> TaskStatusResponse:
+    """Get the status of a background task."""
+    try:
+        pool, _ = await get_queue_pool(get_default_queue())
+
+        job_key = f"arq:job:{task_id}"
+        result_key = f"arq:result:{task_id}"
+
+        job_exists = await pool.exists(job_key)
+        result_exists = await pool.exists(result_key)
+
+        if not job_exists and not result_exists:
+            await pool.aclose()
+            raise HTTPException(
+                status_code=404,
+                detail={
+                    "error": "task_not_found",
+                    "message": f"Task {task_id} not found",
+                },
+            )
+
+        if result_exists:
+            result_data = await pool.get(result_key)
+            if result_data:
+                try:
+                    import pickle
+
+                    result = pickle.loads(result_data)
+                    if isinstance(result, dict) and result.get("error"):
+                        status = "failed"
+                        error = result.get("error")
+                    else:
+                        status = "complete"
+                        error = None
+                except Exception:
+                    status = "complete"
+                    error = None
+            else:
+                status = "complete"
+                error = None
+        elif job_exists:
+            status = "queued"
+            error = None
+        else:
+            status = "unknown"
+            error = None
+
+        await pool.aclose()
+
+        return TaskStatusResponse(
+            task_id=task_id,
+            status=status,
+            result_available=result_exists,
+            error=error,
+            enqueue_time=None,
+            start_time=None,
+            finish_time=None
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to get task status for {task_id}: {e}")
+        raise HTTPException(
+            status_code=500, detail={"error": "status_check_failed", "message": str(e)}
+        )
+
+
+@router.get("/result/{task_id}", response_model=TaskResultResponse)
+async def get_task_result(task_id: str) -> TaskResultResponse:
+    """Get the result of a completed background task."""
+    try:
+        pool, _ = await get_queue_pool(get_default_queue())
+
+        result_key = f"arq:result:{task_id}"
+        result_exists = await pool.exists(result_key)
+
+        if not result_exists:
+            job_key = f"arq:job:{task_id}"
+            job_exists = await pool.exists(job_key)
+            await pool.aclose()
+
+            if not job_exists:
+                raise HTTPException(
+                    status_code=404,
+                    detail={
+                        "error": "task_not_found",
+                        "message": f"Task {task_id} not found",
+                    },
+                )
+            else:
+                raise HTTPException(
+                    status_code=400,
+                    detail={
+                        "error": "task_not_completed",
+                        "message": f"Task {task_id} has not completed yet",
+                        "current_status": "queued or in_progress",
+                    },
+                )
+
+        result_data = await pool.get(result_key)
+        await pool.aclose()
+
+        if not result_data:
+            raise HTTPException(
+                status_code=500,
+                detail={
+                    "error": "result_data_missing",
+                    "message": "Result data is missing",
+                },
+            )
+
+        try:
+            import pickle
+
+            result = pickle.loads(result_data)
+
+            if isinstance(result, Exception):
+                result_data = {
+                    "error_type": type(result).__name__,
+                    "error_message": str(result),
+                    "task_failed": True,
+                }
+                task_status = "failed"
+            else:
+                try:
+                    import json
+
+                    json.dumps(result)
+                    result_data = result
+                    task_status = "completed"
+                except (TypeError, ValueError):
+                    result_data = {
+                        "result_type": type(result).__name__,
+                        "result_str": str(result),
+                        "note": "Result was not JSON-serializable, converted to string",
+                    }
+                    task_status = "completed"
+
+            return TaskResultResponse(
+                task_id=task_id,
+                status=task_status,
+                result=result_data,
+                enqueue_time=None,
+                start_time=None,
+                finish_time=None
+            )
+
+        except Exception as e:
+            raise HTTPException(
+                status_code=500,
+                detail={
+                    "error": "result_deserialization_failed",
+                    "message": f"Failed to deserialize result: {str(e)}",
+                },
+            )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get task result for {task_id}: {e}")
+        raise HTTPException(
+            status_code=500, detail={"error": "result_fetch_failed", "message": str(e)}
+        )
+
+
+@router.post("/load-test", response_model=TaskResponse)
+async def start_load_test(load_test_config: LoadTestRequest) -> TaskResponse:
+    """Start a comprehensive load test that measures queue throughput."""
+    from app.components.worker.constants import TaskNames
+    from app.services.load_test import LoadTestConfiguration, LoadTestService
+
+    logger.info(
+        f"🚀 Starting load test: {load_test_config.num_tasks} "
+        f"{load_test_config.task_type} tasks"
+    )
+
+    valid_types = [
+        LoadTestTypes.CPU_INTENSIVE,
+        LoadTestTypes.IO_SIMULATION,
+        LoadTestTypes.MEMORY_OPERATIONS,
+        LoadTestTypes.FAILURE_TESTING,
+    ]
+    if load_test_config.task_type not in valid_types:
+        raise HTTPException(
+            status_code=400,
+            detail={
+                "error": "invalid_task_type",
+                "message": f"Invalid task type: {load_test_config.task_type}",
+                "valid_types": valid_types,
+            },
+        )
+
+    config = LoadTestConfiguration(
+        num_tasks=load_test_config.num_tasks,
+        task_type=load_test_config.task_type,
+        batch_size=load_test_config.batch_size,
+        delay_ms=load_test_config.delay_ms,
+        target_queue=load_test_config.target_queue,
+    )
+
+    try:
+        task_id = await LoadTestService.enqueue_load_test(config)
+
+        return TaskResponse(
+            task_id=task_id,
+            task_name=TaskNames.LOAD_TEST_ORCHESTRATOR,
+            queue_type=load_test_config.target_queue,
+            queued_at=datetime.now(),
+            estimated_start=None,
+            message=(
+                f"Load test '{load_test_config.task_type}' enqueued: "
+                f"{load_test_config.num_tasks} tasks to "
+                f"{load_test_config.target_queue} queue"
+            ),
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to enqueue load test: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "error": "load_test_failed",
+                "message": f"Failed to start load test: {str(e)}",
+            },
+        )
+
+
+@router.post("/examples/load-test-small", response_model=TaskResponse)
+async def enqueue_small_load_test() -> TaskResponse:
+    """Example: Small load test with 50 CPU tasks."""
+    load_test_config = LoadTestRequest(
+        num_tasks=50,
+        task_type=LoadTestTypes.CPU_INTENSIVE,
+        batch_size=10,
+        delay_ms=0,
+        target_queue=get_default_queue(),
+    )
+    return await start_load_test(load_test_config)
+
+
+@router.post("/examples/load-test-medium", response_model=TaskResponse)
+async def enqueue_medium_load_test() -> TaskResponse:
+    """Example: Medium load test with 200 I/O tasks."""
+    load_test_config = LoadTestRequest(
+        num_tasks=200,
+        task_type=LoadTestTypes.IO_SIMULATION,
+        batch_size=20,
+        delay_ms=50,
+        target_queue=get_default_queue(),
+    )
+    return await start_load_test(load_test_config)
+
+
+@router.post("/examples/load-test-large", response_model=TaskResponse)
+async def enqueue_large_load_test() -> TaskResponse:
+    """Example: Large load test with 1000 memory tasks."""
+    load_test_config = LoadTestRequest(
+        num_tasks=1000,
+        task_type=LoadTestTypes.MEMORY_OPERATIONS,
+        batch_size=50,
+        delay_ms=0,
+        target_queue=get_default_queue(),
+    )
+    return await start_load_test(load_test_config)
+
+
+@router.get("/load-test-result/{task_id}")
+async def get_load_test_result(
+    task_id: str, target_queue: str | None = None
+) -> dict[str, Any]:
+    """Get enhanced load test results with analysis and verification."""
+    from app.services.load_test import LoadTestService
+
+    try:
+        result = await LoadTestService.get_load_test_result(task_id, target_queue)
+
+        if not result:
+            raise HTTPException(
+                status_code=404,
+                detail={
+                    "error": "load_test_not_found",
+                    "message": f"No load test results found for task {task_id}",
+                    "task_id": task_id,
+                    "target_queue": target_queue,
+                },
+            )
+
+        return result
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get load test result for {task_id}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail={
+                "error": "result_retrieval_failed",
+                "message": f"Failed to retrieve load test results: {str(e)}",
+            },
+        )
+
+
+@router.get("/load-test-types")
+async def get_load_test_types() -> dict[str, Any]:
+    """Get information about available load test types."""
+    from app.components.worker.constants import LoadTestTypes
+    from app.services.load_test import LoadTestService
+
+    test_types = {}
+
+    all_types = [
+        LoadTestTypes.CPU_INTENSIVE,
+        LoadTestTypes.IO_SIMULATION,
+        LoadTestTypes.MEMORY_OPERATIONS,
+        LoadTestTypes.FAILURE_TESTING,
+    ]
+    for test_type in all_types:
+        test_types[test_type] = LoadTestService.get_test_type_info(test_type)
+
+    return {
+        "available_test_types": test_types,
+        "usage_examples": {
+            "quick_cpu_test": {
+                "description": "Quick CPU test with 50 tasks",
+                "parameters": {
+                    "num_tasks": 50,
+                    "task_type": "cpu_intensive",
+                    "batch_size": 10,
+                    "target_queue": "load_test",
+                },
+            },
+            "io_stress_test": {
+                "description": "I/O stress test with concurrent operations",
+                "parameters": {
+                    "num_tasks": 200,
+                    "task_type": "io_simulation",
+                    "batch_size": 20,
+                    "delay_ms": 50,
+                    "target_queue": "load_test",
+                },
+            },
+            "memory_load_test": {
+                "description": "Memory allocation test with GC pressure",
+                "parameters": {
+                    "num_tasks": 500,
+                    "task_type": "memory_operations",
+                    "batch_size": 25,
+                    "target_queue": "media",
+                },
+            },
+        },
+    }
+{%- endif %}

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.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/cookiecutter-aegis-project/{{cookiecutter.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/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/middleware/__init__.py

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

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.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/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/shutdown/__init__.py

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

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.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/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/startup/__init__.py

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