Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

18.1 KB
Raw Blame
#
# Copyright 2026 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""
Isolated filesystem adapter implementation (async).

Uses auto-generated isolated_execution API modules with explicit session_id.
"""

import json
import logging
from collections.abc import AsyncGenerator
from io import IOBase, TextIOBase
from uuid import UUID

import httpx

from opensandbox._httpx import build_async_redirect_client_options
from opensandbox.adapters.converter.exception_converter import ExceptionConverter
from opensandbox.adapters.converter.filesystem_model_converter import (
    FilesystemModelConverter,
)
from opensandbox.adapters.converter.response_handler import (
    extract_request_id,
    handle_api_error,
)
from opensandbox.adapters.download_response import (
    create_read_bytes_response,
    iter_async_response_bytes,
)
from opensandbox.config import ConnectionConfig
from opensandbox.exceptions import InvalidArgumentException, SandboxApiException
from opensandbox.models.filesystem import (
    AsyncReadBytesStream,
    ContentReplaceEntry,
    ContentReplaceResult,
    DirectoryListEntry,
    EntryInfo,
    MoveEntry,
    ReadBytesResponse,
    SearchEntry,
    SetPermissionEntry,
    WriteEntry,
)
from opensandbox.models.sandboxes import SandboxEndpoint
from opensandbox.services.filesystem import Filesystem

logger = logging.getLogger(__name__)


class IsolatedFilesystemAdapter(Filesystem):
    """
    Filesystem adapter for isolated sessions using auto-generated API client.

    Uses generated isolated_execution modules with explicit session_id parameter
    instead of URL prefix composition.
    """

    UPLOAD_PATH = "/v1/isolated/session/{session_id}/files/upload"
    DOWNLOAD_PATH = "/v1/isolated/session/{session_id}/files/download"

    def __init__(
        self,
        connection_config: ConnectionConfig,
        execd_endpoint: SandboxEndpoint,
        session_id: str,
    ) -> None:
        self.connection_config = connection_config
        self.execd_endpoint = execd_endpoint
        self._session_id = session_id
        self._session_uuid = UUID(session_id)

        from opensandbox.api.execd import Client

        protocol = self.connection_config.protocol
        base_url = f"{protocol}://{self.execd_endpoint.endpoint}"
        timeout_seconds = self.connection_config.request_timeout.total_seconds()
        timeout = httpx.Timeout(timeout_seconds)
        headers = self.execd_endpoint.build_request_headers(self.connection_config)

        self._httpx_client = httpx.AsyncClient(
            base_url=base_url,
            headers=headers,
            timeout=timeout,
            transport=self.connection_config.transport,
            **build_async_redirect_client_options(self.connection_config, base_url),
        )

        self._client = Client(
            base_url=base_url,
            timeout=timeout,
            follow_redirects=self.connection_config.follow_redirects,
        )
        self._client.set_async_httpx_client(self._httpx_client)

    def _get_url(self, path_template: str) -> str:
        protocol = self.connection_config.protocol
        path = path_template.format(session_id=self._session_id)
        return f"{protocol}://{self.execd_endpoint.endpoint}{path}"

    async def read_file(
        self,
        path: str,
        *,
        encoding: str = "utf-8",
        range_header: str | None = None,
        offset: int | None = None,
        limit: int | None = None,
    ) -> str:
        content = await self.read_bytes(
            path, range_header=range_header, offset=offset, limit=limit
        )
        return content.decode(encoding)

    async def read_bytes(
        self,
        path: str,
        *,
        range_header: str | None = None,
        offset: int | None = None,
        limit: int | None = None,
    ) -> bytes:
        return (
            await self.read_bytes_detailed(
                path, range_header=range_header, offset=offset, limit=limit
            )
        ).body

    async def read_bytes_detailed(
        self,
        path: str,
        *,
        range_header: str | None = None,
        offset: int | None = None,
        limit: int | None = None,
    ) -> ReadBytesResponse[bytes]:
        try:
            url = self._get_url(self.DOWNLOAD_PATH)
            params: dict[str, str] = {"path": path}
            headers: dict[str, str] = {}
            if range_header:
                headers["Range"] = range_header
            if offset is not None:
                params["offset"] = str(offset)
            if limit is not None:
                params["limit"] = str(limit)

            response = await self._httpx_client.get(url, headers=headers, params=params)
            response.raise_for_status()
            return create_read_bytes_response(
                response,
                response.content,
                line_based=offset is not None or limit is not None,
            )
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def read_bytes_stream(
        self,
        path: str,
        *,
        chunk_size: int = 64 * 1024,
        range_header: str | None = None,
        offset: int | None = None,
        limit: int | None = None,
    ) -> AsyncGenerator[bytes, None]:
        response = await self.read_bytes_stream_detailed(
            path,
            chunk_size=chunk_size,
            range_header=range_header,
            offset=offset,
            limit=limit,
        )

        async def _iter() -> AsyncGenerator[bytes, None]:
            try:
                yield b""
                async for chunk in response.body:
                    yield chunk
            finally:
                await response.body.aclose()

        # Start the generator so its finally block also runs when it is
        # closed or dropped before the caller reads the first chunk.
        chunks = _iter()
        await anext(chunks)
        return chunks

    async def read_bytes_stream_detailed(
        self,
        path: str,
        *,
        chunk_size: int = 64 * 1024,
        range_header: str | None = None,
        offset: int | None = None,
        limit: int | None = None,
    ) -> ReadBytesResponse[AsyncReadBytesStream]:
        try:
            url = self._get_url(self.DOWNLOAD_PATH)
            params: dict[str, str] = {"path": path}
            headers: dict[str, str] = {}
            if range_header:
                headers["Range"] = range_header
            if offset is not None:
                params["offset"] = str(offset)
            if limit is not None:
                params["limit"] = str(limit)

            request = self._httpx_client.build_request(
                "GET", url, headers=headers, params=params
            )
            response = await self._httpx_client.send(request, stream=True)

            if response.status_code >= 300:
                try:
                    await response.aread()
                finally:
                    await response.aclose()
                raise SandboxApiException(
                    f"Failed to stream file {path}: {response.status_code}",
                    status_code=response.status_code,
                    request_id=extract_request_id(response.headers),
                )
            return create_read_bytes_response(
                response,
                iter_async_response_bytes(response, chunk_size),
                line_based=offset is not None or limit is not None,
            )
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def write_files(self, entries: list[WriteEntry]) -> None:
        if not entries:
            return
        try:
            multipart_parts = []
            for entry in entries:
                if not entry.path:
                    raise InvalidArgumentException("File path cannot be null")
                if entry.data is None:
                    raise InvalidArgumentException("File data cannot be null")

                metadata = {
                    "path": entry.path,
                    "owner": entry.owner,
                    "group": entry.group,
                    "mode": entry.mode,
                }
                multipart_parts.append(
                    ("metadata", ("metadata", json.dumps(metadata), "application/json"))
                )

                if isinstance(entry.data, bytes):
                    content = entry.data
                    content_type = "application/octet-stream"
                elif isinstance(entry.data, str):
                    encoding = entry.encoding or "utf-8"
                    content = entry.data.encode(encoding)
                    content_type = f"text/plain; charset={encoding}"
                elif isinstance(entry.data, IOBase):
                    if isinstance(entry.data, TextIOBase):
                        raise InvalidArgumentException(
                            "File stream must be binary (opened with 'rb'). Text streams are not supported."
                        )
                    content = entry.data
                    content_type = "application/octet-stream"
                else:
                    raise InvalidArgumentException(
                        f"Unsupported file data type: {type(entry.data)}"
                    )

                multipart_parts.append(("file", (entry.path, content, content_type)))

            url = self._get_url(self.UPLOAD_PATH)
            response = await self._httpx_client.post(
                url,
                files=multipart_parts,
                follow_redirects=False,
            )
            response.raise_for_status()
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def write_file(
        self,
        path: str,
        data: str | bytes | IOBase,
        *,
        encoding: str = "utf-8",
        mode: int = 755,
        owner: str | None = None,
        group: str | None = None,
    ) -> None:
        entry = WriteEntry(
            path=path, data=data, mode=mode, owner=owner, group=group, encoding=encoding
        )
        await self.write_files([entry])

    async def create_directories(self, entries: list[WriteEntry]) -> None:
        try:
            from opensandbox.api.execd.api.isolated_execution import isolated_make_dirs

            response_obj = await isolated_make_dirs.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                body=FilesystemModelConverter.to_api_isolated_make_dirs_body(entries),
            )
            handle_api_error(response_obj, "Create directories")
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def delete_files(self, paths: list[str]) -> None:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_remove_files,
            )

            response_obj = await isolated_remove_files.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                path=paths,
            )
            handle_api_error(response_obj, "Delete files")
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def delete_directories(self, paths: list[str]) -> None:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_remove_dirs,
            )

            response_obj = await isolated_remove_dirs.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                path=paths,
            )
            handle_api_error(response_obj, "Delete directories")
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def move_files(self, entries: list[MoveEntry]) -> None:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_rename_files,
            )

            rename_items = FilesystemModelConverter.to_api_rename_file_items(entries)
            response_obj = await isolated_rename_files.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                body=rename_items,
            )
            handle_api_error(response_obj, "Move files")
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def set_permissions(self, entries: list[SetPermissionEntry]) -> None:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_chmod_files,
            )

            response_obj = await isolated_chmod_files.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                body=FilesystemModelConverter.to_api_isolated_chmod_files_body(entries),
            )
            handle_api_error(response_obj, "Set permissions")
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def replace_contents(self, entries: list[ContentReplaceEntry]) -> None:
        try:
            from json import JSONDecodeError

            from opensandbox.api.execd.api.isolated_execution import (
                isolated_replace_content,
            )

            try:
                response_obj = await isolated_replace_content.asyncio_detailed(
                    self._session_uuid,
                    client=self._client,
                    body=FilesystemModelConverter.to_api_isolated_replace_content_body(
                        entries
                    ),
                )
                handle_api_error(response_obj, "Replace contents")
            except JSONDecodeError:
                pass
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def replace_contents_detailed(
        self, entries: list[ContentReplaceEntry]
    ) -> list[ContentReplaceResult]:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_replace_content,
            )

            response_obj = await isolated_replace_content.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                body=FilesystemModelConverter.to_api_isolated_replace_content_body(
                    entries
                ),
            )
            handle_api_error(response_obj, "Replace contents")
            return FilesystemModelConverter.to_replace_results(response_obj.parsed)
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def search(self, entry: SearchEntry) -> list[EntryInfo]:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_search_files,
            )
            from opensandbox.api.execd.models import FileInfo

            response_obj = await isolated_search_files.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                path=entry.path,
                pattern=entry.pattern,
            )
            handle_api_error(response_obj, "Search files")

            parsed = response_obj.parsed
            if not parsed:
                return []
            if isinstance(parsed, list) and all(
                isinstance(x, FileInfo) for x in parsed
            ):
                return FilesystemModelConverter.to_entry_info_list(parsed)
            raise SandboxApiException(
                message="Search files failed: unexpected response type",
                request_id=extract_request_id(getattr(response_obj, "headers", None)),
            )
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def list_directory(self, entry: DirectoryListEntry) -> list[EntryInfo]:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_list_directory,
            )
            from opensandbox.api.execd.models import FileInfo
            from opensandbox.api.execd.types import UNSET

            response_obj = await isolated_list_directory.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                path=entry.path,
                depth=entry.depth if entry.depth is not None else UNSET,
            )
            handle_api_error(response_obj, "List directory")

            parsed = response_obj.parsed
            if not parsed:
                return []
            if isinstance(parsed, list) and all(
                isinstance(x, FileInfo) for x in parsed
            ):
                return FilesystemModelConverter.to_entry_info_list(parsed)
            raise SandboxApiException(
                message="List directory failed: unexpected response type",
                request_id=extract_request_id(getattr(response_obj, "headers", None)),
            )
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e

    async def get_file_info(self, paths: list[str]) -> dict[str, EntryInfo]:
        try:
            from opensandbox.api.execd.api.isolated_execution import (
                isolated_get_files_info,
            )

            response_obj = await isolated_get_files_info.asyncio_detailed(
                self._session_uuid,
                client=self._client,
                path=paths,
            )
            handle_api_error(response_obj, "Get file info")

            if not response_obj.parsed:
                return {}
            return FilesystemModelConverter.to_entry_info_map(response_obj.parsed)
        except Exception as e:
            raise ExceptionConverter.to_sandbox_exception(e) from e