karkas/docs/MODULES-SPEC.md

106 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Спецификация модулей
> **Внимание!**
>
> Данная спецификация ещё не закончена и активно разрабатывается.
>
> Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes).
Каждый модуль представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.
## Метаданные модуля (`info.json`)
Файл `info.json` содержит информацию о модуле в формате JSON. Пример структуры `info.json` приведён ниже:
```json
{
"id": "standard.info",
"name": "Info",
"description": "Модуль с информацией",
"author": "Karkas Team",
"version": "1.0.0",
"privileged": false,
"dependencies": {
"required": {
"standard.roles": "^1.0.0",
"standard.database": {
"version": "^1.0.0",
"uses": ["db_api"]
}
},
"optional": {
"external.yandexgpt": "*"
}
},
"pythonDependencies": {
"required": {
"some_package": "^1.2.3"
},
"optional": {
"another_package": "*"
}
}
}
```
| Поле | Описание |
| :-----------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Уникальный идентификатор модуля |
| `name` | Название модуля |
| `description` | Описание функциональности модуля |
| `author` | Автор модуля |
| `version` | Версия модуля в формате [SemVer](https://semver.org/) |
| `privileged` | Является ли модуль привилегированным (булево значение) |
| `dependencies` | Объект, описывающий зависимости модуля от других модулей |
| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор модуля, значение — версия или объект `DependencyInfo`. |
| `pythonDependencies` | Объект, описывающий зависимости модуля от внешних Python пакетов. |
| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. |
### DependencyInfo
Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещён. Пример объекта `DependencyInfo`:
```json
{
"version": "^1.0.0",
"uses": ["db_api"]
}
```
| Поле | Описание |
| :-------: | ------------------------------------ |
| `version` | Версия модуля |
| `uses` | Список используемых атрибутов модуля |
## Режимы работы модулей
### Непривилегированный режим (`privileged: false`)
- Модуль выполняется в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`, а также несколько стандартных модулей, необходимых для работы;
- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом.
### Привилегированный режим (`privileged: true`)
- Модуль выполняется без ограничений;
- Имеет полный доступ ко всем пакетам, доступным в окружении;
- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.
## Жизненный цикл модуля
1. Загрузка метаданных из `info.json`;
2. Проверка зависимостей:
- Проверка всех обязательных зависимостей;
- Проверка совместимости версий зависимостей;
- Проверка зависимостей Python;
3. Загрузка кода модуля из `__init__.py`;
4. Вызов функции `module_init`, если она есть;
5. После загрузки всех модулей вызывается функция `module_late_init`, если она есть.
## Межмодульное взаимодейтвие
Для взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py),
предоставляемое системой управления модулями.
Например, можно использовать функцию `get_module` для получения модуля или предоставляемых им объекты по идентификатору.