Разработка нового модуля
Модуль реализует предметные операции и обменивается данными с основной службой 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.