Перейти к основному содержимому
Открыть Markdown

Протоколы песочницы для обмена данными в реальном времени

В части платформы для работы с данными песочницы Just Run предоставляет три контракта обмена данными в реальном времени:

КонтрактЭндпоинтСпособ передачиНазначение
Выполнение команды со стримингомPOST /v1/sandboxes/{id}/exec-streamServer-Sent EventsЗапустить одну команду и последовательно получать stdout, stderr и exit
Подключение к процессуGET /v1/sandboxes/{id}/processes/{pid}/attachWebSocketПолучить воспроизведение и следить за существующим фоновым процессом с возможностью отправки stdin
Интерактивный терминалGET /v1/sandboxes/{id}/terminalWebSocketЗапустить 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[]
cols120; значение ограничивается диапазоном 1..65535
rows40; значение ограничивается диапазоном 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-stream400
Превышено ограничение частоты запросов429
Управляющий компонент-владелец среды выполнения временно недоступен502 или 503

После ответа SSE 200 или перехода на WebSocket 101 закрытие соединения заменяет тело ошибки HTTP. Считайте неопределенным результатом конец потока SSE без exit, закрытие подключения к процессу без exit или закрытие терминала без exited; решение о переподключении зависит от семантики воспроизведения конкретного контракта.