← Sandbox SDK / sandbox / api

Терминал

Подключайте интерфейсы терминала в браузере к shell песочницы через WebSocket. Серверная часть terminal() метод проксирует WebSocket-соединения к контейнеру, а клиентский SandboxAddon интегрируется с xterm.js для отрисовки терминала.

Проксируйте запрос на обновление до WebSocket, чтобы создать соединение с терминалом.

const response = await sandbox.terminal(request: Request, options?: PtyOptions): Promise<Response>

Параметры:

• request - Запрос на обновление до WebSocket от браузера (должен включать Upgrade: websocket заголовок)
• options (необязательно):
  • cols - Ширина терминала в столбцах (по умолчанию: 80)
  • rows - Высота терминала в строках (по умолчанию: 24)

Возвращает: Promise<Response> : Ответ на обновление до WebSocket

// In your Worker's fetch handler
return await sandbox.terminal(request, { cols: 120, rows: 30 });

// In your Worker's fetch handler
return await sandbox.terminal(request, { cols: 120, rows: 30 });

Работает с обоими сессии по умолчанию и явно созданные сессии:

// Default session
return await sandbox.terminal(request);

// Specific session
const session = await sandbox.getSession("dev");
return await session.terminal(request);

// Default session
return await sandbox.terminal(request);

// Specific session
const session = await sandbox.getSession('dev');
return await session.terminal(request);

@cloudflare/sandbox/xterm модуль предоставляет SandboxAddon для xterm.js, который обрабатывает соединение WebSocket, переподключение и передачу изменения размера терминала.

import { SandboxAddon } from '@cloudflare/sandbox/xterm';

const addon = new SandboxAddon(options: SandboxAddonOptions);

Параметры:

• getWebSocketUrl(params) - Формирует URL-адрес WebSocket для каждой попытки подключения. Принимает:
  • sandboxId - ID целевой песочницы
  • sessionId (необязательно) - ID целевой сессии
  • origin - Источник WebSocket, определяемый из window.location (например, wss://example.com)
• reconnect - Включите автоматическое переподключение с экспоненциальной задержкой (по умолчанию: true)
• onStateChange(state, error?) - Обратный вызов для изменений состояния подключения

import { Terminal } from "@xterm/xterm";
import { SandboxAddon } from "@cloudflare/sandbox/xterm";

const terminal = new Terminal({ cursorBlink: true });
terminal.open(document.getElementById("terminal"));

const addon = new SandboxAddon({
	getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
		const params = new URLSearchParams({ id: sandboxId });
		if (sessionId) params.set("session", sessionId);
		return `${origin}/ws/terminal?${params}`;
	},
	onStateChange: (state, error) => {
		console.log(`Terminal ${state}`, error);
	},
});

terminal.loadAddon(addon);
addon.connect({ sandboxId: "my-sandbox" });

import { Terminal } from '@xterm/xterm';
import { SandboxAddon } from '@cloudflare/sandbox/xterm';

const terminal = new Terminal({ cursorBlink: true });
terminal.open(document.getElementById('terminal'));

const addon = new SandboxAddon({
  getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
    const params = new URLSearchParams({ id: sandboxId });
    if (sessionId) params.set('session', sessionId);
    return `${origin}/ws/terminal?${params}`;
  },
  onStateChange: (state, error) => {
    console.log(`Terminal ${state}`, error);
  }
});

terminal.loadAddon(addon);
addon.connect({ sandboxId: 'my-sandbox' });

Установите соединение с терминалом песочницы.

addon.connect(target: ConnectionTarget): void

Параметры:

• target:
  • sandboxId - Песочница, к которой нужно подключиться
  • sessionId (необязательно) - Сессия внутри песочницы

Вызов connect() с новой целью отключается от текущей цели и подключается к новой. Вызов с той же целью при уже установленном соединении не выполняет никаких действий.

Закройте соединение и остановите все попытки переподключения.

addon.disconnect(): void

SandboxAddon обрабатывает протокол WebSocket автоматически. Эти детали нужны для создания собственных клиентов терминала без надстройки. Полный пример см. в Подключайтесь без xterm.js.

1. Клиент открывает WebSocket-соединение с конечной точкой Worker. Задайте binaryType к arraybuffer.
2. Сервер повторно воспроизводит все буферизованный вывод от предыдущего соединения в виде бинарных кадров. Это может прийти раньше, чем ready сообщение.
3. Сервер отправляет ready статусное сообщение: терминал теперь принимает ввод.
4. Бинарные фреймы передаются в обоих направлениях: от клиента поступают нажатия клавиш в кодировке UTF-8, а от сервера поступает вывод терминала (включая ANSI-последовательности).
5. Если клиент отключается, PTY остаётся активным. При повторном подключении к той же сессии буферизованный вывод воспроизводится заново, поэтому терминал выглядит так же, как прежде.

Отправляйте текстовые фреймы JSON, чтобы управлять терминалом.

Изменение размера : обновление размеров терминала (оба cols и rows должен быть положительным):

{ "type": "resize", "cols": 120, "rows": 30 }

Сервер отправляет текстовые кадры JSON для событий жизненного цикла.

Готово : PTY инициализирован. Буферизованный вывод (если есть) уже отправлен:

{ "type": "ready" }

Выход : процесс shell завершился:

{ "type": "exit", "code": 0, "signal": "SIGTERM" }

Ошибка : произошла ошибка (например, недопустимое управляющее сообщение или сессия не найдена):

{ "type": "error", "message": "Session not found" }

interface PtyOptions {
	cols?: number;
	rows?: number;
}

type ConnectionState = "disconnected" | "connecting" | "connected";

interface ConnectionTarget {
	sandboxId: string;
	sessionId?: string;
}

interface SandboxAddonOptions {
	getWebSocketUrl: (params: {
		sandboxId: string;
		sessionId?: string;
		origin: string;
	}) => string;
	reconnect?: boolean;
	onStateChange?: (state: ConnectionState, error?: Error) => void;
}

• Подключения терминала : как работают подключения терминала
• Терминалы в браузере : Пошаговое руководство по настройке
• Sessions API : Управление сессиями
• Commands API : выполнение команд в неинтерактивном режиме