moose-lib 0.6.90__py3-none-any.whl → 0.6.283__py3-none-any.whl

moose_lib/dmv2/web_app.py

@@ -0,0 +1,175 @@
+"""
+WebApp support for Python - bring your own FastAPI application.
+
+This module allows developers to register FastAPI applications as WebApp resources
+that are managed by the Moose infrastructure, similar to other resources like
+OlapTables, Streams, and APIs.
+"""
+
+from typing import Optional, Dict, Any
+from dataclasses import dataclass
+
+
+# Reserved mount paths that cannot be used by WebApps
+RESERVED_MOUNT_PATHS = [
+    "/admin",
+    "/api",
+    "/consumption",
+    "/health",
+    "/ingest",
+    "/moose",  # reserved for future use
+    "/ready",
+    "/workflows",
+]
+
+
+@dataclass
+class WebAppMetadata:
+    """Metadata for a WebApp.
+
+    Attributes:
+        description: Optional description of the WebApp's purpose.
+    """
+
+    description: Optional[str] = None
+
+
+@dataclass
+class WebAppConfig:
+    """Configuration for a WebApp.
+
+    Attributes:
+        mount_path: The URL path where the WebApp will be mounted (required).
+                   Cannot be "/" (root path).
+                   Cannot end with "/" (trailing slash).
+                   Cannot start with reserved paths.
+        metadata: Optional metadata for documentation purposes.
+        inject_moose_utils: Whether to inject MooseClient utilities into requests.
+                           Defaults to True.
+    """
+
+    mount_path: str
+    metadata: Optional[WebAppMetadata] = None
+    inject_moose_utils: bool = True
+
+
+class WebApp:
+    """A WebApp resource that wraps a FastAPI application.
+
+    WebApps are managed by the Moose infrastructure and automatically
+    proxied through the Rust webserver, allowing them to coexist with
+    other Moose resources on the same port.
+
+    Example:
+        ```python
+        from fastapi import FastAPI, Request
+        from moose_lib.dmv2 import WebApp, WebAppConfig, WebAppMetadata
+        from moose_lib.dmv2.web_app_helpers import get_moose_utils
+
+        app = FastAPI()
+
+        @app.get("/hello")
+        async def hello(request: Request):
+            moose = get_moose_utils(request)
+            # Use moose.client for queries
+            return {"message": "Hello World"}
+
+        # Register as a WebApp with custom mount path
+        my_webapp = WebApp(
+            "myApi",
+            app,
+            WebAppConfig(
+                mount_path="/myapi",
+                metadata=WebAppMetadata(description="My custom API"),
+            )
+        )
+        ```
+
+    Args:
+        name: Unique name for this WebApp.
+        app: The FastAPI application instance.
+        config: Configuration for the WebApp (required, must include mount_path).
+
+    Raises:
+        ValueError: If validation fails (duplicate name, invalid mount path, etc.)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        app: Any,  # FastAPI app, typed as Any to avoid import dependency
+        config: WebAppConfig,
+    ):
+        self.name = name
+        self.app = app
+        self.config = config
+
+        # Import the registry here to avoid circular dependency
+        from ._registry import _web_apps
+
+        # Validate the configuration
+        self._validate(name, self.config, _web_apps)
+
+        # Register this WebApp
+        _web_apps[name] = self
+
+    @staticmethod
+    def _validate(
+        name: str, config: WebAppConfig, existing_web_apps: Dict[str, "WebApp"]
+    ) -> None:
+        """Validate WebApp configuration.
+
+        Args:
+            name: The name of the WebApp being validated.
+            config: The configuration to validate.
+            existing_web_apps: Dictionary of already registered WebApps.
+
+        Raises:
+            ValueError: If validation fails.
+        """
+        # Check for duplicate name
+        if name in existing_web_apps:
+            raise ValueError(f"WebApp with name '{name}' already exists")
+
+        # Validate mountPath - it is required
+        if not config.mount_path:
+            raise ValueError(
+                f'mountPath is required. Please specify a mount path for your WebApp (e.g., "/myapi").'
+            )
+
+        mount_path = config.mount_path
+
+        # Check for root path - not allowed as it would overlap reserved paths
+        if mount_path == "/":
+            raise ValueError(
+                f'mountPath cannot be "/" as it would allow routes to overlap with reserved paths: '
+                f"{', '.join(RESERVED_MOUNT_PATHS)}"
+            )
+
+        # Validate mount path format
+        if mount_path.endswith("/"):
+            raise ValueError(
+                f"mountPath cannot end with a trailing slash. "
+                f"Remove the '/' from: \"{mount_path}\""
+            )
+
+        # Check for reserved path prefixes
+        for reserved in RESERVED_MOUNT_PATHS:
+            if mount_path == reserved or mount_path.startswith(f"{reserved}/"):
+                raise ValueError(
+                    f"mountPath cannot begin with a reserved path: "
+                    f"{', '.join(RESERVED_MOUNT_PATHS)}. "
+                    f'Got: "{mount_path}"'
+                )
+
+        # Check for duplicate mount path
+        for existing_name, existing_app in existing_web_apps.items():
+            existing_mount = existing_app.config.mount_path
+            if existing_mount == mount_path:
+                raise ValueError(
+                    f'WebApp with mountPath "{mount_path}" already exists '
+                    f'(used by WebApp "{existing_name}")'
+                )
+
+    def __repr__(self) -> str:
+        return f"WebApp(name='{self.name}', mount_path='{self.config.mount_path}')"

moose_lib/dmv2/web_app_helpers.py

@@ -0,0 +1,96 @@
+"""
+Helper utilities for WebApp integration with FastAPI.
+
+This module provides utilities to access Moose services (ClickHouse, Temporal)
+from within FastAPI request handlers.
+"""
+
+from typing import Optional, Any, Dict
+from dataclasses import dataclass
+
+
+@dataclass
+class ApiUtil:
+    """Utilities available to WebApp request handlers.
+
+    Attributes:
+        client: MooseClient instance for executing queries and workflows.
+        sql: SQL template function for building safe queries.
+        jwt: JWT payload if authentication is enabled, None otherwise.
+    """
+
+    client: Any  # MooseClient, typed as Any to avoid circular import
+    sql: Any  # sql function from moose_lib.main
+    jwt: Optional[Dict[str, Any]] = None
+
+
+def get_moose_utils(request: Any) -> Optional[ApiUtil]:
+    """Extract Moose utilities from a FastAPI request.
+
+    The Moose infrastructure automatically injects utilities into request.state
+    when inject_moose_utils is enabled (default).
+
+    Args:
+        request: FastAPI Request object.
+
+    Returns:
+        ApiUtil instance if available, None otherwise.
+
+    Example:
+        ```python
+        from fastapi import FastAPI, Request
+        from moose_lib.dmv2.web_app_helpers import get_moose_utils
+
+        app = FastAPI()
+
+        @app.get("/data")
+        async def get_data(request: Request):
+            moose = get_moose_utils(request)
+            if not moose:
+                return {"error": "Moose utilities not available"}
+
+            # Execute a query
+            result = moose.client.query.execute(
+                moose.sql("SELECT * FROM my_table LIMIT {limit}", limit=10)
+            )
+            return result
+        ```
+    """
+    # FastAPI uses request.state for storing custom data
+    if hasattr(request, "state") and hasattr(request.state, "moose"):
+        return request.state.moose
+    return None
+
+
+def get_moose_dependency():
+    """FastAPI dependency for injecting Moose utilities.
+
+    Can be used with FastAPI's Depends() to automatically inject
+    Moose utilities into route handlers.
+
+    Returns:
+        A dependency function that extracts ApiUtil from the request.
+
+    Example:
+        ```python
+        from fastapi import FastAPI, Depends, Request
+        from moose_lib.dmv2.web_app_helpers import get_moose_dependency, ApiUtil
+
+        app = FastAPI()
+
+        @app.get("/data")
+        async def get_data(moose: ApiUtil = Depends(get_moose_dependency())):
+            # moose is automatically injected
+            result = moose.client.query.execute(...)
+            return result
+        ```
+    """
+
+    def moose_dependency(request: Any) -> ApiUtil:
+        moose = get_moose_utils(request)
+        if moose is None:
+            # This should rarely happen if inject_moose_utils=True
+            raise RuntimeError("Moose utilities not available in request")
+        return moose
+
+    return moose_dependency

moose_lib/dmv2/workflow.py

@@ -4,6 +4,7 @@ Workflow definitions for Moose Data Model v2 (dmv2).
 This module provides classes for defining and configuring workflows composed of tasks,
 including task dependencies, configurations, and execution functions.
 """
+
 import dataclasses
 from typing import Any, Optional, Dict, List, Callable, Union, Awaitable, Generic
 from pydantic import BaseModel
@@ -11,6 +12,7 @@ from pydantic import BaseModel
 from .types import TypedMooseResource, T_none, U_none
 from ._registry import _workflows
 
+
 @dataclasses.dataclass
 class TaskContext(Generic[T_none]):
     """Context object passed to task handlers.
@@ -18,10 +20,15 @@ class TaskContext(Generic[T_none]):
     - When a task declares an input model `T`, `input` is of type `T` (not Optional).
     - For no-input tasks (`T` is `None`), `input` is exactly `None`.
     """
+
     state: Dict[str, Any]
     input: T_none
 
-type TaskRunFunc[T_none, U_none] = Callable[[TaskContext[T_none]], Union[U_none, Awaitable[U_none]]]
+
+type TaskRunFunc[T_none, U_none] = Callable[
+    [TaskContext[T_none]], Union[U_none, Awaitable[U_none]]
+]
+
 
 @dataclasses.dataclass
 class TaskConfig(Generic[T_none, U_none]):
@@ -36,12 +43,16 @@ class TaskConfig(Generic[T_none, U_none]):
         timeout: Optional timeout string (e.g. "5m", "1h", "never").
         retries: Optional number of retry attempts.
     """
+
     run: TaskRunFunc[T_none, U_none]
     on_complete: Optional[list["Task[U_none, Any]"]] = None
-    on_cancel: Optional[Callable[[TaskContext[T_none]], Union[None, Awaitable[None]]]] = None
+    on_cancel: Optional[
+        Callable[[TaskContext[T_none]], Union[None, Awaitable[None]]]
+    ] = None
     timeout: Optional[str] = None
     retries: Optional[int] = None
 
+
 class Task(TypedMooseResource, Generic[T_none, U_none]):
     """Represents a task that can be executed as part of a workflow.
 
@@ -61,6 +72,7 @@ class Task(TypedMooseResource, Generic[T_none, U_none]):
         name (str): The name of the task.
         model_type (type[T]): The Pydantic model associated with this task's input.
     """
+
     config: TaskConfig[T_none, U_none]
 
     def __init__(self, name: str, config: TaskConfig[T_none, U_none], **kwargs):
@@ -70,17 +82,27 @@ class Task(TypedMooseResource, Generic[T_none, U_none]):
 
     @classmethod
     def _get_type(cls, keyword_args: dict):
-        t = keyword_args.get('t')
+        t = keyword_args.get("t")
         if t is None:
-            raise ValueError(f"Use `{cls.__name__}[T, U](name='...')` to supply both input and output types")
+            raise ValueError(
+                f"Use `{cls.__name__}[T, U](name='...')` to supply both input and output types"
+            )
         if not isinstance(t, tuple) or len(t) != 2:
-            raise ValueError(f"Use `{cls.__name__}[T, U](name='...')` to supply both input and output types")
+            raise ValueError(
+                f"Use `{cls.__name__}[T, U](name='...')` to supply both input and output types"
+            )
 
         input_type, output_type = t
-        if input_type is not None and (not isinstance(input_type, type) or not issubclass(input_type, BaseModel)):
+        if input_type is not None and (
+            not isinstance(input_type, type) or not issubclass(input_type, BaseModel)
+        ):
             raise ValueError(f"Input type {input_type} is not a Pydantic model or None")
-        if output_type is not None and (not isinstance(output_type, type) or not issubclass(output_type, BaseModel)):
-            raise ValueError(f"Output type {output_type} is not a Pydantic model or None")
+        if output_type is not None and (
+            not isinstance(output_type, type) or not issubclass(output_type, BaseModel)
+        ):
+            raise ValueError(
+                f"Output type {output_type} is not a Pydantic model or None"
+            )
         return t
 
     def _set_type(self, name: str, t: tuple[type[T_none], type[U_none]]):
@@ -89,6 +111,7 @@ class Task(TypedMooseResource, Generic[T_none, U_none]):
         self._u = output_type
         self.name = name
 
+
 @dataclasses.dataclass
 class WorkflowConfig:
     """Configuration for a workflow.
@@ -99,11 +122,13 @@ class WorkflowConfig:
         timeout: Optional timeout string for the entire workflow.
         schedule: Optional cron-like schedule string for recurring execution.
     """
+
     starting_task: Task[Any, Any]
     retries: Optional[int] = None
     timeout: Optional[str] = None
     schedule: Optional[str] = None
 
+
 class Workflow:
     """Represents a workflow composed of one or more tasks.
 
@@ -118,6 +143,7 @@ class Workflow:
         name (str): The name of the workflow.
         config (WorkflowConfig): The configuration for this workflow.
     """
+
     def __init__(self, name: str, config: WorkflowConfig):
         self.name = name
         self.config = config
@@ -130,6 +156,7 @@ class Workflow:
         Returns:
             list[str]: List of task names in the workflow, including all child tasks
         """
+
         def collect_task_names(task: Task) -> list[str]:
             names = [task.name]
             if task.config.on_complete:
@@ -148,6 +175,7 @@ class Workflow:
         Returns:
             Optional[Task]: The task if found, None otherwise
         """
+
         def find_task(task: Task) -> Optional[Task]:
             if task.name == task_name:
                 return task
@@ -158,4 +186,4 @@ class Workflow:
                         return found
             return None
 
-        return find_task(self.config.starting_task)
+        return find_task(self.config.starting_task)