Стриминг и обмен данными в реальном времени
Just Run использует способы передачи данных в реальном времени для вывода команд и интерактивных сессий песочницы. Общей шины событий продукта нет. Выбирайте способ передачи по тому, какая работа должна пережить разрыв соединения:
- Постепенный вывод одной конечной команды: используйте SSE
exec-stream. У команды нет курсора возобновления; повторный запрос запускает новую команду. - Фоновый процесс, живущий дольше клиента: запустите его и используйте WebSocket для подключения к процессу. Процесс продолжает работу, а переподключение получает ограниченное воспроизведение.
- Интерактивная оболочка для человека: используйте WebSocket терминала. Переподключение создает свежий PTY; вывод терминала не воспроизводится.
- Полный вывод в одном детерминированном ответе: используйте
execс буферизацией. Соединения в реальном времени нет; ответ приходит после завершения.
Точные схемы запросов, событий и фреймов приведены на странице Протоколы песочницы для обмена данными в реальном времени.
Аутентификация соединения
Используйте bearer-токен в запросе SSE и при WebSocket handshake в клиентах,
поддерживающих пользовательские заголовки. Эти эндпоинты выполняют код или
передают ввод процесса, поэтому применяйте учетные данные с полными правами,
хотя сам переход на WebSocket использует HTTP GET.
Встроенный в браузер WebSocket не позволяет задать заголовок Authorization.
Дашборд авторизованного пользователя передает короткоживущие учетные данные
доступа в строке запроса при handshake. Не помещайте долговременный
персональный токен в URL.
Для терминала и подключения к процессу нужна песочница в состоянии running.
Перед подключением возобновите или пробудите ее. exec-stream может участвовать
в настроенном пробуждении по запросу, но переносимой интеграции следует явно
управлять переходами жизненного цикла.
Чтение SSE без повторного выполнения
exec-stream — это POST с телом JSON, поэтому API браузера EventSource не
подходит: он отправляет GET и не может добавить нужный заголовок с
bearer-токеном. Используйте HTTP-клиент с поддержкой стриминга или fetch.
Для каждой SSE-записи:
- Игнорируйте записи поддержания соединения, состоящие только из комментария.
- Разберите значение
dataкак JSON. - Добавляйте фрагменты
stdoutиstderr, не считая их границами строк. - Считайте только
exitподтвержденным терминальным результатом.
Если тело ответа закрылось без exit, результат неизвестен. Не повторяйте POST
автоматически: идентификаторов событий SSE и ключа идемпотентности нет, поэтому
повторная попытка может запустить команду дважды.
Когда работа должна поддерживать переподключение, запустите ее как фоновый процесс и используйте WebSocket для подключения к процессу. Если всю операцию нужно безопасно повторять, сделайте саму команду идемпотентной и проверьте ее внешний результат до нового запуска.
Переподключение к процессу с учетом воспроизведения
Подключение к процессу отделяет сохраненную историю от текущего вывода:
replaystart → retained stdout/stderr → replayend → live stdout/stderr → exit
Процесс не зависит от WebSocket и продолжает работу после отключения клиента. При каждом новом подключении сервер начинает воспроизведение с самого старого сохраненного вывода. Воспроизведение ограничено и не содержит порядковых идентификаторов, поэтому уже увиденный в предыдущем соединении вывод может появиться снова.
Используйте маркеры воспроизведения, чтобы отделить исторический вывод от текущего. Если интеграции нужен долговременный журнал с семантикой «ровно один раз», процесс должен сам писать вывод в хранилище, файл или внешнюю систему журналирования; буфер подключения таким журналом не является.
Отправляйте stdin через сокет только ожидающему его процессу. Сигналы
отправляйте через эндпоинт REST signal — текущее сообщение WebSocket signal
игнорируется.
Переподключение терминала как новой сессии
WebSocket терминала — это PTY, а не долговременный поток подключения к
процессу. Его первое сообщение всегда имеет тип start; вывод передается
исходными бинарными байтами, а управляющие сообщения — как текст JSON.
Используйте декодер, который обрабатывает данные по частям, для бинарных
фреймов, чтобы сохранить символы UTF-8, разделенные между фреймами.
При потере соединения:
- закройте и удалите состояние старого сокета;
- повторяйте попытки с ограниченной экспоненциальной задержкой и случайным разбросом;
- откройте новый WebSocket;
- отправьте новое сообщение
startдо любого ввода или изменения размера.
При плавном обновлении управляющий компонент закрывает сокет с кодом 1001.
Дашборд использует его как сигнал для переподключения и запускает свежую
оболочку. Когда состояние оболочки должно переживать переподключение, дашборд
использует tmux; у обычной сессии оболочки нет воспроизведения на уровне
платформы.
Не храните важные побочные эффекты только в сессии терминала. Запускайте сервис как фоновый процесс, сохраняйте данные в файловой системе песочницы или хранилище аккаунта, а переподключение терминала используйте только для восстановления интерактивного доступа.
Порядок и завершение
Контракты гарантируют порядок только внутри одного отправляемого потока:
- SSE и подключение к процессу отправляют
exitпосле получения оставшихся stdout и stderr. - Терминал отправляет
exitedпосле передачи буферизованного вывода PTY. - Фрагменты stdout и stderr не являются строками или записями с временными метками.
- Ни один контракт не предоставляет глобальную последовательность для разных соединений, песочниц или независимых потоков.
Сохраняйте порядок получения сообщений внутри одного соединения. Не объединяйте stdout и stderr по времени получения клиентом и не считайте результат полным порядком по времени выполнения.
Обнаружение незавершенного результата
Считайте неопределенными, а не успешными, следующие случаи:
- SSE закрылся без
exit; - подключение к процессу закрылось без
exit; - терминал закрылся без
exited, если его не закрыл сам клиент.
Запишите ID песочницы, PID процесса при наличии, код закрытия, статус HTTP при
handshake, временную метку и x-request-id, если он был возвращен. Затем
используйте способ восстановления конкретного контракта: проверьте внешний
результат до повтора SSE, переподключитесь к процессу для воспроизведения или
запустите свежий терминал.
WebSocket приложений
Сервис внутри песочницы может открыть собственный WebSocket через прокси песочницы или порт превью. Just Run пересылает текстовые, бинарные, ping- и pong-фреймы, но приложение само определяет протокол, режим аутентификации и семантику переподключения. Документируйте эти сообщения вместе с приложением, а не как события Just Run в реальном времени.