quartermaster-code-runner 0.0.1__py3-none-any.whl

quartermaster_code_runner/__init__.py

@@ -0,0 +1,38 @@
+"""quartermaster-code-runner: Secure sandboxed code execution service.
+
+Executes untrusted code in isolated Docker containers with support
+for Python, Node.js, Go, Rust, Deno, and Bun.
+"""
+
+from quartermaster_code_runner.config import ResourceLimits, Settings
+from quartermaster_code_runner.errors import (
+    CodeRunnerError,
+    DockerError,
+    ExecutionError,
+    InvalidLanguageError,
+    ResourceExhaustedError,
+    RuntimeNotAvailableError,
+    TimeoutError,
+)
+from quartermaster_code_runner.schemas import (
+    CodeExecutionRequest,
+    CodeExecutionResponse,
+    HealthResponse,
+)
+
+__all__ = [
+    "CodeExecutionRequest",
+    "CodeExecutionResponse",
+    "CodeRunnerError",
+    "DockerError",
+    "ExecutionError",
+    "HealthResponse",
+    "InvalidLanguageError",
+    "ResourceExhaustedError",
+    "ResourceLimits",
+    "RuntimeNotAvailableError",
+    "Settings",
+    "TimeoutError",
+]
+
+__version__ = "0.1.0"

quartermaster_code_runner/app.py

@@ -0,0 +1,269 @@
+"""FastAPI application for sandboxed code execution.
+
+Provides REST API endpoints for executing code in isolated Docker containers
+with support for Python, Node.js, Go, Rust, Deno, and Bun.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import io
+import logging
+import os
+import tarfile
+import time
+from typing import Any
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+
+from quartermaster_code_runner.config import (
+    MAX_CODE_SIZE_BYTES,
+    Settings,
+)
+from quartermaster_code_runner.execution import (
+    cleanup_orphaned_containers,
+    execute_code_in_container,
+    get_docker_client,
+)
+from quartermaster_code_runner.images import (
+    cleanup_prebuilds,
+    configure_images,
+    ensure_prebuilt_image,
+    router as images_router,
+)
+from quartermaster_code_runner.schemas import CodeExecutionRequest, CodeExecutionResponse
+from quartermaster_code_runner.security import configure_auth, verify_auth
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+# Global settings and docker client
+_settings: Settings | None = None
+_docker_client = None
+
+
+async def _periodic_cleanup(interval_hours: int, max_age_days: int) -> None:
+    """Periodically clean up old prebuilt images."""
+    while True:
+        await asyncio.sleep(interval_hours * 3600)
+        try:
+            removed = await asyncio.to_thread(cleanup_prebuilds, max_age_days)
+            if removed:
+                logger.info(
+                    "Auto-cleanup removed %d prebuilt images: %s",
+                    len(removed),
+                    removed,
+                )
+        except Exception:
+            logger.exception("Auto-cleanup failed")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
+    """Application lifespan: setup and teardown."""
+    global _settings, _docker_client
+
+    # Load settings
+    _settings = Settings.from_env()
+    _settings.validate()
+
+    # Set log level
+    log_level = getattr(logging, _settings.log_level.upper(), logging.INFO)
+    logging.getLogger().setLevel(log_level)
+
+    # Configure authentication
+    configure_auth(
+        api_keys=_settings.api_keys,
+        auth_token=_settings.auth_token,
+    )
+
+    # Initialize Docker client
+    _docker_client = get_docker_client()
+
+    # Configure image management
+    configure_images(
+        docker_client=_docker_client,
+        runtime_dir=_settings.runtime_dir,
+        verify_auth_dep=verify_auth,
+    )
+
+    # Cleanup orphaned resources from previous runs
+    try:
+        cleanup_orphaned_containers(_docker_client)
+        logger.info("Startup: orphaned resources cleaned up")
+    except Exception:
+        logger.exception("Startup: failed to clean orphaned resources")
+
+    # Start periodic cleanup task
+    cleanup_task = asyncio.create_task(
+        _periodic_cleanup(
+            _settings.cleanup_interval_hours,
+            _settings.cleanup_max_age_days,
+        )
+    )
+
+    logger.info(
+        "Code Runner started (auth=%s, runtime_dir=%s)",
+        "enabled" if _settings.auth_enabled else "disabled",
+        _settings.runtime_dir,
+    )
+
+    try:
+        yield
+    finally:
+        cleanup_task.cancel()
+        logger.info("Code Runner shutting down")
+
+
+app = FastAPI(
+    title="quartermaster-code-runner",
+    description="Secure sandboxed code execution service",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+app.include_router(images_router)
+
+
+@app.post("/run", response_model=CodeExecutionResponse)
+async def run_code(
+    request: Request,
+    payload: CodeExecutionRequest,
+    _: str | None = Depends(verify_auth),
+) -> dict[str, Any]:
+    """Execute code in a secure, isolated Docker container.
+
+    Supports Python, Node.js, Go, Rust, Deno, and Bun runtimes.
+    """
+    assert _settings is not None
+    assert _docker_client is not None
+
+    logger.info("[run] request image=%s", payload.image)
+
+    if not payload.code and not payload.entrypoint:
+        raise HTTPException(
+            status_code=400,
+            detail="Either code or entrypoint must be provided.",
+        )
+
+    # Check code size
+    total_size = len(payload.code.encode("utf-8"))
+    if payload.files:
+        for content in payload.files.values():
+            total_size += len(content.encode("utf-8"))
+
+    if total_size > MAX_CODE_SIZE_BYTES:
+        raise HTTPException(status_code=413, detail="Code size exceeds the limit.")
+
+    start_time = time.time()
+
+    # Apply defaults from settings
+    timeout_seconds = (
+        payload.timeout if payload.timeout is not None else _settings.default_timeout
+    )
+    mem_limit = (
+        payload.mem_limit if payload.mem_limit is not None else _settings.default_memory
+    )
+    cpu_shares = (
+        payload.cpu_shares
+        if payload.cpu_shares is not None
+        else _settings.default_cpu_shares
+    )
+    disk_limit = (
+        payload.disk_limit if payload.disk_limit is not None else _settings.default_disk
+    )
+    network_disabled = not payload.allow_network
+
+    # Build container environment
+    container_env: dict[str, str] = {"HOME": "/tmp"}
+    if payload.environment:
+        container_env.update(payload.environment)
+    if payload.code:
+        container_env["ENCODED_CODE"] = base64.b64encode(
+            payload.code.encode("utf-8")
+        ).decode("utf-8")
+    if payload.entrypoint:
+        container_env["CUSTOM_ENTRYPOINT"] = payload.entrypoint
+
+    # Package additional files as tar archive
+    if payload.files:
+        tar_buffer = io.BytesIO()
+        with tarfile.open(fileobj=tar_buffer, mode="w:gz") as tar:
+            for filename, content in payload.files.items():
+                if ".." in filename or os.path.isabs(filename):
+                    raise HTTPException(
+                        status_code=400,
+                        detail=f"Invalid filename: {filename}",
+                    )
+                tarinfo = tarfile.TarInfo(name=filename)
+                file_bytes = content.encode("utf-8")
+                tarinfo.size = len(file_bytes)
+                tar.addfile(tarinfo, io.BytesIO(file_bytes))
+
+        tar_buffer.seek(0)
+        encoded_files = base64.b64encode(tar_buffer.read()).decode("utf-8")
+        container_env["ENCODED_FILES"] = encoded_files
+
+    # Execute
+    stdout, stderr, result, metadata = await execute_code_in_container(
+        docker_client=_docker_client,
+        image=payload.image,
+        environment=container_env,
+        timeout_seconds=timeout_seconds,
+        mem_limit=mem_limit,
+        cpu_shares=cpu_shares,
+        disk_limit=disk_limit,
+        network_disabled=network_disabled,
+        prebuild_spec=payload.prebuild_spec,
+        ensure_prebuilt_fn=ensure_prebuilt_image,
+    )
+
+    execution_time = time.time() - start_time
+
+    response: dict[str, Any] = {
+        "stdout": stdout,
+        "stderr": stderr,
+        "exit_code": result.get("StatusCode", -1),
+        "execution_time": round(execution_time, 4),
+    }
+
+    if metadata is not None:
+        response["metadata"] = metadata
+
+    return response
+
+
+@app.get("/health")
+def health() -> dict[str, Any]:
+    """Health check endpoint."""
+    docker_connected = False
+    if _docker_client:
+        try:
+            _docker_client.ping()
+            docker_connected = True
+        except Exception:
+            pass
+
+    return {
+        "status": "ok" if docker_connected else "degraded",
+        "docker_connected": docker_connected,
+        "auth_enabled": _settings.auth_enabled if _settings else False,
+    }
+
+
+@app.get("/runtimes")
+def list_runtimes() -> dict[str, Any]:
+    """List available runtimes. Alias for /images."""
+    from quartermaster_code_runner.images import list_images
+
+    return list_images()
+
+
+@app.get("/")
+def read_root() -> dict[str, Any]:
+    """Root endpoint."""
+    return {"message": "Code Runner is operational."}

quartermaster_code_runner/config.py

@@ -0,0 +1,175 @@
+"""Configuration for code runner service.
+
+All settings are configurable via environment variables with sensible defaults.
+Supports .env file loading via python-dotenv.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+logger = logging.getLogger(__name__)
+
+# Image naming conventions
+RUNTIME_IMAGE_PREFIX = "code-runner-"
+PREBUILT_IMAGE_PREFIX = "prebuilt-"
+DEFAULT_IMAGE = "python"
+SUPPORTED_IMAGES = ["python", "node", "bun", "go", "deno", "rust"]
+METADATA_FILE_PATH = "/metadata/.quartermaster_metadata.json"
+MAX_CODE_SIZE_BYTES = 1024 * 1024  # 1MB
+
+
+def get_image_name(image: str) -> str:
+    """Convert short image name to full Docker image name."""
+    if image.startswith(RUNTIME_IMAGE_PREFIX) or image.startswith(
+        PREBUILT_IMAGE_PREFIX
+    ):
+        return image
+    return f"{RUNTIME_IMAGE_PREFIX}{image}"
+
+
+def get_short_image_name(image: str) -> str:
+    """Get short image name from full or short name."""
+    if image.startswith(RUNTIME_IMAGE_PREFIX):
+        return image[len(RUNTIME_IMAGE_PREFIX) :]
+    return image
+
+
+@dataclass
+class ResourceLimits:
+    """Resource limits for a single code execution."""
+
+    cpu_cores: float = 1.0
+    memory_mb: int = 512
+    disk_mb: int = 500
+
+
+@dataclass
+class Settings:
+    """Global service settings loaded from environment variables.
+
+    All settings have sensible defaults and can be overridden via
+    environment variables or a .env file.
+    """
+
+    # Server
+    host: str = "0.0.0.0"
+    port: int = 8000
+    log_level: str = "info"
+
+    # Execution defaults
+    default_timeout: int = 30
+    max_timeout: int = 300
+    default_memory: str = "256m"
+    max_memory_mb: int = 2048
+    default_cpu_shares: int = 512
+    max_cpu_cores: float = 4.0
+    default_disk: str = "512m"
+    max_disk_mb: int = 5000
+
+    # Docker
+    docker_socket: str = "/var/run/docker.sock"
+
+    # Security
+    auth_token: str | None = None
+    api_keys: list[str] = field(default_factory=list)
+
+    # Cleanup
+    cleanup_interval_hours: int = 24
+    cleanup_max_age_days: int = 7
+
+    # Runtime image build path (relative to package)
+    runtime_dir: str = ""
+
+    @classmethod
+    def from_env(cls, env_file: str | None = None) -> Settings:
+        """Load settings from environment variables, with optional .env file.
+
+        Args:
+            env_file: Path to .env file. If None, searches current directory.
+        """
+        if env_file:
+            load_dotenv(env_file)
+        else:
+            load_dotenv()
+
+        api_keys_str = os.getenv("CODE_RUNNER_API_KEYS", "")
+        api_keys = [k.strip() for k in api_keys_str.split(",") if k.strip()]
+
+        # Also support AUTH_TOKEN as single-token auth
+        auth_token = os.getenv("AUTH_TOKEN")
+
+        # Determine runtime directory
+        runtime_dir = os.getenv(
+            "RUNTIME_DIR",
+            str(Path(__file__).parent / "runtime"),
+        )
+
+        return cls(
+            host=os.getenv("HOST", "0.0.0.0"),
+            port=int(os.getenv("PORT", "8000")),
+            log_level=os.getenv("LOG_LEVEL", "info"),
+            default_timeout=int(os.getenv("DEFAULT_TIMEOUT", "30")),
+            max_timeout=int(os.getenv("MAX_TIMEOUT", "300")),
+            default_memory=os.getenv("DEFAULT_MEMORY", "256m"),
+            max_memory_mb=int(os.getenv("MAX_MEMORY_MB", "2048")),
+            default_cpu_shares=int(os.getenv("DEFAULT_CPU_SHARES", "512")),
+            max_cpu_cores=float(os.getenv("MAX_CPU_CORES", "4.0")),
+            default_disk=os.getenv("DEFAULT_DISK", "512m"),
+            max_disk_mb=int(os.getenv("MAX_DISK_MB", "5000")),
+            docker_socket=os.getenv("DOCKER_SOCKET", "/var/run/docker.sock"),
+            auth_token=auth_token,
+            api_keys=api_keys,
+            cleanup_interval_hours=int(os.getenv("CLEANUP_INTERVAL_HOURS", "24")),
+            cleanup_max_age_days=int(os.getenv("CLEANUP_MAX_AGE_DAYS", "7")),
+            runtime_dir=runtime_dir,
+        )
+
+    def validate(self) -> list[str]:
+        """Validate configuration and return list of warnings/errors.
+
+        Raises:
+            ValueError: If configuration is fatally invalid.
+        """
+        errors: list[str] = []
+
+        if self.default_timeout <= 0:
+            errors.append("DEFAULT_TIMEOUT must be positive")
+        if self.max_timeout < self.default_timeout:
+            errors.append("MAX_TIMEOUT must be >= DEFAULT_TIMEOUT")
+        if self.max_memory_mb <= 0:
+            errors.append("MAX_MEMORY_MB must be positive")
+        if self.max_cpu_cores <= 0:
+            errors.append("MAX_CPU_CORES must be positive")
+        if self.max_disk_mb <= 0:
+            errors.append("MAX_DISK_MB must be positive")
+        if self.cleanup_interval_hours <= 0:
+            errors.append("CLEANUP_INTERVAL_HOURS must be positive")
+        if self.cleanup_max_age_days < 0:
+            errors.append("CLEANUP_MAX_AGE_DAYS must be non-negative")
+
+        if not Path(self.docker_socket).exists():
+            logger.warning("Docker socket not found at %s", self.docker_socket)
+
+        if not self.api_keys and not self.auth_token:
+            logger.warning(
+                "No authentication configured. API is open to all requests. "
+                "Set CODE_RUNNER_API_KEYS or AUTH_TOKEN to secure the API."
+            )
+
+        if errors:
+            raise ValueError(
+                "Invalid configuration:\n" + "\n".join(f"  - {e}" for e in errors)
+            )
+
+        return []
+
+    @property
+    def auth_enabled(self) -> bool:
+        """Whether any authentication method is configured."""
+        return bool(self.api_keys) or bool(self.auth_token)

quartermaster_code_runner/errors.py

@@ -0,0 +1,88 @@
+"""Exception types for code runner errors."""
+
+
+class CodeRunnerError(Exception):
+    """Base exception for all code runner errors."""
+
+    pass
+
+
+class ExecutionError(CodeRunnerError):
+    """Raised when code execution fails."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: int | None = None,
+        stdout: str | None = None,
+        stderr: str | None = None,
+    ) -> None:
+        """Initialize execution error.
+
+        Args:
+            message: Error message.
+            exit_code: Exit code from execution.
+            stdout: Standard output captured before error.
+            stderr: Standard error output.
+        """
+        self.exit_code = exit_code
+        self.stdout = stdout
+        self.stderr = stderr
+        super().__init__(message)
+
+
+class TimeoutError(CodeRunnerError):
+    """Raised when code execution times out."""
+
+    def __init__(
+        self,
+        message: str,
+        duration: float | None = None,
+        stdout: str | None = None,
+    ) -> None:
+        """Initialize timeout error.
+
+        Args:
+            message: Error message.
+            duration: Duration before timeout.
+            stdout: Partial output captured before timeout.
+        """
+        self.duration = duration
+        self.stdout = stdout
+        super().__init__(message)
+
+
+class ResourceExhaustedError(CodeRunnerError):
+    """Raised when execution exceeds resource limits."""
+
+    def __init__(
+        self,
+        message: str,
+        resource_type: str | None = None,
+    ) -> None:
+        """Initialize resource exhausted error.
+
+        Args:
+            message: Error message.
+            resource_type: Type of resource (memory, cpu, disk).
+        """
+        self.resource_type = resource_type
+        super().__init__(message)
+
+
+class DockerError(CodeRunnerError):
+    """Raised when Docker operations fail."""
+
+    pass
+
+
+class RuntimeNotAvailableError(CodeRunnerError):
+    """Raised when requested runtime is not available."""
+
+    pass
+
+
+class InvalidLanguageError(CodeRunnerError):
+    """Raised when language is not supported."""
+
+    pass