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

Стриминг и обмен данными в реальном времени

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-записи:

  1. Игнорируйте записи поддержания соединения, состоящие только из комментария.
  2. Разберите значение data как JSON.
  3. Добавляйте фрагменты stdout и stderr, не считая их границами строк.
  4. Считайте только 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, разделенные между фреймами.

При потере соединения:

  1. закройте и удалите состояние старого сокета;
  2. повторяйте попытки с ограниченной экспоненциальной задержкой и случайным разбросом;
  3. откройте новый WebSocket;
  4. отправьте новое сообщение 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 в реальном времени.