Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

15.6 KB
Raw Blame
from typing import (
    Any,
    Callable,
    Dict,
    Generator,
    Iterable,
    List,
    Literal,
    Optional,
    Union,
    overload,
)

import httpx

from e2b.api.client_sync import get_envd_api
from packaging.version import Version
from e2b.connection_config import (
    ConnectionConfig,
    Username,
    KEEPALIVE_PING_HEADER,
    KEEPALIVE_PING_INTERVAL_SEC,
    STREAM_INPUT_TIMEOUT,
)
from protobuf import Oneof

from e2b.envd.process import process_connect, process_pb
from e2b.envd.api import check_sandbox_health
from e2b.envd.rpc import handle_rpc_exception_with_health, kill_process
from e2b.envd.utils import (
    authentication_header,
    extract_start_pid,
    timeout_to_ms,
)
from e2b.envd.client_sync import as_stream, create_rpc_client
from e2b.envd.versions import ENVD_COMMANDS_STDIN, ENVD_ENVD_CLOSE
from e2b.exceptions import InvalidArgumentException, SandboxException
from e2b.sandbox.commands.main import ProcessInfo
from e2b.sandbox.commands.command_handle import CommandResult
from e2b.sandbox.commands.stream_input import stream_input_data, stream_input_start
from e2b.sandbox_sync.commands.command_handle import CommandHandle


class Commands:
    """
    Module for executing commands in the sandbox.
    """

    def __init__(
        self,
        envd_api_url: str,
        connection_config: ConnectionConfig,
        envd_version: Version,
        envd_api: httpx.Client,
    ) -> None:
        self._connection_config = connection_config
        self._envd_version = envd_version
        self._rpc = create_rpc_client(
            process_connect.ProcessClientSync,
            envd_api_url,
            connection_config,
        )
        self._envd_api = envd_api
        # The health probe run after a request failed goes without the
        # connection retries, so a sandbox that cannot be reached is not tried
        # all over again (see `get_transport`).
        self._envd_health_api = get_envd_api(
            connection_config, envd_api_url, retry_connect=False
        )

    def _check_health(self) -> Optional[bool]:
        return check_sandbox_health(self._envd_health_api)

    def list(
        self,
        request_timeout: Optional[float] = None,
    ) -> List[ProcessInfo]:
        """
        Lists all running commands and PTY sessions.

        :param request_timeout: Timeout for the request in **seconds**

        :return: List of running commands and PTY sessions
        """
        try:
            res = self._rpc.list(
                process_pb.ListRequest(),
                timeout_ms=timeout_to_ms(
                    self._connection_config.get_request_timeout(request_timeout)
                ),
            )
            return [
                ProcessInfo(
                    pid=p.pid,
                    # Optional scalars: unset reads as "" — presence checks keep
                    # them None
                    tag=p.tag if p.has_field("tag") else None,
                    cmd=config.cmd,
                    args=list(config.args),
                    envs=dict(config.envs),
                    cwd=config.cwd if config.has_field("cwd") else None,
                )
                for p in res.processes
                for config in (p.config or process_pb.ProcessConfig(),)
            ]
        except Exception as e:
            raise handle_rpc_exception_with_health(e, self._check_health)

    def kill(
        self,
        pid: int,
        request_timeout: Optional[float] = None,
    ) -> bool:
        """
        Kill a running command specified by its process ID.
        It uses `SIGKILL` signal to kill the command.

        :param pid: Process ID of the command. You can get the list of processes using `sandbox.commands.list()`
        :param request_timeout: Timeout for the request in **seconds**

        :return: `True` if the command was killed, `False` if the command was not found
        """
        return kill_process(
            self._rpc,
            pid,
            self._connection_config.get_request_timeout(request_timeout),
            self._check_health,
        )

    def send_stdin(
        self,
        pid: int,
        data: Union[str, bytes],
        request_timeout: Optional[float] = None,
    ):
        """
        Send data to command stdin.

        :param pid Process ID of the command. You can get the list of processes using `sandbox.commands.list()`.
        :param data: Data to send to the command
        :param request_timeout: Timeout for the request in **seconds**
        """
        try:
            self._rpc.send_input(
                process_pb.SendInputRequest(
                    process=process_pb.ProcessSelector(selector=Oneof("pid", pid)),
                    input=process_pb.ProcessInput(
                        input=Oneof(
                            "stdin", data.encode() if isinstance(data, str) else data
                        ),
                    ),
                ),
                timeout_ms=timeout_to_ms(
                    self._connection_config.get_request_timeout(request_timeout)
                ),
            )
        except Exception as e:
            raise handle_rpc_exception_with_health(e, self._check_health)

    def stream_input(
        self,
        pid: int,
        data: Iterable[Union[str, bytes]],
        *,
        timeout: Optional[float] = STREAM_INPUT_TIMEOUT,
    ) -> None:
        """Stream input to command stdin.

        Blocks until ``data`` is exhausted; input is sent as the iterable
        yields it, and no keepalives are sent while it blocks.

        :param pid: Process ID of the command.
        :param data: Iterable of strings or bytes to send in order.
        :param timeout: Timeout in seconds; defaults to ``STREAM_INPUT_TIMEOUT``
            (60 seconds). ``0`` or ``None`` disables the timeout.
        :return: ``None`` after all input is sent and envd acknowledges the stream.
        :raises NotFoundException: If the command does not exist.
        :raises TimeoutException: If the stream timeout expires.
        :raises SandboxException: If the streaming request fails.
        :raises InvalidArgumentException: If ``data`` is a single ``str`` or
            ``bytes`` value instead of an iterable of chunks.
        """
        if isinstance(data, (str, bytes, bytearray, memoryview)):
            raise InvalidArgumentException(
                "`data` must be an iterable of str or bytes chunks, not a single "
                "chunk; wrap it in a list, e.g. `stream_input(pid, [data])`."
            )

        def requests() -> Generator[process_pb.StreamInputRequest, None, None]:
            yield stream_input_start(pid)
            for item in data:
                yield stream_input_data("stdin", item)

        try:
            self._rpc.stream_input(
                requests(),
                timeout_ms=timeout_to_ms(timeout),
            )
        except Exception as error:
            raise handle_rpc_exception_with_health(error, self._check_health)

    def close_stdin(
        self,
        pid: int,
        request_timeout: Optional[float] = None,
    ) -> None:
        """
        Close the command stdin.

        This signals EOF to the command. The command must have been started with `stdin=True`.

        :param pid Process ID of the command. You can get the list of processes using `sandbox.commands.list()`.
        :param request_timeout: Timeout for the request in **seconds**
        """
        if self._envd_version < ENVD_ENVD_CLOSE:
            raise SandboxException(
                f"Sandbox envd version {self._envd_version} doesn't support closing stdin. "
                f"Please rebuild your template to pick up the latest sandbox version."
            )

        try:
            self._rpc.close_stdin(
                process_pb.CloseStdinRequest(
                    process=process_pb.ProcessSelector(selector=Oneof("pid", pid)),
                ),
                timeout_ms=timeout_to_ms(
                    self._connection_config.get_request_timeout(request_timeout)
                ),
            )
        except Exception as e:
            raise handle_rpc_exception_with_health(e, self._check_health)

    @overload
    def run(
        self,
        cmd: str,
        background: Union[Literal[False], None] = None,
        envs: Optional[Dict[str, str]] = None,
        user: Optional[Username] = None,
        cwd: Optional[str] = None,
        on_stdout: Optional[Callable[[str], None]] = None,
        on_stderr: Optional[Callable[[str], None]] = None,
        stdin: Optional[bool] = None,
        timeout: Optional[float] = 60,
        request_timeout: Optional[float] = None,
    ) -> CommandResult:
        """
        Start a new command and wait until it finishes executing.

        :param cmd: Command to execute
        :param background: **`False` if the command should be executed in the foreground**, `True` if the command should be executed in the background
        :param envs: Environment variables used for the command
        :param user: User to run the command as
        :param cwd: Working directory to run the command
        :param on_stdout: Callback for command stdout output
        :param on_stderr: Callback for command stderr output
        :param stdin: If `True`, the command will have a stdin stream that you can send data to using `sandbox.commands.send_stdin()`
        :param timeout: Timeout for the command connection in **seconds**. Using `0` will not limit the command connection time
        :param request_timeout: Not applied to this streaming call — both opening the stream and the stream itself are bounded by `timeout` (unlimited when `0`)

        :return: `CommandResult` result of the command execution
        """
        ...

    @overload
    def run(
        self,
        cmd: str,
        background: Literal[True],
        envs: Optional[Dict[str, str]] = None,
        user: Optional[Username] = None,
        cwd: Optional[str] = None,
        on_stdout: None = None,
        on_stderr: None = None,
        stdin: Optional[bool] = None,
        timeout: Optional[float] = 60,
        request_timeout: Optional[float] = None,
    ) -> CommandHandle:
        """
        Start a new command and return a handle to interact with it.

        :param cmd: Command to execute
        :param background: `False` if the command should be executed in the foreground, **`True` if the command should be executed in the background**
        :param envs: Environment variables used for the command
        :param user: User to run the command as
        :param cwd: Working directory to run the command
        :param stdin: If `True`, the command will have a stdin stream that you can send data to using `sandbox.commands.send_stdin()`
        :param timeout: Timeout for the command connection in **seconds**. Using `0` will not limit the command connection time
        :param request_timeout: Not applied to this streaming call — both opening the stream and the stream itself are bounded by `timeout` (unlimited when `0`)

        :return: `CommandHandle` handle to interact with the running command
        """
        ...

    def run(
        self,
        cmd: str,
        background: Union[bool, None] = None,
        envs: Optional[Dict[str, str]] = None,
        user: Optional[Username] = None,
        cwd: Optional[str] = None,
        on_stdout: Optional[Callable[[str], None]] = None,
        on_stderr: Optional[Callable[[str], None]] = None,
        stdin: Optional[bool] = None,
        timeout: Optional[float] = 60,
        request_timeout: Optional[float] = None,
    ):
        # Check version for stdin support
        if stdin is False and self._envd_version < ENVD_COMMANDS_STDIN:
            raise SandboxException(
                f"Sandbox envd version {self._envd_version} can't specify stdin, it's always turned on. "
                f"Please rebuild your template if you need this feature."
            )

        # Default to `False`
        stdin = stdin or False

        proc = self._start(
            cmd,
            envs,
            user,
            cwd,
            stdin,
            timeout,
            request_timeout,
        )

        return (
            proc
            if background
            else proc.wait(
                on_stdout=on_stdout,
                on_stderr=on_stderr,
            )
        )

    def _start(
        self,
        cmd: str,
        envs: Optional[Dict[str, str]],
        user: Optional[Username],
        cwd: Optional[str],
        stdin: bool,
        timeout: Optional[float],
        request_timeout: Optional[float],
    ):
        events = as_stream(
            self._rpc.start(
                process_pb.StartRequest(
                    process=process_pb.ProcessConfig(
                        cmd="/bin/bash",
                        envs=envs,
                        args=["-l", "-c", cmd],
                        cwd=cwd,
                    ),
                    stdin=stdin,
                ),
                headers={
                    **authentication_header(self._envd_version, user),
                    KEEPALIVE_PING_HEADER: str(KEEPALIVE_PING_INTERVAL_SEC),
                },
                # The command `timeout` bounds the whole stream; `request_timeout`
                # has no per-call equivalent here — connection setup is bounded by
                # the transport's connect timeout instead.
                timeout_ms=timeout_to_ms(timeout),
            )
        )

        return self._create_handle(events, "start process")

    def connect(
        self,
        pid: int,
        timeout: Optional[float] = 60,
        request_timeout: Optional[float] = None,
    ):
        """
        Connects to a running command.
        You can use `CommandHandle.wait()` to wait for the command to finish and get execution results.

        :param pid: Process ID of the command to connect to. You can get the list of processes using `sandbox.commands.list()`
        :param timeout: Timeout for the connection in **seconds**. Using `0` will not limit the connection time
        :param request_timeout: Not applied to this streaming call — both opening the stream and the stream itself are bounded by `timeout` (unlimited when `0`)

        :return: `CommandHandle` handle to interact with the running command
        """
        events = as_stream(
            self._rpc.connect(
                process_pb.ConnectRequest(
                    process=process_pb.ProcessSelector(selector=Oneof("pid", pid)),
                ),
                headers={
                    KEEPALIVE_PING_HEADER: str(KEEPALIVE_PING_INTERVAL_SEC),
                },
                timeout_ms=timeout_to_ms(timeout),
            )
        )

        return self._create_handle(events, "connect to process")

    def _create_handle(
        self,
        events: Generator[
            Union[process_pb.StartResponse, process_pb.ConnectResponse], Any, None
        ],
        action: str,
    ) -> CommandHandle:
        try:
            start_event = events.__next__()

            pid = extract_start_pid(start_event, action)
            return CommandHandle(
                pid=pid,
                handle_kill=lambda: self.kill(pid),
                events=events,
                handle_send_stdin=lambda data, request_timeout=None: self.send_stdin(
                    pid, data, request_timeout
                ),
                handle_close_stdin=lambda request_timeout=None: self.close_stdin(
                    pid, request_timeout
                ),
                check_health=self._check_health,
            )
        except Exception as e:
            try:
                events.close()
            except Exception:
                pass
            raise handle_rpc_exception_with_health(e, self._check_health)