Stream SDK file uploads and downloads instead of buffering in memory

[mishushakov]

Description

Removes full in-memory buffering from the SDK sandbox file-transfer paths, in both JS and Python (sync + async).

Streamed uploads — Sandbox.files.write / write_files streams ReadableStream (JS, outside the browser) and file-like (Python) input to the sandbox with chunk-by-chunk gzip compression, instead of buffering the whole body in memory. useOctetStream/use_octet_stream now defaults to auto-detect — octet-stream when any entry is streamable (so streamed uploads aren't silently buffered), multipart/form-data otherwise; browsers always use multipart/form-data since streaming request bodies aren't supported there. A streamed upload is bounded by a per-chunk timeout on the wire (Python's per-write httpx timeout, default the request timeout); a stalled upload the wire can't observe is bounded server-side. On Python's AsyncSandbox, the blocking file reads and gzip compression of a streamed upload now run in a worker thread so a large upload doesn't stall the event loop.

Streamed downloads — Sandbox.files.read(format="stream") now streams the response body from the sandbox instead of downloading it into memory before iterating (Python sync + async), and the 60s request timeout no longer kills the stream while it's being consumed:

• The request timeout now bounds only the initial handshake.
• The body is bounded by a per-chunk idle-read timeout on the wire — a per-read() option (streamIdleTimeoutMs in JS, stream_idle_timeout in Python; default the request timeout — 60s — 0/None to disable). It's armed only while waiting on a network read and cleared the moment a chunk arrives, so it aborts only when the server stops sending mid-stream; a slow or paused consumer never trips it (a held-but-unread stream is reclaimed server-side, not by this timer).
• A dropped connection during the handshake surfaces the same typed, health-checked error as non-stream reads. In JS, signal can still cancel an in-flight stream.
• The stream holds its pooled connection until it is consumed to the end, cancelled/closed, errors, or the idle timeout fires — consume it fully, use the context manager, or close it. (This replaces the earlier GC-finalizer net.) Python returns a FileStreamReader/AsyncFileStreamReader supporting deterministic cleanup via close()/aclose() and (async) context-manager use; both still satisfy Iterator[bytes]/AsyncIterator[bytes], so existing iteration is unchanged.

Empty files — JS Sandbox.files.read() with blob or stream format now returns a format-correct empty value (empty Blob / empty ReadableStream) for empty files instead of "".

Note

The equivalent volume streaming changes (Volume.writeFile/write_file, Volume.readFile/read_file streams) live in a follow-up PR, #1453, which is based on this branch.

Usage

// JS: upload a large file without holding it in memory
const file = createReadStream('large.bin')
await sandbox.files.write('large.bin', Readable.toWeb(file), { gzip: true })

// JS: consume a download for longer than 60s without it being killed
const stream = await sandbox.files.read('large.bin', { format: 'stream' })
for await (const chunk of stream) { /* ... */ }

// JS: tune (or disable) the per-chunk idle-read timeout for a read
const stream = await sandbox.files.read('large.bin', {
  format: 'stream',
  streamIdleTimeoutMs: 120_000, // 0 to disable
})

// JS: empty files now return format-correct empty values
const blob = await sandbox.files.read('empty.txt', { format: 'blob' }) // Blob (size 0), not ''

# Python: streamed upload and download
with open("large.bin", "rb") as f:
    sandbox.files.write("large.bin", f, gzip=True)

for chunk in sandbox.files.read("large.bin", format="stream"):
    ...

# Python: deterministic cleanup when not reading the stream to the end
with sandbox.files.read("large.bin", format="stream") as stream:
    first_chunk = next(iter(stream))  # connection released on block exit

# Python: tune (or disable) the per-chunk idle-read timeout for a read
for chunk in sandbox.files.read(
    "large.bin", format="stream", stream_idle_timeout=120.0  # None to disable
):
    ...

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Touches core HTTP file transfer, timeout semantics, and connection pooling in both SDKs; behavior changes (defaults, stream lifetime) are subtle but covered by new unit and sandbox tests.

Overview
JS and Python sandbox file I/O no longer buffers entire stream bodies in memory for the common streaming paths, with tighter timeout and connection lifecycle behavior.

Uploads: files.write / write_files send ReadableStream (JS, non-browser) and file-like IO (Python) as chunked octet-stream bodies, including chunk-by-chunk gzip. useOctetStream / use_octet_stream defaults to auto-detect (octet-stream when any entry is streamable so uploads aren’t silently buffered via multipart). JS streamed uploads use duplex: 'half' and skip the normal request timeout on the wire; async Python moves blocking read/gzip work to worker threads via new io_utils helpers.

Downloads: read({ format: 'stream' }) uses a handshake-only request timeout plus a wire idle timeout (streamIdleTimeoutMs / stream_idle_timeout, default 60s) that fires only when the server stops sending mid-read—not when the consumer is slow. JS adds wrapStreamWithConnectionCleanup to release pooled connections on finish, cancel, error, or idle abort; Python returns FileStreamReader / AsyncFileStreamReader that own the httpx response and support close() / context managers. Stream handshake failures get the same health-checked errors as non-stream reads.

Other: Empty files in JS blob / stream reads return empty Blob / ReadableStream instead of "".

^{Reviewed by Cursor Bugbot for commit 4351aae. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4351aae

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
e2b	Patch
@e2b/python-sdk	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Package Artifacts

Built from d182095. Download artifacts from this workflow run.

JS SDK (e2b@2.30.3-mishushakov-stream-write-file-upload.0):

npm install ./e2b-2.30.3-mishushakov-stream-write-file-upload.0.tgz

CLI (@e2b/cli@2.12.1-mishushakov-stream-write-file-upload.0):

npm install ./e2b-cli-2.12.1-mishushakov-stream-write-file-upload.0.tgz

Python SDK (e2b==2.29.2+mishushakov-stream-write-file-upload):

pip install ./e2b-2.29.2+mishushakov.stream.write.file.upload-py3-none-any.whl

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6cda03fa92

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[matthewlouisbrockman]

this will leak the connection if we don't use it right? do we need to 404 immediately vs wait to actually use it?

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[mishushakov]

I will wait with this PR until we have server-side connection handling for dropping idle clients.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4351aae. Configure here.}

[matthewlouisbrockman]

lgtm