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.mdindex 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.mdindex 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.pyindex 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 SandboxEndpointfrom opensandbox.services.command import Commands-from opensandbox.transport import streaming_transport+from opensandbox.transport import sse_timeout, streaming_transportlogger = 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 headerssse_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_clientasync 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.pyindex 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_transportlogger = 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 headerssse_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__.pyindex 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 RetryAsyncTransportfrom opensandbox.transport._sync_retry import RetrySyncTransportfrom 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.pyindex 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 httpximport pytest+from opensandbox import transport as transport_modulefrom opensandbox.adapters.command_adapter import CommandsAdapterfrom opensandbox.config import ConnectionConfigfrom opensandbox.config.connection_sync import ConnectionConfigSync+from opensandbox.exceptions import SandboxTimeoutExceptionfrom opensandbox.models.sandboxes import SandboxEndpointfrom 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_clientassert sse_client is not Noneassert 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: