tetra-rp 0.6.0__py3-none-any.whl → 0.24.0__py3-none-any.whl

tetra_rp/cli/commands/build_utils/__init__.py

@@ -0,0 +1 @@
+"""Build utilities for Flash handler generation."""

tetra_rp/cli/commands/build_utils/handler_generator.py

@@ -0,0 +1,176 @@
+"""Generator for handler_<name>.py files."""
+
+import importlib
+import importlib.util
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+from tetra_rp.runtime.models import Manifest
+
+logger = logging.getLogger(__name__)
+
+HANDLER_TEMPLATE = '''"""
+Auto-generated handler for resource: {resource_name}
+Generated at: {timestamp}
+
+This file is generated by the Flash build process. Do not edit manually.
+"""
+
+import importlib
+from tetra_rp.runtime.generic_handler import create_handler
+
+# Import all functions/classes that belong to this resource
+{imports}
+
+# Function registry for this handler
+FUNCTION_REGISTRY = {{
+{registry}
+}}
+
+# Create configured handler
+handler = create_handler(FUNCTION_REGISTRY)
+
+if __name__ == "__main__":
+    import runpod
+    runpod.serverless.start({{"handler": handler}})
+'''
+
+
+class HandlerGenerator:
+    """Generates handler_<name>.py files for each resource config."""
+
+    def __init__(self, manifest: Union[Dict[str, Any], Manifest], build_dir: Path):
+        self.manifest = manifest
+        self.build_dir = build_dir
+
+    def generate_handlers(self) -> List[Path]:
+        """Generate all handler files for queue-based (non-LB) resources."""
+        handler_paths = []
+
+        # Handle both dict and Manifest types
+        resources = (
+            self.manifest.resources
+            if isinstance(self.manifest, Manifest)
+            else self.manifest.get("resources", {})
+        )
+
+        for resource_name, resource_data in resources.items():
+            # Skip load-balanced resources (handled by LBHandlerGenerator)
+            # Use flag determined by isinstance() at scan time
+            is_load_balanced = (
+                resource_data.is_load_balanced
+                if hasattr(resource_data, "is_load_balanced")
+                else resource_data.get("is_load_balanced", False)
+            )
+            if is_load_balanced:
+                continue
+
+            handler_path = self._generate_handler(resource_name, resource_data)
+            handler_paths.append(handler_path)
+
+        return handler_paths
+
+    def _generate_handler(self, resource_name: str, resource_data: Any) -> Path:
+        """Generate a single handler file."""
+        handler_filename = f"handler_{resource_name}.py"
+        handler_path = self.build_dir / handler_filename
+
+        # Get timestamp from manifest
+        timestamp = (
+            self.manifest.generated_at
+            if isinstance(self.manifest, Manifest)
+            else self.manifest.get("generated_at", "")
+        )
+
+        # Get functions from resource (handle both dict and ResourceConfig)
+        functions = (
+            resource_data.functions
+            if hasattr(resource_data, "functions")
+            else resource_data.get("functions", [])
+        )
+
+        # Generate imports section
+        imports = self._generate_imports(functions)
+
+        # Generate function registry
+        registry = self._generate_registry(functions)
+
+        # Format template
+        handler_code = HANDLER_TEMPLATE.format(
+            resource_name=resource_name,
+            timestamp=timestamp,
+            imports=imports,
+            registry=registry,
+        )
+
+        handler_path.write_text(handler_code)
+
+        # Validate that generated handler can be imported
+        self._validate_handler_imports(handler_path)
+
+        return handler_path
+
+    def _generate_imports(self, functions: List[Any]) -> str:
+        """Generate import statements for functions using dynamic imports.
+
+        Uses importlib.import_module() to handle module names with invalid
+        Python identifiers (e.g., names starting with digits like '01_hello_world').
+        """
+        if not functions:
+            return "# No functions to import"
+
+        imports = []
+        for func in functions:
+            # Handle both dict and FunctionMetadata
+            module = func.module if hasattr(func, "module") else func.get("module")
+            name = func.name if hasattr(func, "name") else func.get("name")
+
+            if module and name:
+                # Use dynamic import to handle invalid identifiers
+                imports.append(f"{name} = importlib.import_module('{module}').{name}")
+
+        return "\n".join(imports) if imports else "# No functions to import"
+
+    def _generate_registry(self, functions: List[Any]) -> str:
+        """Generate function registry dictionary."""
+        if not functions:
+            return "    # No functions registered"
+
+        registry_lines = []
+
+        for func in functions:
+            # Handle both dict and FunctionMetadata
+            name = func.name if hasattr(func, "name") else func.get("name")
+            registry_lines.append(f'    "{name}": {name},')
+
+        return "\n".join(registry_lines)
+
+    def _validate_handler_imports(self, handler_path: Path) -> None:
+        """Validate that generated handler has valid Python syntax.
+
+        Attempts to load the handler module to catch syntax errors.
+        ImportErrors for missing worker modules are logged but not fatal,
+        as those imports may not be available at build time.
+
+        Args:
+            handler_path: Path to generated handler file
+
+        Raises:
+            ValueError: If handler has syntax errors or cannot be parsed
+        """
+        try:
+            spec = importlib.util.spec_from_file_location("handler", handler_path)
+            if spec and spec.loader:
+                module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(module)
+            else:
+                raise ValueError("Failed to create module spec")
+        except SyntaxError as e:
+            raise ValueError(f"Handler has syntax errors: {e}") from e
+        except ImportError as e:
+            # Log but don't fail - imports might not be available at build time
+            logger.debug(f"Handler import validation: {e}")
+        except Exception as e:
+            # Only raise for truly unexpected errors
+            logger.warning(f"Handler validation warning: {e}")

tetra_rp/cli/commands/build_utils/lb_handler_generator.py

@@ -0,0 +1,309 @@
+"""Generator for FastAPI handlers for LoadBalancerSlsResource endpoints."""
+
+import importlib.util
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+from tetra_rp.runtime.models import Manifest
+
+logger = logging.getLogger(__name__)
+
+LB_HANDLER_TEMPLATE = '''"""
+Auto-generated FastAPI handler for LoadBalancerSlsResource: {resource_name}
+Generated at: {timestamp}
+
+This file is generated by the Flash build process. Do not edit manually.
+
+Load-balanced endpoints expose HTTP servers directly to clients, enabling:
+- REST APIs with custom HTTP routing
+- WebSocket servers
+- Real-time communication patterns
+"""
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, Request
+from tetra_rp.runtime.lb_handler import create_lb_handler
+
+logger = logging.getLogger(__name__)
+
+# Import all functions/classes that belong to this resource
+{imports}
+
+# Route registry: (method, path) -> function
+ROUTE_REGISTRY = {{
+{registry}
+}}
+
+
+# Lifespan context manager for startup/shutdown
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Handle application startup and shutdown."""
+    # Startup
+    logger.info("Starting {resource_name} endpoint")
+
+    # Check if this is the mothership and run reconciliation
+    # Note: Resources are now provisioned upfront by the CLI during deployment.
+    # This background task runs reconciliation on mothership startup to ensure
+    # all resources are still deployed and in sync with the manifest.
+    try:
+        from tetra_rp.runtime.mothership_provisioner import (
+            is_mothership,
+            reconcile_children,
+            get_mothership_url,
+        )
+        from tetra_rp.runtime.state_manager_client import StateManagerClient
+
+        if is_mothership():
+            logger.info("=" * 60)
+            logger.info("Mothership detected - Starting reconciliation task")
+            logger.info("Resources are provisioned upfront by the CLI")
+            logger.info("This task ensures all resources remain in sync")
+            logger.info("=" * 60)
+            try:
+                mothership_url = get_mothership_url()
+                logger.info(f"Mothership URL: {{mothership_url}}")
+
+                # Initialize State Manager client for reconciliation
+                state_client = StateManagerClient()
+
+                # Spawn background reconciliation task (non-blocking)
+                # This will verify all resources from manifest are deployed
+                manifest_path = Path(__file__).parent / "flash_manifest.json"
+                task = asyncio.create_task(
+                    reconcile_children(manifest_path, mothership_url, state_client)
+                )
+                # Add error callback to catch and log background task exceptions
+                task.add_done_callback(
+                    lambda t: logger.error(f"Reconciliation task failed: {{t.exception()}}")
+                    if t.exception()
+                    else None
+                )
+
+            except Exception as e:
+                logger.error(f"Failed to start reconciliation task: {{e}}")
+                # Don't fail startup - continue serving traffic
+
+    except ImportError:
+        logger.debug("Mothership provisioning modules not available")
+
+    yield
+
+    # Shutdown
+    logger.info("Shutting down {resource_name} endpoint")
+
+
+# Create FastAPI app with routes and lifespan
+# Note: include_execute={include_execute} for this endpoint type
+# - LiveLoadBalancer (local): include_execute=True for /execute endpoint
+# - LoadBalancerSlsResource (deployed): include_execute=False (security)
+app = create_lb_handler(ROUTE_REGISTRY, include_execute={include_execute}, lifespan=lifespan)
+
+
+# Health check endpoint (required for RunPod load-balancer endpoints)
+@app.get("/ping")
+def ping():
+    """Health check endpoint for RunPod load-balancer.
+
+    Returns:
+        dict: Status response
+    """
+    return {{"status": "healthy"}}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    # Local development server for testing
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+'''
+
+
+class LBHandlerGenerator:
+    """Generates FastAPI handlers for LoadBalancerSlsResource endpoints."""
+
+    def __init__(self, manifest: Union[Dict[str, Any], Manifest], build_dir: Path):
+        self.manifest = manifest
+        self.build_dir = build_dir
+
+    def generate_handlers(self) -> List[Path]:
+        """Generate all LB handler files."""
+        handler_paths = []
+
+        # Handle both dict and Manifest types
+        resources = (
+            self.manifest.resources
+            if isinstance(self.manifest, Manifest)
+            else self.manifest.get("resources", {})
+        )
+
+        for resource_name, resource_data in resources.items():
+            # Generate for both LiveLoadBalancer (local dev) and LoadBalancerSlsResource (deployed)
+            # Use flag determined by isinstance() at scan time
+            is_load_balanced = (
+                resource_data.is_load_balanced
+                if hasattr(resource_data, "is_load_balanced")
+                else resource_data.get("is_load_balanced", False)
+            )
+            if not is_load_balanced:
+                continue
+
+            handler_path = self._generate_handler(resource_name, resource_data)
+            handler_paths.append(handler_path)
+
+        return handler_paths
+
+    def _generate_handler(self, resource_name: str, resource_data: Any) -> Path:
+        """Generate a single FastAPI handler file."""
+        handler_filename = f"handler_{resource_name}.py"
+        handler_path = self.build_dir / handler_filename
+
+        # Get timestamp from manifest
+        timestamp = (
+            self.manifest.generated_at
+            if isinstance(self.manifest, Manifest)
+            else self.manifest.get("generated_at", "")
+        )
+
+        # Determine if /execute endpoint should be included
+        # LiveLoadBalancer (local dev) includes /execute, deployed LoadBalancerSlsResource does not
+        # Use flag determined by isinstance() at scan time
+        include_execute = (
+            resource_data.is_live_resource
+            if hasattr(resource_data, "is_live_resource")
+            else resource_data.get("is_live_resource", False)
+        )
+
+        # Get functions from resource (handle both dict and ResourceConfig)
+        functions = (
+            resource_data.functions
+            if hasattr(resource_data, "functions")
+            else resource_data.get("functions", [])
+        )
+
+        # Generate imports section
+        imports = self._generate_imports(functions)
+
+        # Generate route registry
+        registry = self._generate_route_registry(functions)
+
+        # Format template
+        handler_code = LB_HANDLER_TEMPLATE.format(
+            resource_name=resource_name,
+            timestamp=timestamp,
+            imports=imports,
+            registry=registry,
+            include_execute=str(include_execute),
+        )
+
+        handler_path.write_text(handler_code)
+
+        # Validate that generated handler can be imported
+        self._validate_handler_imports(handler_path)
+
+        return handler_path
+
+    def _generate_imports(self, functions: List[Any]) -> str:
+        """Generate import statements for functions.
+
+        Uses importlib to handle module paths with any characters,
+        including numeric prefixes that aren't valid Python identifiers.
+
+        Args:
+            functions: List of function metadata (dicts or FunctionMetadata objects)
+
+        Returns:
+            Import statements as string
+        """
+        if not functions:
+            return "# No functions to import"
+
+        imports = ["import importlib"]
+
+        for func in functions:
+            # Handle both dict and FunctionMetadata
+            module = func.module if hasattr(func, "module") else func.get("module")
+            name = func.name if hasattr(func, "name") else func.get("name")
+
+            if module and name:
+                # Use importlib to handle module names with invalid identifiers
+                imports.append(f"{name} = importlib.import_module('{module}').{name}")
+
+        return "\n".join(imports)
+
+    def _generate_route_registry(self, functions: List[Any]) -> str:
+        """Generate route registry for FastAPI app.
+
+        Creates mapping of (method, path) tuples to function names.
+
+        Args:
+            functions: List of function metadata dicts with http_method and http_path
+
+        Returns:
+            Registry dictionary as string
+        """
+        if not functions:
+            return "    # No functions registered"
+
+        registry_lines = []
+
+        for func in functions:
+            # Handle both dict and FunctionMetadata
+            name = func.name if hasattr(func, "name") else func.get("name")
+            method = (
+                func.http_method
+                if hasattr(func, "http_method")
+                else func.get("http_method")
+            )
+            path = (
+                func.http_path if hasattr(func, "http_path") else func.get("http_path")
+            )
+
+            if name and method and path:
+                # Create tuple key: ("GET", "/api/process")
+                registry_lines.append(f'    ("{method}", "{path}"): {name},')
+            elif name:
+                # Skip if method or path missing (shouldn't happen with validation)
+                logger.warning(
+                    f"Function '{name}' missing http_method or http_path. Skipping."
+                )
+
+        return (
+            "\n".join(registry_lines)
+            if registry_lines
+            else "    # No routes registered"
+        )
+
+    def _validate_handler_imports(self, handler_path: Path) -> None:
+        """Validate that generated handler has valid Python syntax.
+
+        Attempts to load the handler module to catch syntax errors.
+        ImportErrors for missing worker modules are logged but not fatal,
+        as those imports may not be available at build time.
+
+        Args:
+            handler_path: Path to generated handler file
+
+        Raises:
+            ValueError: If handler has syntax errors or cannot be parsed
+        """
+        try:
+            spec = importlib.util.spec_from_file_location("handler", handler_path)
+            if spec and spec.loader:
+                module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(module)
+            else:
+                raise ValueError("Failed to create module spec")
+        except SyntaxError as e:
+            raise ValueError(f"Handler has syntax errors: {e}") from e
+        except ImportError as e:
+            # Log but don't fail - imports might not be available at build time
+            logger.debug(f"Handler import validation: {e}")
+        except Exception as e:
+            # Only raise for truly unexpected errors
+            logger.warning(f"Handler validation warning: {e}")