Skip to content

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

9.1 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 interface.

Defines the contract for **blocking** sandbox lifecycle operations.
This is the sync counterpart of :mod:`opensandbox.services.sandbox`.
"""

from datetime import datetime, timedelta
from typing import Protocol

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,
)


class SandboxesSync(Protocol):
    """
    Core sandbox lifecycle management service (sync).

    This service provides a clean abstraction over sandbox creation, management, and termination
    operations, isolating business logic from API implementation details.
    """

    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:
        """
        Create a new sandbox with the specified configuration (blocking).

        Args:
            spec: Image specification for the sandbox.
            entrypoint: Command to run as entrypoint.
            env: Environment variables.
            metadata: Custom metadata.
            timeout: Sandbox lifetime / expiration duration. Pass None to require explicit cleanup.
            resource: Resource limits.
            network_policy: Optional outbound network policy (egress).
            credential_proxy: Optional Credential Vault proxy startup settings.
            extensions: Opaque extension parameters passed through to the server as-is.
                Prefer namespaced keys (e.g. ``storage.id``).
            volumes: Optional list of volumes to mount in the sandbox.
            secure_access: Whether to enable secured access for sandbox endpoints.
            lifecycle: Optional pre-start and periodic lifecycle hooks.

        Returns:
            Sandbox create response.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    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:
        """
        Create a sandbox from a ``Succeeded`` fsb template (blocking).

        Template mode fixes the workload shape on the server: only metadata,
        network policy, extensions and the control-plane ``idle_policy``
        may accompany the template id, and the timeout is required.
        """
        ...

    def get_sandbox_info(self, sandbox_id: str) -> SandboxInfo:
        """
        Retrieve information about an existing sandbox.

        Args:
            sandbox_id: Unique identifier of the sandbox.

        Returns:
            Current sandbox information.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def list_sandboxes(self, filter: SandboxFilter) -> PagedSandboxInfos:
        """
        List sandboxes with optional filtering.

        Args:
            filter: Filter criteria.

        Returns:
            Paged list of sandbox information matching the filter.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def patch_sandbox_metadata(
        self, sandbox_id: str, patch: dict[str, str | None]
    ) -> SandboxInfo:
        """
        Patch sandbox metadata.

        Args:
            sandbox_id: Unique identifier of the sandbox.
            patch: Metadata merge patch. String values add or replace keys; None deletes keys.

        Returns:
            Current sandbox information after applying the patch.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def get_sandbox_endpoint(
        self, sandbox_id: str, port: int, use_server_proxy: bool = False
    ) -> SandboxEndpoint:
        """
        Get sandbox endpoint for an exposed port.

        Args:
            sandbox_id: Sandbox id.
            port: Endpoint port number.
            use_server_proxy: Whether to use server proxy for endpoint.

        Returns:
            Target sandbox endpoint.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def get_signed_sandbox_endpoint(
        self, sandbox_id: str, port: int, expires: int,
        use_server_proxy: bool = False,
    ) -> SandboxEndpoint:
        """
        Get signed sandbox endpoint with an OSEP-0011 route token.

        Args:
            sandbox_id: Sandbox id.
            port: Endpoint port number.
            expires: Unix epoch seconds for the signed route token expiry.
            use_server_proxy: Whether to use server proxy for endpoint.

        Returns:
            Target sandbox endpoint.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def pause_sandbox(self, sandbox_id: str) -> None:
        """
        Pause a running sandbox, preserving its state.

        Args:
            sandbox_id: Unique identifier of the sandbox.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def resume_sandbox(self, sandbox_id: str) -> None:
        """
        Resume a paused sandbox.

        Args:
            sandbox_id: Unique identifier of the sandbox.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def renew_sandbox_expiration(
        self, sandbox_id: str, new_expiration_time: datetime
    ) -> SandboxRenewResponse:
        """
        Renew the expiration time of a sandbox.

        Args:
            sandbox_id: Unique identifier of the sandbox.
            new_expiration_time: New expiration timestamp (timezone-aware recommended).

        Returns:
            Renew response including the new expiration time.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def kill_sandbox(self, sandbox_id: str) -> None:
        """
        Request irreversible termination of the remote sandbox. Returns when
        deletion is accepted; runtime cleanup may continue afterward.

        Args:
            sandbox_id: Unique identifier of the sandbox.

        Raises:
            SandboxException: If the operation fails.
        """
        ...

    def create_snapshot(
        self, sandbox_id: str, request: CreateSnapshotRequest | None = None
    ) -> SnapshotInfo:
        """Create a persistent snapshot from a sandbox (blocking)."""
        ...

    def get_snapshot(self, snapshot_id: str) -> SnapshotInfo:
        """Retrieve information about an existing snapshot (blocking)."""
        ...

    def list_snapshots(self, filter: SnapshotFilter) -> PagedSnapshotInfos:
        """List snapshots with optional filtering (blocking)."""
        ...

    def delete_snapshot(self, snapshot_id: str) -> None:
        """Delete a snapshot (blocking)."""
        ...

    def create_template(self, request: CreateTemplateRequest) -> TemplateInfo:
        """Create a fsb template (golden-image build); the build is asynchronous (blocking)."""
        ...

    def get_template(self, template_id: str) -> TemplateInfo:
        """Get one template with its latest build status (blocking)."""
        ...

    def list_templates(self, filter: TemplateFilter) -> PagedTemplateInfos:
        """List the current tenant's templates with optional filtering (blocking)."""
        ...

    def delete_template(self, template_id: str) -> None:
        """Delete a template (blocking)."""
        ...

    def invalidate_endpoint_cache(self, sandbox_id: str) -> None:
        """Remove all cached endpoints for a sandbox. No-op if caching is disabled."""
        ...