loopix-sdk 2.30.0__py3-none-any.whl

loopix/api/client_async/__init__.py

@@ -0,0 +1,74 @@
+import asyncio
+import weakref
+from typing import Dict, Optional, Tuple
+
+import httpx
+
+from httpx._types import ProxyTypes
+
+from loopix.api import AsyncApiClient, connection_retries, limits
+from loopix.connection_config import ConnectionConfig
+
+TransportKey = Tuple[bool, Optional[ProxyTypes]]
+
+
+def get_api_client(config: ConnectionConfig, **kwargs) -> AsyncApiClient:
+    return AsyncApiClient(
+        config,
+        async_transport_factory=lambda: get_transport(config),
+        **kwargs,
+    )
+
+
+class AsyncTransportWithLogger(httpx.AsyncHTTPTransport):
+    # Keyed weakly by the event loop object itself, not id(loop) — CPython
+    # reuses object ids, so a new loop could otherwise inherit a transport
+    # bound to a previous, closed loop.
+    _instances: weakref.WeakKeyDictionary[
+        asyncio.AbstractEventLoop,
+        Dict[TransportKey, "AsyncTransportWithLogger"],
+    ] = weakref.WeakKeyDictionary()
+
+    @property
+    def pool(self):
+        return self._pool
+
+
+def _get_cached_transport(cls, config: ConnectionConfig, http2: bool):
+    loop = asyncio.get_running_loop()
+    loop_instances = cls._instances.get(loop)
+    if loop_instances is None:
+        loop_instances = {}
+        cls._instances[loop] = loop_instances
+
+    key: TransportKey = (http2, config.proxy)
+    transport = loop_instances.get(key)
+    if transport is None:
+        transport = cls(
+            limits=limits,
+            proxy=config.proxy,
+            http2=http2,
+            retries=connection_retries,
+        )
+        loop_instances[key] = transport
+
+    return transport
+
+
+def get_transport(
+    config: ConnectionConfig, http2: bool = True
+) -> AsyncTransportWithLogger:
+    return _get_cached_transport(AsyncTransportWithLogger, config, http2)
+
+
+class AsyncEnvdTransportWithLogger(AsyncTransportWithLogger):
+    _instances: weakref.WeakKeyDictionary[
+        asyncio.AbstractEventLoop,
+        Dict[TransportKey, "AsyncEnvdTransportWithLogger"],
+    ] = weakref.WeakKeyDictionary()
+
+
+def get_envd_transport(
+    config: ConnectionConfig, http2: bool = True
+) -> AsyncEnvdTransportWithLogger:
+    return _get_cached_transport(AsyncEnvdTransportWithLogger, config, http2)

loopix/api/client_sync/__init__.py

@@ -0,0 +1,73 @@
+from typing import Dict, Optional, Tuple
+
+import httpx
+import threading
+
+from httpx._types import ProxyTypes
+
+from loopix.api import ApiClient, connection_retries, limits
+from loopix.connection_config import ConnectionConfig
+
+TransportKey = Tuple[bool, Optional[ProxyTypes]]
+
+
+def get_api_client(config: ConnectionConfig, **kwargs) -> ApiClient:
+    return ApiClient(
+        config,
+        transport_factory=lambda: get_transport(config),
+        **kwargs,
+    )
+
+
+class TransportWithLogger(httpx.HTTPTransport):
+    _thread_local = threading.local()
+
+    @property
+    def pool(self):
+        return self._pool
+
+
+def get_transport(config: ConnectionConfig, http2: bool = True) -> TransportWithLogger:
+    instances: Dict[TransportKey, TransportWithLogger] = getattr(
+        TransportWithLogger._thread_local, "instances", {}
+    )
+    key: TransportKey = (http2, config.proxy)
+    cached = instances.get(key)
+    if cached is not None:
+        return cached
+
+    transport = TransportWithLogger(
+        limits=limits,
+        proxy=config.proxy,
+        http2=http2,
+        retries=connection_retries,
+    )
+    instances[key] = transport
+    TransportWithLogger._thread_local.instances = instances
+    return transport
+
+
+class EnvdTransportWithLogger(TransportWithLogger):
+    _thread_local = threading.local()
+
+
+def get_envd_transport(
+    config: ConnectionConfig, http2: bool = True
+) -> EnvdTransportWithLogger:
+    instances: Dict[TransportKey, EnvdTransportWithLogger] = getattr(
+        EnvdTransportWithLogger._thread_local, "instances", {}
+    )
+    key: TransportKey = (http2, config.proxy)
+    cached = instances.get(key)
+    if cached is not None:
+        return cached
+
+    transport = EnvdTransportWithLogger(
+        limits=limits,
+        proxy=config.proxy,
+        http2=http2,
+        retries=connection_retries,
+    )
+    instances[key] = transport
+    EnvdTransportWithLogger._thread_local.instances = instances
+    return transport

loopix/api/metadata.py

@@ -0,0 +1,14 @@
+import platform
+
+from importlib import metadata
+
+package_version = metadata.version("loopix")
+
+default_headers = {
+    "lang": "python",
+    "lang_version": platform.python_version(),
+    "package_version": metadata.version("loopix"),
+    "publisher": "loopix",
+    "sdk_runtime": "python",
+    "system": platform.system(),
+}

loopix/connection_config.py

@@ -0,0 +1,309 @@
+import logging
+import os
+
+from typing import cast, Optional, Dict, TypedDict
+
+from httpx._types import ProxyTypes
+from typing_extensions import Unpack
+
+from loopix.api.metadata import package_version
+
+REQUEST_TIMEOUT: float = 60.0  # 60 seconds
+
+KEEPALIVE_PING_INTERVAL_SEC = 50  # 50 seconds
+KEEPALIVE_PING_HEADER = "Keepalive-Ping-Interval"
+
+
+class ApiParams(TypedDict, total=False):
+    """
+    Parameters for a request.
+
+    In the case of a sandbox, it applies to all **requests made to the returned sandbox**.
+    """
+
+    request_timeout: Optional[float]
+    """Timeout for the request in **seconds**, defaults to 60 seconds."""
+
+    headers: Optional[Dict[str, str]]
+    """Additional headers to send with the request. Deprecated, use api_headers instead."""
+
+    api_headers: Optional[Dict[str, str]]
+    """Additional headers to send with Loopix API requests."""
+
+    api_key: Optional[str]
+    """Loopix API Key to use for authentication, defaults to `LOOPIX_API_KEY` environment variable."""
+
+    validate_api_key: Optional[bool]
+    """Whether to validate the format of the Loopix API key on the client side.
+    Disable this when your deployment issues API keys that don't match the
+    default `lpx_` format. Defaults to `LOOPIX_VALIDATE_API_KEY` environment
+    variable or `True`."""
+
+    domain: Optional[str]
+    """Loopix domain to use for authentication, defaults to `LOOPIX_DOMAIN` environment variable."""
+
+    api_url: Optional[str]
+    """URL to use for the API, defaults to `https://api.<domain>`. For internal use only."""
+
+    debug: Optional[bool]
+    """Whether to use debug mode, defaults to `LOOPIX_DEBUG` environment variable."""
+
+    proxy: Optional[ProxyTypes]
+    """Proxy to use for the request. In case of a sandbox it applies to all **requests made to the returned sandbox**."""
+
+    sandbox_url: Optional[str]
+    """URL to connect to sandbox, defaults to `LOOPIX_SANDBOX_URL` environment variable."""
+
+
+class ApiParamsWithLogger(ApiParams, total=False):
+    """:class:`ApiParams` plus the construction-time ``logger``.
+
+    Internal type returned by :meth:`ConnectionConfig.get_api_params` so that the
+    logger a sandbox was created/connected with keeps propagating to the
+    throwaway ``ConnectionConfig`` that instance control-plane methods rebuild.
+    Unlike :class:`ApiParams`, ``logger`` is not a public per-request option.
+    """
+
+    logger: Optional[logging.Logger]
+
+
+class ConnectionConfig:
+    """
+    Configuration for the connection to the API.
+    """
+
+    envd_port = 49983
+
+    @staticmethod
+    def _domain():
+        return os.getenv("LOOPIX_DOMAIN") or "vm.betmandu.net"
+
+    @staticmethod
+    def _debug():
+        return os.getenv("LOOPIX_DEBUG", "false").lower() == "true"
+
+    @staticmethod
+    def _api_key():
+        return os.getenv("LOOPIX_API_KEY")
+
+    @staticmethod
+    def _validate_api_key():
+        return os.getenv("LOOPIX_VALIDATE_API_KEY", "true").lower() != "false"
+
+    @staticmethod
+    def _api_url():
+        return os.getenv("LOOPIX_API_URL")
+
+    @staticmethod
+    def _sandbox_url():
+        return os.getenv("LOOPIX_SANDBOX_URL")
+
+    @staticmethod
+    def _access_token():
+        return os.getenv("LOOPIX_ACCESS_TOKEN")
+
+    @staticmethod
+    def _build_user_agent(
+        integration: Optional[str] = None,
+    ) -> str:
+        user_agent_parts = [f"loopix-python-sdk/{package_version}"]
+
+        if integration:
+            user_agent_parts.append(integration)
+
+        return " ".join(user_agent_parts)
+
+    def __init__(
+        self,
+        domain: Optional[str] = None,
+        debug: Optional[bool] = None,
+        api_key: Optional[str] = None,
+        validate_api_key: Optional[bool] = None,
+        api_url: Optional[str] = None,
+        sandbox_url: Optional[str] = None,
+        access_token: Optional[str] = None,
+        request_timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+        api_headers: Optional[Dict[str, str]] = None,
+        integration: Optional[str] = None,
+        extra_sandbox_headers: Optional[Dict[str, str]] = None,
+        proxy: Optional[ProxyTypes] = None,
+        logger: Optional[logging.Logger] = None,
+    ):
+        self.logger = logger
+        self.domain = domain or ConnectionConfig._domain()
+        self.debug = debug if debug is not None else ConnectionConfig._debug()
+        self.api_key = api_key or ConnectionConfig._api_key()
+        self.validate_api_key = (
+            validate_api_key
+            if validate_api_key is not None
+            else ConnectionConfig._validate_api_key()
+        )
+        # Deprecated: pass the token through `api_headers` instead, e.g.
+        # api_headers={"Authorization": f"Bearer {token}"}.
+        self.access_token = access_token or ConnectionConfig._access_token()
+        self.integration = integration
+        self.headers = {**(headers or {}), **(api_headers or {})}
+        if self.integration is not None or "User-Agent" not in self.headers:
+            self.headers["User-Agent"] = self._build_user_agent(
+                self.integration,
+            )
+        self.__extra_sandbox_headers = extra_sandbox_headers or {}
+
+        self.proxy = proxy
+
+        self.request_timeout = ConnectionConfig._get_request_timeout(
+            REQUEST_TIMEOUT,
+            request_timeout,
+        )
+
+        self.api_url = (
+            api_url
+            or ConnectionConfig._api_url()
+            or ("http://localhost:3000" if self.debug else f"https://{self.domain}/api")
+        )
+
+        self._sandbox_url: Optional[str] = (
+            sandbox_url or ConnectionConfig._sandbox_url()
+        )
+
+    @staticmethod
+    def _get_request_timeout(
+        default_timeout: Optional[float],
+        request_timeout: Optional[float],
+    ):
+        if request_timeout == 0:
+            return None
+        elif request_timeout is not None:
+            return request_timeout
+        else:
+            return default_timeout
+
+    def get_request_timeout(self, request_timeout: Optional[float] = None):
+        return self._get_request_timeout(self.request_timeout, request_timeout)
+
+    def get_sandbox_url(self, sandbox_id: str, sandbox_domain: str) -> str:
+        if self._sandbox_url:
+            return self._sandbox_url  # type: ignore[return-value]
+
+        sandbox_domain = sandbox_domain or self.domain
+
+        if self.debug:
+            return f"http://{sandbox_domain}/sandbox/{sandbox_id}"
+
+        return f"https://{sandbox_domain}/sandbox/{sandbox_id}"
+
+    def get_sandbox_direct_url(self, sandbox_id: str, sandbox_domain: str) -> str:
+        if self._sandbox_url:
+            return self._sandbox_url  # type: ignore[return-value]
+
+        sandbox_domain = sandbox_domain or self.domain
+
+        if self.debug:
+            return f"http://{sandbox_domain}/sandbox/{sandbox_id}/{self.envd_port}"
+
+        return f"https://{sandbox_domain}/sandbox/{sandbox_id}/{self.envd_port}"
+
+    def get_host(self, sandbox_id: str, sandbox_domain: str, 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
+        :param sandbox_domain: Domain to connect to
+        :param sandbox_id: Sandbox to connect to
+
+        :return: Host address to connect to
+        """
+        domain = sandbox_domain or self.domain
+
+        if self.debug:
+            return f"localhost:{port}"
+
+        return f"{domain}/sandbox/{sandbox_id}/{port}"
+
+    def get_api_params(
+        self,
+        **opts: Unpack[ApiParams],
+    ) -> dict:
+        """
+        Get the parameters for the API call.
+
+        This is used to avoid passing the following attributes to the API call:
+        - access_token
+        - api_url
+
+        It also returns a copy, so the original object is not modified.
+
+        :return: Dictionary of parameters for the API call
+        """
+        headers = opts.get("headers")
+        api_headers = opts.get("api_headers")
+        request_timeout = opts.get("request_timeout")
+        api_key = opts.get("api_key")
+        validate_api_key = opts.get("validate_api_key")
+        api_url = opts.get("api_url")
+        domain = opts.get("domain")
+        debug = opts.get("debug")
+        proxy = opts.get("proxy")
+        sandbox_url = opts.get("sandbox_url")
+
+        req_headers = self.headers.copy()
+        if headers is not None:
+            req_headers.update(headers)
+        if api_headers is not None:
+            req_headers.update(api_headers)
+        if self.integration is not None:
+            req_headers["User-Agent"] = self._build_user_agent(
+                self.integration,
+            )
+
+        # `logger` is a construction-time option rather than a per-request
+        # ApiParams field, but it must propagate to the throwaway
+        # ConnectionConfig that instance control-plane methods (kill, pause,
+        # set_timeout, get_info, connect, ...) rebuild from these params, so
+        # those requests keep logging with the logger the sandbox was created
+        # or connected with.
+        return dict(
+            ApiParamsWithLogger(
+                api_key=api_key if api_key is not None else self.api_key,
+                validate_api_key=(
+                    validate_api_key
+                    if validate_api_key is not None
+                    else self.validate_api_key
+                ),
+                api_url=api_url if api_url is not None else self.api_url,
+                domain=domain if domain is not None else self.domain,
+                debug=debug if debug is not None else self.debug,
+                request_timeout=self.get_request_timeout(request_timeout),
+                headers=req_headers,
+                proxy=proxy if proxy is not None else self.proxy,
+                sandbox_url=(
+                    sandbox_url
+                    if sandbox_url is not None
+                    else cast(Optional[str], self._sandbox_url)
+                ),
+                logger=self.logger,
+            )
+        )
+
+    @property
+    def sandbox_headers(self):
+        """
+        We need this separate as we use the same header for Loopix access token to API and envd access token to sandbox.
+        """
+        return {
+            "User-Agent": self.headers["User-Agent"],
+            **self.__extra_sandbox_headers,
+        }
+
+
+Username = str
+"""
+User used for the operation in the sandbox.
+"""
+
+default_username: Username = "user"
+"""
+Default user used for the operation in the sandbox.
+"""

loopix/envd/api.py

@@ -0,0 +1,170 @@
+import httpx
+import json
+
+from typing import Callable, Optional
+
+from loopix.envd.rpc import format_terminated_exception
+from loopix.exceptions import (
+    SandboxException,
+    NotFoundException,
+    AuthenticationException,
+    InvalidArgumentException,
+    NotEnoughSpaceException,
+    RateLimitException,
+    format_sandbox_timeout_exception,
+)
+
+
+ENVD_API_FILES_ROUTE = "/files"
+ENVD_API_HEALTH_ROUTE = "/health"
+
+_DEFAULT_API_ERROR_MAP: dict[int, Callable[[str], Exception]] = {
+    400: InvalidArgumentException,
+    401: AuthenticationException,
+    404: NotFoundException,
+    429: lambda message: RateLimitException(
+        f"{message}: The requests are being rate limited."
+    ),
+    502: format_sandbox_timeout_exception,
+    507: NotEnoughSpaceException,
+}
+
+
+HEALTH_CHECK_TIMEOUT = 5  # seconds
+
+
+def check_sandbox_health(envd_api: httpx.Client) -> Optional[bool]:
+    """Probe the sandbox's envd health endpoint.
+
+    :return: ``True`` if the sandbox is running, ``False`` if it is not, ``None`` if its state could not be determined.
+    """
+    try:
+        r = envd_api.get(ENVD_API_HEALTH_ROUTE, timeout=HEALTH_CHECK_TIMEOUT)
+        if r.status_code == 502:
+            return False
+        if r.is_success:
+            return True
+        return None
+    except Exception:
+        return None
+
+
+async def acheck_sandbox_health(envd_api: httpx.AsyncClient) -> Optional[bool]:
+    """Async version of :func:`check_sandbox_health`."""
+    try:
+        r = await envd_api.get(ENVD_API_HEALTH_ROUTE, timeout=HEALTH_CHECK_TIMEOUT)
+        if r.status_code == 502:
+            return False
+        if r.is_success:
+            return True
+        return None
+    except Exception:
+        return None
+
+
+def handle_envd_api_transport_exception(
+    e: Exception,
+    sandbox_running: Optional[bool] = None,
+) -> Exception:
+    """Handle transport-level errors from envd API requests.
+
+    :param e: The caught exception, expected to be a transport-level ``httpx`` error.
+    :param sandbox_running: Result of a sandbox health probe (``None`` when unknown), used to disambiguate a connection dropped mid-request.
+    :return: A ``TimeoutException`` when the connection dropped mid-request and the sandbox is confirmed gone, or the original exception unchanged otherwise.
+    """
+    # 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, httpx.RemoteProtocolError):
+        return format_terminated_exception(e, sandbox_running)
+
+    return e
+
+
+def handle_envd_api_transport_exception_with_health(
+    e: Exception,
+    envd_api: httpx.Client,
+) -> Exception:
+    """Like :func:`handle_envd_api_transport_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 = (
+        check_sandbox_health(envd_api)
+        if isinstance(e, httpx.RemoteProtocolError)
+        else None
+    )
+    return handle_envd_api_transport_exception(e, sandbox_running)
+
+
+async def ahandle_envd_api_transport_exception_with_health(
+    e: Exception,
+    envd_api: httpx.AsyncClient,
+) -> Exception:
+    """Async version of :func:`handle_envd_api_transport_exception_with_health`."""
+    sandbox_running = (
+        await acheck_sandbox_health(envd_api)
+        if isinstance(e, httpx.RemoteProtocolError)
+        else None
+    )
+    return handle_envd_api_transport_exception(e, sandbox_running)
+
+
+def get_message(e: httpx.Response) -> str:
+    try:
+        message = e.json().get("message", e.text)
+    except json.JSONDecodeError:
+        message = e.text
+
+    return message
+
+
+def handle_envd_api_exception(
+    res: httpx.Response,
+    error_map: Optional[dict[int, Callable[[str], Exception]]] = None,
+):
+    """Handle errors from envd API responses by mapping HTTP status codes to specific exception types.
+
+    :param res: The HTTP response.
+    :param error_map: Optional map of HTTP status codes to exception factories that override the defaults.
+    :return: The corresponding exception, or ``None`` if the response is successful.
+    """
+    if res.is_success:
+        return
+
+    res.read()
+
+    return format_envd_api_exception(res.status_code, get_message(res), error_map)
+
+
+async def ahandle_envd_api_exception(
+    res: httpx.Response,
+    error_map: Optional[dict[int, Callable[[str], Exception]]] = None,
+):
+    """Async version of :func:`handle_envd_api_exception`."""
+    if res.is_success:
+        return
+
+    await res.aread()
+
+    return format_envd_api_exception(res.status_code, get_message(res), error_map)
+
+
+def format_envd_api_exception(
+    status_code: int,
+    message: str,
+    error_map: Optional[dict[int, Callable[[str], Exception]]] = None,
+):
+    """Map an HTTP status code and message to the appropriate exception.
+
+    :param status_code: The HTTP status code.
+    :param message: The error message from the response body.
+    :param error_map: Optional map of HTTP status codes to exception factories that override the defaults.
+    :return: The corresponding exception.
+    """
+    if error_map and status_code in error_map:
+        return error_map[status_code](message)
+
+    if status_code in _DEFAULT_API_ERROR_MAP:
+        return _DEFAULT_API_ERROR_MAP[status_code](message)
+
+    return SandboxException(f"{status_code}: {message}")