mdb-engine 0.1.7__py3-none-any.whl → 0.2.0__py3-none-any.whl

mdb_engine/core/engine.py

@@ -30,7 +30,7 @@ import os
 import secrets
 from contextlib import asynccontextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, Tuple
 
 from motor.motor_asyncio import AsyncIOMotorClient
 from pymongo.errors import PyMongoError
@@ -280,7 +280,21 @@ class MongoDBEngine:
 
     @property
     def _initialized(self) -> bool:
-        """Check if engine is initialized."""
+        """Check if engine is initialized (internal)."""
+        return self._connection_manager.initialized
+
+    @property
+    def initialized(self) -> bool:
+        """
+        Check if engine is initialized.
+
+        Returns:
+            True if the engine has been initialized, False otherwise.
+
+        Example:
+            if engine.initialized:
+                db = engine.get_scoped_db("my_app")
+        """
         return self._connection_manager.initialized
 
     def get_scoped_db(
@@ -861,6 +875,30 @@ class MongoDBEngine:
             return self._service_initializer.get_memory_service(slug)
         return None
 
+    def get_embedding_service(self, slug: str) -> Optional[Any]:
+        """
+        Get EmbeddingService for an app.
+
+        Auto-detects OpenAI or AzureOpenAI from environment variables.
+        Uses embedding_config from manifest.json if available.
+
+        Args:
+            slug: App slug
+
+        Returns:
+            EmbeddingService instance if embedding is enabled for this app, None otherwise
+
+        Example:
+            ```python
+            embedding_service = engine.get_embedding_service("my_app")
+            if embedding_service:
+                vectors = await embedding_service.embed_chunks(["Hello world"])
+            ```
+        """
+        from ..embeddings.dependencies import get_embedding_service_for_app
+
+        return get_embedding_service_for_app(slug, self)
+
     @property
     def _apps(self) -> Dict[str, Any]:
         """
@@ -1052,6 +1090,12 @@ class MongoDBEngine:
         slug: str,
         manifest: Path,
         title: Optional[str] = None,
+        on_startup: Optional[
+            Callable[["FastAPI", "MongoDBEngine", Dict[str, Any]], Awaitable[None]]
+        ] = None,
+        on_shutdown: Optional[
+            Callable[["FastAPI", "MongoDBEngine", Dict[str, Any]], Awaitable[None]]
+        ] = None,
         **fastapi_kwargs: Any,
     ) -> "FastAPI":
         """
@@ -1065,20 +1109,33 @@ class MongoDBEngine:
            - "app" (default): Per-app token authentication
            - "shared": Shared user pool with SSO, auto-adds SharedAuthMiddleware
         5. Auto-retrieves app tokens (for "app" mode)
-        6. Shuts down the engine on shutdown
+        6. Calls on_startup callback (if provided)
+        7. Shuts down the engine on shutdown (calls on_shutdown first if provided)
 
         Args:
             slug: Application slug (must match manifest slug)
             manifest: Path to manifest.json file
             title: FastAPI app title. Defaults to app name from manifest
+            on_startup: Optional async callback called after engine initialization.
+                       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
             **fastapi_kwargs: Additional arguments passed to FastAPI()
 
         Returns:
             Configured FastAPI application
 
         Example:
+            async def my_startup(app, engine, manifest):
+                db = engine.get_scoped_db("my_app")
+                await db.config.insert_one({"initialized": True})
+
             engine = MongoDBEngine(mongo_uri=..., db_name=...)
-            app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
+            app = engine.create_app(
+                slug="my_app",
+                manifest=Path("manifest.json"),
+                on_startup=my_startup,
+            )
 
             @app.get("/")
             async def index():
@@ -1151,12 +1208,181 @@ 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)
+                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
                 await engine.auto_retrieve_app_token(slug)
 
+            # Auto-initialize authorization provider from manifest config
+            try:
+                logger.info(
+                    f"🔍 Checking auth config for '{slug}': "
+                    f"auth_config keys={list(auth_config.keys())}"
+                )
+                auth_policy = auth_config.get("policy", {})
+                logger.info(f"🔍 Auth policy for '{slug}': {auth_policy}")
+                authz_provider_type = auth_policy.get("provider")
+                logger.info(f"🔍 Authz provider type for '{slug}': {authz_provider_type}")
+            except (KeyError, AttributeError, TypeError) as e:
+                logger.exception(f"❌ Error reading auth config for '{slug}': {e}")
+                authz_provider_type = None
+
+            if authz_provider_type == "oso":
+                # Initialize OSO Cloud provider
+                try:
+                    from ..auth.oso_factory import initialize_oso_from_manifest
+
+                    authz_provider = await initialize_oso_from_manifest(engine, slug, app_manifest)
+                    if authz_provider:
+                        app.state.authz_provider = authz_provider
+                        logger.info(f"✅ OSO Cloud provider auto-initialized for '{slug}'")
+                    else:
+                        logger.warning(
+                            f"⚠️  OSO provider not initialized for '{slug}' - "
+                            "check OSO_AUTH and OSO_URL environment variables"
+                        )
+                except ImportError as e:
+                    logger.warning(
+                        f"⚠️  OSO Cloud SDK not available for '{slug}': {e}. "
+                        "Install with: pip install oso-cloud"
+                    )
+                except (ValueError, TypeError, RuntimeError, AttributeError, KeyError) as e:
+                    logger.exception(f"❌ Failed to initialize OSO provider for '{slug}': {e}")
+
+            elif authz_provider_type == "casbin":
+                # Initialize Casbin provider
+                logger.info(f"🔧 Initializing Casbin provider for '{slug}'...")
+                try:
+                    from ..auth.casbin_factory import initialize_casbin_from_manifest
+
+                    logger.debug(f"Calling initialize_casbin_from_manifest for '{slug}'")
+                    authz_provider = await initialize_casbin_from_manifest(
+                        engine, slug, app_manifest
+                    )
+                    logger.debug(
+                        f"initialize_casbin_from_manifest returned: {authz_provider is not None}"
+                    )
+                    if authz_provider:
+                        app.state.authz_provider = authz_provider
+                        logger.info(
+                            f"✅ Casbin provider auto-initialized for '{slug}' "
+                            f"and set on app.state"
+                        )
+                        logger.info(
+                            f"✅ Provider type: {type(authz_provider).__name__}, "
+                            f"initialized: {getattr(authz_provider, '_initialized', 'unknown')}"
+                        )
+                        # Verify it's actually set
+                        if hasattr(app.state, "authz_provider") and app.state.authz_provider:
+                            logger.info("✅ Verified: app.state.authz_provider is set and not None")
+                        else:
+                            logger.error(
+                                "❌ CRITICAL: app.state.authz_provider was set but is now "
+                                "None or missing!"
+                            )
+                    else:
+                        logger.error(
+                            f"❌ Casbin provider initialization returned None for '{slug}' - "
+                            f"check logs above for errors"
+                        )
+                        logger.error(f"❌ This means authorization will NOT work for '{slug}'")
+                except ImportError as e:
+                    # ImportError is expected if Casbin is not installed
+                    logger.warning(
+                        f"❌ Casbin not available for '{slug}': {e}. "
+                        "Install with: pip install mdb-engine[casbin]"
+                    )
+                except (ValueError, TypeError, RuntimeError, AttributeError, KeyError) as e:
+                    logger.exception(f"❌ Failed to initialize Casbin provider for '{slug}': {e}")
+                    # Informational message, not exception logging
+                    logger.error(  # noqa: TRY400
+                        f"❌ This means authorization will NOT work for '{slug}' - "
+                        f"app.state.authz_provider will remain None"
+                    )
+                except (
+                    RuntimeError,
+                    ValueError,
+                    AttributeError,
+                    TypeError,
+                    ConnectionError,
+                    OSError,
+                ) as e:
+                    # Catch specific exceptions that might occur during initialization
+                    logger.exception(
+                        f"❌ Unexpected error initializing Casbin provider for '{slug}': {e}"
+                    )
+                    # Informational message, not exception logging
+                    logger.error(  # noqa: TRY400
+                        f"❌ This means authorization will NOT work for '{slug}' - "
+                        f"app.state.authz_provider will remain None"
+                    )
+
+            elif authz_provider_type is None and auth_policy:
+                # Default to Casbin if provider not specified but auth.policy exists
+                logger.info(
+                    f"⚠️  No provider specified in auth.policy for '{slug}', "
+                    f"defaulting to Casbin"
+                )
+                try:
+                    from ..auth.casbin_factory import initialize_casbin_from_manifest
+
+                    authz_provider = await initialize_casbin_from_manifest(
+                        engine, slug, app_manifest
+                    )
+                    if authz_provider:
+                        app.state.authz_provider = authz_provider
+                        logger.info(f"✅ Casbin provider auto-initialized for '{slug}' (default)")
+                    else:
+                        logger.warning(
+                            f"⚠️  Casbin provider not initialized for '{slug}' "
+                            f"(default attempt failed)"
+                        )
+                except ImportError as e:
+                    logger.warning(
+                        f"⚠️  Casbin not available for '{slug}': {e}. "
+                        "Install with: pip install mdb-engine[casbin]"
+                    )
+                except (
+                    ValueError,
+                    TypeError,
+                    RuntimeError,
+                    AttributeError,
+                    KeyError,
+                ) as e:
+                    logger.exception(
+                        f"❌ Failed to initialize Casbin provider for '{slug}' (default): {e}"
+                    )
+            elif authz_provider_type:
+                logger.warning(
+                    f"⚠️  Unknown authz provider type '{authz_provider_type}' for '{slug}' - "
+                    f"skipping initialization"
+                )
+
+            # Auto-seed demo users if configured in manifest
+            users_config = auth_config.get("users", {})
+            if users_config.get("enabled") and users_config.get("demo_users"):
+                try:
+                    from ..auth import ensure_demo_users_exist
+
+                    db = engine.get_scoped_db(slug)
+                    demo_users = await ensure_demo_users_exist(
+                        db=db,
+                        slug_id=slug,
+                        config=app_manifest,
+                    )
+                    if demo_users:
+                        logger.info(f"✅ Seeded {len(demo_users)} demo user(s) for '{slug}'")
+                except (
+                    ImportError,
+                    ValueError,
+                    TypeError,
+                    RuntimeError,
+                    AttributeError,
+                    KeyError,
+                ) as e:
+                    logger.warning(f"⚠️  Failed to seed demo users for '{slug}': {e}")
+
             # Expose engine state on app.state
             app.state.engine = engine
             app.state.app_slug = slug
@@ -1165,13 +1391,57 @@ class MongoDBEngine:
             app.state.auth_mode = auth_mode
             app.state.ray_actor = engine.ray_actor
 
+            # Initialize DI container (if not already set)
+            from ..di import Container
+
+            if not hasattr(app.state, "container") or app.state.container is None:
+                app.state.container = Container()
+                logger.debug(f"DI Container initialized for '{slug}'")
+
+            # Call on_startup callback if provided
+            if on_startup:
+                try:
+                    await on_startup(app, engine, app_manifest)
+                    logger.info(f"on_startup callback completed for '{slug}'")
+                except (ValueError, TypeError, RuntimeError, AttributeError, KeyError) as e:
+                    logger.exception(f"on_startup callback failed for '{slug}': {e}")
+                    raise
+
             yield
 
+            # Call on_shutdown callback if provided
+            if on_shutdown:
+                try:
+                    await on_shutdown(app, engine, app_manifest)
+                    logger.info(f"on_shutdown callback completed for '{slug}'")
+                except (ValueError, TypeError, RuntimeError, AttributeError, KeyError) as e:
+                    logger.warning(f"on_shutdown callback failed for '{slug}': {e}")
+
             await engine.shutdown()
 
         # Create FastAPI app
         app = FastAPI(title=app_title, lifespan=lifespan, **fastapi_kwargs)
 
+        # Add request scope middleware (innermost layer - runs first on request)
+        # This sets up the DI request scope for each request
+        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()
+
+        app.add_middleware(RequestScopeMiddleware)
+        logger.debug(f"RequestScopeMiddleware added for '{slug}'")
+
         # Add rate limiting middleware FIRST (outermost layer)
         # This ensures rate limiting happens before auth validation
         rate_limits_config = auth_config.get("rate_limits", {})
@@ -1236,6 +1506,7 @@ class MongoDBEngine:
     async def _initialize_shared_user_pool(
         self,
         app: "FastAPI",
+        manifest: Optional[Dict[str, Any]] = None,
     ) -> None:
         """
         Initialize shared user pool, audit log, and set them on app.state.
@@ -1251,6 +1522,7 @@ class MongoDBEngine:
 
         Args:
             app: FastAPI application instance
+            manifest: Optional manifest dict for seeding demo users
         """
         from ..auth.audit import AuthAuditLog
         from ..auth.shared_users import SharedUserPool
@@ -1275,8 +1547,37 @@ class MongoDBEngine:
         # Expose user pool on app.state for middleware to access
         app.state.user_pool = self._shared_user_pool
 
+        # Seed demo users to SharedUserPool if configured in manifest
+        if manifest:
+            auth_config = manifest.get("auth", {})
+            users_config = auth_config.get("users", {})
+            demo_users = users_config.get("demo_users", [])
+
+            if demo_users and users_config.get("demo_user_seed_strategy", "auto") != "disabled":
+                for demo in demo_users:
+                    try:
+                        email = demo.get("email")
+                        password = demo.get("password")
+                        app_roles = demo.get("app_roles", {})
+
+                        existing = await self._shared_user_pool.get_user_by_email(email)
+
+                        if not existing:
+                            await self._shared_user_pool.create_user(
+                                email=email,
+                                password=password,
+                                app_roles=app_roles,
+                            )
+                            logger.info(f"✅ Created shared demo user: {email}")
+                        else:
+                            logger.debug(f"ℹ️  Shared demo user exists: {email}")
+                    except (ValueError, TypeError, RuntimeError, AttributeError, KeyError) as e:
+                        logger.warning(
+                            f"⚠️  Failed to create shared demo user {demo.get('email')}: {e}"
+                        )
+
         # Initialize audit logging if enabled
-        auth_config = getattr(app.state, "manifest", {}).get("auth", {})
+        auth_config = (manifest or {}).get("auth", {})
         audit_config = auth_config.get("audit", {})
         audit_enabled = audit_config.get("enabled", True)  # Default: enabled for shared auth
 

mdb_engine/core/manifest.py

@@ -300,24 +300,44 @@ MANIFEST_SCHEMA_V2 = {
                                 "initial_policies": {
                                     "type": "array",
                                     "items": {
-                                        "type": "object",
-                                        "properties": {
-                                            "role": {"type": "string"},
-                                            "resource": {
-                                                "type": "string",
-                                                "default": "documents",
+                                        "oneOf": [
+                                            {
+                                                "type": "array",
+                                                "items": {"type": "string"},
+                                                "minItems": 3,
+                                                "maxItems": 3,
+                                                "description": (
+                                                    "Casbin policy as array: "
+                                                    '["role", "resource", "action"]'
+                                                ),
                                             },
-                                            "action": {"type": "string"},
-                                        },
-                                        "required": ["role", "action"],
-                                        "additionalProperties": False,
+                                            {
+                                                "type": "object",
+                                                "properties": {
+                                                    "role": {"type": "string"},
+                                                    "resource": {
+                                                        "type": "string",
+                                                        "default": "documents",
+                                                    },
+                                                    "action": {"type": "string"},
+                                                },
+                                                "required": ["role", "action"],
+                                                "additionalProperties": False,
+                                                "description": (
+                                                    "OSO policy as object: "
+                                                    '{"role": "admin", "resource": "documents", '
+                                                    '"action": "read"}'
+                                                ),
+                                            },
+                                        ],
                                     },
                                     "description": (
-                                        "Initial permission policies to set up "
-                                        "in OSO Cloud on startup. Only used "
-                                        "when provider is 'oso'. Example: "
-                                        '[{"role": "admin", "resource": '
-                                        '"documents", "action": "read"}]'
+                                        "Initial permission policies to set up on startup. "
+                                        "For Casbin provider: use arrays like "
+                                        '["admin", "clicks", "read"]. '
+                                        "For OSO Cloud provider: use objects like "
+                                        '{"role": "admin", "resource": "documents", '
+                                        '"action": "read"}.'
                                     ),
                                 },
                             },

mdb_engine/database/README.md

@@ -576,7 +576,34 @@ except (ConnectionFailure, ServerSelectionTimeoutError) as e:
 
 ## Integration Examples
 
-### FastAPI Integration
+### FastAPI Integration (Recommended)
+
+Use the request-scoped `get_scoped_db` dependency from `mdb_engine.dependencies`:
+
+```python
+from fastapi import Depends
+from mdb_engine import MongoDBEngine
+from mdb_engine.dependencies import get_scoped_db
+
+engine = MongoDBEngine(mongo_uri="...", db_name="...")
+app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
+
+@app.get("/data")
+async def get_data(db=Depends(get_scoped_db)):
+    # db is automatically scoped to "my_app"
+    docs = await db.my_collection.find({}).to_list(length=10)
+    return {"data": docs}
+
+@app.post("/data")
+async def create_data(db=Depends(get_scoped_db)):
+    # Writes are automatically scoped to "my_app"
+    result = await db.my_collection.insert_one({"name": "New Document"})
+    return {"inserted_id": str(result.inserted_id)}
+```
+
+### Legacy FastAPI Integration
+
+For apps not using `engine.create_app()`:
 
 ```python
 from fastapi import FastAPI, Depends