Протоколы песочницы для обмена данными в реальном времени
В части платформы для работы с данными песочницы Just Run предоставляет три контракта обмена данными в реальном времени:
| Контракт | Эндпоинт | Способ передачи | Назначение |
|---|---|---|---|
| Выполнение команды со стримингом | POST /v1/sandboxes/{id}/exec-stream | Server-Sent Events | Запустить одну команду и последовательно получать stdout, stderr и exit |
| Подключение к процессу | GET /v1/sandboxes/{id}/processes/{pid}/attach | WebSocket | Получить воспроизведение и следить за существующим фоновым процессом с возможностью отправки stdin |
| Интерактивный терминал | GET /v1/sandboxes/{id}/terminal | WebSocket | Запустить PTY-сессию и управлять ей |
Запросы HTTP handshake входят в сгенерированный справочник REST. Эта страница определяет контракты событий и фреймов. WebSocket-соединения приложений внутри песочницы используют протокол самого приложения и не входят в эти схемы сообщений платформы.
Аутентификация
Используйте тот же адрес инсталляции, что и для REST API. В инсталляции с HTTPS
URL WebSocket использует wss:
https://your-just-run-host/v1/sandboxes/{id}/exec-stream
wss://your-just-run-host/v1/sandboxes/{id}/processes/{pid}/attach
wss://your-just-run-host/v1/sandboxes/{id}/terminal
Для SSE и WebSocket-клиентов, умеющих задавать заголовки handshake,
отправляйте Authorization: Bearer <token>. Каждый эндпоинт проверяет доступ
аутентифицированного аккаунта к песочнице.
Для всех трех контрактов используйте персональный токен с правами full. Эти
эндпоинты выполняют код или передают ввод процесса, поэтому их нельзя считать
доступными только для чтения лишь потому, что переход на WebSocket использует
HTTP GET.
WebSocket API браузера не позволяет задать заголовок Authorization. Шлюз также
принимает учетные данные активной сессии в параметре строки запроса token или
access_token при handshake и может использовать cookie активной сессии. Не
помещайте долговременный персональный токен в URL: строка запроса может
попасть в историю браузера, журналы доступа и системы мониторинга.
Всем трем контрактам нужна работающая среда выполнения песочницы. Терминал и подключение к процессу не пробуждают остановленную песочницу или песочницу в гибернации при handshake WebSocket.
Выполнение команды со стримингом через SSE
Отправьте обычную JSON-форму exec без stdin:
curl --no-buffer --fail-with-body \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec-stream" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"cmd": "sh",
"args": ["-lc", "printf \"step 1\\n\"; printf \"warning\\n\" >&2"],
"cwd": "/tmp",
"env": {"RUN_MODE": "stream"},
"timeout": 30000
}'
Поля запроса:
| Поле | Тип | Поведение |
|---|---|---|
cmd | строка | Обязательный исполняемый файл; пустая строка отклоняется |
args | массив строк | Необязательные аргументы; по умолчанию [] |
cwd | строка или null | Необязательная рабочая директория |
env | объект | Необязательные дополнения переменных окружения; по умолчанию {} |
timeout | целое число или null | Необязательный положительный таймаут в миллисекундах; задавайте явно, когда команде нужна граница |
user | строка или null | Необязательный пользователь Unix; по умолчанию пользователь песочницы |
stdin | строка или null | Здесь не поддерживается; любое переданное значение получает HTTP 400 |
Успешный ответ имеет тип содержимого text/event-stream. В каждой записи data
находится один объект JSON:
data: {"type":"stdout","text":"step 1\n"}
data: {"type":"stderr","text":"warning\n"}
data: {"type":"exit","code":0}
type | Поля | Значение |
|---|---|---|
stdout | строка text | Один полученный фрагмент stdout |
stderr | строка text | Один полученный фрагмент stderr |
exit | целое число code, необязательная строка reason | Терминальный результат после чтения оставшегося вывода |
Фрагменты не являются записями по строкам: одна строка может занимать несколько событий, а одно событие — содержать несколько строк. Байты, не являющиеся корректным UTF-8, преобразуются с заменой.
Обычная команда заканчивается ровно одним событием exit. При остановке
управляющего компонента терминальное событие имеет вид
{"type":"exit","code":-1,"reason":"supervisor shutdown"}. Если HTTP-поток
закончился без exit, завершение команды неизвестно.
Поток не отправляет SSE id и не реализует Last-Event-ID. Повторный POST
запускает еще одну команду, поэтому автоматическое переподключение SSE может
дублировать выполнение. Клиент при разборе SSE должен игнорировать возможные
записи поддержания соединения, состоящие только из комментариев.
Подключение к фоновому процессу
Создайте процесс через POST /v1/sandboxes/{id}/start, сохраните возвращенный
pid, затем выполните переход на WebSocket:
wss://your-just-run-host/v1/sandboxes/{id}/processes/{pid}/attach
Текстовые фреймы от сервера к клиенту
Каждый фрейм платформы содержит текст JSON:
| Фрейм | Значение |
|---|---|
{"type":"replaystart"} | Начало исторического вывода |
{"type":"stdout","data":"..."} | Фрагмент stdout из воспроизведения или текущего потока |
{"type":"stderr","data":"..."} | Фрагмент stderr из воспроизведения или текущего потока |
{"type":"replayend"} | Конец исторического вывода; следующий вывод относится к текущему потоку |
{"type":"exit","code":0} | Процесс завершился; это терминальный фрейм |
Соединение начинается с replaystart, отправляет сохраненный вывод процесса, а
затем обычно присылает replayend перед текущим выводом. Если exit
завершившегося процесса уже находится в воспроизведении, он закрывает WebSocket
и может прийти без последующего replayend.
Воспроизведение — это ограниченная помощь при восстановлении, а не долговременный журнал. Текущий буфер процесса хранит до 10 МиБ вывода и сначала удаляет самые старые фрагменты. Публичных порядковых номеров и курсоров нет. После переподключения воспроизведение начинается с самого старого все еще доступного фрагмента, поэтому клиент, добавляющий данные между соединениями, может увидеть дубликаты.
exit записывается после того, как из stdout и stderr прочитаны оставшиеся
данные. Фрагменты сохраняют порядок собранных событий, но не являются границами
строк или глобальными временными метками для двух потоков операционной системы.
Фреймы от клиента к серверу
Отправляйте stdin как текст JSON:
{"type":"stdin","data":"hello\n"}
либо как бинарный фрейм WebSocket с исходными байтами. Значение data в JSON
кодируется в UTF-8 перед записью.
Не отправляйте фрейм signal. Текущий обработчик WebSocket игнорирует его;
используйте:
POST /v1/sandboxes/{id}/processes/{pid}/signal
с SIGTERM, SIGKILL или SIGINT.
Закрытие сокета подключения к процессу не останавливает фоновый процесс. Пока
запись о процессе доступна, новое подключение может получить сохраненный вывод и
продолжить следить за процессом. При плавном обновлении управляющий компонент
закрывает подключение к процессу с кодом WebSocket 1001; переподключитесь к
тому же PID и обработайте новый сегмент воспроизведения.
WebSocket интерактивного терминала
Выполните переход на WebSocket:
wss://your-just-run-host/v1/sandboxes/{id}/terminal
Первым фреймом клиента должно быть сообщение JSON start:
{
"type": "start",
"shell": "/bin/bash",
"args": [],
"cols": 120,
"rows": 40,
"envs": {"TERM": "xterm-256color"},
"cwd": "/home/user",
"user": "user"
}
| Поле | Значение по умолчанию |
|---|---|
shell | /bin/bash |
args | [] |
cols | 120; значение ограничивается диапазоном 1..65535 |
rows | 40; значение ограничивается диапазоном 1..65535 |
envs | {}, объединенный поверх переменных окружения песочницы |
cwd | Домашняя директория выбранного пользователя |
user | Пользователь песочницы по умолчанию |
Первое значение JSON можно передать как текстовый фрейм или как бинарный фрейм с
JSON; используйте текстовый, чтобы не спутать его с последующим исходным вводом
PTY. Если первое значение не является корректным сообщением start, сервер
закрывает уже открытое соединение WebSocket. После start клиент может
отправлять:
{"type":"input","data":"printf 'hello\\n'\r"}
{"type":"resize","cols":100,"rows":30}
Бинарный фрейм клиента считается исходным вводом PTY. Дополнительные сообщения
start игнорируются.
Для управляющих сообщений сервер отправляет текст JSON, а для вывода — бинарные фреймы:
| Фрейм | Значение |
|---|---|
{"type":"started","pid":42} | Процесс PTY запущен |
| Бинарный фрейм | Исходные байты вывода PTY |
{"type":"exited","exit_code":0} | Оболочка завершилась после отправки буферизованного вывода |
Декодируйте бинарный вывод как непрерывный поток байтов. Кодовая точка UTF-8 может быть разделена между фреймами, поэтому используйте декодер, который обрабатывает данные по частям, а не декодируйте каждый фрейм отдельно.
У сессии терминала нет воспроизведения и курсора возобновления. После разрыва
соединения откройте новый WebSocket и отправьте новое сообщение start; это
создает свежий PTY. При плавном обновлении управляющий компонент закрывает
соединение с кодом WebSocket 1001 (Going Away), чтобы клиент мог
переподключиться. Не рассчитывайте на сохранение состояния оболочки, если
намеренно не храните его в таком инструменте, как tmux, или в отсоединенном
фоновом сервисе.
Ошибки и незавершенные потоки
До принятия SSE или перехода на WebSocket ошибки используют обычный статус HTTP и ошибку JSON:
| Условие | Типичный результат |
|---|---|
| Учетные данные отсутствуют, неверны, истекли или не имеют доступа | 401, 403 или 404, скрывающий принадлежность песочницы |
| Песочницы нет или она не видна | 404 |
| Среда выполнения песочницы не запущена | 400 |
| PID процесса недоступен для подключения | 404 |
Неверное тело exec или stdin в exec-stream | 400 |
| Превышено ограничение частоты запросов | 429 |
| Управляющий компонент-владелец среды выполнения временно недоступен | 502 или 503 |
После ответа SSE 200 или перехода на WebSocket 101 закрытие соединения
заменяет тело ошибки HTTP. Считайте неопределенным результатом конец потока SSE
без exit, закрытие подключения к процессу без exit или закрытие терминала
без exited; решение о переподключении зависит от семантики воспроизведения
конкретного контракта.