INTEGRITY Документация

← Sandbox SDK / sandbox / configuration

Режимы транспорта

Настройте, как Sandbox SDK взаимодействует с контейнерами с помощью режимов транспорта.

Обзор

Sandbox SDK поддерживает три режима транспорта для взаимодействия между Durable Object и контейнером:

Когда использовать RPC-транспорт

Используйте транспорт RPC, если ваш Worker или Durable Object выполняет много операций SDK за один запрос. Это позволяет избежать ограничения на подзапросы.

Лимиты подзапросов

У Cloudflare Workers есть ограничения на количество подзапросов, которые действуют при обращении к внешним сервисам, включая вызовы API контейнера:

При HTTP-транспорте (по умолчанию) каждая операция SDK (exec(), readFile(), writeFile(), и т. д.) расходует один подзапрос. Приложения, которые выполняют много операций с песочницей в рамках одного запроса, могут упереться в эти лимиты.

Чем полезен RPC-транспорт

RPC-транспорт устанавливает единое постоянное соединение с контейнером и мультиплексирует через него все операции SDK. Обновление до WebSocket считается как один подзапрос независимо от того, сколько операций вы выполните после этого.

Пример с HTTP-транспортом (4 подзапроса):

await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");

Тот же код с RPC-транспортом (1 подзапрос):

// Identical code - transport is configured via environment variable
await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");

RPC-транспорт также устраняет Ограничение в 32 MiB который есть у HTTP-транспорта. Передайте ReadableStream экземпляр к writeFile() метод.

const req = await fetch("https://example.com/archive.tar.gz");
await sandbox.writeFile("/archive.tar.gz", req.body);

Конфигурация

Задайте SANDBOX_TRANSPORT переменную окружения в конфигурации Worker. SDK считывает её из привязок окружения Worker (а не изнутри контейнера).

HTTP-транспорт (по умолчанию)

HTTP-транспорт используется по умолчанию и не требует дополнительной настройки.

RPC-транспорт

Включите RPC-транспорт, добавив SANDBOX_TRANSPORT в конфигурацию вашего Worker vars:

{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}
name = "my-sandbox-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

[vars]
SANDBOX_TRANSPORT = "rpc"

[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

Изменять код приложения не нужно. SDK автоматически использует настроенный транспорт для всех операций.

Поведение транспорта

Жизненный цикл соединения

HTTP-транспорт:

RPC-транспорт:

Поддержка потоковой передачи

Все транспорты поддерживают потоковые операции (например, exec() с выводом в реальном времени):

Код остаётся одинаковым независимо от режима передачи.

Обработка ошибок

Все транспорты обеспечивают одинаковое поведение при обработке ошибок. При временных ошибках (например, ответах 503) SDK автоматически повторяет запрос с экспоненциальной задержкой (exponential backoff).

Особенности поведения, характерные для WebSocket:

Выбор транспорта

Мы ожидаем, что в одном из будущих релизов транспорт RPC заменит транспорт HTTP по умолчанию. Новая функциональность может поддерживать только транспорт RPC. Если перейти на него уже сейчас, в будущем не придётся выполнять миграцию.

Руководство по миграции

Переключение между транспортами не требует изменений кода.

Переход с HTTP на RPC

Добавить SANDBOX_TRANSPORT в ваш wrangler.jsonc:

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}
[vars]
SANDBOX_TRANSPORT = "rpc"

Затем разверните:

npx wrangler deploy

Переход с RPC на HTTP

Удалите SANDBOX_TRANSPORT переменную (или установите её в "http"):

{
	"vars": {
		// Remove SANDBOX_TRANSPORT or set to "http"
	},
}
vars = { }

Переход с устаревшего WebSocket на RPC

Задайте SANDBOX_TRANSPORT переменную на "rpc":

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}
[vars]
SANDBOX_TRANSPORT = "rpc"