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

Процессы

Запускайте и отслеживайте управляемые процессы в текущем контейнере песочницы.

Общую модель работы см. в Выполнение процессов. Об интерактивном вводе PTY и терминалах в браузере см. Терминалы и Terminals API.

У дескрипторов процессов есть без стандартного ввода. Используйте cwd, env, и argv (или явный shell-скрипт) для неинтерактивной работы. Используйте терминал когда вам нужен интерактивный PTY.

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

exec(command: SandboxCommand, options?: ExecOptions): Promise<SandboxProcess>

type SandboxCommand = readonly [executable: string, ...args: string[]];

• command[0] должен быть непустым путём или именем исполняемого файла.
• Последующие аргументы могут быть пустыми строками.
• Записи передаются как есть (без экранирования оболочки для argv).
• Синтаксис shell требует явного указания shell, например ['/bin/bash', '-lc', script].

Promise<SandboxProcess>

const process = await sandbox.exec(["node", "--version"]);
const output = await process.output({ encoding: "utf8" });

console.log(process.id, process.pid, output.stdout, output.exitCode);

const process = await sandbox.exec(["node", "--version"]);
const output = await process.output({ encoding: "utf8" });

console.log(process.id, process.pid, output.stdout, output.exitCode);

Возвращает дескриптор для процесса, запущенного в текущий контейнер для этого сандбокса, или null.

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

getProcess(id: string): Promise<SandboxProcess | null>

ID процессов не сохраняются при остановке или замене контейнера. См. Сколько живёт процесс.

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

listProcesses(): Promise<ProcessStatus[]>

Каждая запись представляет собой ProcessStatus значение (такой же структуры, как status()).

У этого дескриптора нет API stdin для процесса.

status(): Promise<ProcessStatus>

См. ProcessStatus. Процесс остается running пока контролируемый группа процессов устоялось, даже если корневой pid завершается, а потомки продолжают работу.

Буферизует stdout и stderr до завершения процесса (или до окончания локального ожидания), а затем возвращает метаданные завершения.

output(options?: ProcessOutputOptions): Promise<ProcessOutput<Uint8Array>>
output(
	options: ProcessOutputOptions & { encoding: "utf8" },
): Promise<ProcessOutput<string>>

interface ProcessOutput<T = Uint8Array> {
	stdout: T;
	stderr: T;
	exitCode: number;
	signal?: number;
	timedOut: boolean;
	truncated: boolean;
}

Кодировка тела по умолчанию: binary (Uint8Array) если только вы не передадите encoding: "utf8". Предпочитайте logs() когда объём вывода может превысить желаемый размер буфера.

maxBytes при установке должен быть неотрицательным конечным числом.

const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"], {
	cwd: "/workspace/app",
});
const result = await process.output({ encoding: "utf8", timeout: 120_000 });

console.log(result.exitCode, result.stdout, result.timedOut, result.truncated);

const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"], {
	cwd: "/workspace/app",
});
const result = await process.output({ encoding: "utf8", timeout: 120_000 });

console.log(result.exitCode, result.stdout, result.timedOut, result.truncated);

Передаёт воспроизводимые события журнала с использованием непрозрачного курсора.

logs(options?: ProcessLogsOptions): Promise<ReadableStream<ProcessLogEvent>>

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

Сохранение последних cursor из доставленных событий, если последующий запрос Worker возобновляется с logs({ since: cursor, replay: true, follow: true }) на одинаковый процесс в одинаковый контейнер.

const process = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

const stream = await process.logs({ follow: true, replay: true });
const reader = stream.getReader();
const decoder = new TextDecoder();

for (;;) {
	const { done, value } = await reader.read();
	if (done) break;

	if (value.type === "stdout" || value.type === "stderr") {
		// Keep value.cursor if you will resume later
		console.log(value.type, decoder.decode(value.data, { stream: true }));
		continue;
	}

	if (value.type === "terminal") {
		console.log("done", value.state);
		break;
	}
}

const process = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

const stream = await process.logs({ follow: true, replay: true });
const reader = stream.getReader();
const decoder = new TextDecoder();

for (;;) {
	const { done, value } = await reader.read();
	if (done) break;

	if (value.type === "stdout" || value.type === "stderr") {
		// Keep value.cursor if you will resume later
		console.log(value.type, decoder.decode(value.data, { stream: true }));
		continue;
	}

	if (value.type === "terminal") {
		console.log("done", value.state);
		break;
	}
}

Дождитесь стабилизации отслеживаемой группы процессов.

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

Возвращает ProcessExit. Локальный тайм-аут проявляется как ProcessWaitTimeoutError. Локальное прерывание проявляется как ProcessAbortedError.

const build = await sandbox.exec(["/bin/bash", "-lc", "npm run build"], {
	cwd: "/workspace/app",
});
const exit = await build.waitForExit({ timeout: 600_000 });
console.log(exit.code, exit.signal, exit.timedOut);

const build = await sandbox.exec(["/bin/bash", "-lc", "npm run build"], {
	cwd: "/workspace/app",
});
const exit = await build.waitForExit({ timeout: 600_000 });
console.log(exit.code, exit.signal, exit.timedOut);

Дождитесь, пока stdout и (или) stderr совпадут с паттерном.

waitForLog(
	pattern: string | RegExp,
	options?: WaitForLogOptions,
): Promise<WaitForLogResult>

interface WaitForLogResult {
	stream: "stdout" | "stderr";
	text: string;
	match: string;
	cursor?: string;
}

• text это совпадающее окно декодированного вывода для этого потока.
• match это найденная подстрока.
• cursor это курсор лога в точке совпадения, если он доступен.

Если процесс завершается до совпадения, SDK выбрасывает исключение ProcessExitedBeforeLogError. Локальный тайм-аут ожидания вызывает исключение ProcessWaitTimeoutError.

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

const ready = await server.waitForLog(/listening on/i, {
	stream: "both",
	timeout: 60_000,
});
console.log(ready.stream, ready.match);

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

const ready = await server.waitForLog(/listening on/i, {
	stream: "both",
	timeout: 60_000,
});
console.log(ready.stream, ready.match);

Дождитесь готовности порта либо завершите с ошибкой, если процесс завершится раньше или закончится локальное ожидание.

waitForPort(port: number, options?: WaitForPortOptions): Promise<void>

Режим TCP (по умолчанию) считается успешным, когда порт принимает соединение:

const db = await sandbox.exec(["redis-server"]);

await db.waitForPort(6379, {
	mode: "tcp",
	timeout: 10_000,
});

const db = await sandbox.exec(["redis-server"]);

await db.waitForPort(6379, {
	mode: "tcp",
	timeout: 10_000,
});

Режим HTTP отправляет HTTP запрос и проверяет статус ответа:

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

await server.waitForPort(3000, {
	mode: "http",
	path: "/health",
	status: { min: 200, max: 299 },
	timeout: 60_000,
});

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

await server.waitForPort(3000, {
	mode: "http",
	path: "/health",
	status: { min: 200, max: 299 },
	timeout: 60_000,
});

Типичные сбои:

• ProcessReadyTimeoutError : порт не готов до истечения локального таймаута
• ProcessExitedBeforeReadyError : процесс завершился раньше, чем порт стал готов
• ProcessAbortedError : локальный AbortSignal отменил ожидание (процесс может всё ещё выполняться)

Отправьте процессу числовой сигнал.

kill(signal?: number): Promise<void>

По умолчанию signal это 15 (SIGTERM). Передавайте только числовой сигнал (например, 9 для SIGKILL). Строковые имена сигналов не принимаются.

Остановка процесса не связана с отменой локального ожидания или подписки на логи.

readonly exitCode: Promise<number>

Возвращает код завершения после того, как контролируемая группа процессов завершит работу (та же граница завершения, что и у waitForExit()). Отдавайте предпочтение waitForExit() когда вам также нужен signal или timedOut.

type ProcessStatus =
	| {
			state: "running";
			id: string;
			pid: number;
			command: SandboxCommand;
			cwd?: string;
			startedAt: string;
	  }
	| {
			state: "exited";
			id: string;
			pid: number;
			command: SandboxCommand;
			cwd?: string;
			startedAt: string;
			endedAt: string;
			exit: ProcessExit;
	  }
	| {
			state: "error";
			id: string;
			pid: number;
			command: SandboxCommand;
			cwd?: string;
			startedAt: string;
			endedAt: string;
			error: ProcessFailure;
	  };

listProcesses() возвращает ProcessStatus[] используя такую структуру.

Результат, наблюдаемый для корень подпроцесс, когда контролируемая группа завершает работу.

interface ProcessExit {
	code: number;
	signal?: number;
	timedOut: boolean;
}

Сигналы, доставленные только потомкам, не изменяют этот результат. См. Выполнение процессов.

interface ProcessFailure {
	code: string;
	message: string;
}

getProcess и listProcesses не выбрасывают исключение при отсутствии задачи. Они возвращают null или [] когда контейнер не запущен, идентификатор неизвестен в текущем контейнере или процесс принадлежал предыдущему контейнеру. Следующие классы ошибок относятся к операциям с дескриптором процесса (и к запуску), а не к этим запросам.

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

• Выполнение процессов
• Ошибки и восстановление
• API ошибок
• Terminals API
• Справочник по API
• Переход со стабильной версии SDK
• Стабильно: Команды