mdb-engine 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

mdb_engine/core/manifest.py

@@ -1338,6 +1338,18 @@ MANIFEST_SCHEMA_V2 = {
                                         "auth is required (default: false)"
                                     ),
                                 },
+                                "csrf_required": {
+                                    "type": "boolean",
+                                    "default": True,
+                                    "description": (
+                                        "Require CSRF validation for WebSocket connections "
+                                        "(default: true - security by default). "
+                                        "When true, uses encrypted session keys stored in "
+                                        "private collection for CSRF protection. "
+                                        "Set to false to use Origin validation + "
+                                        "SameSite cookies only."
+                                    ),
+                                },
                             },
                             "additionalProperties": False,
                             "description": (
@@ -1361,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/types.py

@@ -243,6 +243,7 @@ class WebSocketAuthDict(TypedDict, total=False):
 
     required: bool
     allow_anonymous: bool
+    csrf_required: bool  # Whether CSRF cookie is required (default: False)
 
 
 class WebSocketEndpointDict(TypedDict, total=False):
@@ -252,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