Skip to content

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

24.9 KB
Raw Blame
#
# Copyright 2025 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.
#
"""
Synchronous sandbox service adapter implementation.
"""

import logging
from datetime import datetime, timedelta

import httpx

from opensandbox._httpx import build_redirect_client_options
from opensandbox.adapters.converter.exception_converter import (
    ExceptionConverter,
)
from opensandbox.adapters.converter.response_handler import (
    handle_api_error,
    require_parsed,
)
from opensandbox.adapters.converter.sandbox_model_converter import (
    SandboxModelConverter,
)
from opensandbox.adapters.converter.template_model_converter import (
    TemplateModelConverter,
)
from opensandbox.adapters.sandboxes_adapter import encode_metadata_filter
from opensandbox.api.lifecycle.types import UNSET
from opensandbox.config.connection_sync import ConnectionConfigSync
from opensandbox.internal.readiness import constrain_readiness_request
from opensandbox.models.sandboxes import (
    CreateSnapshotRequest,
    CredentialProxyConfig,
    IdlePolicy,
    NetworkPolicy,
    PagedSandboxInfos,
    PagedSnapshotInfos,
    PlatformSpec,
    SandboxCreateResponse,
    SandboxEndpoint,
    SandboxFilter,
    SandboxImageSpec,
    SandboxInfo,
    SandboxLifecycle,
    SandboxRenewResponse,
    SnapshotFilter,
    SnapshotInfo,
    Volume,
)
from opensandbox.models.templates import (
    CreateTemplateRequest,
    PagedTemplateInfos,
    TemplateFilter,
    TemplateInfo,
)
from opensandbox.sync.services.sandbox import SandboxesSync

logger = logging.getLogger(__name__)


class SandboxesAdapterSync(SandboxesSync):
    def __init__(self, connection_config: ConnectionConfigSync) -> None:
        self.connection_config = connection_config

        from opensandbox.adapters.endpoint_cache import EndpointCache

        if not connection_config.endpoint_cache_disabled:
            self._endpoint_cache: EndpointCache | None = EndpointCache(
                maxsize=connection_config.endpoint_cache_size or 1024,
                ttl=connection_config.endpoint_cache_ttl.total_seconds(),
            )
        else:
            self._endpoint_cache = None

        from opensandbox.api.lifecycle import AuthenticatedClient

        api_key = self.connection_config.get_api_key()
        timeout_seconds = self.connection_config.request_timeout.total_seconds()
        timeout = httpx.Timeout(timeout_seconds)

        headers = {
            "User-Agent": self.connection_config.user_agent,
            **self.connection_config.headers,
        }
        if api_key:
            headers["OPEN-SANDBOX-API-KEY"] = api_key

        self._client = AuthenticatedClient(
            base_url=self.connection_config.get_base_url(),
            token=api_key or "",
            prefix="",
            auth_header_name="OPEN-SANDBOX-API-KEY",
            timeout=timeout,
            follow_redirects=self.connection_config.follow_redirects,
        )

        self._httpx_client = httpx.Client(
            base_url=self.connection_config.get_base_url(),
            headers=headers,
            timeout=timeout,
            transport=self.connection_config.transport,
            **build_redirect_client_options(
                self.connection_config,
                self.connection_config.get_base_url(),
                additional_request_hooks=(constrain_readiness_request,),
            ),
        )
        self._client.set_httpx_client(self._httpx_client)

    def _get_client(self):
        return self._client

    def create_sandbox(
        self,
        spec: SandboxImageSpec | None,
        entrypoint: list[str] | None,
        env: dict[str, str],
        metadata: dict[str, str],
        timeout: timedelta | None,
        resource: dict[str, str],
        network_policy: NetworkPolicy | None,
        extensions: dict[str, str],
        volumes: list[Volume] | None,
        platform: PlatformSpec | None = None,
        secure_access: bool = False,
        snapshot_id: str | None = None,
        credential_proxy: CredentialProxyConfig | None = None,
        resource_requests: dict[str, str] | None = None,
        lifecycle: SandboxLifecycle | None = None,
    ) -> SandboxCreateResponse:
        logger.info(
            f"Creating sandbox with startup source: {spec.image if spec is not None else snapshot_id}"
        )
        try:
            from opensandbox.api.lifecycle.api.sandboxes import post_sandboxes
            from opensandbox.api.lifecycle.models import (
                CreateSandboxResponse as ApiCreateSandboxResponse,
            )

            create_request = SandboxModelConverter.to_api_create_sandbox_request(
                spec=spec,
                entrypoint=entrypoint,
                env=env,
                metadata=metadata,
                timeout=timeout,
                resource=resource,
                platform=platform,
                network_policy=network_policy,
                credential_proxy=credential_proxy,
                extensions=extensions,
                volumes=volumes,
                secure_access=secure_access,
                snapshot_id=snapshot_id,
                resource_requests=resource_requests,
                lifecycle=lifecycle,
            )
            response_obj = post_sandboxes.sync_detailed(
                client=self._get_client(), body=create_request
            )
            handle_api_error(response_obj, "Create sandbox")

            parsed = require_parsed(
                response_obj, ApiCreateSandboxResponse, "Create sandbox"
            )
            return SandboxModelConverter.to_sandbox_create_response(parsed)
        except Exception as e:
            logger.warning(
                f"Failed to create sandbox with startup source {spec.image if spec is not None else snapshot_id}: {e}"
            )
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def create_sandbox_from_template(
        self,
        template_id: str,
        timeout: timedelta,
        metadata: dict[str, str] | None = None,
        network_policy: NetworkPolicy | None = None,
        extensions: dict[str, str] | None = None,
        idle_policy: IdlePolicy | None = None,
    ) -> SandboxCreateResponse:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import post_sandboxes
            from opensandbox.api.lifecycle.models import (
                CreateSandboxResponse as ApiCreateSandboxResponse,
            )

            create_request = SandboxModelConverter.to_api_create_template_sandbox_request(
                template_id=template_id,
                timeout=timeout,
                metadata=metadata,
                network_policy=network_policy,
                extensions=extensions,
                idle_policy=idle_policy,
            )
            response_obj = post_sandboxes.sync_detailed(
                client=self._get_client(), body=create_request
            )
            handle_api_error(
                response_obj, f"Create sandbox from template {template_id}"
            )

            parsed = require_parsed(
                response_obj, ApiCreateSandboxResponse, "Create sandbox from template"
            )
            return SandboxModelConverter.to_sandbox_create_response(parsed)
        except Exception as e:
            logger.warning(f"Failed to create sandbox from template {template_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def get_sandbox_info(self, sandbox_id: str) -> SandboxInfo:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import get_sandboxes_sandbox_id
            from opensandbox.api.lifecycle.models import Sandbox as ApiSandbox

            response_obj = get_sandboxes_sandbox_id.sync_detailed(
                client=self._get_client(),
                sandbox_id=sandbox_id,
            )
            handle_api_error(response_obj, f"Get sandbox {sandbox_id}")
            parsed = require_parsed(
                response_obj, ApiSandbox, f"Get sandbox {sandbox_id}"
            )
            return SandboxModelConverter.to_sandbox_info(parsed)
        except Exception as e:
            logger.warning(f"Failed to get sandbox info {sandbox_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def list_sandboxes(self, filter: SandboxFilter) -> PagedSandboxInfos:
        metadata = (
            encode_metadata_filter(filter.metadata) if filter.metadata else UNSET
        )

        try:
            from opensandbox.api.lifecycle.api.sandboxes import get_sandboxes
            from opensandbox.api.lifecycle.models import (
                ListSandboxesResponse as ApiListSandboxesResponse,
            )
            from opensandbox.api.lifecycle.types import UNSET as API_UNSET

            response_obj = get_sandboxes.sync_detailed(
                client=self._get_client(),
                state=filter.states if filter.states else API_UNSET,
                metadata=metadata,
                page=filter.page if filter.page is not None else API_UNSET,
                page_size=filter.page_size
                if filter.page_size is not None
                else API_UNSET,
            )
            handle_api_error(response_obj, "List sandboxes")
            parsed = require_parsed(
                response_obj, ApiListSandboxesResponse, "List sandboxes"
            )
            return SandboxModelConverter.to_paged_sandbox_infos(parsed)
        except Exception as e:
            logger.warning(f"Failed to list sandboxes: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def patch_sandbox_metadata(
        self, sandbox_id: str, patch: dict[str, str | None]
    ) -> SandboxInfo:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                patch_sandboxes_sandbox_id_metadata,
            )
            from opensandbox.api.lifecycle.models import PatchSandboxMetadataRequest
            from opensandbox.api.lifecycle.models import Sandbox as ApiSandbox

            response_obj = patch_sandboxes_sandbox_id_metadata.sync_detailed(
                client=self._get_client(),
                sandbox_id=sandbox_id,
                body=PatchSandboxMetadataRequest.from_dict(patch),
            )
            handle_api_error(response_obj, f"Patch sandbox {sandbox_id} metadata")
            parsed = require_parsed(
                response_obj,
                ApiSandbox,
                f"Patch sandbox {sandbox_id} metadata",
            )
            return SandboxModelConverter.to_sandbox_info(parsed)
        except Exception as e:
            logger.warning(f"Failed to patch sandbox {sandbox_id} metadata: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def get_sandbox_endpoint(
        self, sandbox_id: str, port: int, use_server_proxy: bool = False
    ) -> SandboxEndpoint:
        if self._endpoint_cache is not None:
            key = (sandbox_id, port, use_server_proxy)
            return self._endpoint_cache.get_or_fetch(
                key,
                lambda: self._fetch_sandbox_endpoint(
                    sandbox_id, port, use_server_proxy
                ),
            )
        return self._fetch_sandbox_endpoint(sandbox_id, port, use_server_proxy)

    def _fetch_sandbox_endpoint(
        self, sandbox_id: str, port: int, use_server_proxy: bool = False
    ) -> SandboxEndpoint:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                get_sandboxes_sandbox_id_endpoints_port,
            )
            from opensandbox.api.lifecycle.models import Endpoint as ApiEndpoint

            response_obj = get_sandboxes_sandbox_id_endpoints_port.sync_detailed(
                sandbox_id=sandbox_id,
                port=port,
                client=self._get_client(),
                use_server_proxy=use_server_proxy,
            )
            handle_api_error(
                response_obj, f"Get endpoint for sandbox {sandbox_id} port {port}"
            )
            parsed = require_parsed(response_obj, ApiEndpoint, "Get endpoint")
            return SandboxModelConverter.to_sandbox_endpoint(
                parsed, origin=self._sandbox_origin(response_obj)
            )
        except Exception as e:
            logger.warning(
                f"Failed to retrieve sandbox endpoint for sandbox {sandbox_id}: {e}"
            )
            raise ExceptionConverter.to_sandbox_exception(e) from e

    @staticmethod
    def _sandbox_origin(response_obj: object) -> str | None:
        """Extract the OPEN-SANDBOX-ORIGIN response header when present."""
        headers = getattr(response_obj, "headers", None)
        if headers is None:
            return None
        value = headers.get("OPEN-SANDBOX-ORIGIN")
        return value or None

    def invalidate_endpoint_cache(self, sandbox_id: str) -> None:
        """Remove all cached endpoints for a sandbox."""
        if self._endpoint_cache is not None:
            self._endpoint_cache.invalidate(sandbox_id)

    def get_signed_sandbox_endpoint(
        self,
        sandbox_id: str,
        port: int,
        expires: int,
        use_server_proxy: bool = False,
    ) -> SandboxEndpoint:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                get_sandboxes_sandbox_id_endpoints_port,
            )
            from opensandbox.api.lifecycle.models import Endpoint as ApiEndpoint

            response_obj = get_sandboxes_sandbox_id_endpoints_port.sync_detailed(
                sandbox_id=sandbox_id,
                port=port,
                client=self._get_client(),
                use_server_proxy=use_server_proxy,
                expires=str(expires),
            )
            handle_api_error(
                response_obj,
                f"Get signed endpoint for sandbox {sandbox_id} port {port}",
            )
            parsed = require_parsed(response_obj, ApiEndpoint, "Get signed endpoint")
            return SandboxModelConverter.to_sandbox_endpoint(
                parsed, origin=self._sandbox_origin(response_obj)
            )
        except Exception as e:
            logger.debug(
                f"Failed to retrieve signed sandbox endpoint for sandbox {sandbox_id}",
                exc_info=e,
            )
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def pause_sandbox(self, sandbox_id: str) -> None:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                post_sandboxes_sandbox_id_pause,
            )

            response_obj = post_sandboxes_sandbox_id_pause.sync_detailed(
                client=self._get_client(), sandbox_id=sandbox_id
            )
            handle_api_error(response_obj, f"Pause sandbox {sandbox_id}")
        except Exception as e:
            logger.warning(f"Failed to pause sandbox {sandbox_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def resume_sandbox(self, sandbox_id: str) -> None:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                post_sandboxes_sandbox_id_resume,
            )

            response_obj = post_sandboxes_sandbox_id_resume.sync_detailed(
                client=self._get_client(), sandbox_id=sandbox_id
            )
            handle_api_error(response_obj, f"Resume sandbox {sandbox_id}")
        except Exception as e:
            logger.warning(f"Failed to resume sandbox {sandbox_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def renew_sandbox_expiration(
        self, sandbox_id: str, new_expiration_time: datetime
    ) -> SandboxRenewResponse:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                post_sandboxes_sandbox_id_renew_expiration,
            )
            from opensandbox.api.lifecycle.models.renew_sandbox_expiration_response import (
                RenewSandboxExpirationResponse,
            )

            renew_request = SandboxModelConverter.to_api_renew_request(
                new_expiration_time
            )
            response_obj = post_sandboxes_sandbox_id_renew_expiration.sync_detailed(
                client=self._get_client(),
                sandbox_id=sandbox_id,
                body=renew_request,
            )
            handle_api_error(response_obj, f"Renew sandbox {sandbox_id} expiration")
            parsed = require_parsed(
                response_obj,
                RenewSandboxExpirationResponse,
                f"Renew sandbox {sandbox_id} expiration",
            )
            return SandboxModelConverter.to_sandbox_renew_response(parsed)
        except Exception as e:
            logger.debug(f"Failed to renew sandbox {sandbox_id} expiration", exc_info=e)
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def kill_sandbox(self, sandbox_id: str) -> None:
        try:
            from opensandbox.api.lifecycle.api.sandboxes import (
                delete_sandboxes_sandbox_id,
            )

            response_obj = delete_sandboxes_sandbox_id.sync_detailed(
                client=self._get_client(), sandbox_id=sandbox_id
            )
            handle_api_error(response_obj, f"Kill sandbox {sandbox_id}")
        except Exception as e:
            logger.warning(f"Failed to kill sandbox {sandbox_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def create_snapshot(
        self, sandbox_id: str, request: CreateSnapshotRequest | None = None
    ) -> SnapshotInfo:
        try:
            from opensandbox.api.lifecycle.api.snapshots import (
                post_sandboxes_sandbox_id_snapshots,
            )
            from opensandbox.api.lifecycle.models import Snapshot as ApiSnapshot

            response_obj = post_sandboxes_sandbox_id_snapshots.sync_detailed(
                client=self._get_client(),
                sandbox_id=sandbox_id,
                body=SandboxModelConverter.to_api_create_snapshot_request(request),
            )
            handle_api_error(response_obj, f"Create snapshot for sandbox {sandbox_id}")
            parsed = require_parsed(response_obj, ApiSnapshot, "Create snapshot")
            return SandboxModelConverter.to_snapshot_info(parsed)
        except Exception as e:
            logger.warning(f"Failed to create snapshot for sandbox {sandbox_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def get_snapshot(self, snapshot_id: str) -> SnapshotInfo:
        try:
            from opensandbox.api.lifecycle.api.snapshots import (
                get_snapshots_snapshot_id,
            )
            from opensandbox.api.lifecycle.models import Snapshot as ApiSnapshot

            response_obj = get_snapshots_snapshot_id.sync_detailed(
                client=self._get_client(),
                snapshot_id=snapshot_id,
            )
            handle_api_error(response_obj, f"Get snapshot {snapshot_id}")
            parsed = require_parsed(
                response_obj, ApiSnapshot, f"Get snapshot {snapshot_id}"
            )
            return SandboxModelConverter.to_snapshot_info(parsed)
        except Exception as e:
            logger.warning(f"Failed to get snapshot info {snapshot_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def list_snapshots(self, filter: SnapshotFilter) -> PagedSnapshotInfos:
        try:
            from opensandbox.api.lifecycle.api.snapshots import get_snapshots
            from opensandbox.api.lifecycle.models import (
                ListSnapshotsResponse as ApiListSnapshotsResponse,
            )
            from opensandbox.api.lifecycle.types import UNSET as API_UNSET

            response_obj = get_snapshots.sync_detailed(
                client=self._get_client(),
                sandbox_id=filter.sandbox_id
                if filter.sandbox_id is not None
                else API_UNSET,
                name=filter.name if filter.name is not None else API_UNSET,
                state=filter.states if filter.states else API_UNSET,
                page=filter.page if filter.page is not None else API_UNSET,
                page_size=filter.page_size
                if filter.page_size is not None
                else API_UNSET,
            )
            handle_api_error(response_obj, "List snapshots")
            parsed = require_parsed(
                response_obj, ApiListSnapshotsResponse, "List snapshots"
            )
            return SandboxModelConverter.to_paged_snapshot_infos(parsed)
        except Exception as e:
            logger.warning(f"Failed to list snapshots: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def delete_snapshot(self, snapshot_id: str) -> None:
        try:
            from opensandbox.api.lifecycle.api.snapshots import (
                delete_snapshots_snapshot_id,
            )

            response_obj = delete_snapshots_snapshot_id.sync_detailed(
                client=self._get_client(),
                snapshot_id=snapshot_id,
            )
            handle_api_error(response_obj, f"Delete snapshot {snapshot_id}")
        except Exception as e:
            logger.warning(f"Failed to delete snapshot {snapshot_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def create_template(self, request: CreateTemplateRequest) -> TemplateInfo:
        try:
            from opensandbox.api.lifecycle.api.templates import create_template
            from opensandbox.api.lifecycle.models import FsbTemplate as ApiTemplate

            response_obj = create_template.sync_detailed(
                client=self._get_client(),
                body=TemplateModelConverter.to_api_create_template_request(request),
            )
            handle_api_error(response_obj, "Create template")
            parsed = require_parsed(response_obj, ApiTemplate, "Create template")
            return TemplateModelConverter.to_template_info(parsed)
        except Exception as e:
            logger.warning(f"Failed to create template: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def get_template(self, template_id: str) -> TemplateInfo:
        try:
            from opensandbox.api.lifecycle.api.templates import get_template
            from opensandbox.api.lifecycle.models import FsbTemplate as ApiTemplate

            response_obj = get_template.sync_detailed(
                client=self._get_client(),
                template_id=template_id,
            )
            handle_api_error(response_obj, f"Get template {template_id}")
            parsed = require_parsed(
                response_obj, ApiTemplate, f"Get template {template_id}"
            )
            return TemplateModelConverter.to_template_info(parsed)
        except Exception as e:
            logger.warning(f"Failed to get template {template_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def list_templates(self, filter: TemplateFilter) -> PagedTemplateInfos:
        metadata = (
            encode_metadata_filter(filter.metadata) if filter.metadata else UNSET
        )

        try:
            from opensandbox.api.lifecycle.api.templates import list_templates
            from opensandbox.api.lifecycle.models import (
                ListFsbTemplatesResponse as ApiListTemplatesResponse,
            )
            from opensandbox.api.lifecycle.types import UNSET as API_UNSET

            response_obj = list_templates.sync_detailed(
                client=self._get_client(),
                metadata=metadata,
                page=filter.page if filter.page is not None else API_UNSET,
                page_size=filter.page_size
                if filter.page_size is not None
                else API_UNSET,
            )
            handle_api_error(response_obj, "List templates")
            parsed = require_parsed(
                response_obj, ApiListTemplatesResponse, "List templates"
            )
            return TemplateModelConverter.to_paged_template_infos(parsed)
        except Exception as e:
            logger.warning(f"Failed to list templates: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e

    def delete_template(self, template_id: str) -> None:
        try:
            from opensandbox.api.lifecycle.api.templates import delete_template

            response_obj = delete_template.sync_detailed(
                client=self._get_client(),
                template_id=template_id,
            )
            handle_api_error(response_obj, f"Delete template {template_id}")
        except Exception as e:
            logger.warning(f"Failed to delete template {template_id}: {e}")
            raise ExceptionConverter.to_sandbox_exception(e) from e