lumen-app 0.4.2__py3-none-any.whl

lumen_app/web/api/server.py

@@ -0,0 +1,253 @@
+"""Server management API endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+
+from lumen_app.utils.logger import get_logger
+from lumen_app.web.core.state import app_state
+from lumen_app.web.models.server import (
+    ServerLogs,
+    ServerRestartRequest,
+    ServerStartRequest,
+    ServerStatus,
+    ServerStopRequest,
+)
+
+logger = get_logger("lumen.web.api.server")
+router = APIRouter()
+
+
+@router.get("/status", response_model=ServerStatus)
+async def get_server_status():
+    """
+    Get the current ML server status.
+
+    Returns detailed information about the running server including:
+    - Running state and PID
+    - Port and host configuration
+    - Uptime in seconds
+    - Health status
+    - Configuration path
+    """
+    manager = app_state.server_manager
+
+    # Get basic status
+    running = manager.is_running
+    pid = manager.pid
+    uptime = manager.uptime_seconds
+
+    # Perform health check if running
+    health = "unknown"
+    if running:
+        health = await manager.health_check()
+
+    return ServerStatus(
+        running=running,
+        pid=pid,
+        port=manager.port or 50051,
+        host="0.0.0.0",
+        uptime_seconds=uptime,
+        service_name="lumen-ai",  # TODO: Get from config
+        config_path=manager.config_path,
+        environment="lumen_env",  # TODO: Get from config
+        health=health,
+        last_error=None,  # TODO: Track last error
+    )
+
+
+@router.post("/start", response_model=ServerStatus)
+async def start_server(request: ServerStartRequest):
+    """
+    Start the ML server with specified configuration.
+
+    Args:
+        request: Server start configuration including:
+            - config_path: Path to the Lumen YAML configuration
+            - port: Optional port override
+            - host: Host address (currently unused, always 0.0.0.0)
+            - environment: Conda environment name
+
+    Returns:
+        Current server status after startup
+
+    Raises:
+        HTTPException 400: If server is already running
+        HTTPException 404: If config file not found
+        HTTPException 500: If server fails to start
+    """
+    logger.info(f"Starting ML server with config: {request.config_path}")
+
+    manager = app_state.server_manager
+
+    # Check if already running
+    if manager.is_running:
+        raise HTTPException(
+            status_code=400,
+            detail="Server is already running. Stop it first or use restart.",
+        )
+
+    try:
+        # Start the server
+        success = await manager.start(
+            config_path=request.config_path,
+            port=request.port,
+            log_level="INFO",  # TODO: Make configurable
+            environment=request.environment,
+        )
+
+        if not success:
+            raise HTTPException(
+                status_code=500,
+                detail="Server failed to start. Check logs for details.",
+            )
+
+        logger.info("✓ ML server started successfully")
+
+        # Return current status
+        return await get_server_status()
+
+    except FileNotFoundError as e:
+        logger.error(f"Config file not found: {e}")
+        raise HTTPException(status_code=404, detail=str(e))
+
+    except RuntimeError as e:
+        logger.error(f"Runtime error starting server: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+    except Exception as e:
+        logger.error(f"Unexpected error starting server: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to start server: {str(e)}")
+
+
+@router.post("/stop", response_model=ServerStatus)
+async def stop_server(request: ServerStopRequest):
+    """
+    Stop the running ML server.
+
+    Args:
+        request: Stop configuration including:
+            - force: If True, force kill immediately without graceful shutdown
+            - timeout: Maximum seconds to wait for graceful shutdown
+
+    Returns:
+        Current server status after shutdown
+
+    Raises:
+        HTTPException 400: If server is not running
+        HTTPException 500: If server fails to stop
+    """
+    logger.info("Stopping ML server")
+
+    manager = app_state.server_manager
+
+    # Check if running
+    if not manager.is_running:
+        raise HTTPException(
+            status_code=400, detail="Server is not running. Nothing to stop."
+        )
+
+    try:
+        # Stop the server
+        success = await manager.stop(timeout=request.timeout, force=request.force)
+
+        if not success:
+            raise HTTPException(
+                status_code=500,
+                detail="Server failed to stop gracefully. Check logs for details.",
+            )
+
+        logger.info("✓ ML server stopped successfully")
+
+        # Return current status
+        return await get_server_status()
+
+    except Exception as e:
+        logger.error(f"Error stopping server: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to stop server: {str(e)}")
+
+
+@router.post("/restart", response_model=ServerStatus)
+async def restart_server(request: ServerRestartRequest):
+    """
+    Restart the ML server with optional new configuration.
+
+    This is equivalent to stop + start, but handles the sequencing automatically.
+
+    Args:
+        request: Restart configuration including:
+            - config_path: Optional new config path (uses existing if not provided)
+            - port: Optional new port (uses existing if not provided)
+            - host: Host address (currently unused)
+            - environment: Environment name
+            - force: If True, force kill during stop
+            - timeout: Maximum seconds to wait for graceful shutdown
+
+    Returns:
+        Current server status after restart
+
+    Raises:
+        HTTPException 400: If no config path available
+        HTTPException 500: If restart fails
+    """
+    logger.info("Restarting ML server")
+
+    manager = app_state.server_manager
+
+    try:
+        # Restart the server
+        success = await manager.restart(
+            config_path=request.config_path,
+            port=request.port,
+            log_level="INFO",  # TODO: Make configurable
+            timeout=request.timeout,
+        )
+
+        if not success:
+            raise HTTPException(
+                status_code=500,
+                detail="Server failed to restart. Check logs for details.",
+            )
+
+        logger.info("✓ ML server restarted successfully")
+
+        # Return current status
+        return await get_server_status()
+
+    except ValueError as e:
+        logger.error(f"Invalid restart configuration: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+    except Exception as e:
+        logger.error(f"Error restarting server: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500, detail=f"Failed to restart server: {str(e)}"
+        )
+
+
+@router.get("/logs", response_model=ServerLogs)
+async def get_server_logs(lines: int = 100, since: float | None = None):
+    """
+    Get recent server logs.
+
+    Args:
+        lines: Number of recent log lines to return (default: 100, 0 for all)
+        since: Unix timestamp to filter logs (currently unused)
+
+    Returns:
+        Server logs with metadata
+
+    Note:
+        The 'since' parameter is reserved for future filtering implementation.
+        Currently returns the most recent N lines from the log buffer.
+    """
+    manager = app_state.server_manager
+
+    # Get logs from manager
+    log_lines = manager.get_logs(tail=lines)
+
+    return ServerLogs(
+        logs=log_lines,
+        total_lines=len(log_lines),
+        new_lines=0,  # TODO: Implement incremental log fetching
+    )

lumen_app/web/core/__init__.py

@@ -0,0 +1 @@
+"""Core modules for Lumen Web API."""

lumen_app/web/core/server_manager.py

@@ -0,0 +1,348 @@
+"""
+Server Manager for gRPC ML Server Process.
+
+This module provides lifecycle management for the gRPC ML server subprocess,
+including starting, stopping, health checking, and log capture.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import deque
+from pathlib import Path
+from typing import Literal
+
+from lumen_app.utils.logger import get_logger
+
+logger = get_logger("lumen.web.server_manager")
+
+
+class ServerManager:
+    """
+    Manages the gRPC ML server as a subprocess.
+
+    This class handles:
+    - Starting the server with proper configuration
+    - Monitoring server health and status
+    - Capturing and buffering logs
+    - Graceful shutdown with timeout handling
+    """
+
+    def __init__(self, max_log_lines: int = 1000):
+        """
+        Initialize the server manager.
+
+        Args:
+            max_log_lines: Maximum number of log lines to keep in memory
+        """
+        self.process: asyncio.subprocess.Process | None = None
+        self.config_path: str | None = None
+        self.port: int | None = None
+        self.start_time: float | None = None
+        self.log_buffer: deque[str] = deque(maxlen=max_log_lines)
+        self._log_task: asyncio.Task | None = None
+        self._shutdown_event = asyncio.Event()
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the server process is running."""
+        if self.process is None:
+            return False
+
+        # Check if process is still alive
+        return self.process.returncode is None
+
+    @property
+    def pid(self) -> int | None:
+        """Get the server process PID."""
+        if self.process:
+            return self.process.pid
+        return None
+
+    @property
+    def uptime_seconds(self) -> float | None:
+        """Get server uptime in seconds."""
+        if self.start_time and self.is_running:
+            return time.time() - self.start_time
+        return None
+
+    async def start(
+        self,
+        config_path: str,
+        port: int | None = None,
+        log_level: str = "INFO",
+        environment: str | None = None,
+    ) -> bool:
+        """
+        Start the gRPC ML server as a subprocess.
+
+        Args:
+            config_path: Path to the Lumen configuration YAML file
+            port: Port number (overrides config file)
+            log_level: Logging level for the server
+            environment: Conda environment name (if using conda)
+
+        Returns:
+            True if server started successfully, False otherwise
+
+        Raises:
+            RuntimeError: If server is already running or config is invalid
+        """
+        if self.is_running:
+            raise RuntimeError("Server is already running")
+
+        # Validate config path
+        config_file = Path(config_path).expanduser()
+        if not config_file.exists():
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+
+        logger.info(f"Starting ML server with config: {config_path}")
+
+        # Build command
+        # We'll use python -m to run the server module
+        cmd = [
+            "python",
+            "-m",
+            "lumen_app.core.server",
+            "--config",
+            str(config_file),
+            "--log-level",
+            log_level,
+        ]
+
+        if port:
+            cmd.extend(["--port", str(port)])
+
+        logger.debug(f"Server command: {' '.join(cmd)}")
+
+        try:
+            # Start the subprocess
+            self.process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,  # Merge stderr into stdout
+                stdin=asyncio.subprocess.DEVNULL,
+            )
+
+            self.config_path = config_path
+            self.port = port
+            self.start_time = time.time()
+
+            logger.info(f"Server process started with PID: {self.process.pid}")
+
+            # Start log capture task
+            self._log_task = asyncio.create_task(self._capture_logs())
+
+            # Wait for server to be ready (with timeout)
+            ready = await self._wait_for_ready(timeout=30.0)
+
+            if not ready:
+                logger.error("Server failed to start within timeout")
+                await self.stop(force=True)
+                return False
+
+            logger.info("✓ ML server is ready")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to start server: {e}", exc_info=True)
+            if self.process:
+                await self.stop(force=True)
+            return False
+
+    async def stop(self, timeout: float = 30.0, force: bool = False) -> bool:
+        """
+        Stop the gRPC ML server.
+
+        Args:
+            timeout: Maximum time to wait for graceful shutdown
+            force: If True, skip graceful shutdown and kill immediately
+
+        Returns:
+            True if server stopped successfully, False otherwise
+        """
+        if not self.process:
+            logger.warning("No server process to stop")
+            return True
+
+        if not self.is_running:
+            logger.info("Server process already stopped")
+            self._cleanup()
+            return True
+
+        logger.info(f"Stopping ML server (PID: {self.process.pid})")
+
+        try:
+            if force:
+                # Force kill immediately
+                logger.warning("Force killing server process")
+                self.process.kill()
+            else:
+                # Try graceful shutdown first
+                logger.info("Sending SIGTERM for graceful shutdown")
+                self.process.terminate()
+
+                # Wait for graceful shutdown with timeout
+                try:
+                    await asyncio.wait_for(self.process.wait(), timeout=timeout)
+                    logger.info("Server stopped gracefully")
+                except asyncio.TimeoutError:
+                    logger.warning(
+                        f"Server did not stop within {timeout}s, force killing"
+                    )
+                    self.process.kill()
+                    await self.process.wait()
+
+            self._cleanup()
+            logger.info("✓ Server stopped")
+            return True
+
+        except Exception as e:
+            logger.error(f"Error stopping server: {e}", exc_info=True)
+            return False
+
+    async def restart(
+        self,
+        config_path: str | None = None,
+        port: int | None = None,
+        log_level: str = "INFO",
+        timeout: float = 30.0,
+    ) -> bool:
+        """
+        Restart the server.
+
+        Args:
+            config_path: New config path (or use existing)
+            port: New port (or use existing)
+            log_level: Logging level
+            timeout: Timeout for stop operation
+
+        Returns:
+            True if restart successful, False otherwise
+        """
+        logger.info("Restarting ML server")
+
+        # Use existing config if not provided
+        config_path = config_path or self.config_path
+        port = port or self.port
+
+        if not config_path:
+            raise ValueError("No config path specified for restart")
+
+        # Stop if running
+        if self.is_running:
+            success = await self.stop(timeout=timeout)
+            if not success:
+                logger.error("Failed to stop server for restart")
+                return False
+
+            # Wait a bit for resources to be freed
+            await asyncio.sleep(1.0)
+
+        # Start with new/existing config
+        return await self.start(config_path=config_path, port=port, log_level=log_level)
+
+    async def health_check(self) -> Literal["healthy", "unhealthy", "unknown"]:
+        """
+        Perform a health check on the server.
+
+        Returns:
+            "healthy" if server is running and responsive
+            "unhealthy" if server process exists but not responsive
+            "unknown" if server is not running
+        """
+        if not self.is_running:
+            return "unknown"
+
+        # TODO: Implement actual gRPC health check
+        # For now, just check if process is running
+        return "healthy"
+
+    def get_logs(self, tail: int = 100) -> list[str]:
+        """
+        Get recent log lines.
+
+        Args:
+            tail: Number of recent lines to return (0 for all)
+
+        Returns:
+            List of log lines
+        """
+        if tail > 0:
+            # Return last N lines
+            return list(self.log_buffer)[-tail:]
+        else:
+            # Return all lines
+            return list(self.log_buffer)
+
+    async def _capture_logs(self):
+        """Background task to capture server stdout/stderr."""
+        if not self.process or not self.process.stdout:
+            return
+
+        logger.debug("Starting log capture")
+
+        try:
+            async for line in self.process.stdout:
+                try:
+                    log_line = line.decode("utf-8").rstrip()
+                    self.log_buffer.append(log_line)
+
+                    # Also log to our logger for debugging
+                    logger.debug(f"[Server] {log_line}")
+
+                except Exception as e:
+                    logger.warning(f"Error decoding log line: {e}")
+
+        except asyncio.CancelledError:
+            logger.debug("Log capture cancelled")
+        except Exception as e:
+            logger.error(f"Error capturing logs: {e}", exc_info=True)
+
+    async def _wait_for_ready(self, timeout: float = 30.0) -> bool:
+        """
+        Wait for the server to be ready.
+
+        Args:
+            timeout: Maximum time to wait
+
+        Returns:
+            True if server is ready, False if timeout or error
+        """
+        logger.info(f"Waiting for server to be ready (timeout: {timeout}s)...")
+
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            # Check if process died
+            if not self.is_running:
+                logger.error("Server process died during startup")
+                return False
+
+            # Look for startup success indicators in logs
+            recent_logs = self.get_logs(tail=10)
+            for log_line in recent_logs:
+                if (
+                    "listening on" in log_line.lower()
+                    or "server running" in log_line.lower()
+                ):
+                    logger.info("Server startup detected in logs")
+                    # Give it a moment to fully initialize
+                    await asyncio.sleep(1.0)
+                    return True
+
+            # Wait a bit before checking again
+            await asyncio.sleep(0.5)
+
+        logger.error(f"Server did not start within {timeout}s")
+        return False
+
+    def _cleanup(self):
+        """Clean up server state after shutdown."""
+        if self._log_task and not self._log_task.done():
+            self._log_task.cancel()
+
+        self.process = None
+        self.start_time = None
+        self._log_task = None