feat(js): retry rate-limited control-plane requests

.changeset/retry-after-rate-limits.md

@@ -0,0 +1,5 @@
+---
+"e2b": patch
+---
+
+Retry control-plane HTTP requests up to three times after `429` responses using the server's delta-seconds `Retry-After` delay. Retries can be configured or disabled with `retries`, and stop when waiting would exhaust the request timeout. Envd requests, including filesystem operations, and volume-content requests are not retried.

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

@@ -11,6 +11,7 @@ import {
   SandboxError,
 } from '../errors'
 import { createApiLogger } from '../logs'
+import { withRateLimitRetry } from '../retry'
 
 /**
  * Map an API error code and message to the matching error class — the same
@@ -105,7 +106,11 @@ class ApiClient {
 
     this.api = createClient<paths>({
       baseUrl: config.apiUrl,
-      fetch: createApiFetch(config.proxy),
+      fetch: withRateLimitRetry(
+        createApiFetch(config.proxy),
+        config.retries,
+        config.requestTimeoutMs
+      ),
       // In HTTP 1.1, all connections are considered persistent unless declared otherwise
       // keepalive: true,
       headers: {

packages/js-sdk/src/connectionConfig.ts

@@ -1,11 +1,13 @@
 import { Logger } from './logs'
 import { getEnvVar, version } from './api/metadata'
 import { runtime } from './utils'
+import { resolveRetries } from './retry'
 
 // Remove once all deployments support sandbox subdomains
 const supportedDomains = ['e2b.app', 'e2b.dev', 'e2b.pro', 'e2b-staging.dev']
 
 export const REQUEST_TIMEOUT_MS = 60_000 // 60 seconds
+export const DEFAULT_RETRIES = 3
 export const DEFAULT_SANDBOX_TIMEOUT_MS = 300_000 // 300 seconds
 export const KEEPALIVE_PING_INTERVAL_SEC = 50 // 50 seconds
 
@@ -58,6 +60,15 @@ export interface ConnectionOpts {
    * @default 60_000 // 60 seconds
    */
   requestTimeoutMs?: number
+  /**
+   * Number of control-plane API retries after a 429 response with a valid,
+   * non-negative integer delta-seconds `Retry-After` header. HTTP-date and
+   * malformed values are not retried.
+   * Retry waits use a 60-second total limit when request timeouts are disabled.
+   *
+   * @default 3
+   */
+  retries?: number
   /**
    * Logger to use for logging messages. It can accept any object that implements `Logger` interface—for example, {@link console}.
    */
@@ -408,6 +419,7 @@ export class ConnectionConfig {
   readonly logger?: Logger
 
   readonly requestTimeoutMs: number
+  readonly retries: number
 
   readonly apiKey?: string
   /**
@@ -435,6 +447,7 @@ export class ConnectionConfig {
     this.debug = opts?.debug ?? ConnectionConfig.debug
     this.domain = opts?.domain || ConnectionConfig.domain
     this.requestTimeoutMs = opts?.requestTimeoutMs ?? REQUEST_TIMEOUT_MS
+    this.retries = resolveRetries(opts?.retries ?? DEFAULT_RETRIES)
     this.logger = opts?.logger
     this.requestSource = ConnectionConfig.getRequestSource()
     this.headers = { ...(opts?.headers ?? {}), ...(opts?.apiHeaders ?? {}) }

packages/js-sdk/src/retry.ts

@@ -0,0 +1,99 @@
+import { InvalidArgumentError } from './errors'
+import { isReadableStreamLike } from './is'
+
+const MAX_RETRY_AFTER_SECONDS = 2_147_483
+const MAX_RETRY_WAIT_WITHOUT_TIMEOUT_MS = 60_000
+
+export function resolveRetries(retries: number): number {
+  if (!Number.isInteger(retries) || retries < 0) {
+    throw new InvalidArgumentError(
+      `Invalid retries=${retries}: expected a non-negative integer.`
+    )
+  }
+  return retries
+}
+
+export function parseRetryAfter(
+  value: string | null | undefined
+): number | undefined {
+  if (!value) return undefined
+
+  const trimmed = value.trim()
+  if (!/^\d+$/.test(trimmed)) return undefined
+
+  const delay = Number(trimmed)
+  return Number.isSafeInteger(delay) && delay <= MAX_RETRY_AFTER_SECONDS
+    ? delay
+    : undefined
+}
+
+type RetryDependencies = {
+  monotonic?: () => number
+  sleep?: (delayMs: number, signal: AbortSignal) => Promise<void>
+}
+
+function wait(delayMs: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.reject(signal.reason)
+
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(signal.reason)
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, delayMs)
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** Retry replayable requests after a 429 carrying `Retry-After`. */
+export function withRateLimitRetry(
+  fetchImpl: typeof fetch,
+  retries: number,
+  requestTimeoutMs: number,
+  dependencies: RetryDependencies = {}
+): typeof fetch {
+  const monotonic = dependencies.monotonic ?? (() => performance.now())
+  const sleep = dependencies.sleep ?? wait
+
+  return (async (input, init) => {
+    // Streaming bodies would be consumed by the first attempt and cannot be
+    // replayed without buffering them, so they get a single attempt.
+    if (retries === 0 || isReadableStreamLike(init?.body)) {
+      return fetchImpl(input, init)
+    }
+
+    // Replaying a Request-form input via `clone()` is safe because the only
+    // producer of those is openapi-fetch, which serializes every body to a
+    // string before constructing the Request — cloning never tees a live
+    // stream.
+    const request =
+      input instanceof Request && init === undefined
+        ? input
+        : new Request(input, init)
+    const deadline =
+      monotonic() + (requestTimeoutMs || MAX_RETRY_WAIT_WITHOUT_TIMEOUT_MS)
+
+    for (let attempt = 0; ; attempt++) {
+      const response = await fetchImpl(
+        attempt === retries ? request : request.clone()
+      )
+      const retryAfter = parseRetryAfter(response.headers.get('Retry-After'))
+      const delayMs = retryAfter === undefined ? undefined : retryAfter * 1000
+
+      if (
+        response.status !== 429 ||
+        delayMs === undefined ||
+        attempt === retries ||
+        monotonic() + delayMs >= deadline
+      ) {
+        return response
+      }
+
+      await response.body?.cancel().catch(() => {})
+      await sleep(delayMs, request.signal)
+    }
+  }) as typeof fetch
+}

packages/js-sdk/src/sandbox/sandboxApi.ts

@@ -514,6 +514,7 @@ export interface SandboxApiOpts extends Partial<
     | 'debug'
     | 'domain'
     | 'requestTimeoutMs'
+    | 'retries'
     | 'signal'
   >
 > {}

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

@@ -167,6 +167,53 @@ test('per-call options take precedence over the client config', async () => {
   assert.equal(lastRequest().apiKey, API_KEY_B)
 })
 
+test('client retries rate-limited control-plane requests', async () => {
+  let attempts = 0
+  server.use(
+    http.get(/\/v2\/sandboxes/, () => {
+      attempts++
+      if (attempts === 1) {
+        return new HttpResponse(null, {
+          status: 429,
+          headers: { 'Retry-After': '0' },
+        })
+      }
+      return HttpResponse.json([])
+    })
+  )
+  const client = new E2B({
+    apiKey: API_KEY_A,
+    domain: DOMAIN_A,
+  })
+
+  await client.Sandbox.list().nextItems()
+
+  assert.equal(attempts, 2)
+})
+
+test('client replays serialized control-plane JSON after a rate limit', async () => {
+  const bodies: unknown[] = []
+  server.use(
+    http.post(/\/sandboxes$/, async ({ request }) => {
+      bodies.push(await request.json())
+      if (bodies.length === 1) {
+        return new HttpResponse(null, {
+          status: 429,
+          headers: { 'Retry-After': '0' },
+        })
+      }
+      return HttpResponse.json(sandboxResponse)
+    })
+  )
+  const client = new E2B({ apiKey: API_KEY_A, domain: DOMAIN_A })
+
+  await client.Sandbox.create()
+
+  expect(bodies).toHaveLength(2)
+  expect(bodies[0]).toMatchObject({ templateID: 'base' })
+  expect(bodies[1]).toEqual(bodies[0])
+})
+
 test('client.Sandbox can be rebound to a variable', async () => {
   const client = new E2B({ apiKey: API_KEY_A, domain: DOMAIN_A })
   const S = client.Sandbox

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

@@ -1,6 +1,7 @@
 import { assert, test, beforeEach, afterEach } from 'vitest'
 import {
   ConnectionConfig,
+  DEFAULT_RETRIES,
   setupRequestController,
   wrapStreamWithConnectionCleanup,
 } from '../src/connectionConfig'
@@ -42,6 +43,12 @@ test('api_url defaults correctly', () => {
   assert.equal(config.apiUrl, 'https://api.e2b.app')
 })
 
+test('retries default to three and accept a non-negative integer', () => {
+  assert.equal(new ConnectionConfig().retries, DEFAULT_RETRIES)
+  assert.equal(new ConnectionConfig({ retries: 2 }).retries, 2)
+  assert.throws(() => new ConnectionConfig({ retries: -1 }))
+})
+
 test('api_url in args', () => {
   const config = new ConnectionConfig({ apiUrl: 'http://localhost:8080' })
   assert.equal(config.apiUrl, 'http://localhost:8080')