Skip to content

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

8.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.
#
"""
Synchronous connection configuration for OpenSandbox SDK.

This mirrors ConnectionConfig (async) but uses httpx sync transports.
"""

import os
import ssl
from datetime import timedelta

import httpx
from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator

from opensandbox._httpx import SyncEventHook
from opensandbox.transport import RetryPolicy, RetrySyncTransport
from opensandbox.transport._deadline_sync import DeadlineSyncTransport


class ConnectionConfigSync(BaseModel):
    """
    Synchronous connection configuration shared across all sync SDK HTTP clients.

    Ownership rules:
    - If `transport` is not provided, the SDK creates a default transport per
      Sandbox/Manager instance and will close it.
    - If `transport` is provided, the SDK will NOT close it (user owns it).
    """

    model_config = ConfigDict(arbitrary_types_allowed=True)

    _owns_transport: bool = PrivateAttr(default=True)
    _ssl_context: ssl.SSLContext | None = PrivateAttr(default=None)

    api_key: str | None = Field(
        default=None, description="API key for authentication with sandbox service"
    )
    domain: str | None = Field(
        default=None, description="Base domain for the sandbox management API"
    )
    protocol: str = Field(default="http", description="Protocol to use (http/https)")
    request_timeout: timedelta = Field(
        default=timedelta(seconds=30),
        description="Timeout for HTTP requests to the management API",
    )
    debug: bool = Field(
        default=False, description="Enable debug logging for HTTP requests"
    )
    user_agent: str = Field(
        default="OpenSandbox-Python-SDK/1.2.0", description="User agent string"
    )
    headers: dict[str, str] = Field(
        default_factory=dict, description="User defined headers"
    )
    follow_redirects: bool = Field(
        default=False,
        description=(
            "Whether HTTP clients should follow redirects. Cross-origin redirects strip "
            "headers prefixed OPEN-SANDBOX- or OPENSANDBOX-, but other sensitive custom "
            "headers may still be forwarded."
        ),
    )
    event_hooks: dict[str, list[SyncEventHook]] = Field(
        default_factory=dict,
        description=(
            "Additional httpx event hooks for SDK-created sync clients. SDK security "
            "hooks run after configured request hooks."
        ),
    )

    transport: httpx.BaseTransport | None = Field(
        default=None,
        description=(
            "Shared httpx transport instance used by all HTTP clients within "
            "a Sandbox/Manager instance. When unset the SDK builds a "
            "deadline-aware transport honoring `retry_policy`. Caller-provided "
            "transports must honor request timeouts."
        ),
    )
    retry_policy: RetryPolicy = Field(
        default_factory=RetryPolicy,
        description=(
            "Retry policy applied to requests going through the shared "
            "transport. Streaming (SSE) requests only get its wake-timeout "
            "retry. Pass RetryPolicy.disabled() for fast-fail."
        ),
    )
    use_server_proxy: bool = Field(
        default=False,
        description=(
            "Using sandbox server as proxy for process execd requests"
            "It's useful when client sdk can't access the created sandbox directly"
        ),
    )
    endpoint_cache_ttl: timedelta = Field(
        default=timedelta(seconds=600),
        description="TTL for cached endpoint entries.",
    )
    endpoint_cache_size: int = Field(
        default=1024,
        description="Maximum number of cached endpoint entries. 0 means default (1024).",
    )
    endpoint_cache_disabled: bool = Field(
        default=False,
        description="Disable endpoint caching entirely.",
    )
    disable_metrics: bool = Field(
        default=False,
        description=(
            "Disable SDK telemetry (sandbox.create latency reports). "
            "Also honored via OPENSANDBOX_DISABLE_METRICS=1."
        ),
    )
    enable_tracing: bool = Field(
        default=False,
        description="Enable OpenTelemetry tracing for SDK operations.",
    )

    _ENV_API_KEY = "OPEN_SANDBOX_API_KEY"
    _ENV_DOMAIN = "OPEN_SANDBOX_DOMAIN"
    _DEFAULT_DOMAIN = "localhost:8080"
    _API_VERSION = "v1"

    def model_post_init(self, __context: object) -> None:
        self._owns_transport = "transport" not in self.model_fields_set
        # Best-effort: attach the SDK host's own IP (see async ConnectionConfig).
        from opensandbox.config import client_ip

        client_ip.apply_client_ip(self.headers)

    @property
    def owns_transport(self) -> bool:
        """True when this config created (and may close) its transport."""
        return self._owns_transport

    def new_owned_transport(
        self,
        *,
        max_connections: int | None = 100,
        max_keepalive_connections: int = 20,
        keepalive_expiry: float = 30.0,
    ) -> httpx.BaseTransport:
        """
        Build a fresh transport stack owned by the caller.

        Same stack as `with_transport_if_missing` builds by default; the
        shared `transport` on this config is never touched. Callers that
        close what they build (e.g. adapter clients) can do so safely.
        """
        if self._ssl_context is None:
            self._ssl_context = httpx.create_ssl_context()
        ssl_context = self._ssl_context
        inner = httpx.HTTPTransport(
            verify=ssl_context,
            limits=httpx.Limits(
                max_connections=max_connections,
                max_keepalive_connections=max_keepalive_connections,
                keepalive_expiry=keepalive_expiry,
            ),
        )
        bounded = DeadlineSyncTransport(inner, ssl_context)
        if self.retry_policy.wraps_transport():
            return RetrySyncTransport(bounded, self.retry_policy, owns_inner=True)
        return bounded

    def with_transport_if_missing(
        self,
        *,
        max_connections: int | None = 100,
        max_keepalive_connections: int = 20,
        keepalive_expiry: float = 30.0,
    ) -> "ConnectionConfigSync":
        if self.transport is not None:
            return self
        config = self.model_copy(
            update={
                "transport": self.new_owned_transport(
                    max_connections=max_connections,
                    max_keepalive_connections=max_keepalive_connections,
                    keepalive_expiry=keepalive_expiry,
                )
            }
        )
        config._owns_transport = True
        return config

    def close_transport_if_owned(self) -> None:
        if self.transport is None or not self._owns_transport:
            return
        try:
            self.transport.close()
        except Exception:
            pass

    @field_validator("protocol")
    @classmethod
    def protocol_must_be_valid(cls, v: str) -> str:
        v = v.lower()
        if v not in ("http", "https"):
            raise ValueError("Protocol must be 'http' or 'https'")
        return v

    @field_validator("request_timeout")
    @classmethod
    def timeout_must_be_positive(cls, v: timedelta) -> timedelta:
        if v.total_seconds() <= 0:
            raise ValueError(f"Request timeout must be positive, got: {v}")
        return v

    def get_api_key(self) -> str:
        return self.api_key or os.getenv(self._ENV_API_KEY, "")

    def get_domain(self) -> str:
        return self.domain or os.getenv(self._ENV_DOMAIN, self._DEFAULT_DOMAIN)

    def get_base_url(self) -> str:
        # Same normalization as ConnectionConfig.get_base_url().
        domain = self.get_domain().rstrip("/")
        version_suffix = f"/{self._API_VERSION}"
        if domain.endswith(version_suffix):
            domain = domain[: -len(version_suffix)]
        if domain.startswith("http://") or domain.startswith("https://"):
            return f"{domain}/{self._API_VERSION}"
        return f"{self.protocol}://{domain}/{self._API_VERSION}"