Backend3: контракт модуля
Назначение и размещение
Backend3 обеспечивает совместимость с существующими модулями Alterator. Модуль устанавливается как исполняемый файл:
/usr/lib/alterator/backend3/<module>
Клиент работает с JSON, но модуль получает текстовый протокол Alterator.
Запрос
Перед передачей запроса от клиента основная служба Altera снимает обёртку, где указан путь к модулю. Примеры ниже представлены уже без обёртки. Корректный клиентский контракт — одноуровневый JSON-объект со строковыми значениями:
{"action":"read","name":"enp2s0","ipv":"4","_objects":"/","language":"ru_RU"}
В stdin модуля поступает:
_message:begin
action:read
name:enp2s0
ipv:4
_objects:/
language:ru_RU
_message:end
Порядок полей не является контрактом. При отсутствии _objects добавляется /; при отсутствии language читается /etc/locale.conf, при неуспехе используется пустая строка. Передача language клиентом избавляет от этого чтения для данного запроса.
При использовании стандартного shell-помощника поля становятся in_action, in_name, in_ipv и т. п.
Числа, массивы и JSON boolean не являются строковыми значениями backend3. Текущий сериализатор некоторые некорректные поля пропускает с диагностикой, а не обязательно отклоняет весь запрос. Клиенту нельзя опираться на такое исправление: значения нужно кодировать в формате конкретного backend.
Ответ и завершение
Для простого ответа модуль выводит:
(
name "eth0"
enabled #t
)
Обязательны завершающий перевод строки и flush при буферизованном выводе.
Клиент получит:
{"name":"eth0","enabled":"true"}
"true" здесь строка, не JSON boolean. Пустой ответ ()\n преобразуется в {}. Граница ответа backend3 одновременно создаёт внутреннее событие завершения операции.
Надёжный контракт — внешние ( и ) на отдельных строках. Парсер также поддерживает часть компактных форм, но не является универсальным интерпретатором Scheme; не следует произвольно менять формат stdout. Вложенные группы могут преобразовываться в объекты с числовыми строковыми ключами, поэтому клиенту нужно учитывать фактический формат конкретного старого модуля.
Правила для автора
Модуль читает запросы циклом, а не завершается после первого. Один запрос должен приводить к одному законченному ответному блоку. Диагностика идёт в stderr, протокольные данные — в stdout. Поле altera зарезервировано сервером.
Внимание! read и list не должны скрыто менять защищаемую конфигурацию: общая блокировка записи определяется именем действия write. Изменения, выполняемые под другими действиями, этой блокировкой не защищаются.
Помощники
alterator-sh-functions(устанавливается в пакетеalterator-sh-functions)alterator-python-functions(устанавливается в пакетеalterator-python-functions)alterator-perl-functions(устанавливается в пакетеalterator-perl-functions)
Они:
- сохраняют протокольный stdout и перенаправляют обычный диагностический вывод в stderr;
- читают сообщение между
_message:beginи_message:end, сбрасывая параметры перед каждым запросом; - разделяют поле по первому
:; - выводят ответ внутри
(...)(справедливо дляalterator-sh-functionsприalterator_api_version=1— иначе скобки должен добавлять сам модуль).
Ориентироваться при разработке модулей рекомендуется на них, а также на документацию по backend3 при создании модулей.
Также следует иметь в виду, что:
- обработчик альтеры чувствителен к тому, чтобы
(и внешняя)выводились отдельными строками (последняя строка ответа обязательно заканчивается\n); - при буферизованном выводе после завершения ответа обязателен flush;
((name "eth0"))\nподдерживается, но(name "eth0")\nтекущий обработчик не распознаёт как завершение;- порядок полей не фиксирован, отсутствующий
_objectsполучает значение/,languageберётся из конфигурации локали; - ключ
alteraзарезервирован для служебных уведомлений Altera и его нельзя использовать.