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

Внимание

Данная спецификация ещё не закончена и активно разрабатывается.

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

Метаданные блока (info.json)

Файл info.json содержит информацию о блоке в формате JSON. Пример структуры info.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
privileged	Является ли блок привилегированным (булево значение)
dependencies	Объект, описывающий зависимости блока от других блоков
dependencies.required и dependencies.optional	Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор блока, значение — версия или объект DependencyInfo.
pythonDependencies	Объект, описывающий зависимости блока от внешних Python пакетов.
pythonDependencies.required и pythonDependencies.optional	Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия.

DependencyInfo

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

{
  "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, предоставляемое системой управления блоками. Например, можно использовать функцию get_module для получения блока или предоставляемых им объекты по идентификатору.