Skip to content

armgit / E2B

Public Imported from GitHub
0

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

7.2 KB
Raw Blame
import createClient from 'openapi-fetch'

import type { components, paths } from './schema.gen'
import { ConnectionConfig } from '../connectionConfig'
import { createApiLogger } from '../logs'
import {
  SandboxError,
  InvalidArgumentError,
  NotFoundError,
  NotEnoughSpaceError,
  formatSandboxUnavailableError,
  SandboxNotRunningError,
  AuthenticationError,
  RateLimitError,
} from '../errors'
import { StartResponse, ConnectResponse } from './process/process_pb'
import { WatchDirResponse } from './filesystem/filesystem_pb'
import {
  isConnectionTerminatedMessage,
  resolveTransportFailure,
  SandboxHealthCheck,
} from './rpc'
import { isNetworkError } from '../retry'

type ApiError = { message?: string } | string

const DEFAULT_ERROR_MAP: Record<number, (message: string) => Error> = {
  400: (message) => new InvalidArgumentError(message),
  401: (message) => new AuthenticationError(message),
  404: (message) => new NotFoundError(message),
  429: (message) =>
    new RateLimitError(`${message}: The requests are being rate limited.`),
  502: formatSandboxUnavailableError,
  507: (message) => new NotEnoughSpaceError(message),
}

const HEALTH_CHECK_TIMEOUT_MS = 5_000

/**
 * Probes the sandbox's envd health endpoint.
 *
 * @param envdApi - The envd API client of the sandbox.
 * @returns `true` if the sandbox is running, `false` if it is not, `undefined` if it answered but its state could not be determined.
 * @throws The `fetch` failure when the sandbox could not be reached (no answer within the probe timeout), or the `SandboxUnreachableError` a request would get when the proxy reports the sandbox running but envd's port not open.
 */
export async function checkSandboxHealth(
  envdApi: EnvdApiClient
): Promise<boolean | undefined> {
  const res = await envdApi.api.GET('/health', {
    signal: AbortSignal.timeout(HEALTH_CHECK_TIMEOUT_MS),
  })

  if (res.response.status === 502) {
    const err = formatSandboxUnavailableError(await getEnvdApiErrorMessage(res))
    if (err instanceof SandboxNotRunningError) {
      return false
    }
    throw err
  }
  if (res.response.ok) {
    return true
  }

  return undefined
}

/**
 * Checks whether a `fetch` rejection is a transport-level failure of the request to
 * the sandbox: the connection could not be established or was dropped mid-request
 * (the latter surfaces with runtime-specific wording, e.g. undici's `terminated`).
 */
function isFetchTransportFailure(err: unknown): err is Error {
  return (
    err instanceof Error &&
    (isConnectionTerminatedMessage(err.message) || isNetworkError(err))
  )
}

/**
 * Handles transport-level fetch failures from envd API calls. When the connection to
 * the sandbox could not be established or was dropped mid-request, probes the sandbox
 * health to tell apart the sandbox being killed from the sandbox being unreachable or
 * a transient network failure (e.g. a load balancer dropping the connection).
 *
 * @param err - The caught error, expected to be a fetch transport failure.
 * @param checkHealth - Probe resolving to whether the sandbox is running (`undefined` when unknown) and rejecting when it cannot be reached.
 * @returns A `SandboxNotRunningError` when the sandbox is confirmed gone, a `SandboxUnreachableError` when the probe got no answer either, or the original error otherwise.
 */
export async function handleEnvdApiFetchError(
  err: unknown,
  checkHealth?: SandboxHealthCheck
): Promise<Error> {
  if (checkHealth && isFetchTransportFailure(err)) {
    const resolved = await resolveTransportFailure(err, checkHealth)
    if (resolved) {
      return resolved
    }
  }

  return err as Error
}

/**
 * Extracts the error message of a non-2xx envd API response: the `message` of its
 * JSON body, else its text body, else its status text.
 */
async function getEnvdApiErrorMessage(res: {
  error?: ApiError
  response: Response
}): Promise<string> {
  let message =
    (typeof res.error === 'string' ? res.error : res.error?.message) ?? ''

  // openapi-fetch consumes the body when parsing the error, except for
  // responses without content
  if (!message && !res.response.bodyUsed) {
    try {
      message = await res.response.text()
    } catch {
      // ignore unreadable bodies
    }
  }

  return message || res.response.statusText
}

/**
 * Handles errors from envd API responses by mapping HTTP status codes to specific error types.
 *
 * @param res - The API response object containing an optional error and the raw `Response`.
 * @param errorMap - Optional map of HTTP status codes to error factory functions that override the defaults.
 * @returns The corresponding `Error` instance if an error is present, or `undefined` if the response is successful.
 */
export async function handleEnvdApiError(
  res: {
    error?: ApiError
    response: Response
  },
  errorMap?: Record<number, (message: string) => Error>
) {
  // openapi-fetch leaves `error` empty for non-2xx responses without content
  // (undefined for Content-Length: 0, '' for an empty body without the
  // header), so check the status instead
  if (res.response.ok) {
    return
  }

  const message = await getEnvdApiErrorMessage(res)

  // Check if a custom error mapping is provided for this error code
  if (errorMap && res.response.status in errorMap) {
    return errorMap[res.response.status]?.(message)
  }

  // Check if there is a default error mapping for this error code
  if (res.response.status in DEFAULT_ERROR_MAP) {
    return DEFAULT_ERROR_MAP[res.response.status]?.(message)
  }

  // Fallback to a generic SandboxError if no specific mapping is found
  return new SandboxError(`${res.response.status}: ${message}`)
}

export async function handleProcessStartEvent(
  events: AsyncIterable<StartResponse | ConnectResponse>
) {
  const startEvent: StartResponse | ConnectResponse = (
    await events[Symbol.asyncIterator]().next()
  ).value
  if (startEvent.event?.event.case !== 'start') {
    throw new Error('Expected start event')
  }

  return startEvent.event.event.value.pid
}

export async function handleWatchDirStartEvent(
  events: AsyncIterable<WatchDirResponse>
) {
  const startEvent: WatchDirResponse = (
    await events[Symbol.asyncIterator]().next()
  ).value
  if (startEvent.event?.case !== 'start') {
    throw new Error('Expected start event')
  }

  return startEvent.event.value
}

class EnvdApiClient {
  readonly api: ReturnType<typeof createClient<paths>>
  readonly version: string

  constructor(
    config: Pick<ConnectionConfig, 'apiUrl' | 'logger'> & {
      /**
       * Sandbox-scoped envd access token, sent as the `X-Access-Token` header.
       */
      envdAccessToken?: string
      fetch?: (request: Request) => ReturnType<typeof fetch>
      headers?: Record<string, string>
    },
    metadata: {
      version: string
    }
  ) {
    this.api = createClient({
      baseUrl: config.apiUrl,
      fetch: config?.fetch,
      headers: {
        ...config?.headers,
        ...(config.envdAccessToken && {
          'X-Access-Token': config.envdAccessToken,
        }),
      },
      // In HTTP 1.1, all connections are considered persistent unless declared otherwise
      // keepalive: true,
    })
    this.version = metadata.version

    if (config.logger) {
      this.api.use(createApiLogger(config.logger))
    }
  }
}

export type { components, paths }
export { EnvdApiClient }