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

СвойствоBackend3Backend4
Клиентский запросПлоский объект строкaction с одним действием и произвольным JSON-значением
Положение _objectsВ корнеВнутри action, рядом с действием
Вход модуля_message:begin, строки key:value, _message:endОдна JSON-строка
Данные stdoutФормат ответов AlteratorJSON Lines
Завершение операцииЗавершённый ответный блокОтдельная строка _message:end
Несколько выходных JSON-сообщений на запросНе основной контракт адаптераДопускаются до маркера завершения
Сохранение JSON-типовОграничено преобразованием старого форматаЧисла, boolean, массивы и объекты сохраняются
Общая инфраструктураUnix-сокет, CLI, Polkit, write-блокировкиТа же

Источники