← Sandbox SDK / sandbox / api

Жизненный цикл

Создавайте контейнеры песочницы и управляйте ими. Получайте экземпляры песочницы, настраивайте параметры и освобождайте ресурсы.

Получение или создание экземпляра песочницы по ID.

const sandbox = getSandbox(
  binding: DurableObjectNamespace<Sandbox>,
  sandboxId: string,
  options?: SandboxOptions
): Sandbox

Параметры:

• binding - Привязка пространства имён Durable Object из окружения вашего Worker
• sandboxId - Уникальный идентификатор этой песочницы. Один и тот же ID всегда возвращает один и тот же экземпляр песочницы. В приложениях с пользовательским интерфейсом привязывайте ID к одному пользователю.
• options (необязательно) - См. SandboxOptions для просмотра всех доступных параметров:
  • enableDefaultSession - Используйте сессию по умолчанию для операций без явного sessionId. Установите значение false чтобы обрабатывать каждый вызов изолированно (по умолчанию: true)
  • sleepAfter - Продолжительность простоя перед автоматическим переходом в спящий режим (по умолчанию: "10m")
  • keepAlive - Полностью отключает автоматический переход в спящий режим. Сохраняется при гибернации (по умолчанию: false)
  • containerTimeouts - Настройте тайм-ауты запуска контейнера
  • normalizeId - Идентификаторы песочниц в нижнем регистре для совместимости с preview URL (по умолчанию: false)

Возвращает: Sandbox инстанс

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

export default {
	async fetch(request, env) {
		const sandbox = getSandbox(env.Sandbox, "user-123");
		const result = await sandbox.exec("python script.py");
		return Response.json(result);
	},
};

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

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const sandbox = getSandbox(env.Sandbox, 'user-123');
    const result = await sandbox.exec('python script.py');
    return Response.json(result);
  }
};

Включайте или отключайте режим keepAlive динамически после создания sandbox.

await sandbox.setKeepAlive(keepAlive: boolean): Promise<void>

Параметры:

• keepAlive - true чтобы предотвратить автоматический переход в спящий режим, false чтобы разрешить обычное поведение при переходе в спящий режим

Когда эта функция включена, sandbox автоматически отправляет heartbeat-пинги каждые 30 секунд, чтобы предотвратить вытеснение контейнера. Когда она отключена, sandbox возвращается к обычному режиму сна на основе sleepAfter конфигурации.

const sandbox = getSandbox(env.Sandbox, "user-123");

// Enable keepAlive for a long-running process
await sandbox.setKeepAlive(true);
await sandbox.startProcess("python long_running_analysis.py");

// Later, disable keepAlive when done
await sandbox.setKeepAlive(false);

const sandbox = getSandbox(env.Sandbox, 'user-123');

// Enable keepAlive for a long-running process
await sandbox.setKeepAlive(true);
await sandbox.startProcess('python long_running_analysis.py');

// Later, disable keepAlive when done
await sandbox.setKeepAlive(false);

Уничтожьте контейнер sandbox и освободите ресурсы.

await sandbox.destroy(): Promise<void>

Немедленно завершает работу контейнера и безвозвратно удаляет всё состояние:

• Все файлы в /workspace, /tmp, а также /home
• Все выполняющиеся процессы
• Все сессии (включая сессию по умолчанию)
• Сетевые подключения и открытые порты

async function executeCode(code) {
	const sandbox = getSandbox(env.Sandbox, `temp-${Date.now()}`);

	try {
		await sandbox.writeFile("/tmp/code.py", code);
		const result = await sandbox.exec("python /tmp/code.py");
		return result.stdout;
	} finally {
		await sandbox.destroy();
	}
}

async function executeCode(code: string): Promise<string> {
  const sandbox = getSandbox(env.Sandbox, `temp-${Date.now()}`);

  try {
    await sandbox.writeFile('/tmp/code.py', code);
    const result = await sandbox.exec('python /tmp/code.py');
    return result.stdout;
  } finally {
    await sandbox.destroy();
  }
}

• Концепция жизненного цикла песочницы - Жизненный цикл и состояние контейнера
• Настройка параметров песочницы - Настройте keepAlive и другие параметры
• Sessions API - Создавайте контексты выполнения внутри песочницы