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

tetra_rp/core/resources/serverless_cpu.py

@@ -0,0 +1,201 @@
+"""
+CPU-specific serverless endpoint classes.
+
+This module contains all CPU-related serverless functionality, separate from GPU serverless.
+"""
+
+import hashlib
+import json
+from typing import List, Optional
+
+from pydantic import field_serializer, model_validator
+
+from .cpu import (
+    CpuInstanceType,
+    CPU_INSTANCE_DISK_LIMITS,
+    get_max_disk_size_for_instances,
+)
+from .serverless import ServerlessEndpoint, get_env_vars
+from .template import KeyValuePair, PodTemplate
+
+
+class CpuEndpointMixin:
+    """Mixin class that provides CPU-specific functionality for serverless endpoints."""
+
+    instanceIds: Optional[List[CpuInstanceType]]
+
+    def _is_cpu_endpoint(self) -> bool:
+        """Check if this is a CPU endpoint (has instanceIds)."""
+        return (
+            hasattr(self, "instanceIds")
+            and self.instanceIds is not None
+            and len(self.instanceIds) > 0
+        )
+
+    def _get_cpu_container_disk_size(self) -> Optional[int]:
+        """Get the appropriate container disk size for CPU instances."""
+        if not self._is_cpu_endpoint():
+            return None
+        return get_max_disk_size_for_instances(self.instanceIds)
+
+    def _apply_cpu_disk_sizing(self, template: PodTemplate) -> None:
+        """Apply CPU disk sizing to a template if it's using the default size."""
+        if not self._is_cpu_endpoint():
+            return
+
+        # Only auto-size if template is using the default value
+        default_disk_size = PodTemplate.model_fields["containerDiskInGb"].default
+        if template.containerDiskInGb == default_disk_size:
+            cpu_disk_size = self._get_cpu_container_disk_size()
+            if cpu_disk_size is not None:
+                template.containerDiskInGb = cpu_disk_size
+
+    def validate_cpu_container_disk_size(self) -> None:
+        """
+        Validate that container disk size doesn't exceed limits for CPU instances.
+
+        Raises:
+            ValueError: If container disk size exceeds the limit for any CPU instance
+        """
+        if (
+            not self._is_cpu_endpoint()
+            or not hasattr(self, "template")
+            or not self.template
+            or not self.template.containerDiskInGb
+        ):
+            return
+
+        max_allowed_disk_size = self._get_cpu_container_disk_size()
+        if max_allowed_disk_size is None:
+            return
+
+        if self.template.containerDiskInGb > max_allowed_disk_size:
+            instance_limits = []
+            for instance_type in self.instanceIds:
+                limit = CPU_INSTANCE_DISK_LIMITS[instance_type]
+                instance_limits.append(f"{instance_type.value}: max {limit}GB")
+
+            raise ValueError(
+                f"Container disk size {self.template.containerDiskInGb}GB exceeds the maximum "
+                f"allowed for CPU instances. Instance limits: {', '.join(instance_limits)}. "
+                f"Maximum allowed: {max_allowed_disk_size}GB"
+            )
+
+    def _sync_cpu_fields(self):
+        """Sync CPU-specific fields, overriding GPU defaults."""
+        # Override GPU-specific fields for CPU
+        if hasattr(self, "gpuCount"):
+            self.gpuCount = 0
+        if hasattr(self, "allowedCudaVersions"):
+            self.allowedCudaVersions = ""
+        if hasattr(self, "gpuIds"):
+            self.gpuIds = ""
+
+    @field_serializer("instanceIds")
+    def serialize_instance_ids(
+        self, value: Optional[List[CpuInstanceType]]
+    ) -> Optional[List[str]]:
+        """Convert CpuInstanceType enums to strings."""
+        if value is None:
+            return None
+        return [item.value if hasattr(item, "value") else str(item) for item in value]
+
+
+class CpuServerlessEndpoint(CpuEndpointMixin, ServerlessEndpoint):
+    """
+    CPU-only serverless endpoint with automatic disk sizing and validation.
+    Represents a CPU-only serverless endpoint distinct from a live serverless.
+    """
+
+    # CPU endpoints don't use GPU-specific fields, so exclude them from API payload
+    # This prevents the RunPod GraphQL API from rejecting CPU endpoints with GPU-specific fields
+    # Note: instanceIds is NOT in _input_only, so it will be sent to the API
+    _input_only = {
+        "id",
+        "cudaVersions",  # GPU-specific, exclude from API payload
+        "datacenter",
+        "env",
+        "gpus",  # Inherited from parent, but always None for CPU endpoints
+        "gpuIds",  # GPU-specific API field, exclude from payload
+        "gpuCount",  # GPU-specific API field, exclude from payload
+        "allowedCudaVersions",  # GPU-specific API field, exclude from payload
+        "flashboot",
+        "flashEnvironmentId",
+        "imageName",
+        "networkVolume",
+    }
+
+    # Override GPU field from parent to None for CPU endpoints
+    gpus: Optional[List] = None
+    instanceIds: Optional[List[CpuInstanceType]] = [CpuInstanceType.CPU3G_2_8]
+
+    @property
+    def config_hash(self) -> str:
+        """Get hash of current configuration excluding GPU-specific fields.
+
+        CPU endpoints need GPU fields in _input_only to exclude them from API payload,
+        but these fields should not be included in config_hash to avoid false drift
+        detection. This override computes the hash using only CPU-relevant fields.
+        """
+        # CPU-relevant fields for config hash, excluding 'env' to prevent false drift
+        # (env is dynamically computed from .env file at initialization time)
+        cpu_fields = {
+            "datacenter",
+            "flashboot",
+            "flashEnvironmentId",
+            "imageName",
+            "gpus",
+            "networkVolume",
+        }
+        config_dict = self.model_dump(
+            exclude_none=True, include=cpu_fields, mode="json"
+        )
+        config_str = json.dumps(config_dict, sort_keys=True)
+        hash_obj = hashlib.md5(f"{self.__class__.__name__}:{config_str}".encode())
+        return hash_obj.hexdigest()
+
+    def _create_new_template(self) -> PodTemplate:
+        """Create a new PodTemplate with CPU-appropriate disk sizing."""
+        template = PodTemplate(
+            name=self.resource_id,
+            imageName=self.imageName,
+            env=KeyValuePair.from_dict(self.env or get_env_vars()),
+        )
+        # Apply CPU-specific disk sizing
+        self._apply_cpu_disk_sizing(template)
+        return template
+
+    def _configure_existing_template(self) -> None:
+        """Configure an existing template with necessary overrides and CPU sizing."""
+        if self.template is None:
+            return
+
+        self.template.name = f"{self.resource_id}__{self.template.resource_id}"
+
+        if self.imageName:
+            self.template.imageName = self.imageName
+        if self.env:
+            self.template.env = KeyValuePair.from_dict(self.env)
+
+        # Apply CPU-specific disk sizing
+        self._apply_cpu_disk_sizing(self.template)
+
+    @model_validator(mode="after")
+    def set_serverless_template(self):
+        # Sync CPU-specific fields first
+        self._sync_cpu_fields()
+
+        if not any([self.imageName, self.template, self.templateId]):
+            raise ValueError(
+                "Either imageName, template, or templateId must be provided"
+            )
+
+        if not self.templateId and not self.template:
+            self.template = self._create_new_template()
+        elif self.template:
+            self._configure_existing_template()
+
+        # Validate container disk size for CPU instances
+        self.validate_cpu_container_disk_size()
+
+        return self

tetra_rp/core/resources/template.py

@@ -1,4 +1,3 @@
-import requests
 from typing import Dict, List, Optional, Any
 from pydantic import BaseModel, model_validator
 from .base import BaseResource
@@ -22,7 +21,7 @@ class KeyValuePair(BaseModel):
 class PodTemplate(BaseResource):
     advancedStart: Optional[bool] = False
     config: Optional[Dict[str, Any]] = {}
-    containerDiskInGb: Optional[int] = 10
+    containerDiskInGb: Optional[int] = 64
     containerRegistryAuthId: Optional[str] = ""
     dockerArgs: Optional[str] = ""
     env: Optional[List[KeyValuePair]] = []
@@ -35,60 +34,3 @@ class PodTemplate(BaseResource):
     def sync_input_fields(self):
         self.name = f"{self.name}__{self.resource_id}"
         return self
-
-
-def update_system_dependencies(
-    template_id, token, system_dependencies, base_entry_cmd=None
-):
-    """
-    Updates Runpod template with system dependencies installed via apt-get,
-    and appends the app start command.
-
-    Args:
-        template_id (str): Runpod template ID.
-        token (str): Runpod API token.
-        system_dependencies (List[str]): List of apt packages to install.
-        base_entry_cmd (List[str]): The default command to run the app, e.g. ["uv", "run", "handler.py"]
-    Returns:
-        dict: API response JSON or error info.
-    """
-
-    # Compose apt-get install command if any packages specified
-    apt_cmd = ""
-    if system_dependencies:
-        joined_pkgs = " ".join(system_dependencies)
-        apt_cmd = f"apt-get update && apt-get install -y {joined_pkgs} && "
-
-    # Default start command if not provided
-    app_cmd = base_entry_cmd or ["uv", "run", "handler.py"]
-    app_cmd_str = " ".join(app_cmd)
-
-    # Full command to run in entrypoint shell
-    full_cmd = f"{apt_cmd}exec {app_cmd_str}"
-
-    payload = {
-        # other required fields like disk, env, image, etc, should be fetched or passed in real usage
-        "dockerEntrypoint": ["/bin/bash", "-c", full_cmd],
-        "dockerStartCmd": [],
-        # placeholder values, replace as needed or fetch from current template state
-        "containerDiskInGb": 50,
-        "containerRegistryAuthId": "",
-        "env": {},
-        "imageName": "your-image-name",
-        "isPublic": False,
-        "name": "your-template-name",
-        "ports": ["8888/http", "22/tcp"],
-        "readme": "",
-        "volumeInGb": 20,
-        "volumeMountPath": "/workspace",
-    }
-
-    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
-
-    url = f"https://rest.runpod.io/v1/templates/{template_id}/update"
-    response = requests.post(url, json=payload, headers=headers)
-
-    try:
-        return response.json()
-    except Exception:
-        return {"error": "Invalid JSON response", "text": response.text}

tetra_rp/core/utils/constants.py

@@ -0,0 +1,10 @@
+"""
+Constants for utility modules and caching configurations.
+
+This module contains configurable constants used across the tetra-rp codebase
+to ensure consistency and easy maintenance.
+"""
+
+# Cache key generation constants
+HASH_TRUNCATE_LENGTH = 16  # Length to truncate hash values for cache keys
+UUID_FALLBACK_LENGTH = 8  # Length to truncate UUID values for fallback keys

tetra_rp/core/utils/file_lock.py

@@ -0,0 +1,260 @@
+"""
+Cross-platform file locking utilities.
+
+Provides unified file locking interface that works across Windows, macOS, and Linux.
+Uses platform-appropriate locking mechanisms:
+- Windows: msvcrt.locking()
+- Unix/Linux/macOS: fcntl.flock()
+- Fallback: Basic file existence checking (limited protection)
+"""
+
+import contextlib
+import logging
+import platform
+import time
+from pathlib import Path
+from typing import BinaryIO, Optional
+
+log = logging.getLogger(__name__)
+
+# Platform detection
+_IS_WINDOWS = platform.system() == "Windows"
+_IS_UNIX = platform.system() in ("Linux", "Darwin")
+
+# Initialize availability flags
+_WINDOWS_LOCKING_AVAILABLE = False
+_UNIX_LOCKING_AVAILABLE = False
+
+# Import platform-specific modules
+if _IS_WINDOWS:
+    try:
+        import msvcrt
+
+        _WINDOWS_LOCKING_AVAILABLE = True
+    except ImportError:
+        msvcrt = None
+        log.warning("msvcrt not available on Windows platform")
+
+if _IS_UNIX:
+    try:
+        import fcntl
+
+        _UNIX_LOCKING_AVAILABLE = True
+    except ImportError:
+        fcntl = None
+        log.warning("fcntl not available on Unix platform")
+
+
+class FileLockError(Exception):
+    """Exception raised when file locking operations fail."""
+
+    pass
+
+
+class FileLockTimeout(FileLockError):
+    """Exception raised when file locking times out."""
+
+    pass
+
+
+@contextlib.contextmanager
+def file_lock(
+    file_handle: BinaryIO,
+    exclusive: bool = True,
+    timeout: Optional[float] = 10.0,
+    retry_interval: float = 0.1,
+):
+    """
+    Cross-platform file locking context manager.
+
+    Args:
+        file_handle: Open file handle to lock
+        exclusive: True for exclusive lock, False for shared lock
+        timeout: Maximum seconds to wait for lock (None = no timeout)
+        retry_interval: Seconds to wait between lock attempts
+
+    Raises:
+        FileLockTimeout: If lock cannot be acquired within timeout
+        FileLockError: If locking operation fails
+
+    Usage:
+        with open("file.dat", "rb") as f:
+            with file_lock(f, exclusive=False):  # Shared read lock
+                data = f.read()
+
+        with open("file.dat", "wb") as f:
+            with file_lock(f, exclusive=True):   # Exclusive write lock
+                f.write(data)
+    """
+    lock_acquired = False
+    start_time = time.time()
+
+    try:
+        # Platform-specific locking
+        while not lock_acquired:
+            try:
+                if _IS_WINDOWS and _WINDOWS_LOCKING_AVAILABLE:
+                    _acquire_windows_lock(file_handle, exclusive)
+                elif _IS_UNIX and _UNIX_LOCKING_AVAILABLE:
+                    _acquire_unix_lock(file_handle, exclusive)
+                else:
+                    # Fallback - limited protection via file existence
+                    _acquire_fallback_lock(file_handle, exclusive, timeout)
+
+                lock_acquired = True
+                log.debug(f"File lock acquired (exclusive={exclusive})")
+
+            except (OSError, IOError, FileLockError) as e:
+                # Check timeout
+                if timeout is not None and (time.time() - start_time) >= timeout:
+                    raise FileLockTimeout(
+                        f"Could not acquire file lock within {timeout} seconds: {e}"
+                    ) from e
+
+                # Retry after interval
+                time.sleep(retry_interval)
+
+        # Lock acquired successfully
+        yield
+
+    finally:
+        # Release lock
+        if lock_acquired:
+            try:
+                if _IS_WINDOWS and _WINDOWS_LOCKING_AVAILABLE:
+                    _release_windows_lock(file_handle)
+                elif _IS_UNIX and _UNIX_LOCKING_AVAILABLE:
+                    _release_unix_lock(file_handle)
+                else:
+                    _release_fallback_lock(file_handle)
+
+                log.debug("File lock released")
+
+            except Exception as e:
+                log.error(f"Error releasing file lock: {e}")
+                # Don't raise - we're in cleanup
+
+
+def _acquire_windows_lock(file_handle: BinaryIO, exclusive: bool) -> None:
+    """Acquire Windows file lock using msvcrt.locking()."""
+    if not _WINDOWS_LOCKING_AVAILABLE:
+        raise FileLockError("Windows file locking not available (msvcrt missing)")
+
+    # Windows locking modes
+    if exclusive:
+        lock_mode = msvcrt.LK_NBLCK  # Non-blocking exclusive lock
+    else:
+        # Windows doesn't have shared locks in msvcrt
+        # Fall back to exclusive for compatibility
+        lock_mode = msvcrt.LK_NBLCK
+        log.debug("Windows: Using exclusive lock instead of shared (msvcrt limitation)")
+
+    try:
+        # Lock the entire file (position 0, length 1)
+        file_handle.seek(0)
+        msvcrt.locking(file_handle.fileno(), lock_mode, 1)
+    except OSError as e:
+        raise FileLockError(f"Failed to acquire Windows file lock: {e}") from e
+
+
+def _release_windows_lock(file_handle: BinaryIO) -> None:
+    """Release Windows file lock."""
+    if not _WINDOWS_LOCKING_AVAILABLE:
+        return
+
+    try:
+        file_handle.seek(0)
+        msvcrt.locking(file_handle.fileno(), msvcrt.LK_UNLCK, 1)
+    except OSError as e:
+        raise FileLockError(f"Failed to release Windows file lock: {e}") from e
+
+
+def _acquire_unix_lock(file_handle: BinaryIO, exclusive: bool) -> None:
+    """Acquire Unix file lock using fcntl.flock()."""
+    if not _UNIX_LOCKING_AVAILABLE:
+        raise FileLockError("Unix file locking not available (fcntl missing)")
+
+    # Unix locking modes
+    if exclusive:
+        lock_mode = fcntl.LOCK_EX | fcntl.LOCK_NB  # Non-blocking exclusive
+    else:
+        lock_mode = fcntl.LOCK_SH | fcntl.LOCK_NB  # Non-blocking shared
+
+    try:
+        fcntl.flock(file_handle.fileno(), lock_mode)
+    except (OSError, IOError) as e:
+        raise FileLockError(f"Failed to acquire Unix file lock: {e}") from e
+
+
+def _release_unix_lock(file_handle: BinaryIO) -> None:
+    """Release Unix file lock."""
+    if not _UNIX_LOCKING_AVAILABLE:
+        return
+
+    try:
+        fcntl.flock(file_handle.fileno(), fcntl.LOCK_UN)
+    except (OSError, IOError) as e:
+        raise FileLockError(f"Failed to release Unix file lock: {e}") from e
+
+
+def _acquire_fallback_lock(
+    file_handle: BinaryIO, exclusive: bool, timeout: Optional[float]
+) -> None:
+    """
+    Fallback locking using lock files.
+
+    This provides minimal protection but doesn't prevent all race conditions.
+    It's better than no locking but not as robust as OS-level file locks.
+    """
+    log.warning(
+        "Using fallback file locking - limited protection against race conditions"
+    )
+
+    # Create lock file based on the original file
+    file_path = (
+        Path(file_handle.name) if hasattr(file_handle, "name") else Path("unknown")
+    )
+    lock_file = file_path.with_suffix(file_path.suffix + ".lock")
+
+    start_time = time.time()
+
+    while True:
+        try:
+            # Try to create lock file atomically
+            lock_file.touch(mode=0o600, exist_ok=False)
+            log.debug(f"Fallback lock file created: {lock_file}")
+            return
+
+        except FileExistsError:
+            # Lock file exists, check timeout
+            if timeout is not None and (time.time() - start_time) >= timeout:
+                raise FileLockError(f"Fallback lock timeout: {lock_file} exists")
+
+            # Wait and retry
+            time.sleep(0.1)
+
+
+def _release_fallback_lock(file_handle: BinaryIO) -> None:
+    """Release fallback lock by removing lock file."""
+    try:
+        file_path = (
+            Path(file_handle.name) if hasattr(file_handle, "name") else Path("unknown")
+        )
+        lock_file = file_path.with_suffix(file_path.suffix + ".lock")
+
+        if lock_file.exists():
+            lock_file.unlink()
+            log.debug(f"Fallback lock file removed: {lock_file}")
+
+    except Exception as e:
+        log.error(f"Failed to remove fallback lock file: {e}")
+
+
+def get_platform_info() -> dict:
+    """Get information about current platform and available locking mechanisms."""
+    return {
+        "platform": platform.system(),
+        "windows_locking": _IS_WINDOWS and _WINDOWS_LOCKING_AVAILABLE,
+        "unix_locking": _IS_UNIX and _UNIX_LOCKING_AVAILABLE,
+        "fallback_only": not (_WINDOWS_LOCKING_AVAILABLE or _UNIX_LOCKING_AVAILABLE),
+    }

tetra_rp/core/utils/http.py

@@ -0,0 +1,67 @@
+"""HTTP utilities for RunPod API communication."""
+
+import os
+from typing import Optional
+
+import httpx
+import requests
+
+
+def get_authenticated_httpx_client(
+    timeout: Optional[float] = None,
+) -> httpx.AsyncClient:
+    """Create httpx AsyncClient with RunPod authentication.
+
+    Automatically includes Authorization header if RUNPOD_API_KEY is set.
+    This provides a centralized place to manage authentication headers for
+    all RunPod HTTP requests, avoiding repetitive manual header addition.
+
+    Args:
+        timeout: Request timeout in seconds. Defaults to 30.0.
+
+    Returns:
+        Configured httpx.AsyncClient with Authorization header
+
+    Example:
+        async with get_authenticated_httpx_client() as client:
+            response = await client.post(url, json=data)
+
+        # With custom timeout
+        async with get_authenticated_httpx_client(timeout=60.0) as client:
+            response = await client.get(url)
+    """
+    headers = {}
+    api_key = os.environ.get("RUNPOD_API_KEY")
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    timeout_config = timeout if timeout is not None else 30.0
+    return httpx.AsyncClient(timeout=timeout_config, headers=headers)
+
+
+def get_authenticated_requests_session() -> requests.Session:
+    """Create requests Session with RunPod authentication.
+
+    Automatically includes Authorization header if RUNPOD_API_KEY is set.
+    Provides a centralized place to manage authentication headers for
+    synchronous RunPod HTTP requests.
+
+    Returns:
+        Configured requests.Session with Authorization header
+
+    Example:
+        session = get_authenticated_requests_session()
+        response = session.post(url, json=data, timeout=30.0)
+        # Remember to close: session.close()
+
+        # Or use as context manager
+        import contextlib
+        with contextlib.closing(get_authenticated_requests_session()) as session:
+            response = session.post(url, json=data)
+    """
+    session = requests.Session()
+    api_key = os.environ.get("RUNPOD_API_KEY")
+    if api_key:
+        session.headers["Authorization"] = f"Bearer {api_key}"
+
+    return session

tetra_rp/core/utils/lru_cache.py

@@ -0,0 +1,75 @@
+"""
+LRU Cache implementation using OrderedDict for memory-efficient caching with automatic eviction.
+
+This module provides a Least Recently Used (LRU) cache implementation that automatically
+manages memory by evicting the least recently used items when the cache exceeds its
+maximum size limit. It maintains O(1) access time and provides a dict-like interface.
+Thread-safe for concurrent access.
+"""
+
+import threading
+from collections import OrderedDict
+from typing import Any, Dict, Optional
+
+
+class LRUCache:
+    """
+    A Least Recently Used (LRU) cache implementation using OrderedDict.
+
+    Automatically evicts the least recently used items when the cache exceeds
+    the maximum size limit. Provides dict-like interface with O(1) operations.
+    Thread-safe for concurrent access using RLock.
+
+    Args:
+        max_size: Maximum number of items to store in cache (default: 1000)
+    """
+
+    def __init__(self, max_size: int = 1000):
+        self.max_size = max_size
+        self.cache = OrderedDict()
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        """Get item from cache, moving it to end (most recent) if found."""
+        with self._lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+                return self.cache[key]
+            return None
+
+    def set(self, key: str, value: Dict[str, Any]) -> None:
+        """Set item in cache, evicting oldest if at capacity."""
+        with self._lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+            else:
+                if len(self.cache) >= self.max_size:
+                    self.cache.popitem(last=False)  # Remove oldest
+            self.cache[key] = value
+
+    def clear(self) -> None:
+        """Clear all items from cache."""
+        with self._lock:
+            self.cache.clear()
+
+    def __contains__(self, key: str) -> bool:
+        """Check if key exists in cache."""
+        with self._lock:
+            return key in self.cache
+
+    def __len__(self) -> int:
+        """Return number of items in cache."""
+        with self._lock:
+            return len(self.cache)
+
+    def __getitem__(self, key: str) -> Dict[str, Any]:
+        """Get item using bracket notation, moving to end if found."""
+        with self._lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+                return self.cache[key]
+            raise KeyError(key)
+
+    def __setitem__(self, key: str, value: Dict[str, Any]) -> None:
+        """Set item using bracket notation."""
+        self.set(key, value)