mdb-engine 0.6.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

mdb_engine/core/manifest.py

@@ -1373,6 +1373,20 @@ MANIFEST_SCHEMA_V2 = {
                                 "alive (default: 30, min: 5, max: 300)"
                             ),
                         },
+                        "ticket_ttl_seconds": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 60,
+                            "default": 10,
+                            "description": (
+                                "WebSocket ticket time-to-live in seconds (default: 10). "
+                                "Tickets are single-use authentication tokens for "
+                                "WebSocket connections. "
+                                "Shorter TTL (3-5s) provides better security but requires "
+                                "faster connection. "
+                                "Longer TTL (10-30s) is more forgiving for slow networks."
+                            ),
+                        },
                     },
                     "required": ["path"],
                     "additionalProperties": False,

mdb_engine/core/ray_integration.py

@@ -360,10 +360,10 @@ def ray_actor_decorator(
         # Convert to Ray remote class
         ray_cls = ray.remote(cls)
 
-        # Store metadata on the class
-        ray_cls._app_slug = actor_app_slug
-        ray_cls._namespace = actor_namespace
-        ray_cls._isolated = isolated
+        # Store metadata on the class (intentional dynamic attribute setting for Ray)
+        ray_cls._app_slug = actor_app_slug  # noqa: SLF001
+        ray_cls._namespace = actor_namespace  # noqa: SLF001
+        ray_cls._isolated = isolated  # noqa: SLF001
 
         # Add spawn class method
         @classmethod

mdb_engine/core/service_initialization.py

@@ -26,6 +26,11 @@ from ..observability import get_logger as get_contextual_logger
 logger = logging.getLogger(__name__)
 contextual_logger = get_contextual_logger(__name__)
 
+try:
+    from openai import OpenAIError
+except ImportError:
+    OpenAIError = RuntimeError
+
 
 class ServiceInitializer:
     """
@@ -54,7 +59,9 @@ class ServiceInitializer:
         self._memory_services: dict[str, Any] = {}
         self._websocket_configs: dict[str, dict[str, Any]] = {}
 
-    async def initialize_memory_service(self, slug: str, memory_config: dict[str, Any]) -> None:
+    async def initialize_memory_service(
+        self, slug: str, memory_config: dict[str, Any] | None
+    ) -> None:
         """
         Initialize Mem0 memory service for an app.
 
@@ -63,8 +70,17 @@ class ServiceInitializer:
 
         Args:
             slug: App slug
-            memory_config: Memory configuration from manifest (already validated)
+            memory_config: Memory configuration from manifest (already validated).
+                Can be None or empty dict to skip initialization.
         """
+        # Handle None or empty config
+        if not memory_config:
+            return
+
+        # Check if memory is enabled (must be checked before import)
+        if not memory_config.get("enabled", False):
+            return
+
         # Try to import Memory service (optional dependency)
         try:
             from ..memory import Mem0MemoryService, Mem0MemoryServiceError
@@ -145,12 +161,41 @@ class ServiceInitializer:
                 extra={"app_slug": slug, "error": str(e)},
                 exc_info=True,
             )
-        except (ImportError, AttributeError, TypeError, ValueError) as e:
-            contextual_logger.error(
-                f"Error initializing memory service for app '{slug}': {e}",
+        except OpenAIError as e:
+            contextual_logger.warning(
+                f"Memory service initialization skipped for app '{slug}': "
+                f"OpenAI API error. {e}",
                 extra={"app_slug": slug, "error": str(e)},
-                exc_info=True,
             )
+        except (
+            ImportError,
+            AttributeError,
+            TypeError,
+            ValueError,
+            RuntimeError,
+            ConnectionError,
+            OSError,
+        ) as e:
+            error_msg = str(e).lower()
+            error_type = type(e).__name__
+            is_api_key_error = (
+                "api_key" in error_msg
+                or "api key" in error_msg
+                or "openai" in error_type.lower()
+                or "openai" in error_msg
+            )
+            if is_api_key_error:
+                contextual_logger.warning(
+                    f"Memory service initialization skipped for app '{slug}': "
+                    f"Missing API key or configuration. {e}",
+                    extra={"app_slug": slug, "error": str(e)},
+                )
+            else:
+                contextual_logger.error(
+                    f"Error initializing memory service for app '{slug}': {e}",
+                    extra={"app_slug": slug, "error": str(e)},
+                    exc_info=True,
+                )
 
     async def register_websockets(self, slug: str, websockets_config: dict[str, Any]) -> None:
         """
@@ -330,7 +375,18 @@ class ServiceInitializer:
                         extra={"app_slug": slug},
                     )
                     return None
-            return service
+                return service
+
+            # Service not found - check if it should be initialized but wasn't
+            # This can happen in multi-app context if initialization was missed
+            # Note: We can't do async initialization here, so we just log a warning
+            # The explicit initialization in create_multi_app should handle this
+            contextual_logger.debug(
+                f"Memory service not found for '{slug}' - "
+                f"it may not be initialized yet or memory is disabled",
+                extra={"app_slug": slug},
+            )
+            return None
         except (KeyError, AttributeError, TypeError) as e:
             contextual_logger.error(
                 f"Error retrieving memory service for '{slug}': {e}",

mdb_engine/core/types.py

@@ -253,6 +253,7 @@ class WebSocketEndpointDict(TypedDict, total=False):
     auth: WebSocketAuthDict
     description: str
     ping_interval: int
+    ticket_ttl_seconds: int
 
 
 class WebSocketsDict(TypedDict):

mdb_engine/database/connection.py

@@ -91,7 +91,8 @@ def get_shared_mongo_client(
         # Verify client is still connected
         try:
             # Non-blocking check - if client was closed, it will be None or invalid
-            if hasattr(_shared_client, "_topology") and _shared_client._topology is not None:
+            # Accessing MongoDB client's internal _topology attribute to check connection status
+            if hasattr(_shared_client, "_topology") and _shared_client._topology is not None:  # noqa: SLF001
                 return _shared_client
         except (AttributeError, RuntimeError):
             # Client was closed or invalid, reset and recreate
@@ -104,7 +105,8 @@ def get_shared_mongo_client(
         # Double-check pattern: another thread may have initialized while we waited
         if _shared_client is not None:
             try:
-                if hasattr(_shared_client, "_topology") and _shared_client._topology is not None:
+                # Accessing MongoDB client's internal _topology attribute to check connection status
+                if hasattr(_shared_client, "_topology") and _shared_client._topology is not None:  # noqa: SLF001
                     return _shared_client
             except (AttributeError, RuntimeError):
                 # Client was closed or invalid, reset and recreate
@@ -234,7 +236,8 @@ async def get_pool_metrics(
     for registered_client in _registered_clients:
         try:
             # Verify client is still valid
-            if hasattr(registered_client, "_topology") and registered_client._topology is not None:
+            # Accessing MongoDB client's internal _topology attribute to check connection status
+            if hasattr(registered_client, "_topology") and registered_client._topology is not None:  # noqa: SLF001
                 return await _get_client_pool_metrics(registered_client)
         except (AttributeError, RuntimeError):
             # Type 2: Recoverable - if this client is invalid, try next one

mdb_engine/database/scoped_wrapper.py

@@ -291,7 +291,7 @@ class AsyncAtlasIndexManager:
         """
         # Unwrap _SecureCollectionProxy if present to get the real collection
         if isinstance(real_collection, _SecureCollectionProxy):
-            real_collection = real_collection._collection
+            real_collection = real_collection._collection  # noqa: SLF001
         if not isinstance(real_collection, AsyncIOMotorCollection):
             raise TypeError(f"Expected AsyncIOMotorCollection, got {type(real_collection)}")
         self._collection = real_collection
@@ -1297,7 +1297,7 @@ class ScopedCollectionWrapper:
         try:
             # Verify token if needed (lazy verification for async contexts)
             if self._parent_wrapper:
-                await self._parent_wrapper._verify_token_if_needed()
+                await self._parent_wrapper._verify_token_if_needed()  # noqa: SLF001
 
             # Validate document size before insert
             self._resource_limiter.validate_document_size(document)
@@ -1390,7 +1390,7 @@ class ScopedCollectionWrapper:
         try:
             # Verify token if needed (lazy verification for async contexts)
             if self._parent_wrapper:
-                await self._parent_wrapper._verify_token_if_needed()
+                await self._parent_wrapper._verify_token_if_needed()  # noqa: SLF001
 
             # Validate query filter for security
             self._query_validator.validate_filter(filter)

mdb_engine/indexes/manager.py

@@ -441,7 +441,7 @@ async def _handle_search_index(
             logger.info(f"{log_prefix} Search index '{index_name}' definition matches.")
             if not existing_index.get("queryable") and existing_index.get("status") != "FAILED":
                 logger.info(f"{log_prefix} Index '{index_name}' not queryable yet; waiting.")
-                await index_manager._wait_for_search_index_ready(
+                await index_manager._wait_for_search_index_ready(  # noqa: SLF001
                     index_name, index_manager.DEFAULT_SEARCH_TIMEOUT
                 )
                 logger.info(f"{log_prefix} Index '{index_name}' now ready.")
@@ -580,7 +580,7 @@ async def _handle_hybrid_index(
                     f"{log_prefix} Vector index '{vector_index_name}' "
                     f"not queryable yet; waiting."
                 )
-                await index_manager._wait_for_search_index_ready(
+                await index_manager._wait_for_search_index_ready(  # noqa: SLF001
                     vector_index_name, index_manager.DEFAULT_SEARCH_TIMEOUT
                 )
                 logger.info(f"{log_prefix} Vector index '{vector_index_name}' now ready.")
@@ -634,7 +634,7 @@ async def _handle_hybrid_index(
                 logger.info(
                     f"{log_prefix} Text index '{text_index_name}' " f"not queryable yet; waiting."
                 )
-                await index_manager._wait_for_search_index_ready(
+                await index_manager._wait_for_search_index_ready(  # noqa: SLF001
                     text_index_name, index_manager.DEFAULT_SEARCH_TIMEOUT
                 )
                 logger.info(f"{log_prefix} Text index '{text_index_name}' now ready.")

mdb_engine/observability/health.py

@@ -184,15 +184,15 @@ async def check_engine_health(engine: Any | None) -> HealthCheckResult:
             message="MongoDBEngine not initialized",
         )
 
-    if not engine._initialized:
-        return HealthCheckResult(
-            name="engine",
-            status=HealthStatus.UNHEALTHY,
-            message="MongoDBEngine not initialized",
-        )
+        if not engine.initialized:
+            return HealthCheckResult(
+                name="engine",
+                status=HealthStatus.UNHEALTHY,
+                message="MongoDBEngine not initialized",
+            )
 
     # Check registered apps
-    app_count = len(engine._apps)
+    app_count = len(engine.apps)
 
     return HealthCheckResult(
         name="engine",

mdb_engine/routing/README.md

@@ -133,8 +133,10 @@ register_message_handler("my_app", "realtime", handle_client_message)
 
 ### Authentication
 
-- Integrates with mdb_engine's JWT authentication system
-- Supports token via query parameter or cookie
+- Uses ticket-based authentication (secure-by-default)
+- Tickets are short-lived (10 seconds), single-use, and in-memory
+- Exchange JWT for ticket via `/auth/ticket` endpoint
+- Include ticket as query parameter (`?ticket=...`) or header (`X-WebSocket-Ticket`)
 - Respects app's `auth_policy` configuration
 - Can be overridden per endpoint
 
@@ -434,6 +436,11 @@ async def on_document_created(document):
 - **Simplicity**: Just declare in manifest.json, register handlers in code
 - **Flexibility**: Full two-way communication (broadcast + listen)
 - **Automatic**: Routes registered automatically during app registration
+- **FastAPI Integration**: Uses FastAPI's `APIRouter` for WebSocket registration, ensuring:
+  - ✅ Full FastAPI feature support (dependency injection, OpenAPI docs, request/response models)
+  - ✅ Consistent behavior across single-app and multi-app modes
+  - ✅ Best practices compliance with FastAPI's recommended patterns
+  - ✅ Better maintainability through FastAPI abstractions
 
 ## Message Flow