Stream SDK file uploads and downloads instead of buffering in memory

.changeset/cuddly-pots-stream.md

@@ -0,0 +1,11 @@
+---
+"e2b": patch
+"@e2b/python-sdk": patch
+---
+
+Stream uploads instead of buffering streaming input entirely in memory:
+
+- `Sandbox.files.write()` / `write_files()`: `ReadableStream` data (JS, outside the browser) and file-like objects (Python) are streamed to the sandbox, including when `gzip` is enabled (compression now happens chunk by chunk). `useOctetStream`/`use_octet_stream` now defaults to auto-detect — octet-stream is used when any entry is streamable (so streamed uploads aren't silently buffered) and `multipart/form-data` otherwise; browsers always use `multipart/form-data`. A streamed upload is bounded by a per-chunk idle timeout (`streamIdleTimeoutMs` in JS, default the request timeout, `0` to disable) that aborts a stalled upload — a producer that stops yielding or a server that stops reading — so a stall no longer holds the connection indefinitely. 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.
+- `Sandbox.files.read(format="stream")`: the request timeout now bounds only the initial handshake instead of killing the stream while it's being consumed. The body is bounded by a per-chunk idle timeout (`streamIdleTimeoutMs` in JS, `stream_idle_timeout` in Python, default the request timeout — 60s — `0`/`None` to disable) that bounds a stalled stream without limiting an actively-flowing one. Use `signal` (JS) to cancel an in-flight stream. A dropped connection during the stream handshake now surfaces the same typed, health-checked error as non-stream reads. The stream holds a 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.
+- Python `Sandbox.files.read(format="stream")`: the response body is now streamed from the sandbox instead of being downloaded into memory before iteration (sync and async).
+- JS `Sandbox.files.read()` with `blob` or `stream` format now returns an empty `Blob`/`ReadableStream` for empty files instead of `""`.

packages/js-sdk/src/connectionConfig.ts

@@ -201,6 +201,160 @@ export function setupRequestController(
   return { controller, clearStartTimeout, cleanup }
 }
 
+/**
+ * Create a resettable idle-timeout that aborts `controller` when no progress is
+ * made within `idleTimeoutMs`. `arm` (re)starts the timer; call it on each
+ * chunk. `clear` stops it. `0`/`undefined` disables it (both are no-ops).
+ *
+ * @internal
+ */
+function createIdleAbort(
+  controller: AbortController,
+  idleTimeoutMs: number | undefined,
+  label: string
+): { arm: () => void; clear: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const clear = () => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+  }
+  const arm = () => {
+    if (!idleTimeoutMs) return
+    clear()
+    timer = setTimeout(
+      () =>
+        controller.abort(
+          new DOMException(
+            `${label} idle for ${idleTimeoutMs}ms`,
+            'TimeoutError'
+          )
+        ),
+      idleTimeoutMs
+    )
+  }
+  return { arm, clear }
+}
+
+/**
+ * Wrap a streaming response body so its pooled connection is released when the
+ * stream is fully read, cancelled, errors, or stays idle for too long.
+ *
+ * Clears the handshake timeout from {@link setupRequestController} (so
+ * consuming the body isn't killed by it) and replaces it with an idle-read
+ * timeout: if no chunk arrives within `idleTimeoutMs` it aborts `controller`,
+ * tearing down the fetch and releasing the connection. The timer resets on
+ * every chunk, so it bounds a stalled stream without limiting an
+ * actively-flowing one. Pass `0`/`undefined` to disable. Call once the
+ * handshake has succeeded.
+ *
+ * @internal
+ */
+export function wrapStreamWithConnectionCleanup(
+  body: ReadableStream<Uint8Array> | null,
+  {
+    clearStartTimeout,
+    cleanup,
+    controller,
+    idleTimeoutMs,
+  }: {
+    clearStartTimeout: () => void
+    cleanup: () => void
+    controller: AbortController
+    idleTimeoutMs?: number
+  }
+): ReadableStream<Uint8Array> {
+  clearStartTimeout()
+
+  if (!body) {
+    cleanup()
+    return new Blob([]).stream()
+  }
+
+  const reader = body.getReader()
+  const idle = createIdleAbort(controller, idleTimeoutMs, 'Stream')
+
+  // Idempotent: safe to call from multiple stream callbacks.
+  const release = () => {
+    idle.clear()
+    cleanup()
+  }
+
+  return new ReadableStream<Uint8Array>({
+    start() {
+      idle.arm()
+    },
+    async pull(streamController) {
+      try {
+        const { done, value } = await reader.read()
+        if (done) {
+          release()
+          streamController.close()
+        } else {
+          idle.arm()
+          streamController.enqueue(value)
+        }
+      } catch (err) {
+        release()
+        streamController.error(err)
+      }
+    },
+    async cancel(reason) {
+      try {
+        await reader.cancel(reason)
+      } finally {
+        release()
+      }
+    },
+  })
+}
+
+/**
+ * Wrap an outgoing (upload) request body so the request is aborted if no chunk
+ * is sent within `idleTimeoutMs`. The timer resets on every chunk, bounding a
+ * stalled upload — a producer that stops yielding or a server that stops
+ * reading — without limiting an actively-flowing one. Pass `0`/`undefined` to
+ * disable, returning the body unwrapped.
+ *
+ * @internal
+ */
+export function wrapUploadStreamWithIdleTimeout(
+  body: ReadableStream<Uint8Array>,
+  controller: AbortController,
+  idleTimeoutMs?: number
+): ReadableStream<Uint8Array> {
+  if (!idleTimeoutMs) return body
+
+  const reader = body.getReader()
+  const idle = createIdleAbort(controller, idleTimeoutMs, 'Upload')
+
+  return new ReadableStream<Uint8Array>({
+    start() {
+      idle.arm()
+    },
+    async pull(streamController) {
+      try {
+        const { done, value } = await reader.read()
+        if (done) {
+          idle.clear()
+          streamController.close()
+        } else {
+          idle.arm()
+          streamController.enqueue(value)
+        }
+      } catch (err) {
+        idle.clear()
+        streamController.error(err)
+      }
+    },
+    async cancel(reason) {
+      idle.clear()
+      await reader.cancel(reason)
+    },
+  })
+}
+
 function buildUserAgent(integration?: string) {
   const userAgentParts = [`e2b-js-sdk/${version}`]