scalebox-sdk 0.1.0__py3-none-any.whl

scalebox/generated/rpc.py

@@ -0,0 +1,50 @@
+import base64
+from typing import Optional
+
+from ..connection_config import Username, default_username
+from ..csx_connect.client import Code, ConnectException
+from ..exceptions import (
+    AuthenticationException,
+    InvalidArgumentException,
+    NotFoundException,
+    RateLimitException,
+    SandboxException,
+    TimeoutException,
+    sandbox_timeout_exception,
+)
+
+
+def handle_rpc_exception(e: Exception):
+    if isinstance(e, ConnectException):
+        if e.status == Code.invalid_argument:
+            return InvalidArgumentException(e.message)
+        elif e.status == Code.unauthenticated:
+            return AuthenticationException(e.message)
+        elif e.status == Code.not_found:
+            return NotFoundException(e.message)
+        elif e.status == Code.unavailable:
+            return sandbox_timeout_exception(e.message)
+        elif e.status == Code.resource_exhausted:
+            return RateLimitException(
+                f"{e.message}: Rate limit exceeded, please try again later."
+            )
+        elif e.status == Code.canceled:
+            return TimeoutException(
+                f"{e.message}: This error is likely due to exceeding 'request_timeout'. You can pass the request timeout value as an option when making the request."
+            )
+        elif e.status == Code.deadline_exceeded:
+            return TimeoutException(
+                f"{e.message}: This error is likely due to exceeding 'timeout' — the total time a long running request (like process or directory watch) can be active. It can be modified by passing 'timeout' when making the request. Use '0' to disable the timeout."
+            )
+        else:
+            return SandboxException(f"{e.status}: {e.message}")
+    else:
+        return e
+
+
+def authentication_header(user: Optional[Username] = None):
+    value = f"{user if user is not None else default_username}:"
+
+    encoded = base64.b64encode(value.encode("utf-8")).decode("utf-8")
+
+    return {"Authorization": f"Basic {encoded}"}

scalebox/generated/versions.py

@@ -0,0 +1,3 @@
+from packaging.version import Version
+
+ENVD_VERSION_RECURSIVE_WATCH = Version("0.1.4")

scalebox/requirements.txt

@@ -0,0 +1,36 @@
+# HTTP and networking
+httpx>=0.24
+aiohttp>=3.8.0
+urllib3>=1.26.0
+httpcore>=0.15.0
+
+# gRPC and protocol buffers
+grpcio>=1.74.0
+grpcio-tools>=1.74.0
+protobuf>=4.21
+
+# ConnectRPC
+connect-python[protobuf]>=0.4.2
+
+# Data structures and serialization
+attrs>=21.4.0
+dataclasses-json>=0.5.0
+
+# Date and time handling
+python-dateutil>=2.8.0
+
+# Retry and resilience
+tenacity>=8.0.0
+
+# Version handling
+packaging>=21.0
+
+# Type extensions
+typing-extensions>=4.0.0
+
+# Async utilities
+asyncio-mqtt>=0.11.0
+
+# Development and testing (optional)
+pytest>=7.0.0
+pytest-asyncio>=0.21.0

scalebox/sandbox/commands/command_handle.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from ...exceptions import SandboxException
+
+Stdout = str
+"""
+Command stdout output.
+"""
+Stderr = str
+"""
+Command stderr output.
+"""
+PtyOutput = bytes
+"""
+Pty output.
+"""
+
+
+@dataclass
+class PtySize:
+    """
+    Pseudo-terminal size.
+    """
+
+    rows: int
+    """
+    Number of rows.
+    """
+    cols: int
+    """
+    Number of columns.
+    """
+
+
+@dataclass
+class CommandResult:
+    """
+    Command execution result.
+    """
+
+    stderr: str
+    """
+    Command stderr output.
+    """
+    stdout: str
+    """
+    Command stdout output.
+    """
+    exit_code: int
+    """
+    Command exit code.
+
+    `0` if the command finished successfully.
+    """
+    error: Optional[str]
+    """
+    Error message from command execution if it failed.
+    """
+
+
+@dataclass
+class CommandExitException(SandboxException, CommandResult):
+    """
+    Exception raised when a command exits with a non-zero exit code.
+    """
+
+    def __str__(self):
+        return f"Command exited with code {self.exit_code} and error:\n{self.stderr}"

scalebox/sandbox/commands/main.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ProcessInfo:
+    """
+    Information about a command, PTY session or start command running in the sandbox as process.
+    """
+
+    pid: int
+    """
+    Process ID.
+    """
+
+    tag: Optional[str]
+    """
+    Custom tag used for identifying special commands like start command in the custom template.
+    """
+
+    cmd: str
+    """
+    Command that was executed.
+    """
+
+    args: List[str]
+    """
+    Command arguments.
+    """
+
+    envs: Dict[str, str]
+    """
+    Environment variables used for the command.
+    """
+
+    cwd: Optional[str]
+    """
+    Executed command working directory.
+    """

scalebox/sandbox/filesystem/filesystem.py

@@ -0,0 +1,95 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import IO, Optional, Union
+
+from ...generated import api_pb2
+
+
+class FileType(Enum):
+    """
+    Enum representing the type of filesystem object.
+    """
+
+    FILE = "file"
+    """
+    Filesystem object is a file.
+    """
+    DIR = "dir"
+    """
+    Filesystem object is a directory.
+    """
+
+
+def map_file_type(ft: api_pb2.FileType):
+    if ft == api_pb2.FileType.FILE_TYPE_FILE:
+        return FileType.FILE
+    elif ft == api_pb2.FileType.FILE_TYPE_DIRECTORY:
+        return FileType.DIR
+
+
+@dataclass
+class WriteInfo:
+    """
+    Sandbox filesystem object information.
+    """
+
+    name: str
+    """
+    Name of the filesystem object.
+    """
+    type: Optional[FileType]
+    """
+    Type of the filesystem object.
+    """
+    path: str
+    """
+    Path to the filesystem object.
+    """
+
+
+@dataclass
+class EntryInfo(WriteInfo):
+    """
+    Extended sandbox filesystem object information.
+    """
+
+    size: int
+    """
+    Size of the filesystem object in bytes.
+    """
+    mode: int
+    """
+    File mode and permission bits.
+    """
+    permissions: str
+    """
+    String representation of file permissions (e.g. 'rwxr-xr-x').
+    """
+    owner: str
+    """
+    Owner of the filesystem object.
+    """
+    group: str
+    """
+    Group owner of the filesystem object.
+    """
+    modified_time: datetime
+    """
+    Last modification time of the filesystem object.
+    """
+    symlink_target: Optional[str] = None
+    """
+    Target of the symlink if the filesystem object is a symlink.
+    If the filesystem object is not a symlink, this field is None.
+    """
+
+
+@dataclass
+class WriteEntry:
+    """
+    Contains path and data of the file to be written to the filesystem.
+    """
+
+    path: str
+    data: Union[str, bytes, IO]

scalebox/sandbox/filesystem/watch_handle.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+from enum import Enum
+
+from ...generated.api_pb2 import EventType
+
+
+class FilesystemEventType(Enum):
+    """
+    Enum representing the type of filesystem event.
+    """
+
+    CHMOD = "chmod"
+    """
+    Filesystem object permissions were changed.
+    """
+    CREATE = "create"
+    """
+    Filesystem object was created.
+    """
+    REMOVE = "remove"
+    """
+    Filesystem object was removed.
+    """
+    RENAME = "rename"
+    """
+    Filesystem object was renamed.
+    """
+    WRITE = "write"
+    """
+    Filesystem object was written to.
+    """
+
+
+def map_event_type(event: EventType):
+    if event == EventType.EVENT_TYPE_CHMOD:
+        return FilesystemEventType.CHMOD
+    elif event == EventType.EVENT_TYPE_CREATE:
+        return FilesystemEventType.CREATE
+    elif event == EventType.EVENT_TYPE_REMOVE:
+        return FilesystemEventType.REMOVE
+    elif event == EventType.EVENT_TYPE_RENAME:
+        return FilesystemEventType.RENAME
+    elif event == EventType.EVENT_TYPE_WRITE:
+        return FilesystemEventType.WRITE
+
+
+@dataclass
+class FilesystemEvent:
+    """
+    Contains information about the filesystem event - the name of the file and the type of the event.
+    """
+
+    name: str
+    """
+    Relative path to the filesystem object.
+    """
+    type: FilesystemEventType
+    """
+    Filesystem operation event type.
+    """

scalebox/sandbox/main.py

@@ -0,0 +1,139 @@
+import urllib.parse
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from httpx import Limits
+
+from ..connection_config import ConnectionConfig
+from ..generated.api import ENVD_API_FILES_ROUTE
+from .signature import get_signature
+
+
+class SandboxSetup(ABC):
+    _limits = Limits(
+        max_keepalive_connections=40,
+        max_connections=40,
+        keepalive_expiry=300,
+    )
+
+    envd_port = 443
+
+    default_sandbox_timeout = 300
+    default_template = "base"
+
+    @property
+    @abstractmethod
+    def connection_config(self) -> ConnectionConfig: ...
+
+    @property
+    @abstractmethod
+    def _envd_access_token(self) -> Optional[str]: ...
+
+    @property
+    @abstractmethod
+    def envd_api_url(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def sandbox_id(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def sandbox_domain(self) -> str: ...
+
+    def _file_url(
+        self,
+        path: Optional[str] = None,
+        user: str = "user",
+        signature: Optional[str] = None,
+        signature_expiration: Optional[int] = None,
+    ) -> str:
+        url = urllib.parse.urljoin(self.envd_api_url, ENVD_API_FILES_ROUTE)
+        query = {"path": path} if path else {}
+        query = {**query, "username": user}
+
+        if signature:
+            query["signature"] = signature
+
+        if signature_expiration:
+            if signature is None:
+                raise ValueError("signature_expiration requires signature to be set")
+            query["signature_expiration"] = str(signature_expiration)
+
+        params = urllib.parse.urlencode(
+            query,
+            quote_via=urllib.parse.quote,
+        )
+        url = urllib.parse.urljoin(url, f"?{params}")
+
+        return url
+
+    def download_url(
+        self,
+        path: str,
+        user: str = "user",
+        use_signature_expiration: Optional[int] = None,
+    ) -> str:
+        """
+        Get the URL to download a file from the sandbox.
+
+        :param path: Path to the file to download
+        :param user: User to upload the file as
+        :param use_signature_expiration: Expiration time for the signed URL in seconds
+
+        :return: URL for downloading file
+        """
+
+        use_signature = self._envd_access_token is not None
+        if use_signature:
+            signature = get_signature(
+                path, "read", user, self._envd_access_token, use_signature_expiration
+            )
+            return self._file_url(
+                path, user, signature["signature"], signature["expiration"]
+            )
+        else:
+            return self._file_url(path)
+
+    def upload_url(
+        self,
+        path: Optional[str] = None,
+        user: str = "user",
+        use_signature_expiration: Optional[int] = None,
+    ) -> str:
+        """
+        Get the URL to upload a file to the sandbox.
+
+        You have to send a POST request to this URL with the file as multipart/form-data.
+
+        :param path: Path to the file to upload
+        :param user: User to upload the file as
+        :param use_signature_expiration: Expiration time for the signed URL in seconds
+
+        :return: URL for uploading file
+        """
+
+        use_signature = self._envd_access_token is not None
+        if use_signature:
+            signature = get_signature(
+                path, "write", user, self._envd_access_token, use_signature_expiration
+            )
+            return self._file_url(
+                path, user, signature["signature"], signature["expiration"]
+            )
+        else:
+            return self._file_url(path)
+
+    def get_host(self, port: int) -> str:
+        """
+        Get the host address to connect to the sandbox.
+        You can then use this address to connect to the sandbox port from outside the sandbox via HTTP or WebSocket.
+
+        :param port: Port to connect to
+
+        :return: Host address to connect to
+        """
+        if self.connection_config.debug:
+            return f"localhost:{port}"
+        return f"{self.sandbox_domain}"
+        # return f"{port}-{self.sandbox_id}.{self.sandbox_domain}"

scalebox/sandbox/sandbox_api.py

@@ -0,0 +1,91 @@
+from abc import ABC
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Dict, Optional
+
+from httpx import Limits
+
+from ..api.client.models import SandboxState
+
+
+@dataclass
+class SandboxInfo:
+    """Information about a sandbox."""
+
+    sandbox_id: str
+    """Sandbox ID."""
+    sandbox_domain: Optional[str]
+    """Domain where the sandbox is hosted."""
+    template_id: str
+    """Template ID."""
+    name: Optional[str]
+    """Template name."""
+    metadata: Dict[str, str]
+    """Saved sandbox metadata."""
+    started_at: datetime
+    """Sandbox start time."""
+    end_at: datetime
+    """Sandbox expiration date."""
+    envd_version: Optional[str]
+    """Envd version."""
+    _envd_access_token: Optional[str]
+    """Envd access token."""
+
+
+@dataclass
+class ListedSandbox:
+    """Information about a sandbox."""
+
+    sandbox_id: str
+    """Sandbox ID."""
+    template_id: str
+    """Template ID."""
+    name: Optional[str]
+    """Template Alias."""
+    state: SandboxState
+    """Sandbox state."""
+    cpu_count: int
+    """Sandbox CPU count."""
+    memory_mb: int
+    """Sandbox Memory size in MB."""
+    metadata: Dict[str, str]
+    """Saved sandbox metadata."""
+    started_at: datetime
+    """Sandbox start time."""
+    end_at: datetime
+
+
+@dataclass
+class SandboxQuery:
+    """Query parameters for listing sandboxes."""
+
+    metadata: Optional[dict[str, str]] = None
+    """Filter sandboxes by metadata."""
+
+
+@dataclass
+class SandboxMetrics:
+    """Sandbox metrics."""
+
+    cpu_count: int
+    """Number of CPUs."""
+    cpu_used_pct: float
+    """CPU usage percentage."""
+    disk_total: int
+    """Total disk space in bytes."""
+    disk_used: int
+    """Disk used in bytes."""
+    mem_total: int
+    """Total memory in bytes."""
+    mem_used: int
+    """Memory used in bytes."""
+    timestamp: datetime
+    """Timestamp of the metric entry."""
+
+
+class SandboxApiBase(ABC):
+    _limits = Limits(
+        max_keepalive_connections=10,
+        max_connections=20,
+        keepalive_expiry=20,
+    )

scalebox/sandbox/signature.py

@@ -0,0 +1,40 @@
+import base64
+import hashlib
+import time
+from typing import Literal, Optional, TypedDict
+
+Operation = Literal["read", "write"]
+
+
+class Signature(TypedDict):
+    signature: str
+    expiration: Optional[int]  # Unix timestamp or None
+
+
+def get_signature(
+    path: str,
+    operation: Operation,
+    user: str,
+    envd_access_token: Optional[str],
+    expiration_in_seconds: Optional[int] = None,
+) -> Signature:
+    """
+    Generate a v1 signature for sandbox file URLs.
+    """
+    if not envd_access_token:
+        raise ValueError("Access token is not set and signature cannot be generated!")
+
+    expiration = (
+        int(time.time()) + expiration_in_seconds if expiration_in_seconds else None
+    )
+
+    raw = (
+        f"{path}:{operation}:{user}:{envd_access_token}"
+        if expiration is None
+        else f"{path}:{operation}:{user}:{envd_access_token}:{expiration}"
+    )
+
+    digest = hashlib.sha256(raw.encode("utf-8")).digest()
+    encoded = base64.b64encode(digest).rstrip(b"=").decode("ascii")
+
+    return {"signature": f"v1_{encoded}", "expiration": expiration}

scalebox/sandbox/utils.py

@@ -0,0 +1,34 @@
+import functools
+from typing import Any, Optional, Type, TypeVar, cast
+
+T = TypeVar("T")
+
+
+class class_method_variant(object):
+    def __init__(self, class_method_name):
+        self.class_method_name = class_method_name
+
+    method: Any
+
+    def __call__(self, method: T) -> T:
+        self.method = method
+        return cast(T, self)
+
+    def __get__(self, obj, objtype: Optional[Type[Any]] = None):
+        @functools.wraps(self.method)
+        def _wrapper(*args, **kwargs):
+            if obj is not None:
+                # Method was called as an instance method, e.g.
+                # instance.method(...)
+                return self.method(obj, *args, **kwargs)
+            elif len(args) > 0 and objtype is not None and isinstance(args[0], objtype):
+                # Method was called as a class method with the instance as the
+                # first argument, e.g. Class.method(instance, ...) which in
+                # Python is the same thing as calling an instance method
+                return self.method(args[0], *args[1:], **kwargs)
+            else:
+                # Method was called as a class method, e.g. Class.method(...)
+                class_method = getattr(objtype, self.class_method_name)
+                return class_method(*args, **kwargs)
+
+        return _wrapper

scalebox/sandbox_async/__init__.py

@@ -0,0 +1 @@
+from .main import AsyncSandbox