Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

fix(sdk): correct filesystem watch handle callback and timeout behavior (#1480)

Mish Ushakovde0c401626c7
diff --git a/.changeset/watch-handle-fixes.md b/.changeset/watch-handle-fixes.md
new file mode 100644
index 000000000..4db54305e
--- /dev/null
+++ b/.changeset/watch-handle-fixes.md
@@ -0,0 +1,10 @@
+---
+"@e2b/python-sdk": patch
+"e2b": patch
+---
+
+Fix three filesystem watch handle bugs:
+
+- **JS**: `WatchHandle` now awaits async `onEvent`/`onExit` callbacks. A rejecting async `onEvent` is routed to `onExit` and stops the watch instead of becoming an unhandled promise rejection that can crash Node, and async callbacks get backpressure/ordering — matching `CommandHandle`.
+- **Python (sync)**: `WatchHandle.get_new_events()` and `stop()` now send a request timeout (default 60s, overridable via `request_timeout`) so a stalled call can't hang the thread forever, and include the authentication header so the polling/stop calls aren't sent unauthenticated on older envd.
+- **Python (async)**: `AsyncWatchHandle` now invokes `on_exit` when the stream ends cleanly (with `None`) and when `stop()` is called, in addition to on error — matching the JS SDK.
diff --git a/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts b/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts
index 9d55573b6..cf16fc6a7 100644
--- a/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts
+++ b/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts
@@ -109,6 +109,7 @@ export class WatchHandle {
}
private async handleEvents() {
+ let iterationError: Error | undefined
try {
for await (const event of this.iterateEvents()) {
const eventType = mapEventType(event.value.type)
@@ -116,7 +117,11 @@ export class WatchHandle {
continue
}
- this.onEvent?.({
+ // Await the callback so an async `onEvent` that rejects is routed to
+ // `onExit` below (instead of becoming an unhandled promise rejection
+ // that can crash Node) and so the user can apply backpressure. Mirrors
+ // `CommandHandle.handleEvents`.
+ await this.onEvent?.({
name: event.value.name,
type: eventType,
entry: event.value.entry
@@ -124,9 +129,22 @@ export class WatchHandle {
: undefined,
})
}
- this.onExit?.()
} catch (err) {
- this.onExit?.(err as Error)
+ iterationError = err as Error
+ }
+
+ try {
+ // Invoke `onExit` exactly once: with the error when the watch ended
+ // because of one, or with no argument on a clean end.
+ if (iterationError) {
+ await this.onExit?.(iterationError)
+ } else {
+ await this.onExit?.()
+ }
+ } catch {
+ // `onExit` is the terminal callback; an error it throws has nowhere to
+ // propagate in this detached handler, so it's swallowed to avoid an
+ // unhandled promise rejection (the failure mode this guards against).
} finally {
this.handleStop()
}
diff --git a/packages/js-sdk/tests/sandbox/files/watchHandle.test.ts b/packages/js-sdk/tests/sandbox/files/watchHandle.test.ts
new file mode 100644
index 000000000..d4c4dc4f1
--- /dev/null
+++ b/packages/js-sdk/tests/sandbox/files/watchHandle.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { EventType } from '../../../src/envd/filesystem/filesystem_pb'
+import {
+ FilesystemEventType,
+ WatchHandle,
+} from '../../../src/sandbox/filesystem/watchHandle'
+
+function filesystemEvent(name: string, type: EventType = EventType.WRITE) {
+ return {
+ event: {
+ case: 'filesystem' as const,
+ value: { name, type, entry: undefined },
+ },
+ }
+}
+
+function events(items: ReturnType<typeof filesystemEvent>[]) {
+ async function* gen() {
+ for (const item of items) {
+ yield item as any
+ }
+ }
+ return gen()
+}
+
+describe('WatchHandle', () => {
+ it('awaits an async onEvent before finishing and firing onExit', async () => {
+ let callbackStarted = false
+ let releaseCallback: (() => void) | undefined
+ const callbackBlocked = new Promise<void>((resolve) => {
+ releaseCallback = resolve
+ })
+
+ const onEvent = async () => {
+ callbackStarted = true
+ await callbackBlocked
+ }
+
+ let exitCalled = false
+ const onExit = () => {
+ exitCalled = true
+ }
+
+ new WatchHandle(
+ () => {},
+ events([filesystemEvent('a.txt')]),
+ onEvent,
+ onExit
+ )
+
+ await vi.waitFor(() => {
+ expect(callbackStarted).toBe(true)
+ })
+ // onExit must not fire while onEvent is still pending.
+ expect(exitCalled).toBe(false)
+
+ releaseCallback?.()
+ await vi.waitFor(() => {
+ expect(exitCalled).toBe(true)
+ })
+ })
+
+ it('routes a rejecting async onEvent to onExit and stops the watch', async () => {
+ const error = new Error('callback failed')
+
+ let stopped = false
+ let exitErr: Error | undefined | 'unset' = 'unset'
+
+ new WatchHandle(
+ () => {
+ stopped = true
+ },
+ events([filesystemEvent('a.txt')]),
+ async () => {
+ throw error
+ },
+ (err) => {
+ exitErr = err ?? undefined
+ }
+ )
+
+ await vi.waitFor(() => {
+ expect(exitErr).not.toBe('unset')
+ })
+ expect(exitErr).toBe(error)
+ expect(stopped).toBe(true)
+ })
+
+ it('calls onExit with no argument when the stream ends cleanly', async () => {
+ const received: FilesystemEventType[] = []
+ let exitArgs: unknown[] | undefined
+
+ new WatchHandle(
+ () => {},
+ events([filesystemEvent('a.txt')]),
+ (event) => {
+ received.push(event.type)
+ },
+ (...args: unknown[]) => {
+ exitArgs = args
+ }
+ )
+
+ await vi.waitFor(() => {
+ expect(exitArgs).toBeDefined()
+ })
+ // No error is passed on a clean exit — onExit is called with zero args.
+ expect(exitArgs).toEqual([])
+ expect(received).toEqual([FilesystemEventType.WRITE])
+ })
+
+ it('does not let a throwing onExit become an unhandled rejection', async () => {
+ let stopped = false
+
+ new WatchHandle(
+ () => {
+ stopped = true
+ },
+ events([filesystemEvent('a.txt')]),
+ () => {},
+ () => {
+ throw new Error('onExit failed')
+ }
+ )
+
+ // handleStop runs after onExit, so observing the stop confirms the loop
+ // ran the throwing onExit to completion. A leaked rejection would fail the
+ // test run instead.
+ await vi.waitFor(() => {
+ expect(stopped).toBe(true)
+ })
+ })
+})
diff --git a/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py b/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py
index eb6dd82c2..63306ebc3 100644
--- a/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py
+++ b/packages/python-sdk/e2b/sandbox_async/filesystem/filesystem.py
@@ -639,7 +639,7 @@ class Filesystem:
self,
path: str,
on_event: OutputHandler[FilesystemEvent],
- on_exit: Optional[OutputHandler[Exception]] = None,
+ on_exit: Optional[OutputHandler[Optional[Exception]]] = None,
user: Optional[Username] = None,
request_timeout: Optional[float] = None,
timeout: Optional[float] = 60,
@@ -652,7 +652,7 @@ class Filesystem:
:param path: Path to a directory to watch
:param on_event: Callback to call on each event in the directory
- :param on_exit: Callback to call when the watching ends
+ :param on_exit: Callback to call when the watching ends. It receives the error that ended the watch, or `None` on a clean end or when `stop()` is called
:param user: Run the operation as this user
:param request_timeout: Timeout for the request in **seconds**
:param timeout: Timeout for the watch operation in **seconds**. Using `0` will not limit the watch time
diff --git a/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.py b/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.py
index 092b066f3..814b46508 100644
--- a/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.py
+++ b/packages/python-sdk/e2b/sandbox_async/filesystem/watch_handle.py
@@ -21,7 +21,7 @@ class AsyncWatchHandle:
self,
events: AsyncGenerator[WatchDirResponse, Any],
on_event: OutputHandler[FilesystemEvent],
- on_exit: Optional[OutputHandler[Exception]] = None,
+ on_exit: Optional[OutputHandler[Optional[Exception]]] = None,
check_health: Optional[Callable[[], Awaitable[Optional[bool]]]] = None,
):
self._events = events
@@ -60,14 +60,38 @@ class AsyncWatchHandle:
except Exception as e:
raise await ahandle_rpc_exception_with_health(e, self._check_health)
+ async def _call_on_exit(self, error: Optional[Exception]):
+ if self._on_exit is None:
+ return
+ try:
+ cb = self._on_exit(error)
+ if inspect.isawaitable(cb):
+ await cb
+ except Exception:
+ # `on_exit` is the terminal callback; an error it raises has nowhere
+ # to propagate in this background task, so it's swallowed to avoid an
+ # "Task exception was never retrieved" warning. A `CancelledError`
+ # (a `BaseException`) is intentionally not caught here.
+ pass
+
async def _handle_events(self):
+ error: Optional[Exception] = None
try:
async for event in self._iterate_events():
cb = self._on_event(event)
if inspect.isawaitable(cb):
await cb
+ except asyncio.CancelledError:
+ # `stop()` cancels this task to end the watch. Treat it as a clean,
+ # user-initiated end: fire `on_exit` (with no error), then propagate
+ # the cancellation so the task still finishes as cancelled.
+ await self._call_on_exit(None)
+ raise
except Exception as e:
- if self._on_exit:
- cb = self._on_exit(e)
- if inspect.isawaitable(cb):
- await cb
+ error = e
+
+ # `on_exit` fires exactly once when the watch ends — with the error when
+ # the stream failed, or with `None` on a clean end. This matches the JS
+ # SDK, which calls `onExit()` after the loop completes and `onExit(err)`
+ # on error.
+ await self._call_on_exit(error)
diff --git a/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py b/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py
index 69ed1a001..b652572f7 100644
--- a/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py
+++ b/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py
@@ -700,5 +700,8 @@ class Filesystem:
return WatchHandle(
lambda: self._rpc,
r.watcher_id,
+ self._connection_config,
+ self._envd_version,
+ user,
lambda: check_sandbox_health(self._envd_api),
)
diff --git a/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.py b/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.py
index 84370e013..7d14b25f0 100644
--- a/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.py
+++ b/packages/python-sdk/e2b/sandbox_sync/filesystem/watch_handle.py
@@ -1,12 +1,15 @@
from typing import Callable, List, Optional
+from packaging.version import Version
+
from e2b import SandboxException
+from e2b.connection_config import ConnectionConfig, Username
from e2b.envd.filesystem import filesystem_connect
from e2b.envd.filesystem.filesystem_pb2 import (
GetWatcherEventsRequest,
RemoveWatcherRequest,
)
-from e2b.envd.rpc import handle_rpc_exception_with_health
+from e2b.envd.rpc import authentication_header, handle_rpc_exception_with_health
from e2b.sandbox.filesystem.filesystem import map_entry_info
from e2b.sandbox.filesystem.watch_handle import FilesystemEvent, map_event_type
@@ -23,31 +26,47 @@ class WatchHandle:
self,
get_rpc: Callable[[], filesystem_connect.FilesystemClient],
watcher_id: str,
+ connection_config: ConnectionConfig,
+ envd_version: Version,
+ user: Optional[Username] = None,
check_health: Optional[Callable[[], Optional[bool]]] = None,
):
self._get_rpc = get_rpc
self._watcher_id = watcher_id
+ self._connection_config = connection_config
+ self._envd_version = envd_version
+ self._user = user
self._check_health = check_health
self._closed = False
- def stop(self):
+ def stop(self, request_timeout: Optional[float] = None):
"""
Stop watching the directory.
After you stop the watcher you won't be able to get the events anymore.
+
+ :param request_timeout: Timeout for the request in **seconds**
"""
try:
self._get_rpc().remove_watcher(
- RemoveWatcherRequest(watcher_id=self._watcher_id)
+ RemoveWatcherRequest(watcher_id=self._watcher_id),
+ request_timeout=self._connection_config.get_request_timeout(
+ request_timeout
+ ),
+ headers=authentication_header(self._envd_version, self._user),
)
except Exception as e:
raise handle_rpc_exception_with_health(e, self._check_health)
self._closed = True
- def get_new_events(self) -> List[FilesystemEvent]:
+ def get_new_events(
+ self, request_timeout: Optional[float] = None
+ ) -> List[FilesystemEvent]:
"""
Get the latest events that have occurred in the watched directory since the last call, or from the beginning of the watching, up until now.
+ :param request_timeout: Timeout for the request in **seconds**
+
:return: List of filesystem events
"""
if self._closed:
@@ -55,7 +74,11 @@ class WatchHandle:
try:
r = self._get_rpc().get_watcher_events(
- GetWatcherEventsRequest(watcher_id=self._watcher_id)
+ GetWatcherEventsRequest(watcher_id=self._watcher_id),
+ request_timeout=self._connection_config.get_request_timeout(
+ request_timeout
+ ),
+ headers=authentication_header(self._envd_version, self._user),
)
except Exception as e:
raise handle_rpc_exception_with_health(e, self._check_health)
diff --git a/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.py b/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.py
index 40052669c..d447087cd 100644
--- a/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.py
+++ b/packages/python-sdk/tests/sync/sandbox_sync/test_thread_local_clients.py
@@ -277,22 +277,24 @@ def test_sync_pty_rpc_clients_are_bound_per_calling_thread(monkeypatch, test_api
assert pty._rpc is main_rpc
-def test_sync_watch_handle_uses_calling_thread_rpc():
+def test_sync_watch_handle_uses_calling_thread_rpc(test_api_key):
class FakeRpc:
def __init__(self, name):
self.name = name
self.calls = []
- def remove_watcher(self, request):
+ def remove_watcher(self, request, **opts):
self.calls.append(("remove", request.watcher_id))
+ config = ConnectionConfig(api_key=test_api_key)
+
main_rpc = FakeRpc("main")
worker_rpc = FakeRpc("worker")
- handle = WatchHandle(lambda: main_rpc, "watcher-id")
+ handle = WatchHandle(lambda: main_rpc, "watcher-id", config, ENVD_VERSION)
handle.stop()
assert main_rpc.calls == [("remove", "watcher-id")]
- handle = WatchHandle(lambda: worker_rpc, "watcher-id")
+ handle = WatchHandle(lambda: worker_rpc, "watcher-id", config, ENVD_VERSION)
run_in_worker_thread(handle.stop)
assert worker_rpc.calls == [("remove", "watcher-id")]
diff --git a/packages/python-sdk/tests/test_watch_handle.py b/packages/python-sdk/tests/test_watch_handle.py
new file mode 100644
index 000000000..2e49f4854
--- /dev/null
+++ b/packages/python-sdk/tests/test_watch_handle.py
@@ -0,0 +1,214 @@
+import asyncio
+
+from packaging.version import Version
+
+from e2b.connection_config import ConnectionConfig
+from e2b.envd.filesystem import filesystem_pb2
+from e2b.envd.versions import ENVD_DEFAULT_USER
+from e2b.sandbox_async.filesystem.watch_handle import AsyncWatchHandle
+from e2b.sandbox_sync.filesystem.watch_handle import WatchHandle
+
+
+def _fs_event(
+ name: str,
+ event_type=filesystem_pb2.EventType.EVENT_TYPE_WRITE,
+) -> filesystem_pb2.WatchDirResponse:
+ return filesystem_pb2.WatchDirResponse(
+ filesystem=filesystem_pb2.FilesystemEvent(name=name, type=event_type)
+ )
+
+
+# --- Sync WatchHandle: request timeout + auth header (bug 28) ---
+
+
+class _FakeSyncRpc:
+ def __init__(self):
+ self.calls = []
+
+ def get_watcher_events(self, req, **opts):
+ self.calls.append(("get_watcher_events", req, opts))
+ return filesystem_pb2.GetWatcherEventsResponse(events=[])
+
+ def remove_watcher(self, req, **opts):
+ self.calls.append(("remove_watcher", req, opts))
+ return filesystem_pb2.RemoveWatcherResponse()
+
+
+def _make_sync_handle(rpc, envd_version: Version, user=None) -> WatchHandle:
+ return WatchHandle(
+ get_rpc=lambda: rpc,
+ watcher_id="watcher-1",
+ connection_config=ConnectionConfig(),
+ envd_version=envd_version,
+ user=user,
+ )
+
+
+def test_sync_get_new_events_passes_request_timeout_and_auth_header():
+ rpc = _FakeSyncRpc()
+ # envd < 0.4.0 has no default user, so the auth header must be sent.
+ handle = _make_sync_handle(rpc, Version("0.3.0"))
+
+ handle.get_new_events()
+
+ name, _, opts = rpc.calls[0]
+ assert name == "get_watcher_events"
+ # A request timeout is always supplied so a stalled call can't hang forever.
+ assert opts["request_timeout"] == 60.0
+ assert opts["headers"].get("Authorization", "").startswith("Basic ")
+
+
+def test_sync_stop_passes_request_timeout_and_auth_header():
+ rpc = _FakeSyncRpc()
+ handle = _make_sync_handle(rpc, Version("0.3.0"))
+
+ handle.stop()
+
+ name, _, opts = rpc.calls[0]
+ assert name == "remove_watcher"
+ assert opts["request_timeout"] == 60.0
+ assert opts["headers"].get("Authorization", "").startswith("Basic ")
+
+
+def test_sync_caller_supplied_request_timeout_is_forwarded():
+ rpc = _FakeSyncRpc()
+ handle = _make_sync_handle(rpc, ENVD_DEFAULT_USER)
+
+ handle.get_new_events(request_timeout=5)
+ handle.stop(request_timeout=7)
+
+ assert rpc.calls[0][2]["request_timeout"] == 5
+ assert rpc.calls[1][2]["request_timeout"] == 7
+ # No explicit user on a recent envd → no auth header forced.
+ assert "Authorization" not in rpc.calls[0][2]["headers"]
+
+
+# --- Async WatchHandle: on_exit lifecycle (bug 29) ---
+
+
+async def test_async_on_exit_fires_with_none_on_clean_end():
+ async def events():
+ yield _fs_event("a.txt")
+
+ received = []
+ exit_calls = []
+
+ handle = AsyncWatchHandle(
+ events=events(),
+ on_event=received.append,
+ on_exit=exit_calls.append,
+ )
+
+ await handle._wait
+
+ assert [e.name for e in received] == ["a.txt"]
+ assert exit_calls == [None]
+
+
+async def test_async_on_exit_fires_with_error_on_stream_error():
+ error = RuntimeError("stream died")
+
+ async def events():
+ raise error
+ yield # pragma: no cover - makes this an async generator
+
+ exit_calls = []
+
+ handle = AsyncWatchHandle(
+ events=events(),
+ on_event=lambda e: None,
+ on_exit=exit_calls.append,
+ )
+
+ await handle._wait
+
+ assert exit_calls == [error]
+
+
+async def test_async_on_exit_fires_on_stop():
+ started = asyncio.Event()
+
+ async def events():
+ started.set()
+ await asyncio.Event().wait() # block until cancelled by stop()
+ yield # pragma: no cover - never reached
+
+ exit_calls = []
+
+ handle = AsyncWatchHandle(
+ events=events(),
+ on_event=lambda e: None,
+ on_exit=exit_calls.append,
+ )
+
+ await started.wait()
+ await handle.stop()
+
+ assert exit_calls == [None]
+
+
+async def test_async_on_exit_awaits_async_callback():
+ async def events():
+ yield _fs_event("a.txt")
+
+ exit_calls = []
+
+ async def on_exit(err):
+ exit_calls.append(err)
+
+ handle = AsyncWatchHandle(
+ events=events(),
+ on_event=lambda e: None,
+ on_exit=on_exit,
+ )
+
+ await handle._wait
+
+ assert exit_calls == [None]
+
+
+async def test_async_on_exit_awaits_async_callback_on_stop():
+ started = asyncio.Event()
+
+ async def events():
+ started.set()
+ await asyncio.Event().wait() # block until cancelled by stop()
+ yield # pragma: no cover - never reached
+
+ exit_done = []
+
+ async def on_exit(err):
+ # A real suspension proves the cancellation path drives the async
+ # callback to completion rather than dropping it mid-await.
+ await asyncio.sleep(0)
+ exit_done.append(err)
+
+ handle = AsyncWatchHandle(
+ events=events(),
+ on_event=lambda e: None,
+ on_exit=on_exit,
+ )
+
+ await started.wait()
+ await handle.stop()
+
+ assert exit_done == [None]
+
+
+async def test_async_on_exit_error_does_not_leak():
+ async def events():
+ yield _fs_event("a.txt")
+
+ async def on_exit(err):
+ raise RuntimeError("on_exit failed")
+
+ handle = AsyncWatchHandle(
+ events=events(),
+ on_event=lambda e: None,
+ on_exit=on_exit,
+ )
+
+ # A raising on_exit must not surface as an unretrieved task exception.
+ await handle._wait
+ assert handle._wait.done()
+ assert handle._wait.exception() is None