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 и его нельзя использовать.

Источники