boxfab 0.1.0a1__py3-none-any.whl

boxfab/__init__.py

@@ -0,0 +1,331 @@
+"""
+Secure sandboxed cloud environments made for AI agents and AI apps.
+
+Check docs [here](https://e2b.dev/docs).
+
+E2B Sandbox is a secure cloud sandbox environment made for AI agents and AI
+apps.
+Sandboxes allow AI agents and apps to have long running cloud secure environments.
+In these environments, large language models can use the same tools as humans do.
+
+E2B Python SDK supports both sync and async API:
+
+```py
+from boxfab import Sandbox
+
+# Create sandbox
+sandbox = Sandbox.create()
+```
+
+```py
+from boxfab import AsyncSandbox
+
+# Create sandbox
+sandbox = await AsyncSandbox.create()
+```
+"""
+
+from .api import (
+    ApiClient,
+    client,
+)
+from .connection_config import (
+    ApiParams,
+    ConnectionConfig,
+    HttpVersion,
+    ProxyTypes,
+    Username,
+)
+from .volume.connection_config import VolumeApiParams, VolumeConnectionConfig
+from .exceptions import (
+    AuthenticationException,
+    FileNotFoundException,
+    GitAuthException,
+    GitUpstreamException,
+    BuildException,
+    FileUploadException,
+    InvalidArgumentException,
+    NotEnoughSpaceException,
+    NotFoundException,
+    RateLimitException,
+    ServiceBusyException,
+    SandboxException,
+    SandboxNotFoundException,
+    SandboxNotRunningException,
+    SandboxUnreachableException,
+    TemplateException,
+    TimeoutException,
+    VolumeException,
+    VolumeNotFoundException,
+    VolumePathNotFoundException,
+    SecretException,
+    SecretNotFoundException,
+)
+from .sandbox.commands.command_handle import (
+    CommandExitException,
+    CommandResult,
+    PtyOutput,
+    PtySize,
+    Stderr,
+    Stdout,
+)
+from .sandbox.commands.main import ProcessInfo
+from .sandbox.filesystem.filesystem import (
+    AsyncWriteData,
+    EntryInfo,
+    FileType,
+    WriteData,
+    WriteInfo,
+)
+from .sandbox.filesystem.watch_handle import (
+    FilesystemEvent,
+    FilesystemEventType,
+)
+from .sandbox._git import GitBranches, GitFileStatus, GitResetMode, GitStatus
+from .sandbox_sync.git import Git
+from .sandbox.network import ALL_TRAFFIC
+from .sandbox.signature import get_signature
+from .sandbox.sandbox_api import (
+    GitHubMcpServer,
+    GitHubMcpServerConfig,
+    McpServer,
+    SandboxEgressProxyInfo,
+    SandboxEgressProxyOpts,
+    SandboxEgressProxyTLSInfo,
+    SandboxEgressProxyTLSOpts,
+    SandboxIamOpts,
+    SandboxIamToken,
+    SandboxIamTokenType,
+    SandboxInfo,
+    SandboxInfoLifecycle,
+    SandboxMetrics,
+    SandboxLifecycle,
+    SandboxOnTimeout,
+    SandboxNetworkInfo,
+    SandboxNetworkOpts,
+    SandboxNetworkRule,
+    SandboxNetworkRuleInfo,
+    SandboxNetworkRules,
+    SandboxNetworkSelector,
+    SandboxNetworkSelectorContext,
+    SandboxNetworkTransform,
+    SandboxNetworkTransformContext,
+    SandboxNetworkTransformResolver,
+    SandboxNetworkUpdate,
+    SandboxOnResume,
+    SandboxListOrder,
+    SandboxQuery,
+    SandboxState,
+    SnapshotInfo,
+    SnapshotMode,
+)
+from .sandbox_async.commands.command_handle import AsyncCommandHandle
+from .sandbox_async.commands.command_input_handle import AsyncCommandInputHandle
+from .sandbox_async.filesystem.watch_handle import AsyncWatchHandle
+from .sandbox_async.main import AsyncSandbox
+from .sandbox_async.paginator import AsyncSandboxPaginator, AsyncSnapshotPaginator
+from .sandbox_async.utils import OutputHandler
+from .secret import (
+    AsyncSecret,
+    AsyncSecretPaginator,
+    Secret,
+    SecretInfo,
+    SecretPaginator,
+)
+from .sandbox_sync.commands.command_handle import CommandHandle
+from .sandbox_sync.filesystem.watch_handle import WatchHandle
+from .sandbox_sync.main import Sandbox
+from .sandbox_sync.paginator import SandboxPaginator, SnapshotPaginator
+from .template.logger import (
+    LogEntry,
+    LogEntryEnd,
+    LogEntryLevel,
+    LogEntryStart,
+    default_build_logger,
+)
+from .template.dockerfile_parser import DockerfileSyntaxError
+from .template.main import TemplateBase, TemplateClass
+from .template.readycmd import (
+    ReadyCmd,
+    wait_for_file,
+    wait_for_port,
+    wait_for_process,
+    wait_for_timeout,
+    wait_for_url,
+)
+from .template.types import (
+    BuildInfo,
+    BuildStatusReason,
+    CopyItem,
+    TemplateBuildStatus,
+    TemplateBuildStatusResponse,
+    TemplateTag,
+    TemplateTagInfo,
+)
+from .template_async.main import AsyncTemplate
+from .template_sync.main import Template
+
+from .volume.volume_sync import Volume
+from .volume.volume_async import AsyncVolume
+from .client import BoxFab, BoxFabClientParams, E2B, E2BClientParams
+from .volume.types import (
+    VolumeInfo,
+    VolumeAndToken,
+    VolumeEntryStat,
+    VolumeFileType,
+)
+
+__all__ = [
+    # Client
+    "BoxFab",
+    "BoxFabClientParams",
+    "E2B",
+    "E2BClientParams",
+    # API
+    "ApiClient",
+    "client",
+    # Connection config
+    "ConnectionConfig",
+    "VolumeConnectionConfig",
+    "HttpVersion",
+    "ProxyTypes",
+    "ApiParams",
+    "VolumeApiParams",
+    "Username",
+    # Exceptions
+    "SandboxException",
+    "ServiceBusyException",
+    "TimeoutException",
+    "NotFoundException",
+    "FileNotFoundException",
+    "SandboxNotFoundException",
+    "SandboxNotRunningException",
+    "SandboxUnreachableException",
+    "AuthenticationException",
+    "GitAuthException",
+    "GitUpstreamException",
+    "InvalidArgumentException",
+    "NotEnoughSpaceException",
+    "TemplateException",
+    "DockerfileSyntaxError",
+    "BuildException",
+    "FileUploadException",
+    "RateLimitException",
+    "VolumeException",
+    "VolumeNotFoundException",
+    "VolumePathNotFoundException",
+    # Sandbox API
+    "SandboxInfo",
+    "SandboxInfoLifecycle",
+    "SandboxMetrics",
+    "ProcessInfo",
+    "SandboxListOrder",
+    "SandboxQuery",
+    "SandboxState",
+    "SandboxMetrics",
+    "GitStatus",
+    "GitBranches",
+    "GitFileStatus",
+    "GitResetMode",
+    # Command handle
+    "CommandResult",
+    "Stderr",
+    "Stdout",
+    "CommandExitException",
+    "PtyOutput",
+    "PtySize",
+    # Filesystem
+    "FilesystemEvent",
+    "FilesystemEventType",
+    "EntryInfo",
+    "WriteInfo",
+    "WriteData",
+    "AsyncWriteData",
+    "FileType",
+    # Network
+    "SandboxEgressProxyOpts",
+    "SandboxEgressProxyInfo",
+    "SandboxEgressProxyTLSOpts",
+    "SandboxEgressProxyTLSInfo",
+    "SandboxNetworkOpts",
+    "SandboxNetworkInfo",
+    "SandboxNetworkSelector",
+    "SandboxNetworkSelectorContext",
+    "SandboxNetworkRule",
+    "SandboxNetworkRuleInfo",
+    "SandboxNetworkRules",
+    "SandboxNetworkTransform",
+    "SandboxNetworkTransformContext",
+    "SandboxNetworkTransformResolver",
+    "SandboxNetworkUpdate",
+    "SandboxLifecycle",
+    "SandboxOnTimeout",
+    "SandboxOnResume",
+    "ALL_TRAFFIC",
+    # IAM
+    "SandboxIamOpts",
+    "SandboxIamToken",
+    "SandboxIamTokenType",
+    "Secret",
+    "AsyncSecret",
+    "SecretInfo",
+    "SecretPaginator",
+    "AsyncSecretPaginator",
+    "SecretException",
+    "SecretNotFoundException",
+    # Snapshot
+    "SnapshotInfo",
+    "SnapshotMode",
+    "SnapshotPaginator",
+    "AsyncSnapshotPaginator",
+    # Signature
+    "get_signature",
+    # Sync sandbox
+    "Sandbox",
+    "SandboxPaginator",
+    "WatchHandle",
+    "CommandHandle",
+    # Async sandbox
+    "OutputHandler",
+    "AsyncSandboxPaginator",
+    "AsyncSandbox",
+    "AsyncWatchHandle",
+    "AsyncCommandHandle",
+    "AsyncCommandInputHandle",
+    # Template
+    "Template",
+    "AsyncTemplate",
+    "TemplateBase",
+    "TemplateClass",
+    "CopyItem",
+    "BuildInfo",
+    "BuildStatusReason",
+    "TemplateBuildStatus",
+    "TemplateBuildStatusResponse",
+    "TemplateTag",
+    "TemplateTagInfo",
+    "ReadyCmd",
+    "wait_for_file",
+    "wait_for_url",
+    "wait_for_port",
+    "wait_for_process",
+    "wait_for_timeout",
+    "LogEntry",
+    "LogEntryStart",
+    "LogEntryEnd",
+    "LogEntryLevel",
+    "default_build_logger",
+    # MCP
+    "McpServer",
+    "GitHubMcpServer",
+    "GitHubMcpServerConfig",
+    # Git
+    "Git",
+    # Volume
+    "Volume",
+    "AsyncVolume",
+    "VolumeInfo",
+    "VolumeAndToken",
+    "VolumeEntryStat",
+    "VolumeFileType",
+]

boxfab/api/__init__.py

@@ -0,0 +1,301 @@
+import json
+import logging
+import os
+from dataclasses import dataclass
+from types import TracebackType
+from typing import (
+    NamedTuple,
+    Optional,
+    Protocol,
+    Tuple,
+    Union,
+)
+from urllib.parse import quote
+
+import httpx
+from httpx import AsyncBaseTransport, BaseTransport, Timeout
+from pyqwest import Proxy
+
+from boxfab.api.client.client import AuthenticatedClient
+from boxfab.api.client.types import Response
+from boxfab.api.metadata import default_headers
+from boxfab.connection_config import ConnectionConfig, ProxyTypes
+from boxfab.exceptions import (
+    AuthenticationException,
+    InvalidArgumentException,
+    RateLimitException,
+    ServiceBusyException,
+    SandboxException,
+)
+
+
+def encode_path_param(value: str) -> str:
+    """
+    Percent-encode a template ID, name, or alias for use as one URL path segment.
+
+    Endpoints that take a template ID also accept a name, which may be
+    namespaced (``namespace/name``) and carry a ``:tag``. Escaping those
+    separators keeps the value inside a single segment instead of splitting the
+    route, matching the JS SDK's ``encodeURIComponent``.
+    """
+    return quote(value, safe="")
+
+
+def make_logging_event_hooks(log: Optional[logging.Logger]) -> dict:
+    """Build synchronous httpx ``event_hooks`` that log requests and responses
+    to the given ``logging.Logger``. Requests log at ``INFO``, successful
+    responses at ``INFO`` and responses with status >= 400 at ``ERROR``.
+
+    Returns no hooks when ``log`` is ``None`` so that nothing is logged unless a
+    logger was explicitly supplied."""
+    if log is None:
+        return {}
+
+    def on_request(request) -> None:
+        log.info(f"Request {request.method} {request.url}")
+
+    def on_response(response: Response) -> None:
+        if response.status_code >= 400:
+            log.error(f"Response {response.status_code}")
+        else:
+            log.info(f"Response {response.status_code}")
+
+    return {"request": [on_request], "response": [on_response]}
+
+
+def make_async_logging_event_hooks(log: Optional[logging.Logger]) -> dict:
+    """Asynchronous counterpart of :func:`make_logging_event_hooks`."""
+    if log is None:
+        return {}
+
+    async def on_request(request) -> None:
+        log.info(f"Request {request.method} {request.url}")
+
+    async def on_response(response: Response) -> None:
+        if response.status_code >= 400:
+            log.error(f"Response {response.status_code}")
+        else:
+            log.info(f"Response {response.status_code}")
+
+    return {"request": [on_request], "response": [on_response]}
+
+
+connection_retries = int(os.getenv("BOXFAB_CONNECTION_RETRIES") or "3")
+
+# Pool tuning for the pyqwest transports, shared by the REST API, envd RPC,
+# and envd HTTP API stacks. `pool_max_idle_per_host` is per host rather than
+# the global idle cap the httpx transports took, which suits both: API traffic
+# goes to a single host and each sandbox is its own host.
+pool_idle_timeout = float(os.getenv("BOXFAB_KEEPALIVE_EXPIRY") or "300")
+pool_max_idle_per_host = int(os.getenv("BOXFAB_MAX_KEEPALIVE_CONNECTIONS") or "20")
+
+# pyqwest spreads an origin's HTTP/2 streams over as many connections as the
+# server's concurrent-stream limit requires (envd's edge, which all sandboxes
+# share, advertises 100), dialing another once every connection is full, so
+# long-running commands never queue behind one connection. `max_connections`
+# caps the connections to each address an origin resolves to; past it, a
+# request waits on the least loaded connection for a stream to free up.
+max_connections = max(1, int(os.getenv("BOXFAB_MAX_CONNECTIONS") or "200"))
+
+
+class ProxyConfig(NamedTuple):
+    """The ``proxy`` connection option in the shape pyqwest transports take.
+
+    A tuple so it can key the transport caches directly: it is hashable and
+    compares by value, where a ``pyqwest.Proxy`` compares by identity and
+    would hand every call its own connection pool."""
+
+    url: str
+    auth: Optional[Tuple[str, str]] = None
+    headers: Tuple[Tuple[str, str], ...] = ()
+
+    def to_pyqwest(self) -> Proxy:
+        """The ``pyqwest.Proxy`` to hand a transport."""
+        return Proxy(self.url, auth=self.auth, headers=self.headers or None)
+
+
+def proxy_to_config(proxy: Optional[ProxyTypes]) -> Optional[ProxyConfig]:
+    """Convert the ``proxy`` connection option — a URL string, an
+    ``httpx.URL``, or an ``httpx.Proxy`` — to the proxy configuration pyqwest
+    transports take: a proxy URL (scheme http, https, socks5, or socks5h,
+    credentials allowed in the userinfo), basic-auth credentials, and headers
+    to send to the proxy. An ``httpx.Proxy`` ``ssl_context`` has no pyqwest
+    counterpart and is rejected rather than silently dropped."""
+    if proxy is None:
+        return None
+    if isinstance(proxy, str):
+        return ProxyConfig(proxy)
+    if isinstance(proxy, httpx.URL):
+        return ProxyConfig(str(proxy))
+    if isinstance(proxy, httpx.Proxy):
+        if proxy.ssl_context is not None:
+            raise InvalidArgumentException("httpx.Proxy ssl_context is not supported")
+        # httpx.Proxy splits userinfo out of the URL into `.auth`; pyqwest
+        # takes the credentials the same way, so they pass straight through.
+        return ProxyConfig(
+            str(proxy.url),
+            auth=proxy.auth,
+            headers=tuple(proxy.headers.items()),
+        )
+    raise InvalidArgumentException(
+        "Only URL-string, httpx.URL, and httpx.Proxy proxies are supported, "
+        'e.g. proxy="http://user:pass@localhost:8030"'
+    )
+
+
+@dataclass
+class SandboxCreateResponse:
+    sandbox_id: str
+    sandbox_domain: Optional[str]
+    envd_version: str
+    envd_access_token: Optional[str]
+    traffic_access_token: Optional[str]
+
+
+def api_exception_from_code(
+    status_code: int,
+    message: Optional[str] = None,
+    default_exception_class: type[Exception] = SandboxException,
+    stack_trace: Optional[TracebackType] = None,
+) -> Exception:
+    """Map an API error code and message to the matching exception class — the
+    same mapping :func:`handle_api_exception` applies to HTTP responses, usable
+    for error objects embedded in response bodies (e.g. per-fork results)."""
+    if status_code == 401:
+        text = f"{status_code}: Unauthorized, please check your credentials."
+        if message:
+            text += f" - {message}"
+        return AuthenticationException(text)
+
+    if status_code == 429:
+        text = f"{status_code}: Rate limit exceeded, please try again later."
+        if message:
+            text += f" - {message}"
+        return RateLimitException(text)
+
+    if status_code == 503:
+        text = f"{status_code}: Service temporarily unavailable, please retry."
+        if message:
+            text += f" - {message}"
+        return ServiceBusyException(text)
+
+    err = default_exception_class(f"{status_code}: {message}").with_traceback(
+        stack_trace
+    )
+    if isinstance(err, SandboxException):
+        err.status_code = status_code
+
+    return err
+
+
+def handle_api_exception(
+    e: "SupportsApiErrorResponse",
+    default_exception_class: type[Exception] = SandboxException,
+    stack_trace: Optional[TracebackType] = None,
+):
+    try:
+        body = json.loads(e.content) if e.content else {}
+    except json.JSONDecodeError:
+        body = {}
+
+    message = body["message"] if "message" in body else None
+    if message is None and e.status_code not in (401, 429, 503):
+        err = default_exception_class(f"{e.status_code}: {e.content}").with_traceback(
+            stack_trace
+        )
+        if isinstance(err, SandboxException):
+            err.status_code = e.status_code
+
+        return err
+
+    return api_exception_from_code(
+        e.status_code, message, default_exception_class, stack_trace
+    )
+
+
+class SupportsApiErrorResponse(Protocol):
+    @property
+    def status_code(self) -> int: ...
+
+    @property
+    def content(self) -> Union[str, bytes]: ...
+
+
+class ApiClient(AuthenticatedClient):
+    """
+    The client for interacting with the E2B API.
+
+    A single lazily-created httpx client (see the generated
+    ``AuthenticatedClient``) serves all threads and event loops: the pyqwest
+    transports it delegates to are thread-safe and loop-independent, and
+    ``httpx.Client`` is documented thread-safe.
+    """
+
+    def __init__(
+        self,
+        config: ConnectionConfig,
+        transport: Optional[Union[BaseTransport, AsyncBaseTransport]] = None,
+        *args,
+        **kwargs,
+    ):
+        self._proxy = config.proxy
+
+        if config.api_key is None:
+            raise AuthenticationException(
+                "API key is required, get one from your BoxFab administrator (keys are shown at https://dashboard.sandd.contextfab.io). "
+                "You can either set the environment variable `BOXFAB_API_KEY` "
+                'or you can pass it directly to the method like api_key="e2b_..."',
+            )
+
+        token = config.api_key
+        auth_header_name = "X-API-KEY"
+        prefix = ""
+
+        self._logger = config.logger
+
+        headers = {
+            **default_headers,
+            **(config.headers or {}),
+        }
+
+        # Prevent passing these parameters twice
+        more_headers: Optional[dict] = kwargs.pop("headers", None)
+        if more_headers:
+            headers.update(more_headers)
+        kwargs.pop("token", None)
+        kwargs.pop("auth_header_name", None)
+        kwargs.pop("prefix", None)
+
+        httpx_args = {
+            "event_hooks": self._logging_event_hooks(),
+        }
+        if transport is not None:
+            # The proxy lives in the transport; passing `proxy` here too
+            # would mount a fresh, never-closed proxy transport per client.
+            httpx_args["transport"] = transport
+        else:
+            httpx_args["proxy"] = config.proxy
+
+        # config.request_timeout is None when the timeout is explicitly
+        # disabled (request_timeout=0), which httpx.Timeout(None) preserves.
+        kwargs.setdefault("timeout", Timeout(config.request_timeout))
+
+        super().__init__(
+            base_url=config.api_url,
+            httpx_args=httpx_args,
+            headers=headers,
+            token=token or "",
+            auth_header_name=auth_header_name,
+            prefix=prefix,
+            *args,
+            **kwargs,
+        )
+
+    def _logging_event_hooks(self) -> dict:
+        return make_logging_event_hooks(self._logger)
+
+
+# We need to override the logging hooks for the async usage
+class AsyncApiClient(ApiClient):
+    def _logging_event_hooks(self) -> dict:
+        return make_async_logging_event_hooks(self._logger)

boxfab/api/client/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing E2B API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

boxfab/api/client/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

boxfab/api/client/api/sandboxes/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""