feat(js-sdk): support AbortSignal for request cancellation (#1328)

Author: mishushakov

.changeset/abort-signal-support.md

@@ -0,0 +1,9 @@
+---
+'e2b': minor
+---
+
+Add `signal: AbortSignal` option to JS SDK methods to support cancelling in-flight requests. The signal can be passed to `Sandbox.create`, `Sandbox.connect`, `sandbox.commands.run`, `sandbox.files.*`, volume methods, and other request options. When the signal is aborted, the underlying `fetch` is aborted and the returned promise rejects with an `AbortError`.
+
+`SandboxPaginator.nextItems` and `SnapshotPaginator.nextItems` now accept a `SandboxApiOpts` argument (including `signal`) — when provided, the per-call options override the connection options the paginator was constructed with for that single request.
+
+Same change in the Python SDK: `SandboxPaginator.next_items` / `SnapshotPaginator.next_items` (sync and async) now accept `**opts: ApiParams` (e.g. `api_key`, `domain`, `headers`, `request_timeout`); when provided, the per-call options override the ones the paginator was constructed with.

packages/cli/package.json

@@ -59,7 +59,7 @@
     "json2md": "^2.0.1",
     "knip": "^5.43.6",
     "tsup": "^8.4.0",
-    "typescript": "^5.2.2",
+    "typescript": "^5.4.5",
     "vitest": "^3.2.4"
   },
   "files": [

packages/js-sdk/src/connectionConfig.ts

@@ -62,6 +62,105 @@ export interface ConnectionOpts {
    * Additional headers to send with the request.
    */
   headers?: Record<string, string>
+
+  /**
+   * An optional `AbortSignal` that can be used to cancel the in-flight request.
+   * When the signal is aborted, the underlying `fetch` is aborted and the
+   * returned promise rejects with an `AbortError`.
+   */
+  signal?: AbortSignal
+}
+
+/**
+ * Build an `AbortSignal` that combines an optional request-timeout signal
+ * (via `AbortSignal.timeout`) with an optional user-provided signal.
+ *
+ * Returns `undefined` when neither input would produce a signal.
+ *
+ * @internal
+ */
+export function buildRequestSignal(
+  requestTimeoutMs: number | undefined,
+  userSignal: AbortSignal | undefined
+): AbortSignal | undefined {
+  const timeoutSignal = requestTimeoutMs
+    ? AbortSignal.timeout(requestTimeoutMs)
+    : undefined
+
+  if (timeoutSignal && userSignal) {
+    return AbortSignal.any([timeoutSignal, userSignal])
+  }
+
+  return timeoutSignal ?? userSignal
+}
+
+/**
+ * Set up an internal `AbortController` for a streaming request.
+ *
+ * Until `clearStartTimeout` is called, the controller aborts when either
+ *  - the optional user signal aborts, or
+ *  - the optional request timeout elapses (used to bound the initial
+ *    handshake; long-lived streams should call `clearStartTimeout` once
+ *    the handshake succeeds).
+ *
+ * The user-signal listener stays attached for the full stream lifetime
+ * so the caller can cancel a long-running stream by aborting the signal.
+ *
+ * `cleanup` is idempotent and detaches the listener, clears the handshake
+ * timer (if still pending), and aborts the controller. Call it when the
+ * stream finishes or when startup fails.
+ *
+ * @internal
+ */
+export function setupRequestController(
+  requestTimeoutMs: number | undefined,
+  userSignal: AbortSignal | undefined
+): {
+  controller: AbortController
+  clearStartTimeout: () => void
+  cleanup: () => void
+} {
+  const controller = new AbortController()
+
+  const onUserAbort = () => controller.abort(userSignal?.reason)
+  if (userSignal) {
+    if (userSignal.aborted) {
+      controller.abort(userSignal.reason)
+    } else {
+      userSignal.addEventListener('abort', onUserAbort, { once: true })
+    }
+  }
+
+  let reqTimeout: ReturnType<typeof setTimeout> | undefined = requestTimeoutMs
+    ? setTimeout(
+        () =>
+          controller.abort(
+            new DOMException(
+              `Request handshake timed out after ${requestTimeoutMs}ms`,
+              'TimeoutError'
+            )
+          ),
+        requestTimeoutMs
+      )
+    : undefined
+
+  const clearStartTimeout = () => {
+    if (reqTimeout) {
+      clearTimeout(reqTimeout)
+      reqTimeout = undefined
+    }
+  }
+
+  let cleaned = false
+  const cleanup = () => {
+    if (cleaned) return
+    cleaned = true
+    userSignal?.removeEventListener('abort', onUserAbort)
+    clearStartTimeout()
+    controller.abort()
+  }
+
+  return { controller, clearStartTimeout, cleanup }
 }
 
 /**
@@ -125,10 +224,8 @@ export class ConnectionConfig {
     return getEnvVar('E2B_ACCESS_TOKEN')
   }
 
-  getSignal(requestTimeoutMs?: number) {
-    const timeout = requestTimeoutMs ?? this.requestTimeoutMs
-
-    return timeout ? AbortSignal.timeout(timeout) : undefined
+  getSignal(requestTimeoutMs?: number, signal?: AbortSignal) {
+    return buildRequestSignal(requestTimeoutMs ?? this.requestTimeoutMs, signal)
   }
 
   getSandboxUrl(

packages/js-sdk/src/sandbox/commands/commandHandle.ts

@@ -235,6 +235,8 @@ export class CommandHandle
       }
     } catch (e) {
       this.iterationError = handleRpcError(e)
+    } finally {
+      this.handleDisconnect()
     }
   }
 }

packages/js-sdk/src/sandbox/commands/index.ts

@@ -12,6 +12,7 @@ import {
   ConnectionOpts,
   KEEPALIVE_PING_HEADER,
   KEEPALIVE_PING_INTERVAL_SEC,
+  setupRequestController,
   Username,
 } from '../../connectionConfig'
 import { handleProcessStartEvent } from '../../envd/api'
@@ -29,7 +30,7 @@ export { Pty } from './pty'
  * Options for sending a command request.
  */
 export interface CommandRequestOpts
-  extends Partial<Pick<ConnectionOpts, 'requestTimeoutMs'>> {}
+  extends Partial<Pick<ConnectionOpts, 'requestTimeoutMs' | 'signal'>> {}
 
 /**
  * Options for starting a new command.
@@ -160,7 +161,10 @@ export class Commands {
       const res = await this.rpc.list(
         {},
         {
-          signal: this.connectionConfig.getSignal(opts?.requestTimeoutMs),
+          signal: this.connectionConfig.getSignal(
+            opts?.requestTimeoutMs,
+            opts?.signal
+          ),
         }
       )
 
@@ -209,7 +213,10 @@ export class Commands {
           },
         },
         {
-          signal: this.connectionConfig.getSignal(opts?.requestTimeoutMs),
+          signal: this.connectionConfig.getSignal(
+            opts?.requestTimeoutMs,
+            opts?.signal
+          ),
         }
       )
     } catch (err) {
@@ -239,7 +246,10 @@ export class Commands {
           },
         },
         {
-          signal: this.connectionConfig.getSignal(opts?.requestTimeoutMs),
+          signal: this.connectionConfig.getSignal(
+            opts?.requestTimeoutMs,
+            opts?.signal
+          ),
         }
       )
     } catch (err) {
@@ -269,7 +279,10 @@ export class Commands {
           signal: Signal.SIGKILL,
         },
         {
-          signal: this.connectionConfig.getSignal(opts?.requestTimeoutMs),
+          signal: this.connectionConfig.getSignal(
+            opts?.requestTimeoutMs,
+            opts?.signal
+          ),
         }
       )
 
@@ -301,13 +314,10 @@ export class Commands {
     const requestTimeoutMs =
       opts?.requestTimeoutMs ?? this.connectionConfig.requestTimeoutMs
 
-    const controller = new AbortController()
-
-    const reqTimeout = requestTimeoutMs
-      ? setTimeout(() => {
-          controller.abort()
-        }, requestTimeoutMs)
-      : undefined
+    const { controller, clearStartTimeout, cleanup } = setupRequestController(
+      requestTimeoutMs,
+      opts?.signal
+    )
 
     const events = this.rpc.connect(
       {
@@ -329,19 +339,19 @@ export class Commands {
 
     try {
       const pid = await handleProcessStartEvent(events)
-
-      clearTimeout(reqTimeout)
+      clearStartTimeout()
 
       return new CommandHandle(
         pid,
-        () => controller.abort(),
+        cleanup,
         () => this.kill(pid),
         events,
         opts?.onStdout,
         opts?.onStderr,
         undefined
       )
     } catch (err) {
+      cleanup()
       throw handleRpcError(err)
     }
   }
@@ -402,17 +412,6 @@ export class Commands {
     cmd: string,
     opts?: CommandStartOpts
   ): Promise<CommandHandle> {
-    const requestTimeoutMs =
-      opts?.requestTimeoutMs ?? this.connectionConfig.requestTimeoutMs
-
-    const controller = new AbortController()
-
-    const reqTimeout = requestTimeoutMs
-      ? setTimeout(() => {
-          controller.abort()
-        }, requestTimeoutMs)
-      : undefined
-
     if (
       opts?.stdin === false &&
       compareVersions(this.envdVersion, ENVD_COMMANDS_STDIN) < 0
@@ -422,6 +421,14 @@ export class Commands {
       )
     }
 
+    const requestTimeoutMs =
+      opts?.requestTimeoutMs ?? this.connectionConfig.requestTimeoutMs
+
+    const { controller, clearStartTimeout, cleanup } = setupRequestController(
+      requestTimeoutMs,
+      opts?.signal
+    )
+
     const events = this.rpc.start(
       {
         process: {
@@ -444,19 +451,19 @@ export class Commands {
 
     try {
       const pid = await handleProcessStartEvent(events)
-
-      clearTimeout(reqTimeout)
+      clearStartTimeout()
 
       return new CommandHandle(
         pid,
-        () => controller.abort(),
+        cleanup,
         () => this.kill(pid),
         events,
         opts?.onStdout,
         opts?.onStderr,
         undefined
       )
     } catch (err) {
+      cleanup()
       throw handleRpcError(err)
     }
   }