moose-lib 0.6.136__tar.gz → 0.6.138__tar.gz

{moose_lib-0.6.136 → moose_lib-0.6.138}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moose_lib
-Version: 0.6.136
+Version: 0.6.138
 Home-page: https://www.fiveonefour.com/moose
 Author: Fiveonefour Labs Inc.
 Author-email: support@fiveonefour.com

{moose_lib-0.6.136 → moose_lib-0.6.138}/moose_lib/dmv2/__init__.py

@@ -80,6 +80,18 @@ from .life_cycle import (
     LifeCycle,
 )
 
+from .web_app import (
+    WebApp,
+    WebAppConfig,
+    WebAppMetadata,
+)
+
+from .web_app_helpers import (
+    ApiUtil,
+    get_moose_utils,
+    get_moose_dependency,
+)
+
 from .registry import (
     get_tables,
     get_table,
@@ -93,6 +105,8 @@ from .registry import (
     get_sql_resource,
     get_workflows,
     get_workflow,
+    get_web_apps,
+    get_web_app,
     # Backward compatibility aliases
     get_consumption_apis,
     get_consumption_api,
@@ -158,6 +172,14 @@ __all__ = [
     # Lifecycle
     'LifeCycle',
 
+    # WebApp
+    'WebApp',
+    'WebAppConfig',
+    'WebAppMetadata',
+    'ApiUtil',
+    'get_moose_utils',
+    'get_moose_dependency',
+
     # Registry
     'get_tables',
     'get_table',
@@ -171,6 +193,8 @@ __all__ = [
     'get_sql_resource',
     'get_workflows',
     'get_workflow',
+    'get_web_apps',
+    'get_web_app',
     # Backward compatibility aliases (deprecated)
     'get_consumption_apis',
     'get_consumption_api',

{moose_lib-0.6.136 → moose_lib-0.6.138}/moose_lib/dmv2/_registry.py

@@ -16,4 +16,5 @@ _api_name_aliases: Dict[str, Any] = {}
 # Map from custom paths to API instances for path-based lookup
 _api_path_map: Dict[str, Any] = {}
 _sql_resources: Dict[str, Any] = {}
-_workflows: Dict[str, Any] = {}
+_workflows: Dict[str, Any] = {}
+_web_apps: Dict[str, Any] = {}

{moose_lib-0.6.136 → moose_lib-0.6.138}/moose_lib/dmv2/registry.py

@@ -11,6 +11,7 @@ from .ingest_api import IngestApi
 from .consumption import Api
 from .sql_resource import SqlResource
 from .workflow import Workflow
+from .web_app import WebApp
 from ._registry import (
     _tables,
     _streams,
@@ -20,6 +21,7 @@ from ._registry import (
     _workflows,
     _api_name_aliases,
     _api_path_map,
+    _web_apps,
 )
 
 def get_tables() -> Dict[str, OlapTable]:
@@ -87,6 +89,14 @@ def get_workflow(name: str) -> Optional[Workflow]:
     """Get a registered workflow by name."""
     return _workflows.get(name)
 
+def get_web_apps() -> Dict[str, WebApp]:
+    """Get all registered WebApps."""
+    return _web_apps
+
+def get_web_app(name: str) -> Optional[WebApp]:
+    """Get a registered WebApp by name."""
+    return _web_apps.get(name)
+
 
 # Backward compatibility aliases (deprecated)
 get_consumption_apis = get_apis

moose_lib-0.6.138/moose_lib/dmv2/web_app.py

@@ -0,0 +1,170 @@
+"""
+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-0.6.138/moose_lib/dmv2/web_app_helpers.py

@@ -0,0 +1,92 @@
+"""
+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-0.6.136 → moose_lib-0.6.138}/moose_lib/internal.py

@@ -19,6 +19,7 @@ from moose_lib.dmv2 import (
     get_apis,
     get_sql_resources,
     get_workflows,
+    get_web_apps,
     OlapTable,
     View,
     MaterializedView,
@@ -265,6 +266,32 @@ class WorkflowJson(BaseModel):
     schedule: Optional[str] = None
 
 
+class WebAppMetadataJson(BaseModel):
+    """Internal representation of WebApp metadata for serialization.
+
+    Attributes:
+        description: Optional description of the WebApp.
+    """
+    model_config = model_config
+
+    description: Optional[str] = None
+
+
+class WebAppJson(BaseModel):
+    """Internal representation of a WebApp configuration for serialization.
+
+    Attributes:
+        name: Name of the WebApp.
+        mount_path: The URL path where the WebApp is mounted.
+        metadata: Optional metadata for documentation purposes.
+    """
+    model_config = model_config
+
+    name: str
+    mount_path: str
+    metadata: Optional[WebAppMetadataJson] = None
+
+
 class InfrastructureSignatureJson(BaseModel):
     """Represents the unique signature of an infrastructure component (Table, Topic, etc.).
 
@@ -311,6 +338,7 @@ class InfrastructureMap(BaseModel):
         apis: Dictionary mapping API names to their configurations.
         sql_resources: Dictionary mapping SQL resource names to their configurations.
         workflows: Dictionary mapping workflow names to their configurations.
+        web_apps: Dictionary mapping WebApp names to their configurations.
     """
     model_config = model_config
 
@@ -320,6 +348,7 @@ class InfrastructureMap(BaseModel):
     apis: dict[str, InternalApiConfig]
     sql_resources: dict[str, SqlResourceConfig]
     workflows: dict[str, WorkflowJson]
+    web_apps: dict[str, WebAppJson]
 
 
 def _map_sql_resource_ref(r: Any) -> InfrastructureSignatureJson:
@@ -538,6 +567,7 @@ def to_infra_map() -> dict:
     apis = {}
     sql_resources = {}
     workflows = {}
+    web_apps = {}
 
     for _registry_key, table in get_tables().items():
         # Convert engine configuration to new format
@@ -657,13 +687,27 @@ def to_infra_map() -> dict:
             schedule=workflow.config.schedule,
         )
 
+    for name, web_app in get_web_apps().items():
+        mount_path = web_app.config.mount_path or "/"
+        metadata = None
+        if web_app.config.metadata:
+            metadata = WebAppMetadataJson(
+                description=web_app.config.metadata.description
+            )
+        web_apps[name] = WebAppJson(
+            name=web_app.name,
+            mount_path=mount_path,
+            metadata=metadata,
+        )
+
     infra_map = InfrastructureMap(
         tables=tables,
         topics=topics,
         ingest_apis=ingest_apis,
         apis=apis,
         sql_resources=sql_resources,
-        workflows=workflows
+        workflows=workflows,
+        web_apps=web_apps
     )
 
     return infra_map.model_dump(by_alias=True)

{moose_lib-0.6.136 → moose_lib-0.6.138}/moose_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moose_lib
-Version: 0.6.136
+Version: 0.6.138
 Home-page: https://www.fiveonefour.com/moose
 Author: Fiveonefour Labs Inc.
 Author-email: support@fiveonefour.com

{moose_lib-0.6.136 → moose_lib-0.6.138}/moose_lib.egg-info/SOURCES.txt

@@ -32,6 +32,8 @@ moose_lib/dmv2/sql_resource.py
 moose_lib/dmv2/stream.py
 moose_lib/dmv2/types.py
 moose_lib/dmv2/view.py
+moose_lib/dmv2/web_app.py
+moose_lib/dmv2/web_app_helpers.py
 moose_lib/dmv2/workflow.py
 moose_lib/streaming/__init__.py
 moose_lib/streaming/streaming_function_runner.py
@@ -44,4 +46,5 @@ tests/test_olap_table_versioning.py
 tests/test_query_builder.py
 tests/test_redis_client.py
 tests/test_s3queue_config.py
-tests/test_simple_aggregate.py
+tests/test_simple_aggregate.py
+tests/test_web_app.py

moose_lib-0.6.138/tests/test_web_app.py

@@ -0,0 +1,221 @@
+"""
+Unit tests for WebApp SDK functionality.
+"""
+import pytest
+from moose_lib.dmv2 import WebApp, WebAppConfig, WebAppMetadata
+from moose_lib.dmv2._registry import _web_apps
+
+
+# Mock FastAPI app for testing
+class MockFastAPIApp:
+    """Mock FastAPI application for testing."""
+    pass
+
+
+@pytest.fixture(autouse=True)
+def clear_registry():
+    """Clear the WebApp registry before each test."""
+    _web_apps.clear()
+    yield
+    _web_apps.clear()
+
+
+def test_webapp_basic_creation():
+    """Test basic WebApp creation with required mount_path."""
+    app = MockFastAPIApp()
+    config = WebAppConfig(mount_path="/test")
+    webapp = WebApp("test_app", app, config)
+
+    assert webapp.name == "test_app"
+    assert webapp.app is app
+    assert webapp.config.mount_path == "/test"
+    assert webapp.config.inject_moose_utils is True
+    assert "test_app" in _web_apps
+
+
+def test_webapp_with_custom_mount_path():
+    """Test WebApp with custom mount path."""
+    app = MockFastAPIApp()
+    config = WebAppConfig(mount_path="/myapi")
+    webapp = WebApp("test_app", app, config)
+
+    assert webapp.config.mount_path == "/myapi"
+
+
+def test_webapp_with_metadata():
+    """Test WebApp with metadata."""
+    app = MockFastAPIApp()
+    config = WebAppConfig(
+        mount_path="/api",
+        metadata=WebAppMetadata(description="My API"),
+    )
+
+    with pytest.raises(ValueError, match="cannot begin with a reserved path"):
+        WebApp("test_app", app, config)
+
+    # Now test with valid mount path
+    config.mount_path = "/myapi"
+    webapp = WebApp("test_app", app, config)
+    assert webapp.config.metadata.description == "My API"
+
+
+def test_webapp_duplicate_name():
+    """Test that duplicate WebApp names are rejected."""
+    app1 = MockFastAPIApp()
+    app2 = MockFastAPIApp()
+
+    WebApp("test_app", app1, WebAppConfig(mount_path="/test1"))
+
+    with pytest.raises(ValueError, match="WebApp with name 'test_app' already exists"):
+        WebApp("test_app", app2, WebAppConfig(mount_path="/test2"))
+
+
+def test_webapp_trailing_slash_validation():
+    """Test that trailing slashes are rejected."""
+    app = MockFastAPIApp()
+    config = WebAppConfig(mount_path="/myapi/")
+
+    with pytest.raises(ValueError, match="mountPath cannot end with a trailing slash"):
+        WebApp("test_app", app, config)
+
+
+def test_webapp_root_path_rejected():
+    """Test that root path '/' is rejected to prevent overlap with reserved paths."""
+    app = MockFastAPIApp()
+    config = WebAppConfig(mount_path="/")
+
+    with pytest.raises(ValueError, match='mountPath cannot be "/" as it would allow routes to overlap with reserved paths'):
+        WebApp("test_app", app, config)
+
+
+def test_webapp_reserved_paths():
+    """Test that reserved paths are rejected."""
+    reserved_paths = [
+        "/admin",
+        "/api",
+        "/consumption",
+        "/health",
+        "/ingest",
+        "/moose",
+        "/ready",
+        "/workflows",
+    ]
+
+    for path in reserved_paths:
+        app = MockFastAPIApp()
+        config = WebAppConfig(mount_path=path)
+
+        with pytest.raises(ValueError, match="cannot begin with a reserved path"):
+            WebApp(f"test_{path}", app, config)
+
+
+def test_webapp_reserved_path_prefix():
+    """Test that paths starting with reserved prefixes are rejected."""
+    app = MockFastAPIApp()
+    config = WebAppConfig(mount_path="/api/v1")
+
+    with pytest.raises(ValueError, match="cannot begin with a reserved path"):
+        WebApp("test_app", app, config)
+
+
+def test_webapp_duplicate_mount_path():
+    """Test that duplicate mount paths are rejected."""
+    app1 = MockFastAPIApp()
+    app2 = MockFastAPIApp()
+
+    config1 = WebAppConfig(mount_path="/myapi")
+    WebApp("app1", app1, config1)
+
+    config2 = WebAppConfig(mount_path="/myapi")
+    with pytest.raises(ValueError, match='WebApp with mountPath "/myapi" already exists'):
+        WebApp("app2", app2, config2)
+
+
+def test_webapp_different_mount_paths():
+    """Test that WebApps with different mount paths can coexist."""
+    app1 = MockFastAPIApp()
+    app2 = MockFastAPIApp()
+
+    WebApp("app1", app1, WebAppConfig(mount_path="/api1"))
+    WebApp("app2", app2, WebAppConfig(mount_path="/api2"))
+
+    assert len(_web_apps) == 2
+
+
+def test_webapp_inject_moose_utils_false():
+    """Test WebApp with inject_moose_utils disabled."""
+    app = MockFastAPIApp()
+    config = WebAppConfig(mount_path="/test", inject_moose_utils=False)
+    webapp = WebApp("test_app", app, config)
+
+    assert webapp.config.inject_moose_utils is False
+
+
+def test_webapp_repr():
+    """Test WebApp string representation."""
+    app = MockFastAPIApp()
+    webapp = WebApp("test_app", app, WebAppConfig(mount_path="/myapi"))
+
+    assert "test_app" in repr(webapp)
+    assert "/myapi" in repr(webapp)
+
+
+def test_webapp_mount_path_required():
+    """Test that mount_path is required."""
+    app = MockFastAPIApp()
+
+    with pytest.raises(ValueError, match="mountPath is required"):
+        WebApp("test_app", app, WebAppConfig(mount_path=""))
+
+
+def test_webapp_serialization():
+    """Test that WebApps can be serialized via internal.py."""
+    from moose_lib.internal import to_infra_map
+    from moose_lib.dmv2 import get_web_apps
+
+    app = MockFastAPIApp()
+    WebApp(
+        "test_app",
+        app,
+        WebAppConfig(
+            mount_path="/myapi",
+            metadata=WebAppMetadata(description="Test API")
+        )
+    )
+
+    # Verify it's in the registry
+    web_apps = get_web_apps()
+    assert "test_app" in web_apps
+
+    # Serialize to infra map
+    infra_map = to_infra_map()
+
+    assert "webApps" in infra_map
+    assert "test_app" in infra_map["webApps"]
+    assert infra_map["webApps"]["test_app"]["name"] == "test_app"
+    assert infra_map["webApps"]["test_app"]["mountPath"] == "/myapi"
+    assert infra_map["webApps"]["test_app"]["metadata"]["description"] == "Test API"
+
+
+def test_webapp_serialization_with_mount_path():
+    """Test WebApp serialization with explicit mount path."""
+    from moose_lib.internal import to_infra_map
+
+    app = MockFastAPIApp()
+    WebApp("test_app", app, WebAppConfig(mount_path="/testpath"))
+
+    infra_map = to_infra_map()
+
+    assert infra_map["webApps"]["test_app"]["mountPath"] == "/testpath"
+
+
+def test_webapp_serialization_no_metadata():
+    """Test WebApp serialization without metadata."""
+    from moose_lib.internal import to_infra_map
+
+    app = MockFastAPIApp()
+    WebApp("test_app", app, WebAppConfig(mount_path="/myapi"))
+
+    infra_map = to_infra_map()
+
+    assert infra_map["webApps"]["test_app"]["metadata"] is None