Skip to content

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

11.2 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.
#
"""
Sandbox-related exception definitions.
"""

from datetime import timedelta


class SandboxError:
    """
    Defines standardized common error codes and messages for the Sandbox SDK.
    """

    INTERNAL_UNKNOWN_ERROR = "INTERNAL_UNKNOWN_ERROR"
    READY_TIMEOUT = "READY_TIMEOUT"
    UNHEALTHY = "UNHEALTHY"
    INVALID_ARGUMENT = "INVALID_ARGUMENT"
    UNEXPECTED_RESPONSE = "UNEXPECTED_RESPONSE"
    POOL_EMPTY = "POOL_EMPTY"
    POOL_ACQUIRE_FAILED = "POOL_ACQUIRE_FAILED"
    POOL_STATE_STORE_UNAVAILABLE = "POOL_STATE_STORE_UNAVAILABLE"
    POOL_NOT_RUNNING = "POOL_NOT_RUNNING"
    POOL_DESTROYED = "POOL_DESTROYED"
    POOL_DESTROY_INCOMPLETE = "POOL_DESTROY_INCOMPLETE"
    TIMEOUT = "TIMEOUT"
    CONNECTION = "CONNECTION"
    RATE_LIMIT = "RATE_LIMIT"
    WAKE_TIMEOUT = "WAKE_TIMEOUT"

    def __init__(self, code: str, message: str | None = None) -> None:
        self.code = code
        self.message = message

    def __repr__(self) -> str:
        return f"SandboxError(code='{self.code}', message='{self.message}')"


class SandboxException(Exception):
    """
    Base exception class for all sandbox-related errors.

    Provides a consistent error structure across the SDK. ``is_retryable``
    reflects whether the SDK actually decided to retry this failure:
    budget exhaustion, deadline expiry, and caller cancellation all
    force it to ``False`` even for transient causes.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
        error: SandboxError | None = None,
        request_id: str | None = None,
        is_retryable: bool = False,
    ) -> None:
        super().__init__(message)
        self.__cause__ = cause
        self.error = error or SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR)
        self.request_id = request_id
        self._is_retryable = is_retryable

    @property
    def is_retryable(self) -> bool:
        """True iff the SDK considered this failure retryable at emission time."""
        return self._is_retryable

    def __str__(self) -> str:
        parts = [super().__str__()]
        if self.error and self.error.message:
            parts.append(f"[{self.error.code}] {self.error.message}")
        if self.request_id:
            parts.append(f"request_id={self.request_id}")
        return " | ".join(parts)


class SandboxApiException(SandboxException):
    """
    Thrown when the Sandbox API returns an error response (e.g., HTTP 4xx or 5xx)
    or meets unexpected error when calling API.

    ``response_body`` carries the raw response bytes from the server so
    callers can inspect payloads the SDK could not parse into a
    structured ``SandboxError``.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
        status_code: int | None = None,
        error: SandboxError | None = None,
        request_id: str | None = None,
        response_body: bytes | None = None,
        is_retryable: bool = False,
    ) -> None:
        super().__init__(
            message,
            cause,
            error or SandboxError(SandboxError.UNEXPECTED_RESPONSE),
            request_id=request_id,
            is_retryable=is_retryable,
        )
        self.status_code = status_code
        self.response_body = response_body


class SandboxRateLimitException(SandboxApiException):
    """
    Thrown when the API returns HTTP 429.

    ``retry_after`` carries the server-supplied header value as a
    ``timedelta`` when present, so fast-fail callers can still act on it.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
        status_code: int | None = 429,
        error: SandboxError | None = None,
        request_id: str | None = None,
        retry_after: timedelta | None = None,
        response_body: bytes | None = None,
        is_retryable: bool = False,
    ) -> None:
        super().__init__(
            message,
            cause,
            status_code=status_code,
            error=error or SandboxError(SandboxError.RATE_LIMIT, message),
            request_id=request_id,
            response_body=response_body,
            is_retryable=is_retryable,
        )
        self.retry_after = retry_after


class SandboxWakeTimeoutException(SandboxApiException):
    """
    Thrown when the OSEP-0024 wake retry budget is exhausted.

    The gateway answered ``503`` with the ``OpenSandbox-Wake: expired``
    marker on every attempt: the sandbox restore did not finish within
    the wake retry policy's budget. The request was never forwarded, so
    retrying later is safe — the server-side resume continues in the
    background regardless.

    ``attempts`` carries the number of marked wake-timeout responses
    received; ``waited`` carries the total wall-clock time spent across
    waits, retries, and request time.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
        attempts: int = 0,
        waited: timedelta | None = None,
        error: SandboxError | None = None,
        request_id: str | None = None,
        response_body: bytes | None = None,
    ) -> None:
        super().__init__(
            message,
            cause,
            status_code=503,
            error=error or SandboxError(SandboxError.WAKE_TIMEOUT, message),
            request_id=request_id,
            response_body=response_body,
            is_retryable=False,
        )
        self.attempts = attempts
        self.waited = waited if waited is not None else timedelta(0)


class SandboxInternalException(SandboxException):
    """
    Thrown when an unexpected internal error occurs within the SDK.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
        error: SandboxError | None = None,
        is_retryable: bool = False,
    ) -> None:
        super().__init__(
            message,
            cause,
            error or SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR),
            is_retryable=is_retryable,
        )


class SandboxTimeoutException(SandboxInternalException):
    """
    Thrown when a per-attempt timeout or overall retry deadline fires.

    Distinct from :class:`SandboxReadyTimeoutException`, which is the
    health-poll timeout during sandbox startup.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
        is_retryable: bool = False,
    ) -> None:
        super().__init__(
            message,
            cause,
            error=SandboxError(SandboxError.TIMEOUT, message),
            is_retryable=is_retryable,
        )


class SandboxConnectionException(SandboxInternalException):
    """Transport-layer failure: DNS, TCP connect, TLS, or connection reset."""

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
        is_retryable: bool = False,
    ) -> None:
        super().__init__(
            message,
            cause,
            error=SandboxError(SandboxError.CONNECTION, message),
            is_retryable=is_retryable,
        )


class SandboxUnhealthyException(SandboxException):
    """
    Thrown when the sandbox is determined to be unhealthy.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
    ) -> None:
        super().__init__(message, cause, SandboxError(SandboxError.UNHEALTHY, message))


class SandboxReadyTimeoutException(SandboxException):
    """
    Thrown when the operation times out waiting for the sandbox to become ready.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
    ) -> None:
        super().__init__(
            message, cause, SandboxError(SandboxError.READY_TIMEOUT, message)
        )


class InvalidArgumentException(SandboxException):
    """
    Thrown when an invalid argument is provided to an SDK method.
    Similar to ValueError but within the SDK's exception hierarchy.
    """

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
    ) -> None:
        super().__init__(
            message, cause, SandboxError(SandboxError.INVALID_ARGUMENT, message)
        )


class PoolEmptyException(SandboxException):
    """Thrown when FAIL_FAST acquire sees no idle sandbox."""

    def __init__(
        self,
        message: str | None = "No idle sandbox available and policy is FAIL_FAST",
        cause: Exception | None = None,
    ) -> None:
        super().__init__(message, cause, SandboxError(SandboxError.POOL_EMPTY, message))


class PoolAcquireFailedException(SandboxException):
    """Thrown when FAIL_FAST acquire sees an unusable idle sandbox candidate."""

    def __init__(
        self,
        message: str | None = "Acquire failed due to unusable idle sandbox candidate(s)",
        cause: Exception | None = None,
    ) -> None:
        super().__init__(
            message, cause, SandboxError(SandboxError.POOL_ACQUIRE_FAILED, message)
        )


class PoolStateStoreUnavailableException(SandboxException):
    """Thrown when the pool state store is unavailable."""

    def __init__(
        self,
        message: str | None = None,
        cause: Exception | None = None,
    ) -> None:
        super().__init__(
            message,
            cause,
            SandboxError(SandboxError.POOL_STATE_STORE_UNAVAILABLE, message),
        )


class PoolNotRunningException(SandboxException):
    """Thrown when acquire is called while the pool is not running."""

    def __init__(
        self,
        message: str | None = "Pool is not running",
        cause: Exception | None = None,
    ) -> None:
        super().__init__(
            message, cause, SandboxError(SandboxError.POOL_NOT_RUNNING, message)
        )


class PoolDestroyedException(SandboxException):
    """Thrown when a pool namespace is being destroyed or has been destroyed."""

    def __init__(
        self,
        message: str | None = "Pool namespace is destroyed",
        cause: Exception | None = None,
    ) -> None:
        super().__init__(
            message, cause, SandboxError(SandboxError.POOL_DESTROYED, message)
        )


class PoolDestroyIncompleteException(SandboxException):
    """Thrown when pool destroy starts but does not complete."""

    def __init__(
        self,
        message: str | None = "Pool destroy did not complete",
        cause: Exception | None = None,
    ) -> None:
        super().__init__(
            message,
            cause,
            SandboxError(SandboxError.POOL_DESTROY_INCOMPLETE, message),
        )