Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
import { ApiClient, handleApiError, components as ApiComponents } from '../api'
import {
VolumeApiClient,
VolumeApiComponents,
VolumeConnectionConfig,
VolumeApiOpts,
FILE_TIMEOUT_MS,
} from './client'
import {
ClientFactory,
ConnectionConfig,
ConnectionOpts,
HttpVersion,
setupRequestController,
wrapStreamWithConnectionCleanup,
} from '../connectionConfig'
import { isArrayBufferLike, isBlobLike } from '../is'
import {
VolumeError,
VolumeNotFoundError,
VolumePathNotFoundError,
} from '../errors'
import { toUploadBody } from '../utils'
import { VolumeFileType } from './types'
import type {
VolumeAndToken,
VolumeEntryStat,
VolumeInfo,
VolumeMetadataOpts,
VolumeReadOpts,
VolumeWriteOpts,
} from './types'
/**
* Convert API VolumeEntryStat to SDK VolumeEntryStat.
*/
function convertVolumeEntryStat(
entry: VolumeApiComponents['schemas']['VolumeEntryStat']
): VolumeEntryStat {
return {
...entry,
type: entry.type as VolumeFileType,
atime: new Date(entry.atime),
mtime: new Date(entry.mtime),
ctime: new Date(entry.ctime),
}
}
/**
* Module for interacting with E2B volumes.
*
* Create a `Volume` instance to interact with a volume by its ID,
* or use the static methods to manage volumes.
*/
export class Volume extends ClientFactory {
/**
* Volume ID.
*/
readonly volumeId: string
/**
* Volume name.
*/
readonly name: string
/**
* Volume auth token.
*/
readonly token: string
/**
* Domain used for constructing the volume API URL.
*/
readonly domain?: string
/**
* Whether to use debug mode (connects to local volume API server).
*/
readonly debug?: boolean
/**
* Proxy URL used for requests to the volume content API.
*/
readonly proxy?: string
/**
* HTTP version used for requests to the volume content API.
*/
readonly httpVersion?: HttpVersion
/**
* Create a local Volume instance with no API call.
*
* @param volumeId volume ID.
* @param name volume name.
* @param token volume auth token.
* @param domain domain for the volume API.
* @param debug whether to use debug mode.
* @param proxy proxy URL for the volume content API.
* @param opts connection options kept for the volume content API.
*/
constructor(
volumeId: string,
name: string,
token: string,
domain?: string,
debug?: boolean,
proxy?: string,
opts?: Pick<ConnectionOpts, 'httpVersion'>
) {
super()
this.volumeId = volumeId
this.name = name
this.token = token
this.domain = domain
this.debug = debug
this.proxy = proxy
this.httpVersion = opts?.httpVersion
}
/**
* Create a new volume.
*
* @param name name of the volume.
* @param opts connection options.
*
* @returns new Volume instance.
*/
static async create<V extends typeof Volume>(
this: V,
name: string,
opts?: ConnectionOpts
): Promise<InstanceType<V>> {
const apiOpts = this.resolveOpts(opts)
const config = new ConnectionConfig(apiOpts)
const client = new ApiClient(config)
const res = await client.api.POST('/volumes', {
body: {
name,
},
signal: config.getSignal(apiOpts?.requestTimeoutMs, apiOpts?.signal),
})
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
if (!res.data) {
throw new Error('Response data is missing')
}
return new this(
res.data.volumeID,
res.data.name,
res.data.token,
res.data.domain || config.domain,
config.debug,
config.proxy,
{ httpVersion: config.httpVersion }
) as InstanceType<V>
}
/**
* Connect to an existing volume by ID.
*
* @param volumeId volume ID.
* @param opts connection options.
*
* @returns Volume instance.
*/
static async connect<V extends typeof Volume>(
this: V,
volumeId: string,
opts?: ConnectionOpts
): Promise<InstanceType<V>> {
const apiOpts = this.resolveOpts(opts)
const config = new ConnectionConfig(apiOpts)
const { name, token, domain } = await this.getInfo(volumeId, apiOpts)
return new this(
volumeId,
name,
token,
domain ?? config.domain,
config.debug,
config.proxy,
{ httpVersion: config.httpVersion }
) as InstanceType<V>
}
/**
* Get volume information.
*
* @param volumeId volume ID.
* @param opts connection options.
*
* @returns volume information.
*/
static async getInfo(
volumeId: string,
opts?: ConnectionOpts
): Promise<VolumeAndToken> {
const apiOpts = this.resolveOpts(opts)
const config = new ConnectionConfig(apiOpts)
const client = new ApiClient(config)
const res = await client.api.GET('/volumes/{volumeID}', {
params: {
path: {
volumeID: volumeId,
},
},
signal: config.getSignal(apiOpts?.requestTimeoutMs, apiOpts?.signal),
})
if (res.response.status === 404) {
throw new VolumeNotFoundError(`Volume ${volumeId} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
return {
volumeId: res.data!.volumeID,
name: res.data!.name,
token: res.data!.token,
domain: res.data!.domain || undefined,
}
}
/**
* List all volumes.
*
* @param opts connection options.
*
* @returns list of volume information.
*/
static async list(opts?: ConnectionOpts): Promise<VolumeInfo[]> {
const apiOpts = this.resolveOpts(opts)
const config = new ConnectionConfig(apiOpts)
const client = new ApiClient(config)
const res = await client.api.GET('/volumes', {
signal: config.getSignal(apiOpts?.requestTimeoutMs, apiOpts?.signal),
})
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
return (res.data ?? []).map((vol: ApiComponents['schemas']['Volume']) => ({
volumeId: vol.volumeID,
name: vol.name,
}))
}
/**
* Destroy a volume.
*
* @param volumeId volume ID.
* @param opts connection options.
*/
static async destroy(
volumeId: string,
opts?: ConnectionOpts
): Promise<boolean> {
const apiOpts = this.resolveOpts(opts)
const config = new ConnectionConfig(apiOpts)
const client = new ApiClient(config)
const res = await client.api.DELETE('/volumes/{volumeID}', {
params: {
path: {
volumeID: volumeId,
},
},
signal: config.getSignal(apiOpts?.requestTimeoutMs, apiOpts?.signal),
})
if (res.response.status === 404) {
return false
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
return true
}
/**
* List directory contents.
*
* @param path path to the directory.
* @param opts connection options.
* @param [opts.depth] number of layers deep to recurse into the directory (default: 1).
*
* @returns list of entries in the directory.
*/
async list(
path: string,
opts?: VolumeApiOpts & { depth?: number }
): Promise<VolumeEntryStat[]> {
const config = new VolumeConnectionConfig(this, opts)
const client = new VolumeApiClient(config)
const res = await client.api.GET('/volumecontent/{volumeID}/dir', {
params: {
path: {
volumeID: this.volumeId,
},
query: {
path,
depth: opts?.depth,
},
},
signal: config.getSignal(),
})
if (res.response.status === 404) {
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
// VolumeDirectoryListing is an array according to the spec
const entries = Array.isArray(res.data) ? res.data : []
return entries.map(convertVolumeEntryStat)
}
/**
* Create a directory.
*
* @param path path to the directory to create.
* @param options directory creation options.
* @param opts connection options.
*/
async makeDir(
path: string,
opts?: VolumeWriteOpts & VolumeApiOpts
): Promise<VolumeEntryStat> {
const config = new VolumeConnectionConfig(this, opts)
const client = new VolumeApiClient(config)
const res = await client.api.POST('/volumecontent/{volumeID}/dir', {
params: {
path: {
volumeID: this.volumeId,
},
query: {
path,
uid: opts?.uid,
gid: opts?.gid,
mode: opts?.mode,
force: opts?.force,
},
},
signal: config.getSignal(),
})
if (res.response.status === 404) {
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
if (!res.data) {
throw new Error('Response data is missing')
}
return convertVolumeEntryStat(
res.data as VolumeApiComponents['schemas']['VolumeEntryStat']
)
}
/**
* Get information about a file or directory.
*
* @param path path to the file or directory.
* @param opts connection options.
*
* @returns information about the entry.
*/
async getInfo(path: string, opts?: VolumeApiOpts): Promise<VolumeEntryStat> {
const config = new VolumeConnectionConfig(this, opts)
const client = new VolumeApiClient(config)
const res = await client.api.GET('/volumecontent/{volumeID}/path', {
params: {
path: {
volumeID: this.volumeId,
},
query: {
path,
},
},
signal: config.getSignal(),
})
if (res.response.status === 404) {
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
if (!res.data) {
throw new Error('Response data is missing')
}
return convertVolumeEntryStat(
res.data as VolumeApiComponents['schemas']['VolumeEntryStat']
)
}
/**
* Check whether a file or directory exists.
*
* Uses {@link getInfo} under the hood. Returns `true` if the path exists,
* `false` if it does not (404). Other errors are rethrown.
*
* @param path path to the file or directory.
* @param opts connection options.
*
* @returns `true` if the path exists, `false` otherwise.
*/
async exists(path: string, opts?: VolumeApiOpts): Promise<boolean> {
try {
await this.getInfo(path, opts)
return true
} catch (err) {
if (err instanceof VolumePathNotFoundError) {
return false
}
throw err
}
}
/**
* Update file or directory metadata.
*
* @param path path to the file or directory.
* @param metadata metadata to update (uid, gid, mode).
* @param opts connection options.
*
* @returns updated entry information.
*/
async updateMetadata(
path: string,
metadata: VolumeMetadataOpts,
opts?: VolumeApiOpts
): Promise<VolumeEntryStat> {
const config = new VolumeConnectionConfig(this, opts)
const client = new VolumeApiClient(config)
const res = await client.api.PATCH('/volumecontent/{volumeID}/path', {
params: {
path: {
volumeID: this.volumeId,
},
query: {
path,
},
},
body: {
uid: metadata.uid,
gid: metadata.gid,
mode: metadata.mode,
},
signal: config.getSignal(),
})
if (res.response.status === 404) {
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
if (!res.data) {
throw new Error('Response data is missing')
}
return convertVolumeEntryStat(
res.data as VolumeApiComponents['schemas']['VolumeEntryStat']
)
}
/**
* Read file content as a `string`.
*
* You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type.
*
* @param path path to the file.
* @param opts connection options.
* @param [opts.format] format of the file content—`text` by default.
*
* @returns file content as string
*/
async readFile(
path: string,
opts?: VolumeReadOpts & { format?: 'text' }
): Promise<string>
/**
* Read file content as a `Uint8Array`.
*
* You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type.
*
* @param path path to the file.
* @param opts connection options.
* @param [opts.format] format of the file content—`bytes`.
*
* @returns file content as `Uint8Array`
*/
async readFile(
path: string,
opts?: VolumeReadOpts & { format: 'bytes' }
): Promise<Uint8Array>
/**
* Read file content as a `Blob`.
*
* You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type.
*
* @param path path to the file.
* @param opts connection options.
* @param [opts.format] format of the file content—`blob`.
*
* @returns file content as `Blob`
*/
async readFile(
path: string,
opts?: VolumeReadOpts & { format: 'blob' }
): Promise<Blob>
/**
* Read file content as a `ReadableStream`.
*
* You can pass `text`, `bytes`, `blob`, or `stream` to `opts.format` to change the return type.
*
* @param path path to the file.
* @param opts connection options.
* @param [opts.format] format of the file content—`stream`.
*
* @returns file content as `ReadableStream`
*/
async readFile(
path: string,
opts?: VolumeReadOpts & { format: 'stream' }
): Promise<ReadableStream<Uint8Array>>
async readFile(
path: string,
opts?: VolumeReadOpts & {
format?: 'text' | 'stream' | 'bytes' | 'blob'
}
): Promise<unknown> {
const format = opts?.format ?? 'text'
const config = new VolumeConnectionConfig(this, {
...opts,
requestTimeoutMs: opts?.requestTimeoutMs ?? FILE_TIMEOUT_MS,
})
const client = new VolumeApiClient(config)
if (format === 'stream') {
// The request timeout bounds only the initial handshake; once the
// response arrives, the stream lives until it's consumed, cancelled, the
// user signal aborts, or the per-chunk idle timeout fires. Matches the
// sandbox `files.read` stream path.
const { controller, clearStartTimeout, cleanup } = setupRequestController(
config.requestTimeoutMs,
opts?.signal
)
try {
const res = await client.api.GET('/volumecontent/{volumeID}/file', {
params: {
path: { volumeID: this.volumeId },
query: { path },
},
parseAs: 'stream',
signal: controller.signal,
})
if (res.response.status === 404) {
// Cancel the unconsumed body so the pooled connection is released
// before we propagate.
if (res.response.body && !res.response.bodyUsed) {
await res.response.body.cancel().catch(() => {})
}
cleanup()
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
if (res.response.body && !res.response.bodyUsed) {
await res.response.body.cancel().catch(() => {})
}
cleanup()
throw err
}
return wrapStreamWithConnectionCleanup(
res.data as ReadableStream<Uint8Array> | null,
{
clearStartTimeout,
cleanup,
controller,
idleTimeoutMs: opts?.streamIdleTimeoutMs ?? config.requestTimeoutMs,
}
)
} catch (err) {
cleanup()
throw err
}
}
const res = await client.api.GET('/volumecontent/{volumeID}/file', {
params: {
path: {
volumeID: this.volumeId,
},
query: {
path,
},
},
parseAs: format === 'bytes' ? 'arrayBuffer' : format,
signal: config.getSignal(),
})
if (res.response.status === 404) {
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
// When the file is empty, `res.data` is `undefined`, so empty values are synthesized below.
if (format === 'bytes') {
return isArrayBufferLike(res.data)
? new Uint8Array(res.data)
: new Uint8Array()
}
if (format === 'text') {
return typeof res.data === 'string' ? res.data : ''
}
// format === 'blob'
return isBlobLike(res.data) ? res.data : new Blob([])
}
/**
* Write content to a file.
*
* Writing to a file that doesn't exist creates the file.
*
* Writing to a file that already exists overwrites the file.
*
* @param path path to the file.
* @param data data to write to the file. Data can be a string, `ArrayBuffer`, `Blob`, or `ReadableStream`. Outside the browser, `ReadableStream` data is streamed to the API instead of being buffered in memory.
* @param options file creation options.
* @param opts connection options.
*
* @returns information about the written file
*/
async writeFile(
path: string,
data: string | ArrayBuffer | Blob | ReadableStream<Uint8Array>,
opts?: VolumeWriteOpts & VolumeApiOpts
): Promise<VolumeEntryStat> {
const config = new VolumeConnectionConfig(this, {
...opts,
requestTimeoutMs: opts?.requestTimeoutMs ?? FILE_TIMEOUT_MS,
})
const client = new VolumeApiClient(config)
// `toUploadBody` streams only for non-browser stream input; otherwise it
// buffers into a Blob.
const { body, streamed } = await toUploadBody(data)
// A streamed upload carries no client-side timeout: the socket-write
// "wire" isn't observable through fetch, and a stalled producer is the
// caller's own code, so a stuck streamed upload is bounded server-side (or
// via `opts.signal`). Buffered uploads keep the normal request timeout.
const signal = streamed ? opts?.signal : config.getSignal()
const res = await client.api.PUT('/volumecontent/{volumeID}/file', {
params: {
path: {
volumeID: this.volumeId,
},
query: {
path,
uid: opts?.uid,
gid: opts?.gid,
mode: opts?.mode,
force: opts?.force,
},
},
bodySerializer: () => body,
body: {} as any,
headers: {
'Content-Type': 'application/octet-stream',
},
signal,
// Streaming request bodies require half-duplex mode.
...(streamed && { duplex: 'half' as const }),
})
if (res.response.status === 404) {
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
if (!res.data) {
throw new Error('Response data is missing')
}
return convertVolumeEntryStat(
res.data as VolumeApiComponents['schemas']['VolumeEntryStat']
)
}
/**
* Remove a file or directory.
*
* @param path path to the file or directory to remove.
* @param opts connection options.
*/
async remove(path: string, opts?: VolumeApiOpts): Promise<void> {
const config = new VolumeConnectionConfig(this, opts)
const client = new VolumeApiClient(config)
const res = await client.api.DELETE('/volumecontent/{volumeID}/path', {
params: {
path: {
volumeID: this.volumeId,
},
query: {
path,
},
},
signal: config.getSignal(),
})
if (res.response.status === 404) {
throw new VolumePathNotFoundError(`Path ${path} not found`)
}
const err = handleApiError(res, VolumeError)
if (err) {
throw err
}
}
}
export type {
VolumeInfo,
VolumeAndToken,
VolumeEntryStat,
VolumeMetadataOpts,
VolumeReadOpts,
VolumeWriteOpts,
// Deprecated aliases, kept for backwards compatibility.
VolumeMetadataOptions,
VolumeWriteOptions,
} from './types'
export type { VolumeApiOpts, VolumeConnectionConfig } from './client'
export { VolumeFileType } from './types'