karkas/docs/MODULES-SPEC.md

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

> **Внимание!**
>
> Данная спецификация еще не закончена и активно разрабатывается.
> Могут быть значительные изменения (breaking changes).

Каждый модуль представлен в виде папки, содержащей два обязательных файла: info.json и `__init__.py`.

## Метаинформация о модуле (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`: Объект, описывающий зависимости модуля от других **Karkas** модулей.
    - `required`: Обязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
    - `optional`: Необязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
- `pythonDependencies`: Объект, описывающий зависимости модуля от внешних Python пакетов.
    - `required`: Обязательные зависимости. Ключ - название пакета, значение - версия.
    - `optional`: Необязательные зависимости. Ключ - название пакета, значение - версия.

### DependencyInfo

Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список разрешенных к использованию
атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещен.

```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`. Она позволяет получить модуль или предоставляемые им объекты по его
идентификатору.