Общий клиентский протокол
Протокол определяет, как клиент адресует запросы модулям бекенда, получает ответы и обрабатывает ошибки. Ниже сначала описан прямой обмен с основной службой Altera через Unix-сокет, затем — дополнения для веб-клиентов.
Unix-клиент
Подключение и формат сообщений
Клиент подключается к /run/altera/.socket. Служба определяет пользователя по учётным данным Unix-соединения. В сборке с legacy-unix-peer перед JSON-обменом нужен дополнительный шаг идентификации, описанный в разделе «Прямой Unix-клиент».
Оба направления используют JSON Lines:
- кодировка UTF-8;
- один JSON-объект на строку;
- каждая строка заканчивается LF (
\n); - размер строки — не более 8 МиБ, включая LF.
Переводы строк внутри строковых значений JSON должны быть экранированы. Один вызов чтения сокета может вернуть часть строки или несколько строк: клиент должен накапливать данные до LF.
Адресация запроса
В примерах используется условное имя example-module. Оно иллюстрирует адресацию и не обозначает поставляемый модуль; параметры и ответы также приведены для примера.
Каждый запрос обёрнут внешним ключом — путём к модулю бекенда, /backend3/<module> или /backend4/<module>:
Запрос к backend3:
{"/backend3/example-module":{"action":"read"}}
Запрос к backend4:
{"/backend4/example-module":{"action":{"read":{"name":"eth0"}}}}
В этих и последующих примерах каждый JSON-объект передаётся отдельной строкой с завершающим LF.
Altera снимает внешний ключ перед передачей запроса модулю и добавляет его к ответам. Содержимое запроса и формат данных определяются контрактом backend3 или backend4 и конкретным модулем. Модуль работает со своим stdin/stdout и не обрабатывает клиентскую обёртку пути.
Пример ответа:
{"/backend4/example-module":{"name":"eth0","enabled":true}}
Ответы и служебные события
Один поток содержит данные модулей, ошибки Altera, уведомления о записи и сообщения диалога Polkit. Ответы и события модуля сохраняют обёртку его пути:
{"/backend4/example-module":{"altera":"write_state","busy":true}}
{"/backend4/example-module":{"auth_needed":true,"query":{"action":{"read":{"name":"eth0"}}}}}
{"/backend4/example-module":{"type":"auth_prompt","prompt_id":2,"message":"Password:","echo":false}}
write_state сообщает о состоянии записи. auth_needed указывает на необходимость интерактивного подтверждения; auth_identities, auth_prompt, auth_info и auth_error относятся к диалогу Polkit. Это события, а не общие ошибки Altera. В частности, auth_error сам по себе не означает окончательный отказ. Формат ответов клиента и порядок диалога описаны в разделе Polkit.
На один запрос может прийти несколько сообщений. В общем протоколе нет универсального request_id и публичного сообщения operation_completed: клиент должен различать данные и события по контракту модуля. Маркеры завершения backend-протокола обрабатываются Altera и клиенту не пересылаются. Автор модуля обязан соблюдать правила завершения из контрактов backend3/backend4: первый выведенный JSON-ответ сам по себе не завершает операцию backend4.
Очереди и время жизни модулей
В одном соединении допускается до 64 активных модулей, у каждого — очередь на 32 ожидающих сообщения. Запросы одного модуля исполняются последовательно, с ожиданием завершения предыдущей операции. Разные модули могут работать параллельно, но это не гарантирует независимость ресурсов ОС, к которым они обращаются.
При переполнении очереди запрос не принимается. Ответ:
{"/backend4/example-module":{"type":"woo-error","code":"busy","message":"module request queue is full"}}
Повторные запросы к одному пути используют тот же процесс модуля, пока его сессия работает. Другое клиентское соединение создаёт отдельный экземпляр модуля.
Для явной остановки одного модуля:
{"/backend3/example-module":"exit"}
Ответ:
{"/backend3/example-module":{"exited":true}}
Остальные модули соединения продолжают работать. Следующий запрос-объект к остановленному пути создаст новый экземпляр без контекста прежнего процесса. Команда "exit" останавливает модуль; для завершения ввода с ожиданием принятых запросов используется EOF, описанный ниже.
Ошибки
Собственные ошибки Altera содержат три поля: type — класс, code — причина, message — пояснение человеку.
Если путь запроса определён, ошибка находится под этим путём:
{"/backend3/example-module":{"type":"woo-error","code":"denied","message":"authorization denied"}}
Ошибка внешнего объекта запроса или потока приходит без пути:
{"type":"woo-error","code":"invalid","message":"expected exactly one module path"}
Например, запрос {"action":"read"} приведёт к ошибке, так как не задан адрес модуля. Несколько внешних ключей, неверный путь, неизвестный backend или недопустимое значение запроса также приводят к ошибке обёртки.
| Тип | Код | Значение для клиента |
|---|---|---|
woo-error | invalid | Неверная обёртка запроса или незавершённая строка JSON Lines |
woo-error | too_large | Входная строка превышает 8 МиБ, включая LF |
woo-error | denied | Отказ авторизации, в том числе после отмены диалога |
woo-error | busy | Модуль занят записью или очередь его запросов заполнена |
woo-error | limit | Достигнут предел активных модулей соединения |
woo-error | not_found | Исполняемый файл модуля не найден |
woo-error | unavailable | Очередь модуля закрылась до передачи запроса |
woo-error | timeout | Истекли 120 секунд интерактивной авторизации; это не тайм-аут операции модуля |
woo-error | failed | Сбой запуска, обмена, неожиданное завершение модуля или нарушение его протокола, включая завершение операции |
type-error | invalid | Невалидный JSON, неверная структура или параметры команды либо ответа в диалоге авторизации |
internal-error | failed | Непредвиденный внутренний сбой |
Ошибки самих модулей передаются без преобразования к этой схеме. Например, {"error":"unsupported value"} внутри ответа модуля остаётся частью его контракта. Собственная ошибка адаптера backend3 в Altera может иметь тип woo-error и код failed.
Отказ отдельной команды или неверная обёртка синтаксически корректного JSON обычно не закрывают соединение. Сбой модуля может завершить его сессию, сохранив работу остальных модулей.
Невалидный JSON, обрезанная строка, превышение лимита строки или ошибка чтения прекращают приём новых запросов. Уже принятая очередь дорабатывает: её ответы могут прийти после ошибки потока, до EOF. Клиент должен продолжать чтение. При ошибке определения учётных данных клиента соединение может закрыться до обработки запросов; при неисправном транспорте доставка JSON-ошибки не гарантируется.
Завершение обмена и разрыв связи
После последнего запроса клиент может закрыть только направление записи сокета и продолжать читать ответы до EOF. Для Altera EOF означает конец ввода: служба дорабатывает принятые запросы и затем останавливает процессы модулей. Это не команда отмены.
Общего тайм-аута завершения принятой операции нет: зависший модуль может задержать закрытие соединения. Если запрос требует ответа в диалоге Polkit, закрытый ввод не позволяет завершить подтверждение, и такой запрос не исполняется.
При потере клиента принятая операция может завершиться без доставки результата. Разрыв связи или клиентский тайм-аут не доказывают отмену записи. Перед повторной отправкой изменяющего запроса нужно проверить результат предыдущего выполнения.
Веб-клиент
Веб-клиент использует HTTP для входа и WebSocket для обмена с модулями. Адреса модулей, содержимое запросов, служебные события, очереди и ошибки основной службы соответствуют описанному выше протоколу. Далее перечислены дополнения веб-интерфейса.
Аутентификация и выбор маршрута
Сначала клиент выполняет POST /auth/login и получает Bearer-токен. При открытии WebSocket передаются два подпротокола: altera и bearer.<token>. Полный формат входа, срок действия токена и выход через POST /auth/logout описаны в разделе «Аутентификация и жизненный цикл подключения».
| Маршрут WebSocket | Запрос клиента | Ответ клиенту |
|---|---|---|
/ws | Объект с одним путём модуля | Объект с путём модуля |
/backend3/<module> или /backend4/<module> | Тело запроса без внешнего пути | Данные и события модуля без внешнего пути |
Например, на /ws отправляется:
{"/backend4/example-module":{"action":{"read":{"name":"eth0"}}}}
На /backend4/example-module тот же запрос выглядит так:
{"action":{"read":{"name":"eth0"}}}
Ответ на фиксированном маршруте:
{"name":"eth0","enabled":true}
Ошибки без пути передаются и на фиксированном маршруте. Открытие WebSocket ещё не подтверждает готовность модуля или успешность запроса: клиент должен обрабатывать последующие ответы и закрытие соединения. Веб-сессия определяет пользователя, а разрешение конкретной операции проверяется через Polkit.
Сообщения, размеры и heartbeat
Одно WebSocket-сообщение содержит один JSON-объект. Завершающий LF не нужен; многострочное форматирование JSON допустимо. В канале модулей принимаются Text и Binary с JSON в UTF-8, ответы и служебные события приходят как Text.
Входное сообщение ограничено 1 МиБ, включая сумму фрагментов. Фрагментация сообщений для модулей поддерживается. Ответ также ограничен 1 МиБ без завершающего LF внутренней JSON-строки; более крупный ответ приводит к закрытию WebSocket с кодом 1011. Для модуля, доступного веб-клиентам, этот предел нужно учитывать при формировании ответов.
Невалидный JSON и JSON, не являющийся объектом, в канале модулей пропускаются без ответа. Клиент не должен ждать JSON-ошибку на такое сообщение.
Сервер по веб-сокету отправляет Ping каждые 5 секунд и закрывает соединение, если Pong не получен в течение 10 секунд. Интервалы можно поменять настройками сервера ALTERA_PING_INTERVAL и ALTERA_PONG_TIMEOUT.
Загрузка файлов использует отдельный маршрут /upload и собственный протокол загрузки. Этот маршрут не принимает запросы к модулям основной службы Altera.
HTTP-ошибки
До WebSocket Upgrade и при HTTP-входе ошибки возвращаются объектом с полями type, code, message. Дополнительно к классам основной службы используются:
| Тип | Код | Значение |
|---|---|---|
session-error | unauthenticated | Токен отсутствует или недействителен, отказано во входе либо пользователь сессии недоступен |
session-error | expired | Срок сессии истёк |
session-error | revoked | Сессия отозвана |
web-error | unavailable | Служба обработки веб-запроса или аутентификации недоступна либо перегружена |
web-error | timeout | Истекло ожидание ответа службы или получения тела запроса входа |
web-error | failed | Сбой службы обработки веб-запроса |
web-error | invalid, denied, too_large | Некорректный HTTP-запрос, запрещённый Origin или превышение размера тела |
Сочетание типа и кода отображается в HTTP-статус так:
| Тип и код | HTTP-статус |
|---|---|
type-error/invalid, woo-error/invalid, web-error/invalid | 400 |
session-error/unauthenticated, session-error/expired, session-error/revoked | 401 |
web-error/denied при запрещённом Origin | 403 |
web-error/timeout при получении тела запроса входа | 408 |
woo-error/too_large, web-error/too_large | 413 |
web-error/failed | 502 |
web-error/unavailable | 503 |
web-error/timeout при ожидании ответа службы | 504 |
Прочие сочетания, включая internal-error/failed | 500 |
Не каждый сетевой сбой сопровождается HTTP JSON: например, отказ TLS или обрыв связи могут быть видны только как ошибка транспорта. Браузерный WebSocket API также не предоставляет приложению тело HTTP-ответа при неудачном Upgrade.
Ошибки и закрытие WebSocket
После Upgrade ошибки отдельных команд передаются обычными JSON-сообщениями с правилами обёртки выбранного маршрута. Такая ошибка сама по себе не закрывает WebSocket.
Недействительная сессия или сбой службы обработки соединения приводят к закрытию WebSocket. JSON-сообщение с причиной перед Close не гарантируется: клиент должен обрабатывать событие закрытия независимо от потока ответов.
| Код Close | Значение |
|---|---|
1000 | Штатное завершение обмена |
1001 | Истёк тайм-аут ожидания Pong |
1008 | Сессия недействительна, истекла или отозвана |
1009 | Превышен входной лимит сообщения 1 МиБ |
1011 | Сбой службы обработки соединения, в том числе слишком большой ответ |
Медленное чтение ответов может привести к закрытию соединения: если очередь доставки не освобождается в течение секунды, сервер прекращает подключение. При транспортном сбое доставка Close не гарантируется.
Logout, истечение сессии, закрытие WebSocket и тайм-аут не отменяют уже принятые основной службой операции. Проверка результата перед повторной записью нужна и веб-клиенту.
Дополнительные материалы
Примеры клиентов, в том числе через altera-cli: «Разработка простого клиента». Форматы команд и правила завершения модулей: backend3 и backend4.