Backend4: контракт модуля
Назначение и размещение
Backend4 — JSON-протокол для модулей, не требующих входного текстового формата backend3. Модуль устанавливается в:
/usr/lib/alterator/backend4/<module>
Язык реализации не является частью протокола: подходят Rust, Python, shell и другие языки, умеющие работать со stdin/stdout. В репозитории есть shell- и Python-помощники и примеры.
Запрос
Перед передачей запроса от клиента основная служба Altera снимает обёртку, где указан путь к модулю. Примеры ниже представлены уже без обёртки.
{"action":{"read":{"name":"eth0"},"_objects":"/"}}
Объект action содержит ровно одно действие и необязательное строковое _objects. Значение самого действия может быть JSON любого типа:
{"action":{"read":{}}}
{"action":{"write":{"enabled":true,"addresses":["192.0.2.10/24"]}}}
{"action":{"read":"","_objects":"some_objects"}}
Altera извлекает действие и _objects для авторизации. Смысл параметров определяется модулем. Вложенный объект с read и write одновременно не соответствует контракту. Сервер не добавляет backend4 поля language и _objects так, как это делает адаптер backend3.
При пересылке в stdin весь запрос сериализуется в одну строку JSON с \n.
Данные и завершение — разные вещи
Модуль может вывести несколько JSON-строк, после которых обязан завершить операцию отдельной строкой:
{"progress":50}
{"result":{"enabled":true}}
_message:end
Каждая JSON-строка передаётся клиенту отдельным сообщением. _message:end разбирается сервером как внутреннее завершение, а не пересылается клиенту как JSON.
Получение JSON с result ещё не освобождает блокировку записи. Это происходит после _message:end. Даже если данных нет, модуль должен вывести:
_message:end
На один запрос нужен ровно один маркер. Его отсутствие оставляет запрос незавершённым; повторный маркер нарушает соответствие запросов и завершений. Flush обязателен.
Ошибка предметной операции может быть оформлена так:
{"error":"unsupported value"}
_message:end
Форма error — полезная договорённость модуля с клиентом; JSON-ошибка не отменяет необходимость завершить операцию маркером.
Помощники
altera-sh-functions (бинарный пакет altera-sh-functions) и altera_python_functions.py (бинарный пакет altera-python-functions) сохраняют протокольный stdout и перенаправляют обычный диагностический вывод в stderr. Они автоматически добавляют маркер завершения после обработчика. При их использовании вручную дублировать _message:end нельзя.
В качестве примера можно предложить такое написание модуля backend4:
#!/usr/bin/env python3
import altera_python_functions as backend
def on_read():
backend.write_json({"value": backend.in_action_payload})
def on_list():
backend.write_json({"actions": ["list", "read"]})
backend.message_loop_backend4(on_read=on_read, on_list=on_list)
Обычный print() не следует использовать вместо write_json() для ответа протоколу.
Сопоставление backend3 и backend4
| Свойство | Backend3 | Backend4 |
|---|---|---|
| Клиентский запрос | Плоский объект строк | action с одним действием и произвольным JSON-значением |
Положение _objects | В корне | Внутри action, рядом с действием |
| Вход модуля | _message:begin, строки key:value, _message:end | Одна JSON-строка |
| Данные stdout | Формат ответов Alterator | JSON Lines |
| Завершение операции | Завершённый ответный блок | Отдельная строка _message:end |
| Несколько выходных JSON-сообщений на запрос | Не основной контракт адаптера | Допускаются до маркера завершения |
| Сохранение JSON-типов | Ограничено преобразованием старого формата | Числа, boolean, массивы и объекты сохраняются |
| Общая инфраструктура | Unix-сокет, CLI, Polkit, write-блокировки | Та же |