Общий клиентский протокол

Протокол определяет, как клиент адресует запросы модулям бекенда, получает ответы и обрабатывает ошибки. Ниже сначала описан прямой обмен с основной службой 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-errorinvalidНеверная обёртка запроса или незавершённая строка JSON Lines
woo-errortoo_largeВходная строка превышает 8 МиБ, включая LF
woo-errordeniedОтказ авторизации, в том числе после отмены диалога
woo-errorbusyМодуль занят записью или очередь его запросов заполнена
woo-errorlimitДостигнут предел активных модулей соединения
woo-errornot_foundИсполняемый файл модуля не найден
woo-errorunavailableОчередь модуля закрылась до передачи запроса
woo-errortimeoutИстекли 120 секунд интерактивной авторизации; это не тайм-аут операции модуля
woo-errorfailedСбой запуска, обмена, неожиданное завершение модуля или нарушение его протокола, включая завершение операции
type-errorinvalidНевалидный JSON, неверная структура или параметры команды либо ответа в диалоге авторизации
internal-errorfailedНепредвиденный внутренний сбой

Ошибки самих модулей передаются без преобразования к этой схеме. Например, {"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-errorunauthenticatedТокен отсутствует или недействителен, отказано во входе либо пользователь сессии недоступен
session-errorexpiredСрок сессии истёк
session-errorrevokedСессия отозвана
web-errorunavailableСлужба обработки веб-запроса или аутентификации недоступна либо перегружена
web-errortimeoutИстекло ожидание ответа службы или получения тела запроса входа
web-errorfailedСбой службы обработки веб-запроса
web-errorinvalid, denied, too_largeНекорректный HTTP-запрос, запрещённый Origin или превышение размера тела

Сочетание типа и кода отображается в HTTP-статус так:

Тип и кодHTTP-статус
type-error/invalid, woo-error/invalid, web-error/invalid400
session-error/unauthenticated, session-error/expired, session-error/revoked401
web-error/denied при запрещённом Origin403
web-error/timeout при получении тела запроса входа408
woo-error/too_large, web-error/too_large413
web-error/failed502
web-error/unavailable503
web-error/timeout при ожидании ответа службы504
Прочие сочетания, включая internal-error/failed500

Не каждый сетевой сбой сопровождается 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.