Alterator-manager (Иван Савин, OSSDEVCONF-2023) — различия между версиями

== Thesis ==

Alterator-manager — это сервис для управления операционной системой через D-Bus. Его функционал реализуется в модулях, а
интерфейс описывается в специальных конфигурационных файлах.

=== Как работает alterator-manager ===
Alterator-manager может быть запущен в двух режимах — обычном и пользовательском:

<pre>
$systemctl start alterator-manager.service
</pre>

или

<pre>
$systemctl --user start alterator-manager.service
</pre>

В первом случае сервис запускается с полномочиями суперпользователя (root) и регистрирует имя
(<tt>ru.basealt.alterator</tt>) на системной шине D-Bus. Во втором случае сервис запускается от обычного пользователя и
регистрирует имя на сессионной шине D-Bus. После запуска происходит считывание конфигурационных файлов из
<tt>/usr/share/alterator/backends/</tt> и загрузка модулей из <tt>/usr/libexec/alterator/</tt>. Конфигурационные файлы
— это glib-овские key-value файлы, они должны иметь расширение <tt>.backend</tt> для обычного режима работы и
<tt>.user.backend</tt> для пользовательского. На их основе формируется интроспекция для D-Bus и правила polkit (только в
обычном режиме).

=== Формат конфигурационных файлов ===
<pre>
[Manager]
module_name = executor
node_name = example
interface_name = example
thread_limit = 5
[make_ls2]
execute = ls -al {param}
[make_ls3]
execute = ls -al {param}
[example]
execute = ls -al {param}
stdout_strings = enabled
stdout_bytes = enabled
stderr_strings = enabled
stdout_signal_name = stdout_signal_example
stderr_signal_name = stderr_signal_example
stdout_byte_limit = 200000
stdout_strings_limit = 200000
stderr_strings_limit = 200000
thread_limit = 3
action_id = method-name
</pre>

Первая секция <tt>Manager</tt> обязательная, она имеет следующие пары ключ-значение:

*  <tt>module_name</tt> — имя модуля который будет обрабатывать запросы;
*  <tt>node_name</tt> — имя узла в поддереве D-Bus;
*  <tt>interface_name</tt> — имя интерфейса D-Bus;
*  <tt>thread_limit</tt> — максимальное число тредов для данного интерфейса.


К <tt>interface_name</tt> автоматически добавляется префикс

«<tt>ru.basealt.alterator.</tt»>. Имя интерфейса может
содержать только <tt>[A-Z][a-z][0-9]_</tt>. Если оно состоит из нескольких секций, то они разделяются точкой. Пустые
секции не допускаются. Из имени интерфейса формируется <tt>action_id</tt> (polkit) по умолчанию для методов
интерфейса, для чего подчёркивания заменяются на тире.

Опция <tt>thread_limit</tt> не обязательна. Если её явно не задать, то её значение будет равно 10 (максимальное число
методов, выполняемых одновременно).

Каждая следующая секция — это метод. Имя секции — имя метода. Имя метода может состоять только из латинских букв, цифр и
символа подчёркивания. Пробелы не допускаются. Содержимое секции зависит от модуля, который будет обрабатывать запрос.

В секции <tt>example</tt> приведены возможные опции метода для модуля <tt>executor</tt>. Поле <tt>execute</tt> —
обязательное, остальные — нет. Поле <tt>execute</tt> содержит строку для <tt>bash</tt> с исполняемым файлом. Внутри
фигурных скобок могут задаваться параметры для метода D-Bus. Параметров может не быть. Имя параметра может содержать
только латинские буквы, цифры и символ подчёркивания. В примере выше метод <tt>make_ls2</tt> будет выполнять команду
<tt>ls -al</tt> с параметром <tt>param</tt>, в который можно будет передать имя директории или файла.

С помощью полей <tt>stdout_strings</tt>, <tt>stdout_bytes</tt> и

<tt>stderr_strings</tt> можно включить возможность
возврата массива строк или массива байт из <tt>stdout</tt> и массива строк из <tt>stderr</tt>. Для этого полю нужно задать
значение <tt>enabled</tt>. Если включён возврат массива байт, то возврат строк из <tt>stdout</tt> отключается (в том
числе сигналами). Максимальный размер в байтах для соответствующего массива можно задать с помощью полей
<tt>stdout_byte_limit</tt>, <tt>stdout_strings_limit</tt> и <tt>stderr_strings_limit</tt>. Значение по умолчанию
— 524288. Допустимый диапазон — от 0 до 2147483647. Вывод из <tt>stdout</tt> и <tt>stderr</tt> можно также получать с
помощью сигналов. Имя сигнала получается путём конкатенации <tt>sender'</tt>а и значения соответствующего поля
(<tt>stdout_signal_name</tt> или <tt>stderr_signal_name</tt>). В <tt>sender'</tt>е «<tt>:</tt»> и «<tt>.</tt»>
заменяются на «<tt>_</tt>». 

Значения полей <tt>stdout_signal_name</tt> и <tt>stderr_signal_name</tt> могут
содержать только латинские буквы, цифры и символ подчёркивания. Сигналы для <tt>stdout</tt> и <tt>stderr</tt> включены,
если соответствующему полю задано значение. С помощью поля <tt>thread_limit</tt> можно задать ограничение на
количество тредов для метода, т.е. сколько экземпляров этого метода можно запустить параллельно. Значение по умолчанию
— 1. В поле <tt>action_id</tt> можно задать <tt>action_id</tt> polkit для метода. Поле может содержать только
следующие символы <tt>[A-Z][a-z][0-9].-</tt>. К значению этого поля будет автоматически добавлен префикс сформированный
из имени интерфейса.

=== Пример ===
Создадим <tt>example.backend</tt>:

<pre>
[Manager]
module_name = executor
node_name = example
interface_name = example
[hexdump]
execute = hexdump -C {param}
stdout_strings = enabled
stdout_strings_limit = 7000000
thread_limit = 3
</pre>

В этом примере мы получаем вывод (<tt>stdout</tt>) запускаемой команды массивом строк, но, как уже писалось выше, вывод мы можем
получать и в виде массива байт.

Запустим наш сервис и посмотрим на дерево D-Bus.

[[File:2023-savin-img001.png|center|640px|Дерево D-Bus для ru.basealt.alterator]]

Объект <tt>/ru/basealt/alterator/example</tt>

Интерфейс <tt>ru.basealt.alterator.example</tt>

Метод <tt>hexdump</tt> возвращает массив строк из <tt>stdout</tt>.

Выполним метод hexdump.

[[File:2023-savin-img002.png|center|640px|Выполнение метода hexdump]]

Таким образом, можно сформировать <tt>backend</tt> для какого-либо приложения с API на D-Bus.



{{----}}
[[File:{{#setmainimage:Alterator-manager (Иван Савин, OSSDEVCONF-2023)!.jpg}}|center|640px]]
{{LinksSection}}
<!-- <blockquote>[©]</blockquote> -->

<references/>

[[Категория:OSSDEVCONF-2023]]
[[Категория:Open-source projects]]
[[Категория:Draft]]