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

В части платформы для работы с данными песочницы 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](/api-reference/rest.md). Эта страница определяет контракты событий и фреймов. WebSocket-соединения приложений внутри песочницы используют протокол самого приложения и не входят в эти схемы сообщений платформы.

## Аутентификация[​](#authentication "Прямая ссылка на Аутентификация")

Используйте тот же адрес инсталляции, что и для 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[​](#streaming-exec-over-sse "Прямая ссылка на Выполнение команды со стримингом через 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 должен игнорировать возможные записи поддержания соединения, состоящие только из комментариев.

## Подключение к фоновому процессу[​](#attach-to-a-background-process "Прямая ссылка на Подключение к фоновому процессу")

Создайте процесс через `POST /v1/sandboxes/{id}/start`, сохраните возвращенный `pid`, затем выполните переход на WebSocket:

```
wss://your-just-run-host/v1/sandboxes/{id}/processes/{pid}/attach
```

### Текстовые фреймы от сервера к клиенту[​](#server-to-client-text-frames "Прямая ссылка на Текстовые фреймы от сервера к клиенту")

Каждый фрейм платформы содержит текст 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 прочитаны оставшиеся данные. Фрагменты сохраняют порядок собранных событий, но не являются границами строк или глобальными временными метками для двух потоков операционной системы.

### Фреймы от клиента к серверу[​](#client-to-server-frames "Прямая ссылка на Фреймы от клиента к серверу")

Отправляйте 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 интерактивного терминала[​](#interactive-terminal-websocket "Прямая ссылка на 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`, или в отсоединенном фоновом сервисе.

## Ошибки и незавершенные потоки[​](#errors-and-incomplete-streams "Прямая ссылка на Ошибки и незавершенные потоки")

До принятия 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`; решение о переподключении зависит от семантики воспроизведения конкретного контракта.

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

* [Стриминг и обмен данными в реальном времени](/developers/streaming-and-realtime.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Основы работы с API](/developers/api-fundamentals.md)
* [Справочник REST API](/api-reference/rest.md)
