Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(sdk-python): close interrupted file download responses
redyyang610dc843e8fa
diff --git a/docs/sdks/python.md b/docs/sdks/python.mdindex 238af19da..b532dc397 100644--- a/docs/sdks/python.md+++ b/docs/sdks/python.md@@ -411,6 +411,8 @@ await sandbox.files.delete_files(["/tmp/hello.txt"])For binary data, pass `bytes` to `WriteEntry.data` and use `read_bytes()`; use `read_bytes_stream()` for large downloads. `read_file()` and `read_bytes()` also accept `offset` and `limit` for partial reads.+Async download iterators release their HTTP response when iteration finishes, fails, or is cancelled. If you stop consuming a download early, close the started iterator with `aclose()` (for example, using `contextlib.aclosing`) to release the connection promptly. This applies to both `sandbox.files` and isolated-session files.+#### File operations with an explicit identityBind a filesystem client to a Linux UID and GID:diff --git a/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.pyindex 1337fdd81..f4dba00ee 100644--- a/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py+++ b/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py@@ -246,7 +246,15 @@ class FilesystemAdapter(Filesystem):status_code=response.status_code,request_id=extract_request_id(response.headers),)- return response.aiter_bytes(chunk_size=chunk_size)++ async def _iter() -> AsyncIterator[bytes]:+ try:+ async for chunk in response.aiter_bytes(chunk_size=chunk_size):+ yield chunk+ finally:+ await response.aclose()++ return _iter()except Exception as e:logger.error(f"Failed to stream file {path}", exc_info=e)raise ExceptionConverter.to_sandbox_exception(e) from ediff --git a/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.pyindex 2ce016c3b..f9fc6dab5 100644--- a/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py+++ b/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py@@ -178,7 +178,15 @@ class IsolatedFilesystemAdapter(Filesystem):status_code=response.status_code,request_id=extract_request_id(response.headers),)- return response.aiter_bytes(chunk_size=chunk_size)++ async def _iter() -> AsyncIterator[bytes]:+ try:+ async for chunk in response.aiter_bytes(chunk_size=chunk_size):+ yield chunk+ finally:+ await response.aclose()++ return _iter()except Exception as e:raise ExceptionConverter.to_sandbox_exception(e) from ediff --git a/sdks/sandbox/python/tests/test_filesystem_download_cleanup.py b/sdks/sandbox/python/tests/test_filesystem_download_cleanup.pynew file mode 100644index 000000000..4119de38f--- /dev/null+++ b/sdks/sandbox/python/tests/test_filesystem_download_cleanup.py@@ -0,0 +1,158 @@+# Copyright 2026 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.++"""Async downloads must release their response when iteration stops."""++import asyncio+from collections.abc import AsyncIterator, Callable+from contextlib import aclosing++import httpx+import pytest++from opensandbox.adapters.filesystem_adapter import FilesystemAdapter+from opensandbox.adapters.isolated_filesystem_adapter import IsolatedFilesystemAdapter+from opensandbox.config import ConnectionConfig+from opensandbox.exceptions import SandboxApiException+from opensandbox.models.sandboxes import SandboxEndpoint++_AdapterFactory = Callable[+ ..., tuple[FilesystemAdapter | IsolatedFilesystemAdapter, httpx.Response]+]+++class _DownloadStream(httpx.AsyncByteStream):+ def __init__(self, *, failure: Exception | None = None, block: bool = False) -> None:+ self.failure = failure+ self.block = block+ self.closed = False+ self.reading = asyncio.Event()++ async def __aiter__(self) -> AsyncIterator[bytes]:+ yield b"abcd"+ if self.failure is not None:+ raise self.failure+ if self.block:+ self.reading.set()+ await asyncio.Event().wait()+ yield b"ef"++ async def aclose(self) -> None:+ self.closed = True++[email protected](params=["sandbox", "isolated"])+def download_adapter(request: pytest.FixtureRequest) -> _AdapterFactory:+ def make(+ stream: _DownloadStream, status_code: int = 200+ ) -> tuple[FilesystemAdapter | IsolatedFilesystemAdapter, httpx.Response]:+ response = httpx.Response(status_code, stream=stream)+ config = ConnectionConfig(+ protocol="http",+ transport=httpx.MockTransport(lambda _: response),+ )+ endpoint = SandboxEndpoint(endpoint="localhost:44772")+ if request.param == "isolated":+ adapter = IsolatedFilesystemAdapter(+ config, endpoint, "12345678-1234-5678-1234-567812345678"+ )+ else:+ adapter = FilesystemAdapter(config, endpoint)+ return adapter, response++ return make+++async def test_download_closes_after_full_consumption(download_adapter: _AdapterFactory) -> None:+ source = _DownloadStream()+ adapter, response = download_adapter(source)+ try:+ chunks = await adapter.read_bytes_stream("/tmp/file", chunk_size=2)+ assert [chunk async for chunk in chunks] == [b"ab", b"cd", b"ef"]+ assert source.closed+ assert response.is_closed+ finally:+ await response.aclose()+ await adapter._httpx_client.aclose()+++async def test_download_aclosing_releases_partial_response(download_adapter: _AdapterFactory) -> None:+ source = _DownloadStream()+ adapter, response = download_adapter(source)+ try:+ chunks = await adapter.read_bytes_stream("/tmp/file", chunk_size=2)+ async with aclosing(chunks):+ assert await anext(chunks) == b"ab"+ assert not source.closed+ assert source.closed+ assert response.is_closed+ finally:+ await response.aclose()+ await adapter._httpx_client.aclose()+++async def test_download_read_failure_releases_response(download_adapter: _AdapterFactory) -> None:+ failure = httpx.ReadError("download disconnected")+ source = _DownloadStream(failure=failure)+ adapter, response = download_adapter(source)+ try:+ chunks = await adapter.read_bytes_stream("/tmp/file", chunk_size=4)+ assert await anext(chunks) == b"abcd"+ with pytest.raises(httpx.ReadError) as exc:+ await anext(chunks)+ assert exc.value is failure+ assert source.closed+ assert response.is_closed+ finally:+ await response.aclose()+ await adapter._httpx_client.aclose()+++async def test_download_cancellation_releases_response(download_adapter: _AdapterFactory) -> None:+ source = _DownloadStream(block=True)+ adapter, response = download_adapter(source)+ try:+ chunks = await adapter.read_bytes_stream("/tmp/file", chunk_size=4)+ assert await anext(chunks) == b"abcd"+ task = asyncio.create_task(anext(chunks))+ try:+ await asyncio.wait_for(source.reading.wait(), timeout=5)+ finally:+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await task+ assert source.closed+ assert response.is_closed+ finally:+ await response.aclose()+ await adapter._httpx_client.aclose()+++async def test_download_http_error_releases_response(download_adapter: _AdapterFactory) -> None:+ source = _DownloadStream()+ adapter, response = download_adapter(source, status_code=404)+ try:+ with pytest.raises(SandboxApiException) as exc:+ await adapter.read_bytes_stream("/tmp/missing")+ assert exc.value.status_code == 404+ assert source.closed+ assert response.is_closed+ finally:+ await response.aclose()+ await adapter._httpx_client.aclose()