← Sandbox SDK / sandbox / concepts

Архитектура

Sandbox SDK позволяет безопасно выполнять недоверенный код из ваших Workers. Он объединяет три технологии Cloudflare, чтобы обеспечить безопасное, изолированное выполнение с сохранением состояния:

• Workers - Логика вашего приложения, которая вызывает Sandbox SDK
• Durable Objects - Постоянные экземпляры песочниц с уникальными идентификаторами
• Containers - Изолированные среды Linux, в которых фактически выполняется код

flowchart TB
    accTitle: Sandbox SDK Architecture
    accDescr: Three-layer architecture showing how Cloudflare Sandbox SDK combines Workers, Durable Objects, and Containers for secure code execution

    subgraph UserSpace["<b>Your Worker</b>"]
        Worker["Application code using the methods exposed by the Sandbox SDK"]
    end

    subgraph SDKSpace["<b>Sandbox SDK Implementation</b>"]
        DO["Sandbox Durable Object routes requests & maintains state"]
        Container["Isolated Ubuntu container executes untrusted code safely"]

        DO -->|HTTP API| Container
    end

    Worker -->|RPC call via the Durable Object stub returned by `getSandbox`| DO

    style UserSpace fill:#fff8f0,stroke:#f6821f,stroke-width:2px
    style SDKSpace fill:#f5f5f5,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5
    style Worker fill:#ffe8d1,stroke:#f6821f,stroke-width:2px
    style DO fill:#dce9f7,stroke:#1d8cf8,stroke-width:2px
    style Container fill:#d4f4e2,stroke:#17b26a,stroke-width:2px

API для разработчиков, который вы используете в своих Workers:

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox");
const result = await sandbox.exec("python script.py");

Назначение: Предоставляет чистый, типобезопасный интерфейс TypeScript для всех операций с песочницей.

Управляет жизненным циклом песочницы и маршрутизацией:

export class Sandbox extends DurableObject<Env> {
	// Extends Cloudflare Container for isolation
	// Routes requests between client and container
	// Manages preview URLs and state
}

Назначение: Предоставляет постоянные, сохраняющие состояние экземпляры песочницы с уникальными идентификаторами.

Почему Durable Objects:

• Постоянная идентичность - Один и тот же ID песочницы всегда направляется на один и тот же экземпляр
• Управление контейнером - Durable Object владеет жизненным циклом контейнера и управляет им
• Географическое распределение - Песочницы работают рядом с пользователями
• Автоматическое масштабирование - Cloudflare берет на себя выделение ресурсов

Выполняет код в изоляции с полным набором возможностей Linux.

Назначение: Безопасно выполняет код из недоверенных источников.

Почему контейнеры:

• Изоляция на основе VM - Каждая песочница выполняется в собственной ВМ
• Полное окружение - Ubuntu Linux с Python, Node.js, Git и другими инструментами

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

Каждый метод SDK выполняет отдельный HTTP-запрос к API контейнера. Это просто, надёжно и подходит для большинства сценариев использования.

// Default behavior - uses HTTP
const sandbox = getSandbox(env.Sandbox, "my-sandbox");
await sandbox.exec("python script.py");

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

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

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}

[vars]
SANDBOX_TRANSPORT = "rpc"

Транспорт WebSocket устарел. Для новых приложений используйте транспорт RPC.

Транспортный уровень прозрачен для кода вашего приложения: все методы SDK работают одинаково независимо от транспорта. Подробности о том, когда использовать тот или иной транспорт, и примеры настройки см. в Режимы транспорта.

Когда вы выполняете команду:

await sandbox.exec("python script.py");

Схема работы HTTP-транспорта:

1. Клиентский SDK проверяет параметры и отправляет HTTP-запрос в Durable Object
2. Durable Object аутентифицирует и перенаправляет HTTP-запрос в контейнер
3. Среда выполнения контейнера проверяет входные данные, выполняет команду, собирает вывод
4. Ответ возвращается обратно через все слои с корректным преобразованием ошибок

Схема работы RPC-транспорта:

1. Клиентский SDK проверяет параметры и отправляет запрос в Durable Object
2. Durable Object поддерживает постоянное соединение с контейнером и мультиплексирует параллельные запросы
3. Среда выполнения контейнера преобразует RPC-сообщения в обработку запросов и ответов в стиле HTTP
4. Ответ возвращается обратно через то же соединение с корректным преобразованием ошибок

Durable Object устанавливает постоянное соединение с контейнером при первом вызове SDK и повторно использует его для всех последующих операций, снижая накладные расходы при высокочастотных операциях.

• Жизненный цикл песочницы - Как создаются песочницы и как ими управлять
• Среда выполнения контейнера - Внутри среды выполнения
• Модель безопасности - Как работают изоляция и валидация
• Управление сессиями - Расширенное управление состоянием