# Спецификация блоков

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