mdb-engine 0.2.4__py3-none-any.whl → 0.3.1__py3-none-any.whl

mdb_engine/__init__.py

@@ -81,7 +81,7 @@ from .repositories import Entity, MongoRepository, Repository, UnitOfWork
 # Utilities
 from .utils import clean_mongo_doc, clean_mongo_docs
 
-__version__ = "0.2.4"  # Patch version bump for exception handling improvements
+__version__ = "0.3.1"  # Patch version bump: Fix public route matching for mounted apps
 
 __all__ = [
     # Core Engine

mdb_engine/auth/shared_middleware.py

@@ -82,6 +82,22 @@ def _compute_fingerprint(request: Request) -> str:
     return hashlib.sha256(fingerprint_string.encode()).hexdigest()
 
 
+def _get_request_path(request: Request) -> str:
+    """
+    Get the request path relative to the mount point.
+
+    For mounted apps (via create_multi_app), use request.scope["path"] which
+    contains the path relative to the mount point. For non-mounted apps,
+    fall back to request.url.path.
+
+    This ensures public routes in manifests (which are relative paths like "/")
+    match correctly when apps are mounted at prefixes like "/auth-hub".
+    """
+    # Use scope["path"] which is relative to mount point for mounted apps
+    # Fall back to url.path for non-mounted apps
+    return request.scope.get("path", request.url.path)
+
+
 class SharedAuthMiddleware(BaseHTTPMiddleware):
     """
     Middleware for shared authentication across multi-app deployments.
@@ -169,7 +185,7 @@ class SharedAuthMiddleware(BaseHTTPMiddleware):
             # However, for Lazy middleware, we want to skip if not initialized yet
             return await call_next(request)
 
-        is_public = self._is_public_route(request.url.path)
+        is_public = self._is_public_route(_get_request_path(request))
 
         # Extract token from cookie or header
         token = self._extract_token(request)
@@ -522,7 +538,7 @@ def _create_lazy_middleware_class(
                 )
                 return await call_next(request)
 
-            is_public = _is_public_route_helper(request.url.path, self._public_routes)
+            is_public = _is_public_route_helper(_get_request_path(request), self._public_routes)
             token = _extract_token_helper(
                 request, self._cookie_name, self._header_name, self._header_prefix
             )

mdb_engine/core/engine.py

@@ -1095,13 +1095,14 @@ class MongoDBEngine:
         | None = None,
         on_shutdown: Callable[["FastAPI", "MongoDBEngine", dict[str, Any]], Awaitable[None]]
         | None = None,
+        is_sub_app: bool = False,
         **fastapi_kwargs: Any,
     ) -> "FastAPI":
         """
         Create a FastAPI application with proper lifespan management.
 
         This method creates a FastAPI app that:
-        1. Initializes the engine on startup
+        1. Initializes the engine on startup (unless is_sub_app=True)
         2. Loads and registers the manifest
         3. Auto-detects multi-site mode from manifest
         4. Auto-configures auth based on manifest auth.mode:
@@ -1119,6 +1120,9 @@ class MongoDBEngine:
                        Signature: async def callback(app, engine, manifest) -> None
             on_shutdown: Optional async callback called before engine shutdown.
                         Signature: async def callback(app, engine, manifest) -> None
+            is_sub_app: If True, skip engine initialization and lifespan management.
+                       Used when mounting as a child app in create_multi_app().
+                       Defaults to False for backward compatibility.
             **fastapi_kwargs: Additional arguments passed to FastAPI()
 
         Returns:
@@ -1177,8 +1181,9 @@ class MongoDBEngine:
             """Lifespan context manager for initialization and cleanup."""
             nonlocal app_manifest, is_multi_site
 
-            # Initialize engine
-            await engine.initialize()
+            # Initialize engine (skip if sub-app - parent manages lifecycle)
+            if not is_sub_app:
+                await engine.initialize()
 
             # Load and register manifest
             app_manifest = await engine.load_manifest(manifest_path)
@@ -1207,7 +1212,20 @@ class MongoDBEngine:
                 logger.info(f"Shared auth mode for '{slug}' - SSO enabled")
                 # Initialize shared user pool and set on app.state
                 # Middleware was already added at app creation time (lazy version)
-                await engine._initialize_shared_user_pool(app, app_manifest)
+                # For sub-apps, check if parent already initialized user pool
+                if is_sub_app:
+                    # Check if parent app has user_pool (set by parent's initialization)
+                    # If not, initialize it (shouldn't happen, but handle gracefully)
+                    if not hasattr(app.state, "user_pool") or app.state.user_pool is None:
+                        logger.warning(
+                            f"Sub-app '{slug}' uses shared auth but user_pool not found. "
+                            "Initializing now (parent should have initialized it)."
+                        )
+                        await engine._initialize_shared_user_pool(app, app_manifest)
+                    else:
+                        logger.debug(f"Sub-app '{slug}' using shared user_pool from parent app")
+                else:
+                    await engine._initialize_shared_user_pool(app, app_manifest)
             else:
                 logger.info(f"Per-app auth mode for '{slug}'")
                 # Auto-retrieve app token for "app" mode
@@ -1416,7 +1434,9 @@ class MongoDBEngine:
                 except (ValueError, TypeError, RuntimeError, AttributeError, KeyError) as e:
                     logger.warning(f"on_shutdown callback failed for '{slug}': {e}")
 
-            await engine.shutdown()
+            # Shutdown engine (skip if sub-app - parent manages lifecycle)
+            if not is_sub_app:
+                await engine.shutdown()
 
         # Create FastAPI app
         app = FastAPI(title=app_title, lifespan=lifespan, **fastapi_kwargs)
@@ -1502,6 +1522,398 @@ class MongoDBEngine:
 
         return app
 
+    def _validate_path_prefixes(self, apps: list[dict[str, Any]]) -> tuple[bool, list[str]]:
+        """
+        Validate path prefixes for multi-app mounting.
+
+        Checks:
+        - All prefixes start with '/'
+        - No prefix is a prefix of another (e.g., '/app' conflicts with '/app/v2')
+        - No conflicts with reserved paths ('/health', '/docs', '/openapi.json')
+
+        Args:
+            apps: List of app configs with 'path_prefix' keys
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        errors: list[str] = []
+        reserved_paths = {"/health", "/docs", "/openapi.json", "/redoc"}
+
+        # Extract path prefixes
+        path_prefixes: list[str] = []
+        for app_config in apps:
+            path_prefix = app_config.get("path_prefix", f"/{app_config.get('slug', 'unknown')}")
+            if not path_prefix.startswith("/"):
+                app_slug = app_config.get("slug", "unknown")
+                errors.append(f"Path prefix '{path_prefix}' must start with '/' (app: {app_slug})")
+                continue
+            path_prefixes.append(path_prefix)
+
+        # Check for conflicts with reserved paths
+        for prefix in path_prefixes:
+            if prefix in reserved_paths:
+                errors.append(
+                    f"Path prefix '{prefix}' conflicts with reserved path. "
+                    "Reserved paths: /health, /docs, /openapi.json, /redoc"
+                )
+
+        # Check for prefix conflicts (one prefix being a prefix of another)
+        path_prefixes_sorted = sorted(path_prefixes)
+        for i, prefix1 in enumerate(path_prefixes_sorted):
+            for prefix2 in path_prefixes_sorted[i + 1 :]:
+                if prefix1.startswith(prefix2) or prefix2.startswith(prefix1):
+                    errors.append(
+                        f"Path prefix conflict: '{prefix1}' and '{prefix2}' overlap. "
+                        "One cannot be a prefix of another."
+                    )
+
+        # Check for duplicates
+        if len(path_prefixes) != len(set(path_prefixes)):
+            seen = set()
+            for prefix in path_prefixes:
+                if prefix in seen:
+                    errors.append(f"Duplicate path prefix: '{prefix}'")
+                seen.add(prefix)
+
+        return len(errors) == 0, errors
+
+    def create_multi_app(
+        self,
+        apps: list[dict[str, Any]] | None = None,
+        multi_app_manifest: Path | None = None,
+        title: str = "Multi-App API",
+        root_path: str = "",
+        **fastapi_kwargs: Any,
+    ) -> "FastAPI":
+        """
+        Create a parent FastAPI app that mounts multiple child apps.
+
+        Each child app is mounted at a path prefix (e.g., /auth-hub, /pwd-zero) and
+        maintains its own routes, middleware, and state while sharing the engine instance.
+
+        Args:
+            apps: List of app configurations. Each dict should have:
+                - slug: App slug (required)
+                - manifest: Path to manifest.json (required)
+                - path_prefix: Optional path prefix (defaults to /{slug})
+                - on_startup: Optional startup callback function
+                - on_shutdown: Optional shutdown callback function
+            multi_app_manifest: Path to a multi-app manifest.json that defines all apps.
+                Format:
+                {
+                    "multi_app": {
+                        "enabled": true,
+                        "apps": [
+                            {
+                                "slug": "app1",
+                                "manifest": "./app1/manifest.json",
+                                "path_prefix": "/app1",
+                            }
+                        ]
+                    }
+                }
+            title: Title for the parent FastAPI app
+            root_path: Root path prefix for all mounted apps (optional)
+            **fastapi_kwargs: Additional arguments passed to FastAPI()
+
+        Returns:
+            Parent FastAPI application with all child apps mounted
+
+        Raises:
+            ValueError: If configuration is invalid or path prefixes conflict
+            RuntimeError: If engine is not initialized
+
+        Example:
+            # Programmatic approach
+            engine = MongoDBEngine(mongo_uri=..., db_name=...)
+            app = engine.create_multi_app(
+                apps=[
+                    {
+                        "slug": "auth-hub",
+                        "manifest": Path("./auth-hub/manifest.json"),
+                        "path_prefix": "/auth-hub",
+                    },
+                    {
+                        "slug": "pwd-zero",
+                        "manifest": Path("./pwd-zero/manifest.json"),
+                        "path_prefix": "/pwd-zero",
+                    },
+                ]
+            )
+
+            # Manifest-based approach
+            app = engine.create_multi_app(
+                multi_app_manifest=Path("./multi_app_manifest.json")
+            )
+        """
+        import json
+
+        from fastapi import FastAPI
+
+        engine = self
+
+        # Load configuration from manifest or apps parameter
+        if multi_app_manifest:
+            manifest_path = Path(multi_app_manifest)
+            with open(manifest_path) as f:
+                multi_app_config = json.load(f)
+
+            multi_app_section = multi_app_config.get("multi_app", {})
+            if not multi_app_section.get("enabled", False):
+                raise ValueError(
+                    "multi_app.enabled must be True in multi_app_manifest to use multi-app mode"
+                )
+
+            apps_config = multi_app_section.get("apps", [])
+            if not apps_config:
+                raise ValueError("multi_app.apps must contain at least one app")
+
+            # Resolve manifest paths relative to multi_app_manifest location
+            manifest_dir = manifest_path.parent
+            apps = []
+            for app_config in apps_config:
+                manifest_rel_path = app_config.get("manifest")
+                if not manifest_rel_path:
+                    raise ValueError(f"App '{app_config.get('slug')}' missing 'manifest' field")
+
+                # Resolve relative to multi_app_manifest location
+                manifest_full_path = (manifest_dir / manifest_rel_path).resolve()
+                slug = app_config.get("slug")
+                path_prefix = app_config.get("path_prefix", f"/{slug}")
+
+                apps.append(
+                    {
+                        "slug": slug,
+                        "manifest": manifest_full_path,
+                        "path_prefix": path_prefix,
+                    }
+                )
+
+        elif apps is not None:
+            apps_config = apps
+            # Convert Path objects to Path if they're strings
+            apps = []
+            for app_config in apps_config:
+                manifest = app_config.get("manifest")
+                if isinstance(manifest, str):
+                    manifest = Path(manifest)
+                apps.append(
+                    {
+                        "slug": app_config.get("slug"),
+                        "manifest": manifest,
+                        "path_prefix": app_config.get("path_prefix", f"/{app_config.get('slug')}"),
+                        "on_startup": app_config.get("on_startup"),
+                        "on_shutdown": app_config.get("on_shutdown"),
+                    }
+                )
+        else:
+            raise ValueError("Either 'apps' or 'multi_app_manifest' must be provided")
+
+        if not apps:
+            raise ValueError("At least one app must be configured")
+
+        # Validate path prefixes
+        is_valid, errors = self._validate_path_prefixes(apps)
+        if not is_valid:
+            raise ValueError(
+                "Path prefix validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+            )
+
+        # Check if any app uses shared auth
+        has_shared_auth = False
+        for app_config in apps:
+            try:
+                manifest_path = app_config["manifest"]
+                with open(manifest_path) as f:
+                    app_manifest_pre = json.load(f)
+                auth_config = app_manifest_pre.get("auth", {})
+                if auth_config.get("mode") == "shared":
+                    has_shared_auth = True
+                    break
+            except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+                logger.warning(f"Could not check auth mode for app '{app_config.get('slug')}': {e}")
+
+        # State for parent app
+        mounted_apps: list[dict[str, Any]] = []
+        shared_user_pool_initialized = False
+
+        @asynccontextmanager
+        async def lifespan(app: FastAPI):
+            """Lifespan context manager for parent app."""
+            nonlocal mounted_apps, shared_user_pool_initialized
+
+            # Initialize engine
+            await engine.initialize()
+
+            # Initialize shared user pool once if any app uses shared auth
+            if has_shared_auth:
+                logger.info("Initializing shared user pool for multi-app deployment")
+                # Find first app with shared auth to get manifest for initialization
+                for app_config in apps:
+                    try:
+                        manifest_path = app_config["manifest"]
+                        with open(manifest_path) as f:
+                            app_manifest_pre = json.load(f)
+                        auth_config = app_manifest_pre.get("auth", {})
+                        if auth_config.get("mode") == "shared":
+                            await engine._initialize_shared_user_pool(app, app_manifest_pre)
+                            shared_user_pool_initialized = True
+                            logger.info("Shared user pool initialized for multi-app deployment")
+                            break
+                    except (FileNotFoundError, json.JSONDecodeError, KeyError) as e:
+                        app_slug = app_config.get("slug", "unknown")
+                        logger.warning(
+                            f"Could not initialize shared user pool from app '{app_slug}': {e}"
+                        )
+
+            # Mount each child app
+            for app_config in apps:
+                slug = app_config["slug"]
+                manifest_path = app_config["manifest"]
+                path_prefix = app_config["path_prefix"]
+                on_startup = app_config.get("on_startup")
+                on_shutdown = app_config.get("on_shutdown")
+
+                try:
+                    # Create child app as sub-app (shares engine and lifecycle)
+                    child_app = engine.create_app(
+                        slug=slug,
+                        manifest=manifest_path,
+                        is_sub_app=True,  # Important: marks as sub-app
+                        on_startup=on_startup,
+                        on_shutdown=on_shutdown,
+                    )
+
+                    # Share user_pool with child app if shared auth is enabled
+                    if shared_user_pool_initialized and hasattr(app.state, "user_pool"):
+                        child_app.state.user_pool = app.state.user_pool
+                        # Also share audit_log if available
+                        if hasattr(app.state, "audit_log"):
+                            child_app.state.audit_log = app.state.audit_log
+                        logger.debug(f"Shared user_pool with child app '{slug}'")
+
+                    # Mount child app at path prefix
+                    app.mount(path_prefix, child_app)
+                    mounted_apps.append(
+                        {
+                            "slug": slug,
+                            "path_prefix": path_prefix,
+                            "status": "mounted",
+                        }
+                    )
+                    logger.info(f"Mounted app '{slug}' at path prefix '{path_prefix}'")
+
+                except (
+                    FileNotFoundError,
+                    json.JSONDecodeError,
+                    ValueError,
+                    KeyError,
+                    RuntimeError,
+                ) as e:
+                    logger.error(f"Failed to mount app '{slug}': {e}", exc_info=True)
+                    mounted_apps.append(
+                        {
+                            "slug": slug,
+                            "path_prefix": path_prefix,
+                            "status": "failed",
+                            "error": str(e),
+                        }
+                    )
+                    # Continue with other apps even if one fails
+                    continue
+
+            # Expose engine and mounted apps info on parent app state
+            app.state.engine = engine
+            app.state.mounted_apps = mounted_apps
+            app.state.is_multi_app = True
+
+            yield
+
+            # Shutdown is handled by parent app
+            await engine.shutdown()
+
+        # Create parent FastAPI app
+        parent_app = FastAPI(title=title, lifespan=lifespan, root_path=root_path, **fastapi_kwargs)
+
+        # Add request scope middleware
+        from starlette.middleware.base import BaseHTTPMiddleware
+
+        from ..di import ScopeManager
+
+        class RequestScopeMiddleware(BaseHTTPMiddleware):
+            """Middleware that manages request-scoped DI instances."""
+
+            async def dispatch(self, request, call_next):
+                ScopeManager.begin_request()
+                try:
+                    response = await call_next(request)
+                    return response
+                finally:
+                    ScopeManager.end_request()
+
+        parent_app.add_middleware(RequestScopeMiddleware)
+        logger.debug("RequestScopeMiddleware added for parent app")
+
+        # Add shared CORS middleware if configured
+        # (Individual apps can add their own CORS, but parent-level is useful)
+        try:
+            from fastapi.middleware.cors import CORSMiddleware
+
+            parent_app.add_middleware(
+                CORSMiddleware,
+                allow_origins=["*"],  # Can be configured via manifest later
+                allow_credentials=True,
+                allow_methods=["*"],
+                allow_headers=["*"],
+            )
+            logger.debug("CORS middleware added for parent app")
+        except ImportError:
+            logger.warning("CORS middleware not available")
+
+        # Add unified health check endpoint
+        @parent_app.get("/health")
+        async def health_check():
+            """Unified health check for all mounted apps."""
+            from ..observability import check_engine_health, check_mongodb_health
+
+            # Both are async functions
+            engine_health = await check_engine_health(engine)
+            mongo_health = await check_mongodb_health(engine.mongo_client)
+
+            mounted_status = {}
+            for mounted_app_info in mounted_apps:
+                mounted_status[mounted_app_info["slug"]] = {
+                    "path_prefix": mounted_app_info["path_prefix"],
+                    "status": mounted_app_info["status"],
+                }
+                if "error" in mounted_app_info:
+                    mounted_status[mounted_app_info["slug"]]["error"] = mounted_app_info["error"]
+
+            overall_status = (
+                "healthy"
+                if engine_health.status.value == "healthy"
+                and mongo_health.status.value == "healthy"
+                else "unhealthy"
+            )
+
+            return {
+                "status": overall_status,
+                "engine": {
+                    "status": engine_health.status.value,
+                    "message": engine_health.message,
+                },
+                "mongodb": {
+                    "status": mongo_health.status.value,
+                    "message": mongo_health.message,
+                },
+                "mounted_apps": mounted_status,
+            }
+
+        logger.info(f"Multi-app parent created with {len(apps)} app(s) configured")
+
+        return parent_app
+
     async def _initialize_shared_user_pool(
         self,
         app: "FastAPI",

mdb_engine/core/manifest.py

@@ -1732,6 +1732,99 @@ MANIFEST_SCHEMA_V2 = {
             "additionalProperties": False,
             "description": "Observability configuration (health checks, metrics, logging)",
         },
+        "multi_app": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "Enable multi-app mounting mode",
+                },
+                "apps": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "slug": {
+                                "type": "string",
+                                "pattern": "^[a-z0-9_-]+$",
+                                "description": (
+                                    "App slug (lowercase alphanumeric, underscores, hyphens)"
+                                ),
+                            },
+                            "manifest": {
+                                "type": "string",
+                                "description": (
+                                    "Path to manifest.json file "
+                                    "(relative to multi_app manifest or absolute)"
+                                ),
+                            },
+                            "path_prefix": {
+                                "type": "string",
+                                "pattern": "^/.*",
+                                "default": "/{slug}",
+                                "description": (
+                                    "Path prefix for mounting (defaults to /{slug}). "
+                                    "Must start with '/' and be unique across all apps."
+                                ),
+                            },
+                            "on_startup": {
+                                "type": "string",
+                                "description": (
+                                    "Optional: Python function path for startup callback "
+                                    "(e.g., 'module.function_name'). "
+                                    "Not yet supported in manifest-based config."
+                                ),
+                            },
+                            "on_shutdown": {
+                                "type": "string",
+                                "description": (
+                                    "Optional: Python function path for shutdown callback "
+                                    "(e.g., 'module.function_name'). "
+                                    "Not yet supported in manifest-based config."
+                                ),
+                            },
+                        },
+                        "required": ["slug", "manifest"],
+                        "additionalProperties": False,
+                    },
+                    "minItems": 1,
+                    "description": "List of apps to mount in multi-app mode",
+                },
+                "shared_middleware": {
+                    "type": "object",
+                    "properties": {
+                        "cors": {
+                            "type": "boolean",
+                            "default": True,
+                            "description": "Enable CORS middleware at parent level (default: true)",
+                        },
+                        "rate_limiting": {
+                            "type": "boolean",
+                            "default": True,
+                            "description": (
+                                "Enable rate limiting middleware at parent level (default: true)"
+                            ),
+                        },
+                        "health_checks": {
+                            "type": "boolean",
+                            "default": True,
+                            "description": (
+                                "Enable unified health check endpoint at /health (default: true)"
+                            ),
+                        },
+                    },
+                    "additionalProperties": False,
+                    "description": "Shared middleware configuration for parent app",
+                },
+            },
+            "additionalProperties": False,
+            "description": (
+                "Multi-app mounting configuration. When enabled, allows mounting "
+                "multiple FastAPI apps under a single parent app with path prefixes. "
+                "Useful for deploying multiple apps (e.g., SSO apps) on a single service."
+            ),
+        },
         "initial_data": {
             "type": "object",
             "patternProperties": {

{mdb_engine-0.2.4.dist-info → mdb_engine-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-engine
-Version: 0.2.4
+Version: 0.3.1
 Summary: MongoDB Engine
 Home-page: https://github.com/ranfysvalle02/mdb-engine
 Author: Fabian Valle
@@ -106,58 +106,162 @@ pip install mdb-engine
 
 ---
 
-## 30-Second Quick Start
+## 30-Second Quick Start: Build a Todo List API
 
-**Step 1**: Create your `manifest.json`:
+Let's build a complete CRUD todo list app in 3 steps!
+
+### Step 1: Create `manifest.json`
 
 ```json
 {
   "schema_version": "2.0",
-  "slug": "my_app",
-  "name": "My App",
+  "slug": "todo_app",
+  "name": "Todo List App",
   "managed_indexes": {
-    "tasks": [
+    "todos": [
       {
         "type": "regular",
-        "keys": {"status": 1, "created_at": -1},
-        "name": "status_sort"
+        "keys": {"completed": 1, "created_at": -1},
+        "name": "completed_sort"
       }
     ]
   }
 }
 ```
 
-**Step 2**: Create your FastAPI app:
+### Step 2: Create `app.py` with Full CRUD
 
 ```python
+from datetime import datetime
 from pathlib import Path
-from fastapi import Depends
+from typing import Optional
+
+from bson import ObjectId
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+
 from mdb_engine import MongoDBEngine
 from mdb_engine.dependencies import get_scoped_db
 
-# Initialize the engine
+# Initialize engine
 engine = MongoDBEngine(
     mongo_uri="mongodb://localhost:27017",
     db_name="my_database"
 )
 
-# Create app - manifest.json is loaded automatically!
-app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
+# Create app - manifest.json loaded automatically!
+app = engine.create_app(
+    slug="todo_app",
+    manifest=Path("manifest.json")
+)
 
-# Use request-scoped dependencies - all queries automatically isolated
-@app.post("/tasks")
-async def create_task(task: dict, db=Depends(get_scoped_db)):
-    result = await db.tasks.insert_one(task)
-    return {"id": str(result.inserted_id)}
+# Pydantic models
+class TodoCreate(BaseModel):
+    title: str
+    description: Optional[str] = None
+
+class TodoUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    completed: Optional[bool] = None
+
+# CREATE - Add a new todo
+@app.post("/todos")
+async def create_todo(todo: TodoCreate, db=Depends(get_scoped_db)):
+    doc = {
+        **todo.dict(),
+        "completed": False,
+        "created_at": datetime.utcnow()
+    }
+    result = await db.todos.insert_one(doc)
+    return {"id": str(result.inserted_id), "message": "Todo created"}
+
+# READ - List all todos
+@app.get("/todos")
+async def list_todos(completed: Optional[bool] = None, db=Depends(get_scoped_db)):
+    query = {}
+    if completed is not None:
+        query["completed"] = completed
+    
+    todos = await db.todos.find(query).sort("created_at", -1).to_list(length=100)
+    for todo in todos:
+        todo["_id"] = str(todo["_id"])
+    return {"todos": todos, "count": len(todos)}
+
+# READ - Get single todo
+@app.get("/todos/{todo_id}")
+async def get_todo(todo_id: str, db=Depends(get_scoped_db)):
+    todo = await db.todos.find_one({"_id": ObjectId(todo_id)})
+    if not todo:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    todo["_id"] = str(todo["_id"])
+    return todo
+
+# UPDATE - Update a todo
+@app.put("/todos/{todo_id}")
+async def update_todo(todo_id: str, todo: TodoUpdate, db=Depends(get_scoped_db)):
+    updates = {k: v for k, v in todo.dict(exclude_unset=True).items() if v is not None}
+    if not updates:
+        raise HTTPException(status_code=400, detail="No fields to update")
+    
+    updates["updated_at"] = datetime.utcnow()
+    result = await db.todos.update_one(
+        {"_id": ObjectId(todo_id)},
+        {"$set": updates}
+    )
+    
+    if result.matched_count == 0:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    return {"message": "Todo updated"}
+
+# DELETE - Delete a todo
+@app.delete("/todos/{todo_id}")
+async def delete_todo(todo_id: str, db=Depends(get_scoped_db)):
+    result = await db.todos.delete_one({"_id": ObjectId(todo_id)})
+    if result.deleted_count == 0:
+        raise HTTPException(status_code=404, detail="Todo not found")
+    return {"message": "Todo deleted"}
+```
+
+### Step 3: Run It!
+
+```bash
+# Start MongoDB (if not running)
+mongod
+
+# Install dependencies
+pip install mdb-engine fastapi uvicorn
+
+# Run the app
+uvicorn app:app --reload
+```
+
+**Test your API:**
+```bash
+# Create a todo
+curl -X POST http://localhost:8000/todos \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Buy groceries", "description": "Milk and eggs"}'
+
+# List todos
+curl http://localhost:8000/todos
+
+# Update a todo (replace {id} with actual ID)
+curl -X PUT http://localhost:8000/todos/{id} \
+  -H "Content-Type: application/json" \
+  -d '{"completed": true}'
+
+# Delete a todo
+curl -X DELETE http://localhost:8000/todos/{id}
 ```
 
 **What just happened?**
-- ✅ Engine loaded your `manifest.json`
-- ✅ Indexes created automatically from `managed_indexes`
-- ✅ Database queries automatically scoped to your app
-- ✅ Lifecycle management handled (startup/shutdown)
+- ✅ **Automatic scoping**: All queries filtered by `app_id` — your data is isolated
+- ✅ **Indexes created**: The `completed_sort` index was created automatically
+- ✅ **Lifecycle managed**: Startup/shutdown handled automatically
+- ✅ **Zero boilerplate**: No connection setup, no index scripts, no auth handlers
 
-That's it. Your data is automatically sandboxed, indexes are created, and cleanup is handled.
+**That's it!** You now have a fully functional, production-ready todo API with automatic data sandboxing, index management, and lifecycle handling.
 
 ---
 

{mdb_engine-0.2.4.dist-info → mdb_engine-0.3.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
 mdb_engine/README.md,sha256=T3EFGcPopY9LslYW3lxgG3hohWkAOmBNbYG0FDMUJiY,3502
-mdb_engine/__init__.py,sha256=ll3Xc4FaoNqqK_lnWOJTyFHY3uAyoB40g3NnBjwyx5U,3155
+mdb_engine/__init__.py,sha256=hyAHO2lyogYrvCIKKoTLuaReM3g0f7gygVUbg2Iht5k,3163
 mdb_engine/config.py,sha256=DTAyxfKB8ogyI0v5QR9Y-SJOgXQr_eDBCKxNBSqEyLc,7269
 mdb_engine/constants.py,sha256=eaotvW57TVOg7rRbLziGrVNoP7adgw_G9iVByHezc_A,7837
 mdb_engine/dependencies.py,sha256=MJuYQhZ9ZGzXlip1ha5zba9Rvn04HDPWahJFJH81Q2s,14107
@@ -26,7 +26,7 @@ mdb_engine/auth/provider.py,sha256=FOSHn-jp4VYtxvmjnzho5kH6y-xDKWbcKUorYRRl1C4,2
 mdb_engine/auth/rate_limiter.py,sha256=l3EYZE1Kz9yVfZwNrKq_1AgdD7GXB1WOLSqqGQVSSgA,15808
 mdb_engine/auth/restrictions.py,sha256=tOyQBO_w0bK9zmTsOPZf9cbvh4oITvpNfSxIXt-XrcU,8824
 mdb_engine/auth/session_manager.py,sha256=ywWJjTarm-obgJ3zO3s-1cdqEYe0XrozlY00q_yMJ8I,15396
-mdb_engine/auth/shared_middleware.py,sha256=3lvm6aC0W_7ECvno_Mj3eu_93DZ--JiXhZ9hte8tvhM,30480
+mdb_engine/auth/shared_middleware.py,sha256=ZyGjv3cQ5pLeFBKrW4X2W11e0-ZsuOhJaWvGAQ7I2Kw,31137
 mdb_engine/auth/shared_users.py,sha256=25OBks4VRHaYZW7R61vnplV7wmr7RRpDctSgnej_nxc,26773
 mdb_engine/auth/token_lifecycle.py,sha256=Q9S1X2Y6W7Ckt5PvyYXswBRh2Tg9DGpyRv_3Xve7VYQ,6708
 mdb_engine/auth/token_store.py,sha256=-B8j5RH5YEoKsswF4rnMoI51BaxMe4icke3kuehXmcI,9121
@@ -46,9 +46,9 @@ mdb_engine/core/app_registration.py,sha256=7szt2a7aBkpSppjmhdkkPPYMKGKo0MkLKZeEe
 mdb_engine/core/app_secrets.py,sha256=bo-syg9UUATibNyXEZs-0TTYWG-JaY-2S0yNSGA12n0,10524
 mdb_engine/core/connection.py,sha256=XnwuPG34pJ7kJGJ84T0mhj1UZ6_CLz_9qZf6NRYGIS8,8346
 mdb_engine/core/encryption.py,sha256=RZ5LPF5g28E3ZBn6v1IMw_oas7u9YGFtBcEj8lTi9LM,7515
-mdb_engine/core/engine.py,sha256=ciQHxHEcFh-DOQ0X9gV5kKk9WAxj3GKg5JDIPfFZjMg,69459
+mdb_engine/core/engine.py,sha256=R1mU99Aa3z0P4xlPnofm9H9sZr4CWnsAaa85j-N3iJQ,86857
 mdb_engine/core/index_management.py,sha256=9-r7MIy3JnjQ35sGqsbj8K_I07vAUWtAVgSWC99lJcE,5555
-mdb_engine/core/manifest.py,sha256=ROaMKrlHY2gi77ScQCWu8U_QB7CVCoR8CQrP1gmtrtw,134756
+mdb_engine/core/manifest.py,sha256=jguhjVPAHMZGxOJcdSGouv9_XiKmxUjDmyjn2yXHCj4,139205
 mdb_engine/core/ray_integration.py,sha256=vexYOzztscvRYje1xTNmXJbi99oJxCaVJAwKfTNTF_E,13610
 mdb_engine/core/seeding.py,sha256=c5IhdwlqUf_4Q5FFTAhPLaHPaUr_Txo3z_DUwZmWsFs,6421
 mdb_engine/core/service_initialization.py,sha256=rtb6BaPvFqomwT_s7bdbbvqi5m74llT0LkJFEhVG9Gg,12996
@@ -89,9 +89,9 @@ mdb_engine/routing/__init__.py,sha256=reupjHi_RTc2ZBA4AH5XzobAmqy4EQIsfSUcTkFknU
 mdb_engine/routing/websockets.py,sha256=3X4OjQv_Nln4UmeifJky0gFhMG8A6alR77I8g1iIOLY,29311
 mdb_engine/utils/__init__.py,sha256=lDxQSGqkV4fVw5TWIk6FA6_eey_ZnEtMY0fir3cpAe8,236
 mdb_engine/utils/mongo.py,sha256=Oqtv4tQdpiiZzrilGLEYQPo8Vmh8WsTQypxQs8Of53s,3369
-mdb_engine-0.2.4.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-mdb_engine-0.2.4.dist-info/METADATA,sha256=DRYO0436-KCFjF-HHi1deGWWoO0Yq3vzKl53qow2ldE,12750
-mdb_engine-0.2.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-mdb_engine-0.2.4.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
-mdb_engine-0.2.4.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
-mdb_engine-0.2.4.dist-info/RECORD,,
+mdb_engine-0.3.1.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+mdb_engine-0.3.1.dist-info/METADATA,sha256=Zxjb2zcIkgk4-eUJbWv0nDs9OMKpeJuiANzINiQkMAw,15810
+mdb_engine-0.3.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mdb_engine-0.3.1.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
+mdb_engine-0.3.1.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
+mdb_engine-0.3.1.dist-info/RECORD,,