Skip to content

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

9.5 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.
#
"""
Unified response handler for API calls.

Provides a centralized way to handle API responses, including:
1. Status code validation
2. Error response handling
3. Unified exception conversion

This eliminates the need to repeat response handling logic in each adapter method.
"""

import logging
from datetime import timedelta
from http import HTTPStatus
from typing import Any, TypeVar

from opensandbox.exceptions import (
    SandboxApiException,
    SandboxError,
    SandboxRateLimitException,
)
from opensandbox.transport._decision import parse_retry_after

logger = logging.getLogger(__name__)


T = TypeVar("T")

# Status codes the SDK treats as transient (the default idempotent
# retryable set from RetryPolicy). Surfaced via ``is_retryable`` so
# callers get a machine-checkable retry decision even after the SDK has
# exhausted its own retries.
_RETRYABLE_STATUS_CODES = frozenset(
    {
        HTTPStatus.TOO_MANY_REQUESTS,   # 429
        HTTPStatus.BAD_GATEWAY,         # 502
        HTTPStatus.SERVICE_UNAVAILABLE, # 503
    }
)


def extract_request_id(headers: Any) -> str | None:
    """
    Extract X-Request-ID from response headers in a case-insensitive way.
    """
    if not headers:
        return None
    try:
        # httpx.Headers supports case-insensitive lookup.
        value = headers.get("X-Request-ID") or headers.get("x-request-id")
        if isinstance(value, str):
            value = value.strip()
        return value or None
    except Exception:
        return None


def _status_code_to_int(status_code: Any) -> int:
    """
    Normalize status_code from openapi-python-client responses to a plain int.

    openapi-python-client may use http.HTTPStatus; some callers may already provide an int.
    """
    if isinstance(status_code, HTTPStatus):
        return int(status_code)
    if isinstance(status_code, int):
        return status_code
    value = getattr(status_code, "value", None)
    if isinstance(value, int):
        return value
    try:
        return int(status_code)
    except Exception:
        return 0


def require_parsed(response_obj: Any, expected_type: type[T], operation_name: str) -> T:
    """
    Validate and return the parsed payload from an openapi-python-client response.

    Use this after `handle_api_error()` to enforce:
    - parsed payload must exist
    - parsed payload must match the expected type
    """
    status_code = _status_code_to_int(getattr(response_obj, "status_code", 0))
    request_id = extract_request_id(getattr(response_obj, "headers", None))

    parsed = getattr(response_obj, "parsed", None)
    if parsed is None:
        raise SandboxApiException(
            message=f"{operation_name} failed: empty response",
            status_code=status_code,
            request_id=request_id,
        )
    if not isinstance(parsed, expected_type):
        raise SandboxApiException(
            message=f"{operation_name} failed: unexpected response type",
            status_code=status_code,
            request_id=request_id,
        )
    return parsed


def _retry_after(headers: Any) -> timedelta | None:
    """Return Retry-After as a timedelta from response headers, or None."""
    if not headers:
        return None
    try:
        raw = headers.get("Retry-After") or headers.get("retry-after")
    except Exception:
        return None
    return parse_retry_after(raw if isinstance(raw, str) else None)


# Upper bound on the raw response body slice we splice into an
# exception's ``str()``. The full body is always available on
# ``exc.response_body`` untruncated.
_RAW_BODY_MESSAGE_LIMIT = 512


def _raw_body_bytes(response_obj: Any) -> bytes | None:
    """Return the response's raw body as ``bytes`` when available."""
    content = getattr(response_obj, "content", None)
    if isinstance(content, bytes):
        return content
    if isinstance(content, bytearray):
        return bytes(content)
    return None


def _raw_body_message_fragment(body: bytes | None) -> str | None:
    """Best-effort decode of the raw body for splicing into an error message."""
    if not body:
        return None
    try:
        text = body.decode("utf-8", errors="replace").strip()
    except Exception:
        return None
    if not text:
        return None
    if len(text) > _RAW_BODY_MESSAGE_LIMIT:
        text = text[:_RAW_BODY_MESSAGE_LIMIT] + "…"
    return text


def build_api_exception_from_httpx(
    response: Any,
    operation_name: str = "API call",
) -> SandboxApiException:
    """
    Build a ``SandboxApiException`` (or ``SandboxRateLimitException`` on
    429) from a raw ``httpx.Response``.

    Use this from direct-httpx adapter paths (SSE bootstraps, isolated
    session endpoints) so 429 responses map to the same exception class
    as those coming through the generated openapi-python-client layer.
    """
    status_code = _status_code_to_int(getattr(response, "status_code", 0))
    headers = getattr(response, "headers", None)
    request_id = extract_request_id(headers)
    body_bytes = getattr(response, "content", None)
    if not isinstance(body_bytes, (bytes, bytearray)):
        body_bytes = None
    else:
        body_bytes = bytes(body_bytes)

    # Try to pull structured code/message from the JSON body.
    from opensandbox.adapters.converter.exception_converter import parse_sandbox_error

    sandbox_error = parse_sandbox_error(body_bytes) if body_bytes else None
    error_message = f"{operation_name} failed: HTTP {status_code}"
    if sandbox_error and sandbox_error.message:
        error_message = f"{operation_name} failed: {sandbox_error.message}"
    elif sandbox_error is None:
        raw_fragment = _raw_body_message_fragment(body_bytes)
        if raw_fragment:
            error_message = f"{error_message}: {raw_fragment}"

    is_retryable = status_code in _RETRYABLE_STATUS_CODES
    if status_code == HTTPStatus.TOO_MANY_REQUESTS:
        return SandboxRateLimitException(
            message=error_message,
            status_code=status_code,
            request_id=request_id,
            retry_after=_retry_after(headers),
            error=sandbox_error,
            response_body=body_bytes,
            is_retryable=is_retryable,
        )
    return SandboxApiException(
        message=error_message,
        status_code=status_code,
        request_id=request_id,
        error=sandbox_error,
        response_body=body_bytes,
        is_retryable=is_retryable,
    )


def handle_api_error(response_obj: Any, operation_name: str = "API call") -> None:
    """
    Check API response for errors and raise exception if needed.

    Call this before accessing response_obj.parsed to validate the response.

    Args:
        response_obj: The Response object from asyncio_detailed or sync_detailed
        operation_name: Name of the operation for error messages

    Raises:
        SandboxRateLimitException: On HTTP 429 (Too Many Requests).
        SandboxApiException: On any other HTTP >= 300.
    """
    status_code = _status_code_to_int(getattr(response_obj, "status_code", 0))
    headers = getattr(response_obj, "headers", None)
    request_id = extract_request_id(headers)
    raw_body = _raw_body_bytes(response_obj)

    logger.debug(f"{operation_name} response: status={status_code}")

    if status_code >= 300:
        error_message = f"{operation_name} failed: HTTP {status_code}"
        sandbox_error: SandboxError | None = None

        if hasattr(response_obj, "parsed") and response_obj.parsed is not None:
            parsed = response_obj.parsed
            parsed_code = getattr(parsed, "code", None)
            parsed_message = getattr(parsed, "message", None)

            if parsed_message:
                error_message = f"{operation_name} failed: {parsed_message}"
            elif parsed_code:
                error_message = f"{operation_name} failed: {parsed_code}"

            if parsed_code:
                sandbox_error = SandboxError(
                    code=str(parsed_code),
                    message=str(parsed_message or ""),
                )

        # Fall back to the raw body when the SDK could not parse a
        # structured message/code, so callers do not lose the server's
        # own explanation.
        if sandbox_error is None:
            raw_fragment = _raw_body_message_fragment(raw_body)
            if raw_fragment:
                error_message = f"{error_message}: {raw_fragment}"

        is_retryable = status_code in _RETRYABLE_STATUS_CODES
        if status_code == HTTPStatus.TOO_MANY_REQUESTS:
            raise SandboxRateLimitException(
                message=error_message,
                status_code=status_code,
                request_id=request_id,
                retry_after=_retry_after(headers),
                error=sandbox_error,
                response_body=raw_body,
                is_retryable=is_retryable,
            )

        raise SandboxApiException(
            message=error_message,
            status_code=status_code,
            request_id=request_id,
            error=sandbox_error,
            response_body=raw_body,
            is_retryable=is_retryable,
        )