Разработка нового модуля

Модуль реализует предметные операции и обменивается данными с основной службой Altera через stdin/stdout. Клиентский транспорт, маршрутизацию и Polkit обслуживает Altera. Язык реализации модуля не является частью протокола.

Ниже используется условный backend4-модуль example-module, который читает и изменяет параметры объекта. Это иллюстрация контракта, а не имя файла или модуля из поставки.

Определение контракта

Перед реализацией нужно согласовать с разработчиком клиента:

Часть контрактаЧто определить
АдресВерсия backend и имя модуля
ДействияПоддерживаемые read, list, write
ПараметрыОбязательные поля, типы, допустимые значения и ограничения
ОтветыДанные, промежуточные сообщения и признак окончательного результата для клиента
ОшибкиФорма предметной ошибки и возможность продолжить обмен после неё
АвторизацияДопустимые _objects и соответствующие action ID Polkit

Для вложенных данных подходит backend4: запрос и ответы представлены в JSON. Backend3 использует текстовый протокол Alterator; его выбирают для совместимости с модулями этого формата.

Пример запроса и ответа

Клиент адресует запрос внешним ключом:

{"/backend4/example-module":{"action":{"read":{"name":"eth0"}}}}

Модуль получает только тело запроса, одной строкой с завершающим LF:

{"action":{"read":{"name":"eth0"}}}

В этом условном контракте name выбирает объект, а read возвращает его состояние. Модуль выводит:

{"name":"eth0","enabled":true}
_message:end

Altera передаёт данные клиенту с обёрткой пути:

{"/backend4/example-module":{"name":"eth0","enabled":true}}

Маркер _message:end обрабатывается Altera и клиенту не пересылается. Если операция возвращает несколько сообщений, контракт модуля должен позволять клиенту распознать окончательный результат: универсального публичного события завершения нет.

Цикл обработки и завершение операции

Модуль обслуживает несколько запросов за время жизни процесса. Для backend4 последовательность такая:

прочитать одну JSON-строку из stdin
    → разобрать действие и проверить параметры
    → выполнить операцию
    → вывести JSON-ответы в stdout
    → вывести ровно один маркер _message:end с LF
    → сбросить буфер stdout (flush)
    → перейти к следующему запросу

Каждый JSON-ответ также заканчивается LF. Логи и прочая диагностика идут в stderr. Поле altera зарезервировано для служебных событий Altera.

Завершение операции означает, что её работа закончена. Нельзя отправить маркер и продолжить изменение данных в фоне: Altera может освободить блокировку записи и допустить следующий запрос. При EOF модуль завершает цикл и освобождает ресурсы.

Для backend3 операция завершается законченным ответным блоком по правилам его протокола. Маркер backend4 к такому ответу добавлять не нужно.

Ошибки параметров и предметные отказы

Модуль проверяет структуру, значения и допустимость параметров, включая пути и содержимое загруженных файлов. Проверка Polkit разрешает действие, но не заменяет эту валидацию.

Форму предметной ошибки определяет контракт модуля. Например:

{"error":"unknown object","name":"eth0"}
_message:end

Если обработчик вернул отказ и закончил текущую операцию, для backend4 маркер завершения нужен и после ошибки, и при отсутствии данных. Вывод JSON-ошибки сам по себе не завершает операцию. Altera передаёт ошибки модуля клиенту без преобразования в собственные классы ошибок.

Использование помощников

Модуль может реализовать цикл самостоятельно либо использовать помощников, перечисленных в разделах backend3 и backend4. Помощники backend4 автоматически добавляют _message:end после обработчика; вручную дублировать его нельзя. Для backend3 нужно соблюдать правила оформления ответного блока выбранного помощника.

Выбранный помощник подключают в коде модуля, а зависимость от пакета, который его предоставляет, указывают в RPM-пакете модуля.

Авторизация и безопасность изменений

Altera запускает модули с правами root. Модуль не должен менять защищаемые данные при старте процесса: запуск ещё не означает, что какой-либо запрос разрешён.

Изменяющие операции должны называться write: общая блокировка записи привязана к этому действию. read и list не должны скрыто изменять конфигурацию. Целостность файлов, откат частичных изменений и взаимодействие с внешними программами остаются ответственностью модуля.

Для условного действия read без отдельной области _objects используется action ID:

org.altlinux.altera.backend4.example-module.read

Пример политики, требующей подтверждения администратора:

<?xml version="1.0" encoding="UTF-8"?>
<policyconfig>
  <action id="org.altlinux.altera.backend4.example-module.read">
    <description>Read object settings</description>
    <message>Administrator authentication is required</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
</policyconfig>

Уровень допуска выбирают по смыслу операции и аудитории модуля. Разрешение read не разрешает автоматически list или write: для них нужны соответствующие зарегистрированные политики. Правила _objects и интерактивного подтверждения описаны в разделе Polkit.

Размещение и интеграция

Исполняемый файл устанавливают в /usr/lib/alterator/backend4/<module> или /usr/lib/alterator/backend3/<module>. Имя файла определяет имя в клиентском пути. Политики устанавливают отдельными .policy-файлами в /usr/share/polkit-1/actions/.

После установки политик нужно открыть новое соединение, чтобы создать контекст модуля с актуальным набором action ID. Клиент обращается к модулю по общему протоколу; выбор Unix-сокета, CLI или веб-входа не меняет предметный контракт.

Проверка модуля

Рекомендуемые сценарии для проверки:

ПроверкаОжидаемый результат
Два последовательных запросаОдин процесс корректно обслуживает оба
Отказ по параметрамПредметная ошибка и корректное завершение операции; следующий запрос обрабатывается
Разрешение и отказ PolkitДействие выполняется только при разрешении
Завершение записиИзменения закончены до маркера завершения
Завершение backend4Ровно один _message:end на каждый обработанный запрос, в том числе после предметной ошибки
Диагностика модуляЛоги идут в stderr, секреты не попадают в диагностический вывод

Протокольный вывод, включая маркеры завершения, проверяют при прямом запуске модуля через stdin/stdout. Работу модуля через Altera можно проверить с помощью altera-cli: CLI получает ответы основной службы и не показывает внутренние маркеры завершения. Политики проверяют через Altera от непривилегированного пользователя: root обходит Polkit.