loopix-sdk 2.30.0__py3-none-any.whl

loopix/envd/rpc.py

@@ -0,0 +1,139 @@
+import base64
+
+import httpcore
+from typing import Awaitable, Callable, Optional
+from packaging.version import Version
+from loopix_connect.client import Code, ConnectException
+
+from loopix.exceptions import (
+    SandboxException,
+    InvalidArgumentException,
+    NotFoundException,
+    TimeoutException,
+    format_sandbox_timeout_exception,
+    AuthenticationException,
+    RateLimitException,
+)
+from loopix.connection_config import Username, default_username
+from loopix.envd.versions import ENVD_DEFAULT_USER
+
+_DEFAULT_RPC_ERROR_MAP: dict[Code, Callable[[str], Exception]] = {
+    Code.invalid_argument: InvalidArgumentException,
+    Code.unauthenticated: AuthenticationException,
+    Code.not_found: NotFoundException,
+    Code.unavailable: format_sandbox_timeout_exception,
+    Code.resource_exhausted: lambda message: RateLimitException(
+        f"{message}: Rate limit exceeded, please try again later."
+    ),
+    Code.canceled: lambda message: TimeoutException(
+        f"{message}: This error is likely due to exceeding 'request_timeout'. You can pass the request timeout value as an option when making the request."
+    ),
+    Code.deadline_exceeded: lambda message: TimeoutException(
+        f"{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."
+    ),
+}
+
+
+def format_terminated_exception(
+    e: Exception,
+    sandbox_running: Optional[bool],
+) -> Exception:
+    """Handle an exception for a connection to the sandbox dropped mid-request: when a
+    sandbox health probe confirmed the sandbox is gone (``sandbox_running is False``),
+    return a ``TimeoutException``; otherwise return the original error unchanged."""
+    if sandbox_running is False:
+        return TimeoutException(
+            f"{e}: The sandbox was killed or reached its end of life while the request was in flight."
+        )
+    return e
+
+
+def handle_rpc_exception(
+    e: Exception,
+    error_map: Optional[dict[Code, Callable[[str], Exception]]] = None,
+    sandbox_running: Optional[bool] = None,
+):
+    """Handle errors from envd RPC calls by mapping gRPC status codes to specific exception types.
+
+    :param e: The caught exception, expected to be a ``ConnectException`` or a transport-level ``httpcore`` error.
+    :param error_map: Optional map of gRPC codes to exception factories that override the defaults.
+    :param sandbox_running: Result of a sandbox health probe (``None`` when unknown), used to disambiguate a connection dropped mid-request.
+    :return: The corresponding exception. A connection dropped mid-request with the sandbox confirmed gone becomes a ``TimeoutException``; non-``ConnectException`` errors are otherwise returned as-is.
+    """
+    if isinstance(e, ConnectException):
+        if error_map and e.status in error_map:
+            return error_map[e.status](e.message)
+
+        if e.status in _DEFAULT_RPC_ERROR_MAP:
+            return _DEFAULT_RPC_ERROR_MAP[e.status](e.message)
+
+        return SandboxException(f"{e.status}: {e.message}")
+
+    # A remote protocol error (e.g. an HTTP/2 stream reset) means the connection to the
+    # sandbox was dropped mid-request — either the sandbox died or the network failed
+    if isinstance(e, httpcore.RemoteProtocolError):
+        return format_terminated_exception(e, sandbox_running)
+
+    # A transport-level timeout from httpcore means a configured timeout was exceeded
+    # before the server responded: `request_timeout` on a unary call's read phase, or
+    # `connect`/`pool`/`write` on a stream's setup/send phase. Streams have no read
+    # timeout — the command `timeout` is enforced server-side and surfaces as a
+    # `deadline_exceeded` ConnectException instead. Unlike the JS SDK, where the
+    # request timeout is an `AbortSignal` that connect normalizes into a `Code.canceled`
+    # ConnectError, httpcore raises this raw transport error outside the ConnectException
+    # path, so we map it here to a `TimeoutException` for a consistent timeout error.
+    if isinstance(e, httpcore.TimeoutException):
+        return TimeoutException(
+            f"{e}: This error is likely due to exceeding 'timeout' — the total time a long running request (like process or directory watch) can be active — or 'request_timeout'. You can modify these by passing 'timeout' or 'request_timeout' when making the request. Use '0' to disable the timeout."
+        )
+
+    return e
+
+
+def handle_rpc_exception_with_health(
+    e: Exception,
+    check_health: Optional[Callable[[], Optional[bool]]] = None,
+    error_map: Optional[dict[Code, Callable[[str], Exception]]] = None,
+):
+    """Like :func:`handle_rpc_exception`, but when the connection to the sandbox was
+    dropped mid-request it probes the sandbox health to tell apart the sandbox being
+    killed from a transient network failure (e.g. a load balancer dropping the connection).
+    """
+    sandbox_running = None
+    if check_health is not None and isinstance(e, httpcore.RemoteProtocolError):
+        try:
+            sandbox_running = check_health()
+        except Exception:
+            sandbox_running = None
+    return handle_rpc_exception(e, error_map, sandbox_running)
+
+
+async def ahandle_rpc_exception_with_health(
+    e: Exception,
+    check_health: Optional[Callable[[], Awaitable[Optional[bool]]]] = None,
+    error_map: Optional[dict[Code, Callable[[str], Exception]]] = None,
+):
+    """Async version of :func:`handle_rpc_exception_with_health`."""
+    sandbox_running = None
+    if check_health is not None and isinstance(e, httpcore.RemoteProtocolError):
+        try:
+            sandbox_running = await check_health()
+        except Exception:
+            sandbox_running = None
+    return handle_rpc_exception(e, error_map, sandbox_running)
+
+
+def authentication_header(
+    envd_version: Version, user: Optional[Username] = None
+) -> dict[str, str]:
+    if user is None and envd_version < ENVD_DEFAULT_USER:
+        user = default_username
+
+    if not user:
+        return {}
+
+    value = f"{user}:"
+
+    encoded = base64.b64encode(value.encode("utf-8")).decode("utf-8")
+
+    return {"Authorization": f"Basic {encoded}"}

loopix/envd/versions.py

@@ -0,0 +1,11 @@
+from packaging.version import Version
+
+ENVD_VERSION_RECURSIVE_WATCH = Version("0.1.4")
+ENVD_DEBUG_FALLBACK = Version("99.99.99")
+ENVD_COMMANDS_STDIN = Version("0.3.0")
+ENVD_DEFAULT_USER = Version("0.4.0")
+ENVD_ENVD_CLOSE = Version("0.5.2")
+ENVD_OCTET_STREAM_UPLOAD = Version("0.5.7")
+ENVD_FILE_METADATA = Version("0.6.2")
+ENVD_VERSION_FS_EVENT_ENTRY_INFO = Version("0.6.3")
+ENVD_VERSION_WATCH_NETWORK_MOUNTS = Version("0.6.4")

loopix/exceptions.py

@@ -0,0 +1,133 @@
+def format_sandbox_timeout_exception(message: str):
+    return TimeoutException(
+        f"{message}: This error is likely due to sandbox timeout. You can modify the sandbox timeout by passing 'timeout' when starting the sandbox or calling '.set_timeout' on the sandbox with the desired timeout."
+    )
+
+
+def format_request_timeout_error() -> Exception:
+    return TimeoutException(
+        "Request timed out — the 'request_timeout' option can be used to increase this timeout",
+    )
+
+
+class SandboxException(Exception):
+    """
+    Base class for all sandbox errors.
+
+    Raised when a general sandbox exception occurs.
+    """
+
+    pass
+
+
+class TimeoutException(SandboxException):
+    """
+    Raised when a timeout occurs.
+
+    The `unavailable` exception type is caused by sandbox timeout.\n
+    The `canceled` exception type is caused by exceeding request timeout.\n
+    The `deadline_exceeded` exception type is caused by exceeding the timeout for process, watch, etc.\n
+    The `unknown` exception type is sometimes caused by the sandbox timeout when the request is not processed correctly.\n
+    """
+
+    pass
+
+
+class InvalidArgumentException(SandboxException):
+    """
+    Raised when an invalid argument is provided.
+    """
+
+    pass
+
+
+class NotEnoughSpaceException(SandboxException):
+    """
+    Raised when there is not enough disk space.
+    """
+
+    pass
+
+
+class NotFoundException(SandboxException):
+    """
+    Raised when a resource is not found.
+
+    .. deprecated::
+        Use :class:`FileNotFoundException` or :class:`SandboxNotFoundException` instead.
+        This class will be removed in the next major version.
+    """
+
+    pass
+
+
+class FileNotFoundException(NotFoundException):
+    """
+    Raised when a file or directory is not found inside a sandbox.
+    """
+
+    pass
+
+
+class SandboxNotFoundException(NotFoundException):
+    """
+    Raised when a sandbox is not found (e.g. it doesn't exist or is no longer running).
+    """
+
+    pass
+
+
+class AuthenticationException(Exception):
+    """
+    Raised when authentication fails.
+    """
+
+    pass
+
+
+class GitAuthException(AuthenticationException):
+    """
+    Raised when git authentication fails.
+    """
+
+    pass
+
+
+class GitUpstreamException(SandboxException):
+    """
+    Raised when git upstream tracking is missing.
+    """
+
+    pass
+
+
+class TemplateException(SandboxException):
+    """
+    Exception raised when the template uses old envd version. It isn't compatible with the new SDK.
+    """
+
+
+class RateLimitException(SandboxException):
+    """
+    Raised when the API rate limit is exceeded.
+    """
+
+
+class BuildException(Exception):
+    """
+    Raised when the build fails.
+    """
+
+
+class FileUploadException(BuildException):
+    """
+    Raised when the file upload fails.
+    """
+
+
+class VolumeException(Exception):
+    """
+    Base class for all volume errors.
+
+    Raised when general volume errors occur.
+    """

loopix/io_utils.py

@@ -0,0 +1,57 @@
+import asyncio
+import zlib
+from typing import IO, AsyncIterable, AsyncIterator, Iterable, Iterator
+
+IO_CHUNK_SIZE = 65_536
+
+
+def iter_io_chunks(data: IO) -> Iterator[bytes]:
+    """Read a file-like object in chunks, encoding text chunks to UTF-8."""
+    while True:
+        chunk = data.read(IO_CHUNK_SIZE)
+        if not chunk:
+            break
+        yield chunk if isinstance(chunk, bytes) else chunk.encode("utf-8")
+
+
+async def aiter_io_chunks(data: IO) -> AsyncIterator[bytes]:
+    """Read a file-like object in chunks, encoding text chunks to UTF-8.
+
+    `data.read` is a synchronous (potentially disk-blocking) call, so it runs in
+    a worker thread to avoid stalling the event loop during large uploads.
+    """
+    while True:
+        chunk = await asyncio.to_thread(data.read, IO_CHUNK_SIZE)
+        if not chunk:
+            break
+        yield chunk if isinstance(chunk, bytes) else chunk.encode("utf-8")
+
+
+def _gzip_compressor():
+    # wbits > 16 makes zlib produce a gzip-formatted stream.
+    return zlib.compressobj(wbits=zlib.MAX_WBITS | 16)
+
+
+def gzip_iter(chunks: Iterable[bytes]) -> Iterator[bytes]:
+    """Gzip-compress a byte stream chunk by chunk."""
+    compressor = _gzip_compressor()
+    for chunk in chunks:
+        compressed = compressor.compress(chunk)
+        if compressed:
+            yield compressed
+    yield compressor.flush()
+
+
+async def agzip_iter(chunks: AsyncIterable[bytes]) -> AsyncIterator[bytes]:
+    """Gzip-compress a byte stream chunk by chunk.
+
+    Compression is CPU-bound, so it runs in a worker thread to avoid stalling
+    the event loop during large uploads (zlib releases the GIL while
+    compressing, so the offload genuinely overlaps with the loop).
+    """
+    compressor = _gzip_compressor()
+    async for chunk in chunks:
+        compressed = await asyncio.to_thread(compressor.compress, chunk)
+        if compressed:
+            yield compressed
+    yield await asyncio.to_thread(compressor.flush)

loopix/paginator.py

@@ -0,0 +1,52 @@
+from typing import Generic, Mapping, Optional, TypeVar
+
+from typing_extensions import Unpack
+
+from loopix.connection_config import ApiParams
+
+T = TypeVar("T")
+OptsT = TypeVar("OptsT", bound=ApiParams)
+
+
+class PaginatorBase(Generic[T, OptsT]):
+    """
+    Shared pagination state for cursor-based list endpoints.
+
+    Owns the `has_next` / `next_token` state and the reading of the
+    `x-next-token` response header (via `_update_pagination`). Each concrete
+    paginator implements `next_items` to do the actual fetching for its
+    endpoint, so any model can expose pagination by subclassing this without
+    reimplementing the bookkeeping.
+
+    `T` is the item type returned by `next_items`; `OptsT` is the connection
+    options type accepted by the paginator (an `ApiParams`-compatible TypedDict).
+    """
+
+    def __init__(
+        self,
+        limit: Optional[int] = None,
+        next_token: Optional[str] = None,
+        **opts: Unpack[OptsT],
+    ):
+        self._opts: OptsT = opts
+        self.limit = limit
+        self._has_next = True
+        self._next_token = next_token
+
+    @property
+    def has_next(self) -> bool:
+        """
+        Returns True if there are more items to fetch.
+        """
+        return self._has_next
+
+    @property
+    def next_token(self) -> Optional[str]:
+        """
+        Returns the next token to use for pagination.
+        """
+        return self._next_token
+
+    def _update_pagination(self, headers: Mapping[str, str]) -> None:
+        self._next_token = headers.get("x-next-token")
+        self._has_next = bool(self._next_token)

loopix/sandbox/_git/__init__.py

@@ -0,0 +1,85 @@
+from loopix.sandbox._git.args import (
+    build_add_args,
+    build_branches_args,
+    build_checkout_branch_args,
+    build_clone_plan,
+    build_commit_args,
+    build_credential_approve_command,
+    build_create_branch_args,
+    build_delete_branch_args,
+    build_git_command,
+    build_has_upstream_args,
+    build_pull_args,
+    build_push_args,
+    build_remote_add_args,
+    build_remote_add_shell_command,
+    build_remote_get_command,
+    build_remote_get_url_args,
+    build_remote_set_url_args,
+    build_reset_args,
+    build_restore_args,
+    build_status_args,
+    shell_escape,
+)
+from loopix.sandbox._git.auth import (
+    build_auth_error_message,
+    build_upstream_error_message,
+    is_auth_failure,
+    is_missing_upstream,
+    strip_credentials,
+    with_credentials,
+)
+from loopix.sandbox._git.config import resolve_config_scope
+from loopix.sandbox._git.parse import (
+    derive_repo_dir_from_url,
+    parse_git_branches,
+    parse_git_status,
+    parse_remote_url,
+)
+from loopix.sandbox._git.types import (
+    ClonePlan,
+    GitBranches,
+    GitFileStatus,
+    GitResetMode,
+    GitStatus,
+)
+
+__all__ = [
+    "build_add_args",
+    "build_auth_error_message",
+    "build_branches_args",
+    "build_checkout_branch_args",
+    "build_clone_plan",
+    "build_commit_args",
+    "build_credential_approve_command",
+    "build_create_branch_args",
+    "build_delete_branch_args",
+    "build_git_command",
+    "build_has_upstream_args",
+    "build_pull_args",
+    "build_push_args",
+    "build_remote_add_args",
+    "build_remote_add_shell_command",
+    "build_remote_get_command",
+    "build_remote_get_url_args",
+    "build_remote_set_url_args",
+    "build_reset_args",
+    "build_restore_args",
+    "build_status_args",
+    "build_upstream_error_message",
+    "derive_repo_dir_from_url",
+    "is_auth_failure",
+    "is_missing_upstream",
+    "parse_git_branches",
+    "parse_git_status",
+    "parse_remote_url",
+    "resolve_config_scope",
+    "shell_escape",
+    "strip_credentials",
+    "with_credentials",
+    "ClonePlan",
+    "GitBranches",
+    "GitFileStatus",
+    "GitResetMode",
+    "GitStatus",
+]