Skip to content

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

fix(sdk-python): bound SSE command streams with a read timeout

Sangkyoon Nam678f770746b6
diff --git a/docs/sdks/python.md b/docs/sdks/python.md
index 2783e6188..ae003ec49 100644
--- a/docs/sdks/python.md
+++ b/docs/sdks/python.md
@@ -553,7 +553,7 @@ Reuse a `ConnectionConfig` (or `ConnectionConfigSync`) when creating multiple sa
| `api_key` | API Key for authentication | Optional; needed when server auth is enabled | `OPEN_SANDBOX_API_KEY` |
| `domain` | The endpoint domain of the sandbox service (`host[:port]` or a full URL); a trailing `/` or `/v1` is ignored | `localhost:8080` | `OPEN_SANDBOX_DOMAIN` |
| `protocol` | HTTP protocol (http/https) | `http` | - |
-| `request_timeout` | Timeout for API requests | 30 seconds | - |
+| `request_timeout` | Timeout for API requests; command streams (SSE) wait at most `max(request_timeout, 30s)` for the response and between stream bytes | 30 seconds | - |
| `debug` | Enable debug logging for HTTP requests | `False` | - |
| `headers` | Custom HTTP headers | Empty | - |
| `follow_redirects` | Follow HTTP redirects for SDK requests | `False` | - |
diff --git a/sdks/sandbox/python/README.md b/sdks/sandbox/python/README.md
index ada377fcd..0758fd1a3 100644
--- a/sdks/sandbox/python/README.md
+++ b/sdks/sandbox/python/README.md
@@ -461,7 +461,7 @@ The `ConnectionConfig` class manages API server connection settings.
| `api_key` | API Key for authentication | Required | `OPEN_SANDBOX_API_KEY` |
| `domain` | The endpoint domain of the sandbox service | Required (or localhost:8080) | `OPEN_SANDBOX_DOMAIN` |
| `protocol` | HTTP protocol (http/https) | `http` | - |
-| `request_timeout` | Timeout for API requests | 30 seconds | - |
+| `request_timeout` | Timeout for API requests; command streams (SSE) wait at most `max(request_timeout, 30s)` for the response and between stream bytes | 30 seconds | - |
| `debug` | Enable debug logging for HTTP requests | `False` | - |
| `headers` | Custom HTTP headers | Empty | - |
| `follow_redirects` | Follow HTTP redirects for SDK requests | `False` | - |
diff --git a/sdks/sandbox/python/src/opensandbox/adapters/command_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/command_adapter.py
index 8124edbc0..c1ef73c1c 100644
--- a/sdks/sandbox/python/src/opensandbox/adapters/command_adapter.py
+++ b/sdks/sandbox/python/src/opensandbox/adapters/command_adapter.py
@@ -69,7 +69,7 @@ from opensandbox.models.execd import (
)
from opensandbox.models.sandboxes import SandboxEndpoint
from opensandbox.services.command import Commands
-from opensandbox.transport import streaming_transport
+from opensandbox.transport import sse_timeout, streaming_transport
logger = logging.getLogger(__name__)
@@ -128,7 +128,8 @@ class CommandsAdapter(Commands):
)
self._client.set_async_httpx_client(self._httpx_client)
- # SSE client (read timeout disabled); endpoint headers already in headers
+ # SSE client: read timeout bounds the wait for response headers and the gap
+ # between stream bytes (see sse_timeout); endpoint headers already in headers
sse_headers = {
**headers,
"Accept": "text/event-stream",
@@ -138,12 +139,7 @@ class CommandsAdapter(Commands):
# status opt-in would cause duplicate execution on a resent SSE POST.
self._sse_client = httpx.AsyncClient(
headers=sse_headers,
- timeout=httpx.Timeout(
- connect=timeout_seconds,
- read=None,
- write=timeout_seconds,
- pool=None,
- ),
+ timeout=sse_timeout(timeout_seconds),
transport=streaming_transport(self.connection_config.transport),
**build_async_redirect_client_options(self.connection_config, base_url),
)
@@ -158,7 +154,7 @@ class CommandsAdapter(Commands):
return f"{protocol}://{self.execd_endpoint.endpoint}{path}"
async def _get_sse_client(self) -> httpx.AsyncClient:
- """Return SSE client (read timeout disabled) for execd streaming."""
+ """Return SSE client (bounded read timeout, see sse_timeout) for execd streaming."""
return self._sse_client
async def _execute_streaming_request(
diff --git a/sdks/sandbox/python/src/opensandbox/sync/adapters/command_adapter.py b/sdks/sandbox/python/src/opensandbox/sync/adapters/command_adapter.py
index acd0494ce..5869aae8a 100644
--- a/sdks/sandbox/python/src/opensandbox/sync/adapters/command_adapter.py
+++ b/sdks/sandbox/python/src/opensandbox/sync/adapters/command_adapter.py
@@ -64,7 +64,7 @@ from opensandbox.sync.adapters.converter.execution_event_dispatcher import (
ExecutionEventDispatcherSync,
)
from opensandbox.sync.services.command import CommandsSync
-from opensandbox.transport import streaming_transport
+from opensandbox.transport import sse_timeout, streaming_transport
logger = logging.getLogger(__name__)
@@ -117,7 +117,8 @@ class CommandsAdapterSync(CommandsSync):
)
self._client.set_httpx_client(self._httpx_client)
- # SSE client (read timeout disabled); endpoint headers already in headers
+ # SSE client: read timeout bounds the wait for response headers and the gap
+ # between stream bytes (see sse_timeout); endpoint headers already in headers
sse_headers = {
**headers,
"Accept": "text/event-stream",
@@ -127,12 +128,7 @@ class CommandsAdapterSync(CommandsSync):
# status opt-in would cause duplicate execution on a resent SSE POST.
self._sse_client = httpx.Client(
headers=sse_headers,
- timeout=httpx.Timeout(
- connect=timeout_seconds,
- read=None,
- write=timeout_seconds,
- pool=None,
- ),
+ timeout=sse_timeout(timeout_seconds),
transport=streaming_transport(self.connection_config.transport),
**build_redirect_client_options(self.connection_config, base_url),
)
diff --git a/sdks/sandbox/python/src/opensandbox/transport/__init__.py b/sdks/sandbox/python/src/opensandbox/transport/__init__.py
index f67d02374..64e208ae5 100644
--- a/sdks/sandbox/python/src/opensandbox/transport/__init__.py
+++ b/sdks/sandbox/python/src/opensandbox/transport/__init__.py
@@ -17,6 +17,8 @@
from typing import TypeVar
+import httpx
+
from opensandbox.transport._async_retry import RetryAsyncTransport
from opensandbox.transport._sync_retry import RetrySyncTransport
from opensandbox.transport.retry import (
@@ -63,6 +65,32 @@ def streaming_transport(transport: _T) -> _T:
return transport
+# execd sends an SSE ``ping`` every 3 seconds while a command runs, so a stream
+# that stays silent for much longer has stopped. The read timeout is an idle
+# limit, not a command deadline: every byte (pings included) resets it. The
+# floor keeps a short ``request_timeout`` from cutting a healthy stream between
+# pings and matches the Go SDK's response-header timeout. Waiting for the
+# response headers is a read in httpx, so this also bounds a sandbox that
+# accepts the connection and never answers (for example a paused one).
+SSE_READ_TIMEOUT_FLOOR_SECONDS = 30.0
+
+
+def sse_timeout(request_timeout_seconds: float) -> httpx.Timeout:
+ """
+ Timeout for a streaming (SSE) client.
+
+ Connect and write follow ``request_timeout``; read is bounded by
+ ``max(request_timeout, SSE_READ_TIMEOUT_FLOOR_SECONDS)`` so a silent
+ stream raises ``httpx.ReadTimeout`` instead of blocking forever.
+ """
+ return httpx.Timeout(
+ connect=request_timeout_seconds,
+ read=max(request_timeout_seconds, SSE_READ_TIMEOUT_FLOOR_SECONDS),
+ write=request_timeout_seconds,
+ pool=None,
+ )
+
+
__all__ = [
"JitterMode",
"RetryAsyncTransport",
@@ -70,6 +98,8 @@ __all__ = [
"RetryEvent",
"RetryPolicy",
"RetrySyncTransport",
+ "SSE_READ_TIMEOUT_FLOOR_SECONDS",
+ "sse_timeout",
"streaming_transport",
"unwrap_retry_transport",
]
diff --git a/sdks/sandbox/python/tests/test_command_service_sse_client_config.py b/sdks/sandbox/python/tests/test_command_service_sse_client_config.py
index b1a95fc03..e5e29061a 100644
--- a/sdks/sandbox/python/tests/test_command_service_sse_client_config.py
+++ b/sdks/sandbox/python/tests/test_command_service_sse_client_config.py
@@ -14,15 +14,28 @@
# limitations under the License.
#
+import asyncio
+import concurrent.futures
+import socket
+import threading
+from datetime import timedelta
+
import httpx
import pytest
+from opensandbox import transport as transport_module
from opensandbox.adapters.command_adapter import CommandsAdapter
from opensandbox.config import ConnectionConfig
from opensandbox.config.connection_sync import ConnectionConfigSync
+from opensandbox.exceptions import SandboxTimeoutException
from opensandbox.models.sandboxes import SandboxEndpoint
from opensandbox.sync.adapters.command_adapter import CommandsAdapterSync
-from opensandbox.transport import RetryAsyncTransport, RetryPolicy, RetrySyncTransport
+from opensandbox.transport import (
+ SSE_READ_TIMEOUT_FLOOR_SECONDS,
+ RetryAsyncTransport,
+ RetryPolicy,
+ RetrySyncTransport,
+)
_SSE_BODY = (
b'data: {"type":"init","text":"exec-1","timestamp":1}\n\n'
@@ -48,7 +61,7 @@ def _wake_then_stream_handler(calls: list[str]):
return handler
-def test_sse_client_has_event_stream_headers_and_no_read_timeout() -> None:
+def test_sse_client_has_event_stream_headers_and_bounded_read_timeout() -> None:
cfg = ConnectionConfig(protocol="http")
endpoint = SandboxEndpoint(endpoint="localhost:44772", port=44772)
adapter = CommandsAdapter(cfg, endpoint)
@@ -56,7 +69,133 @@ def test_sse_client_has_event_stream_headers_and_no_read_timeout() -> None:
sse_client = adapter._sse_client
assert sse_client is not None
assert sse_client.headers.get("Accept") == "text/event-stream"
- assert sse_client.timeout.read is None
+ # The read timeout is an idle limit: with the default 30 s request timeout
+ # it equals the floor, so a stream that stops sending (pings included)
+ # fails instead of blocking forever.
+ assert sse_client.timeout.read == SSE_READ_TIMEOUT_FLOOR_SECONDS
+ assert sse_client.timeout.connect == 30.0
+ assert sse_client.timeout.write == 30.0
+ assert sse_client.timeout.pool is None
+
+
+ ("request_timeout", "expected_read"),
+ [(timedelta(seconds=5), 30.0), (timedelta(seconds=60), 60.0)],
+)
+def test_sse_read_timeout_is_request_timeout_with_a_floor(
+ request_timeout: timedelta, expected_read: float
+) -> None:
+ """A short request_timeout must not cut a healthy stream between execd's
+ 3-second pings; a longer one is honored as is."""
+ endpoint = SandboxEndpoint(endpoint="localhost:44772", port=44772)
+ async_adapter = CommandsAdapter(
+ ConnectionConfig(protocol="http", request_timeout=request_timeout), endpoint
+ )
+ sync_adapter = CommandsAdapterSync(
+ ConnectionConfigSync(protocol="http", request_timeout=request_timeout), endpoint
+ )
+
+ assert async_adapter._sse_client.timeout.read == expected_read
+ assert sync_adapter._sse_client.timeout.read == expected_read
+ assert async_adapter._sse_client.timeout.connect == request_timeout.total_seconds()
+ assert sync_adapter._sse_client.timeout.connect == request_timeout.total_seconds()
+
+
+def _silent_stream_handler(request: httpx.Request) -> httpx.Response:
+ """execd accepted the connection but never answered: httpx raises
+ ReadTimeout once the read timeout elapses."""
+ raise httpx.ReadTimeout("timed out", request=request)
+
+
+async def test_run_raises_timeout_when_stream_stays_silent() -> None:
+ cfg = ConnectionConfig(
+ protocol="http", transport=httpx.MockTransport(_silent_stream_handler)
+ )
+ adapter = CommandsAdapter(cfg, SandboxEndpoint(endpoint="localhost:44772"))
+
+ with pytest.raises(SandboxTimeoutException):
+ await adapter.run("echo hi")
+
+
+def test_sync_run_raises_timeout_when_stream_stays_silent() -> None:
+ cfg = ConnectionConfigSync(
+ protocol="http", transport=httpx.MockTransport(_silent_stream_handler)
+ )
+ adapter = CommandsAdapterSync(cfg, SandboxEndpoint(endpoint="localhost:44772"))
+
+ with pytest.raises(SandboxTimeoutException):
+ adapter.run("echo hi")
+
+
+def silent_server():
+ """A server that accepts the connection and never answers: the paused
+ sandbox case. Yields its endpoint; closes on teardown."""
+ server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ server.bind(("127.0.0.1", 0))
+ server.listen(4)
+ held: list[socket.socket] = []
+ stop = threading.Event()
+
+ def accept_and_hold() -> None:
+ server.settimeout(0.05)
+ while not stop.is_set():
+ try:
+ conn, _ = server.accept()
+ except (TimeoutError, OSError):
+ continue
+ held.append(conn)
+
+ thread = threading.Thread(target=accept_and_hold, daemon=True)
+ thread.start()
+ try:
+ yield f"127.0.0.1:{server.getsockname()[1]}"
+ finally:
+ stop.set()
+ thread.join(1)
+ for conn in held:
+ conn.close()
+ server.close()
+
+
+async def test_run_times_out_when_the_sandbox_never_answers(
+ silent_server: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(transport_module, "SSE_READ_TIMEOUT_FLOOR_SECONDS", 0.3)
+ cfg = ConnectionConfig(protocol="http", request_timeout=timedelta(milliseconds=100))
+ adapter = CommandsAdapter(cfg, SandboxEndpoint(endpoint=silent_server))
+
+ # The outer wait_for is a watchdog: if the read timeout regressed to None
+ # the test fails here instead of hanging until the CI job limit.
+ with pytest.raises(SandboxTimeoutException) as excinfo:
+ await asyncio.wait_for(adapter.run("echo hi"), timeout=5)
+ assert isinstance(excinfo.value.__cause__, httpx.ReadTimeout)
+
+
+def test_sync_run_times_out_when_the_sandbox_never_answers(
+ silent_server: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ monkeypatch.setattr(transport_module, "SSE_READ_TIMEOUT_FLOOR_SECONDS", 0.3)
+ cfg = ConnectionConfigSync(
+ protocol="http", request_timeout=timedelta(milliseconds=100)
+ )
+ adapter = CommandsAdapterSync(cfg, SandboxEndpoint(endpoint=silent_server))
+
+ # Same watchdog as the async test: a regression to an unbounded read must
+ # fail within 5 seconds, not hang the suite. The executor is shut down
+ # without waiting, so a worker still blocked on the socket does not hold
+ # the test; the fixture's teardown closes that connection and releases it.
+ pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+ future = pool.submit(adapter.run, "echo hi")
+ try:
+ with pytest.raises(SandboxTimeoutException) as excinfo:
+ future.result(timeout=5)
+ finally:
+ pool.shutdown(wait=False)
+ assert isinstance(excinfo.value.__cause__, httpx.ReadTimeout)
def test_sse_client_keeps_only_wake_retry() -> None: