Fix volume SDK issues: transports, timeouts, empty files, eager stream errors (#1431)

Fixes a batch of review findings in the JS and Python volume SDKs,
aligning behavior between the two. Python now caches `AsyncVolume` HTTP
transports per event loop and proxy (sync per thread) instead of a
process-wide singleton, applies the 60s default `request_timeout` to
metadata operations that previously ran with httpx timeouts disabled, no
longer falls back to `E2B_ACCESS_TOKEN` for volume content auth, and no
longer mutates the caller's `headers` dict. JS `Volume.readFile` now
returns empty values instead of `undefined` for empty files, and volume
content requests get the documented 60s default request timeout. All
changes are covered by new mock-based unit tests (no live API needed)
plus changesets for both SDKs.

## Usage examples

```python
volume = await AsyncVolume.connect(volume_id)

# Times out after 60s by default (previously could hang indefinitely)
entries = await volume.list("/")
```

```ts
const volume = await Volume.connect(volumeId)

// Returns an empty Blob / ReadableStream for empty files (previously undefined)
const blob = await volume.readFile('empty.txt', { format: 'blob' })

// Times out after the documented 60s by default; pass 0 to disable
await volume.getInfo('file.txt', { requestTimeoutMs: 0 })
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: mishushakov

.changeset/great-pears-search.md

@@ -0,0 +1,10 @@
+---
+"@e2b/python-sdk": patch
+---
+
+Fix several issues in the volume content API client:
+
+- `AsyncVolume` HTTP transports are now cached per event loop (and per proxy) instead of a process-wide singleton, and sync transports are cached per thread.
+- Volume metadata operations (`list`, `make_dir`, `get_info`, `update_metadata`, `remove`) now respect `request_timeout` (60s by default) instead of running with httpx timeouts disabled.
+- Volume content auth no longer falls back to the `E2B_ACCESS_TOKEN` environment variable; it requires the volume token, matching the JS SDK.
+- `VolumeConnectionConfig` no longer mutates the caller's `headers` dict.

.changeset/heavy-pots-repair.md

@@ -0,0 +1,5 @@
+---
+"e2b": patch
+---
+
+Fix `Volume.readFile` returning `undefined` instead of an empty `Blob`/`ReadableStream` for empty files, and apply the documented 60s default request timeout to volume content requests.

packages/js-sdk/src/volume/client.ts

@@ -7,6 +7,7 @@ import { buildRequestSignal } from '../connectionConfig'
 import { createApiLogger, Logger } from '../logs'
 import type { Volume } from './index'
 
+const REQUEST_TIMEOUT_MS = 60_000 // 60 seconds
 const FILE_TIMEOUT_MS = 3_600_000 // 1 hour
 
 export interface VolumeApiOpts {
@@ -72,7 +73,7 @@ export class VolumeConnectionConfig {
   readonly token?: string
   readonly headers?: Record<string, string>
   readonly logger?: Logger
-  readonly requestTimeoutMs?: number
+  readonly requestTimeoutMs: number
   readonly signal?: AbortSignal
   readonly proxy?: string
 
@@ -86,7 +87,7 @@ export class VolumeConnectionConfig {
     this.token = opts?.token || volume.token
     this.headers = opts?.headers
     this.logger = opts?.logger
-    this.requestTimeoutMs = opts?.requestTimeoutMs
+    this.requestTimeoutMs = opts?.requestTimeoutMs ?? REQUEST_TIMEOUT_MS
     this.signal = opts?.signal
     this.proxy = opts?.proxy || volume.proxy
   }

packages/js-sdk/src/volume/index.ts

@@ -561,19 +561,22 @@ export class Volume {
       throw err
     }
 
+    // When the file is empty, `res.data` is `undefined`, so empty values are synthesized below.
     if (format === 'bytes') {
-      return new Uint8Array(res.data as ArrayBuffer)
+      return res.data instanceof ArrayBuffer
+        ? new Uint8Array(res.data)
+        : new Uint8Array()
     }
 
     if (format === 'text') {
-      // When the file is empty, res.data is parsed as `{}`. This is a workaround to return an empty string.
-      if (res.response.headers.get('content-length') === '0') {
-        return ''
-      }
       return typeof res.data === 'string' ? res.data : ''
     }
 
-    return res.data
+    if (format === 'blob') {
+      return res.data instanceof Blob ? res.data : new Blob([])
+    }
+
+    return res.data instanceof ReadableStream ? res.data : new Blob([]).stream()
   }
 
   /**

packages/js-sdk/tests/volume/volume.test.ts

@@ -13,6 +13,9 @@ const volumes = new Map<
   { volumeID: string; name: string; token: string }
 >()
 
+// In-memory store for mock volume file contents, keyed by path
+const volumeFiles = new Map<string, string>()
+
 const restHandlers = [
   // POST /volumes - create (returns VolumeAndToken)
   http.post(apiUrl('/volumes'), async ({ request }) => {
@@ -58,6 +61,22 @@ const restHandlers = [
       return new HttpResponse(null, { status: 204 })
     }
   ),
+
+  // GET /volumecontent/:volumeID/file - read file content
+  http.get(apiUrl('/volumecontent/:volumeID/file'), ({ request }) => {
+    const path = new URL(request.url).searchParams.get('path') ?? ''
+    const content = volumeFiles.get(path)
+    if (content === undefined) {
+      return HttpResponse.json(
+        { code: 404, message: 'Not found' },
+        { status: 404 }
+      )
+    }
+    return new HttpResponse(content.length > 0 ? content : null, {
+      status: 200,
+      headers: { 'Content-Length': String(content.length) },
+    })
+  }),
 ]
 
 const server = setupServer(...restHandlers)
@@ -67,6 +86,7 @@ afterAll(() => server.close())
 afterEach(() => {
   server.resetHandlers()
   volumes.clear()
+  volumeFiles.clear()
 })
 
 describe('Volume CRUD', () => {
@@ -187,3 +207,84 @@ describe('Volume CRUD', () => {
     expect(listAfter).toHaveLength(0)
   })
 })
+
+describe('Volume content readFile', () => {
+  it('should return content for a non-empty file in every format', async () => {
+    volumeFiles.set('hello.txt', 'hello world')
+    const vol = await Volume.create('content-volume')
+
+    const text = await vol.readFile('hello.txt')
+    expect(text).toBe('hello world')
+
+    const bytes = await vol.readFile('hello.txt', { format: 'bytes' })
+    expect(bytes).toBeInstanceOf(Uint8Array)
+    expect(new TextDecoder().decode(bytes)).toBe('hello world')
+
+    const blob = await vol.readFile('hello.txt', { format: 'blob' })
+    expect(blob).toBeInstanceOf(Blob)
+    expect(await blob.text()).toBe('hello world')
+
+    const stream = await vol.readFile('hello.txt', { format: 'stream' })
+    expect(stream).toBeInstanceOf(ReadableStream)
+    expect(await new Response(stream).text()).toBe('hello world')
+  })
+
+  it('should return empty values for an empty file in every format', async () => {
+    volumeFiles.set('empty.txt', '')
+    const vol = await Volume.create('content-volume')
+
+    const text = await vol.readFile('empty.txt')
+    expect(text).toBe('')
+
+    const bytes = await vol.readFile('empty.txt', { format: 'bytes' })
+    expect(bytes).toBeInstanceOf(Uint8Array)
+    expect(bytes.length).toBe(0)
+
+    const blob = await vol.readFile('empty.txt', { format: 'blob' })
+    expect(blob).toBeInstanceOf(Blob)
+    expect(blob.size).toBe(0)
+
+    const stream = await vol.readFile('empty.txt', { format: 'stream' })
+    expect(stream).toBeInstanceOf(ReadableStream)
+    expect(await new Response(stream).text()).toBe('')
+  })
+
+  it('should throw NotFoundError for a missing file', async () => {
+    const vol = await Volume.create('content-volume')
+
+    await expect(vol.readFile('missing.txt')).rejects.toThrow(NotFoundError)
+  })
+
+  it('should reject at call time for a missing file with stream format', async () => {
+    const vol = await Volume.create('content-volume')
+
+    await expect(
+      vol.readFile('missing.txt', { format: 'stream' })
+    ).rejects.toThrow(NotFoundError)
+  })
+})
+
+describe('VolumeConnectionConfig request timeout', () => {
+  it('should default the request timeout to 60 seconds', async () => {
+    const vol = await Volume.create('timeout-volume')
+
+    const config = new VolumeConnectionConfig(vol)
+    expect(config.requestTimeoutMs).toBe(60_000)
+    expect(config.getSignal()).toBeInstanceOf(AbortSignal)
+  })
+
+  it('should let a per-call timeout override the default', async () => {
+    const vol = await Volume.create('timeout-volume')
+
+    const config = new VolumeConnectionConfig(vol, { requestTimeoutMs: 1_000 })
+    expect(config.requestTimeoutMs).toBe(1_000)
+  })
+
+  it('should disable the timeout when requestTimeoutMs is 0', async () => {
+    const vol = await Volume.create('timeout-volume')
+
+    const config = new VolumeConnectionConfig(vol, { requestTimeoutMs: 0 })
+    expect(config.requestTimeoutMs).toBe(0)
+    expect(config.getSignal()).toBeUndefined()
+  })
+})

packages/python-sdk/e2b/volume/client_async/__init__.py

@@ -1,9 +1,11 @@
+import asyncio
 import logging
 import os
-from typing import Optional
+from typing import Dict, Optional, Tuple
 
 import httpx
 from httpx import Limits
+from httpx._types import ProxyTypes
 
 from e2b.api.metadata import default_headers
 from e2b.exceptions import AuthenticationException
@@ -18,32 +20,40 @@
     keepalive_expiry=int(os.getenv("E2B_KEEPALIVE_EXPIRY", "300")),
 )
 
+TransportKey = Tuple[int, Optional[ProxyTypes]]
+
 
 def get_api_client(config: VolumeConnectionConfig, **kwargs) -> AsyncVolumeApiClient:
     if config.access_token is None:
         raise AuthenticationException(
-            "Access token is required for volume operations. "
-            "Set `E2B_ACCESS_TOKEN` or pass `token` in options.",
+            "Volume token is required for volume content operations. "
+            "Use `AsyncVolume.create`/`AsyncVolume.connect` to obtain it "
+            "or pass `token` in options.",
         )
 
     headers = {
         **default_headers,
         **(config.headers or {}),
     }
 
+    request_timeout = config.request_timeout
+
     return AsyncVolumeApiClient(
         base_url=config.api_url,
         token=config.access_token,
         auth_header_name="Authorization",
         prefix="Bearer",
         headers=headers,
+        timeout=(
+            httpx.Timeout(request_timeout) if request_timeout is not None else None
+        ),
         httpx_args={"proxy": config.proxy, "transport": get_transport(config)},
         **kwargs,
     )
 
 
 class AsyncTransportWithLogger(httpx.AsyncHTTPTransport):
-    singleton: Optional["AsyncTransportWithLogger"] = None
+    _instances: Dict[TransportKey, "AsyncTransportWithLogger"] = {}
 
     async def handle_async_request(self, request):
         url = f"{request.url.scheme}://{request.url.host}{request.url.path}"
@@ -58,12 +68,14 @@ def pool(self):
 
 
 def get_transport(config: VolumeConnectionConfig) -> AsyncTransportWithLogger:
-    if AsyncTransportWithLogger.singleton is not None:
-        return AsyncTransportWithLogger.singleton
+    key: TransportKey = (id(asyncio.get_running_loop()), config.proxy)
+
+    if key in AsyncTransportWithLogger._instances:
+        return AsyncTransportWithLogger._instances[key]
 
     transport = AsyncTransportWithLogger(
         limits=limits,
         proxy=config.proxy,
     )
-    AsyncTransportWithLogger.singleton = transport
+    AsyncTransportWithLogger._instances[key] = transport
     return transport

packages/python-sdk/e2b/volume/client_sync/__init__.py

@@ -1,9 +1,11 @@
 import logging
 import os
-from typing import Optional
+import threading
+from typing import Dict, Optional
 
 import httpx
 from httpx import Limits
+from httpx._types import ProxyTypes
 
 from e2b.api.metadata import default_headers
 from e2b.exceptions import AuthenticationException
@@ -18,32 +20,40 @@
     keepalive_expiry=int(os.getenv("E2B_KEEPALIVE_EXPIRY", "300")),
 )
 
+TransportKey = Optional[ProxyTypes]
+
 
 def get_api_client(config: VolumeConnectionConfig, **kwargs) -> VolumeApiClient:
     if config.access_token is None:
         raise AuthenticationException(
-            "Access token is required for volume operations. "
-            "Set `E2B_ACCESS_TOKEN` or pass `token` in options.",
+            "Volume token is required for volume content operations. "
+            "Use `Volume.create`/`Volume.connect` to obtain it "
+            "or pass `token` in options.",
         )
 
     headers = {
         **default_headers,
         **(config.headers or {}),
     }
 
+    request_timeout = config.request_timeout
+
     return VolumeApiClient(
         base_url=config.api_url,
         token=config.access_token,
         auth_header_name="Authorization",
         prefix="Bearer",
         headers=headers,
+        timeout=(
+            httpx.Timeout(request_timeout) if request_timeout is not None else None
+        ),
         httpx_args={"proxy": config.proxy, "transport": get_transport(config)},
         **kwargs,
     )
 
 
 class TransportWithLogger(httpx.HTTPTransport):
-    singleton: Optional["TransportWithLogger"] = None
+    _thread_local = threading.local()
 
     def handle_request(self, request):
         url = f"{request.url.scheme}://{request.url.host}{request.url.path}"
@@ -58,12 +68,18 @@ def pool(self):
 
 
 def get_transport(config: VolumeConnectionConfig) -> TransportWithLogger:
-    if TransportWithLogger.singleton is not None:
-        return TransportWithLogger.singleton
+    instances: Dict[TransportKey, TransportWithLogger] = getattr(
+        TransportWithLogger._thread_local, "instances", {}
+    )
+    key: TransportKey = config.proxy
+    cached = instances.get(key)
+    if cached is not None:
+        return cached
 
     transport = TransportWithLogger(
         limits=limits,
         proxy=config.proxy,
     )
-    TransportWithLogger.singleton = transport
+    instances[key] = transport
+    TransportWithLogger._thread_local.instances = instances
     return transport

packages/python-sdk/e2b/volume/connection_config.py

@@ -57,10 +57,6 @@ def _debug():
     def _volume_api_url():
         return os.getenv("E2B_VOLUME_API_URL")
 
-    @staticmethod
-    def _access_token():
-        return os.getenv("E2B_ACCESS_TOKEN")
-
     @staticmethod
     def _get_request_timeout(
         default_timeout: Optional[float],
@@ -91,11 +87,11 @@ def __init__(
             or self._volume_api_url()
             or ("http://localhost:8080" if self.debug else f"https://api.{self.domain}")
         )
-        self.access_token = token or self._access_token()
+        self.access_token = token
         self.token = self.access_token
         self.proxy = proxy
 
-        self.headers = headers or {}
+        self.headers = dict(headers) if headers else {}
         self.headers["User-Agent"] = f"e2b-python-sdk/{package_version}"
 
         self.request_timeout = self._get_request_timeout(