← Sandbox SDK / sandbox / 1-0-preview / api

Терминалы

Создавайте интерактивные PTY-терминалы в текущем контейнере песочницы и управляйте ими.

Общую модель работы и пошаговое руководство по подключению браузера см. в Терминалы.

Запустите терминал из argv (обычно shell). Промис разрешается при создании ресурса терминала. Действуют те же правила, что и для процесса exec: без неявного оборачивания в shell, аргументы argv не экранируются для shell.

createTerminal(options: CreateTerminalOptions): Promise<Terminal>

SandboxCommand это тот же тип argv, что и у process exec: readonly [executable: string, ...args: string[]].

Promise<Terminal> : handle для терминала в текущий контейнер.

const terminal = await sandbox.createTerminal({
	command: ["bash"],
	cwd: "/workspace",
	env: { TERM: "xterm-256color" },
	cols: 120,
	rows: 40,
});

console.log(terminal.id);

const terminal = await sandbox.createTerminal({
	command: ["bash"],
	cwd: "/workspace",
	env: { TERM: "xterm-256color" },
	cols: 120,
	rows: 40,
});

console.log(terminal.id);

Возвращает дескриптор терминала в текущий контейнер, или null.

Не запускает контейнер, если ни один не выполняется. Возвращает null когда контейнер не запущен, когда идентификатор терминала неизвестен в текущем контейнере или когда этот терминал принадлежал предыдущему контейнеру с тем же идентификатором песочницы.

getTerminal(id: string): Promise<Terminal | null>

Выводит список терминалов в текущем контейнере этой песочницы. Не запускает контейнер, если он не работает. Если контейнер не запущен, возвращает пустой список.

listTerminals(): Promise<Terminal[]>

interface TerminalSnapshot {
	id: string;
	pid?: number;
	command: SandboxCommand;
	cwd?: string;
	status: "running" | "exited" | "error";
	exit?: ProcessExit;
	error?: ProcessFailure;
}

write(data: Uint8Array): Promise<void>

Запись байтов в PTY. Нажатия клавиш в браузере обычно поступают через connect() взамен.

resize(cols: number, rows: number): Promise<void>

output(options?: TerminalOutputOptions): Promise<ReadableStream<TerminalOutputEvent>>

type TerminalOutputEvent =
	| {
			type: "data";
			terminalId: string;
			cursor: string;
			timestamp: string;
			data: Uint8Array;
	  }
	| {
			type: "terminal";
			terminalId: string;
			cursor: string;
			timestamp: string;
			state: "exited";
			exit: ProcessExit;
	  }
	| {
			type: "terminal";
			terminalId: string;
			cursor: string;
			timestamp: string;
			state: "error";
			error: ProcessFailure;
	  }
	| {
			type: "truncated";
			terminalId: string;
			cursor?: string;
			timestamp: string;
	  };

Сохранение последних cursor из доставленных событий при повторном подключении или вызове output({ since, replay: true }) позже в одинаковый терминал в одинаковый контейнер.

waitForExit(options?: {
	timeout?: number;
	signal?: AbortSignal;
}): Promise<ProcessExit>

Локальный timeout / signal отменяют только ожидание. Они не завершают терминал. Вызовите terminate() или interrupt() когда вы собираетесь остановить его.

interrupt(): Promise<void>
terminate(): Promise<void>

Это операции управления терминалом. Они отличаются от операций с процессом kill(signal) на exec хендл.

Подключите к этому терминалу запрос на обновление WebSocket от браузера (или другого источника).

connect(
	request: Request,
	options?: {
		cursor?: string;
		cols?: number;
		rows?: number;
	},
): Promise<Response>

• request должен быть запросом на обновление до WebSocket.
• cursor возобновляет воспроизведение вывода после предыдущего отключения, если он есть у клиента.
• cols / rows задаёт размер PTY для этого подключения, если указан.

Возвращает обновление до WebSocket Response ваш Worker должен вернуть клиенту.

const url = new URL(request.url);
const terminalId = url.searchParams.get("terminalId");
if (!terminalId) {
	return new Response("terminalId is required", { status: 400 });
}

const terminal = await sandbox.getTerminal(terminalId);
if (!terminal) {
	return new Response("Terminal not found", { status: 404 });
}

return terminal.connect(request, {
	cursor: url.searchParams.get("cursor") ?? undefined,
	cols: 120,
	rows: 40,
});

const url = new URL(request.url);
const terminalId = url.searchParams.get("terminalId");
if (!terminalId) {
	return new Response("terminalId is required", { status: 400 });
}

const terminal = await sandbox.getTerminal(terminalId);
if (!terminal) {
	return new Response("Terminal not found", { status: 404 });
}

return terminal.connect(request, {
	cursor: url.searchParams.get("cursor") ?? undefined,
	cols: 120,
	rows: 40,
});

Полный путь с Worker и xterm.js см. в Терминалы.

SandboxAddon интегрирует xterm.js ↗ с preview-терминалами.

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

const addon = new SandboxAddon({
	// `origin` is already a WebSocket origin (`wss://` or `ws://`).
	getWebSocketUrl: ({ sandboxId, terminalId, cursor, origin }) => {
		const params = new URLSearchParams({ sandboxId });
		if (terminalId) params.set("terminalId", terminalId);
		if (cursor) params.set("cursor", cursor);
		return `${origin}/ws/terminal?${params}`;
	},
	reconnect: true,
	onStateChange: (state, error) => {
		/* update UI */
	},
});

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

const addon = new SandboxAddon({
	// `origin` is already a WebSocket origin (`wss://` or `ws://`).
	getWebSocketUrl: ({ sandboxId, terminalId, cursor, origin }) => {
		const params = new URLSearchParams({ sandboxId });
		if (terminalId) params.set("terminalId", terminalId);
		if (cursor) params.set("cursor", cursor);
		return `${origin}/ws/terminal?${params}`;
	},
	reconnect: true,
	onStateChange: (state, error) => {
		/* update UI */
	},
});

@xterm/xterm это необязательная peer зависимость предварительного пакета.

Рекомендации по восстановлению: Ошибки и восстановление. Полный каталог: API ошибок. Время жизни: Сколько живёт процесс.

• Терминалы
• Ошибки и восстановление
• API ошибок
• API процессов
• Справочник по API
• Миграция
• Стабильно: Терминал