karkas/docs/MODULES-SPEC.md

# Спецификация модулей

> **Внимание!**
>
> Данная спецификация ещё не закончена и активно разрабатывается.
>
> Могут возникнуть изменения, которые не будут обратно совместимы (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` для получения модуля или предоставляемых им объекты по идентификатору.