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

Just Run использует способы передачи данных в реальном времени для вывода команд и интерактивных сессий песочницы. Общей шины событий продукта нет. Выбирайте способ передачи по тому, какая работа должна пережить разрыв соединения:

* **Постепенный вывод одной конечной команды:** используйте SSE `exec-stream`. У команды нет курсора возобновления; повторный запрос запускает новую команду.
* **Фоновый процесс, живущий дольше клиента:** запустите его и используйте WebSocket для подключения к процессу. Процесс продолжает работу, а переподключение получает ограниченное воспроизведение.
* **Интерактивная оболочка для человека:** используйте WebSocket терминала. Переподключение создает свежий PTY; вывод терминала не воспроизводится.
* **Полный вывод в одном детерминированном ответе:** используйте `exec` с буферизацией. Соединения в реальном времени нет; ответ приходит после завершения.

Точные схемы запросов, событий и фреймов приведены на странице [Протоколы песочницы для обмена данными в реальном времени](/api-reference/realtime.md).

## Аутентификация соединения[​](#authenticate-the-connection "Прямая ссылка на Аутентификация соединения")

Используйте bearer-токен в запросе SSE и при WebSocket handshake в клиентах, поддерживающих пользовательские заголовки. Эти эндпоинты выполняют код или передают ввод процесса, поэтому применяйте учетные данные с полными правами, хотя сам переход на WebSocket использует HTTP `GET`.

Встроенный в браузер WebSocket не позволяет задать заголовок `Authorization`. Дашборд авторизованного пользователя передает короткоживущие учетные данные доступа в строке запроса при handshake. Не помещайте долговременный персональный токен в URL.

Для терминала и подключения к процессу нужна песочница в состоянии `running`. Перед подключением возобновите или пробудите ее. `exec-stream` может участвовать в настроенном пробуждении по запросу, но переносимой интеграции следует явно управлять переходами жизненного цикла.

## Чтение SSE без повторного выполнения[​](#consume-sse-without-duplicating-work "Прямая ссылка на Чтение 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 для подключения к процессу. Если всю операцию нужно безопасно повторять, сделайте саму команду идемпотентной и проверьте ее внешний результат до нового запуска.

## Переподключение к процессу с учетом воспроизведения[​](#reconnect-to-a-process-with-replay-awareness "Прямая ссылка на Переподключение к процессу с учетом воспроизведения")

Подключение к процессу отделяет сохраненную историю от текущего вывода:

```
replaystart → retained stdout/stderr → replayend → live stdout/stderr → exit
```

Процесс не зависит от WebSocket и продолжает работу после отключения клиента. При каждом новом подключении сервер начинает воспроизведение с самого старого сохраненного вывода. Воспроизведение ограничено и не содержит порядковых идентификаторов, поэтому уже увиденный в предыдущем соединении вывод может появиться снова.

Используйте маркеры воспроизведения, чтобы отделить исторический вывод от текущего. Если интеграции нужен долговременный журнал с семантикой «ровно один раз», процесс должен сам писать вывод в хранилище, файл или внешнюю систему журналирования; буфер подключения таким журналом не является.

Отправляйте stdin через сокет только ожидающему его процессу. Сигналы отправляйте через эндпоинт REST `signal` — текущее сообщение WebSocket `signal` игнорируется.

## Переподключение терминала как новой сессии[​](#reconnect-a-terminal-as-a-new-session "Прямая ссылка на Переподключение терминала как новой сессии")

WebSocket терминала — это PTY, а не долговременный поток подключения к процессу. Его первое сообщение всегда имеет тип `start`; вывод передается исходными бинарными байтами, а управляющие сообщения — как текст JSON. Используйте декодер, который обрабатывает данные по частям, для бинарных фреймов, чтобы сохранить символы UTF-8, разделенные между фреймами.

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

1. закройте и удалите состояние старого сокета;
2. повторяйте попытки с ограниченной экспоненциальной задержкой и случайным разбросом;
3. откройте новый WebSocket;
4. отправьте новое сообщение `start` до любого ввода или изменения размера.

При плавном обновлении управляющий компонент закрывает сокет с кодом `1001`. Дашборд использует его как сигнал для переподключения и запускает свежую оболочку. Когда состояние оболочки должно переживать переподключение, дашборд использует `tmux`; у обычной сессии оболочки нет воспроизведения на уровне платформы.

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

## Порядок и завершение[​](#ordering-and-completion "Прямая ссылка на Порядок и завершение")

Контракты гарантируют порядок только внутри одного отправляемого потока:

* SSE и подключение к процессу отправляют `exit` после получения оставшихся stdout и stderr.
* Терминал отправляет `exited` после передачи буферизованного вывода PTY.
* Фрагменты stdout и stderr не являются строками или записями с временными метками.
* Ни один контракт не предоставляет глобальную последовательность для разных соединений, песочниц или независимых потоков.

Сохраняйте порядок получения сообщений внутри одного соединения. Не объединяйте stdout и stderr по времени получения клиентом и не считайте результат полным порядком по времени выполнения.

## Обнаружение незавершенного результата[​](#detect-an-incomplete-result "Прямая ссылка на Обнаружение незавершенного результата")

Считайте неопределенными, а не успешными, следующие случаи:

* SSE закрылся без `exit`;
* подключение к процессу закрылось без `exit`;
* терминал закрылся без `exited`, если его не закрыл сам клиент.

Запишите ID песочницы, PID процесса при наличии, код закрытия, статус HTTP при handshake, временную метку и `x-request-id`, если он был возвращен. Затем используйте способ восстановления конкретного контракта: проверьте внешний результат до повтора SSE, переподключитесь к процессу для воспроизведения или запустите свежий терминал.

## WebSocket приложений[​](#application-websockets "Прямая ссылка на WebSocket приложений")

Сервис внутри песочницы может открыть собственный WebSocket через прокси песочницы или порт превью. Just Run пересылает текстовые, бинарные, ping- и pong-фреймы, но приложение само определяет протокол, режим аутентификации и семантику переподключения. Документируйте эти сообщения вместе с приложением, а не как события Just Run в реальном времени.

## Связанные страницы[​](#related "Прямая ссылка на Связанные страницы")

* [Протоколы песочницы для обмена данными в реальном времени](/api-reference/realtime.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Жизненный цикл песочницы](/sandboxes/lifecycle.md)
* [Ошибки и ограничения частоты запросов](/developers/errors-and-rate-limits)
