# Botx-api-framework
## Описание
Фреймворк для разработки ботов под eXpress
## Использование
Добавьте в Cargo.toml
```toml
botx-api-framework = { version = "*", features = ["anthill-di"] }
```
Доступны следующие features:
`actix-web` - включение интеграции с actix-web (default)
Фреймворк не привязан к конкретному web фреймворку, но имеет готовую интеграцию с actix-web
Минимально для работы фреймворка нужно создать объект BotXApiFrameworkContext. Есть несколько способов:
* Через конструктор new - автоматически создастся контекст зависимостей и возьмутся настройки по умолчанию
* Через конструктор from_di_container - контекст зависимостей берется из аргументов, настройки берутся из зависимостей а при отсутствии берутся дефолтные
* Через регистрацию в anthill_di - контекстом зависимостей берется текущий контекст, настройки берутся из зависимостей а при отсутствии берутся дефолтные
```rs
// Пример создания контекста фреймворка из контекста anthill_di
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let ioc_ctx = DependencyContext::new_root();
ioc_ctx.register_botx_api_framework_context().await?;
// Если не использовать метод расширения
// ioc_ctx.register_type::<BotXApiFrameworkContext>(LifeCycle::Transient).await?;
let context = ioc_ctx.resolve::<BotXApiFrameworkContext>().await?;
}
```
После создания объекта фреймворка можно обрабатывать команды методами:
* ```process_command``` - обработка событий бота
* ```process_notification_result``` - обработка асинхронного результата
* ```process_status_result``` - обработка состояния бота
Интеграция с web actix добавляет методы расширения для actix_web::app::App:
* ```add_botx_api_handlers``` - добавляет обработку api (/command, /notification/callback, /status)
* ```add_smartapp_static_files``` - добавляет обработку запроса статики по api /smartapp_files/static/{path*}
Зарегистрированные api при запросе достают контекст фреймворка из зависимостей и передают ему управление
Для добавления обработчиков необходимо регистрировать соответствующий trait и зарегистрировать в контексте зависимостей
Для удобства регистрации обработчиков добавлены методы расширения
Сопоставление trait-ов и методов расширения
|регистрирует регулярное выражения определяющее относится ли сообщение к командам, или простое сообщение|-|`register_command_detection_regex`|
|регистрирует обработчик команд и регулярное выражение для сопоставления сообщения с обработчиком|`ICommandHandler`|`register_command_handler`|
|регистрирует запасной обработчик команд|`ICommandHandler`|`register_default_command_handler`|
|регистрирует обработчик сообщений|`IMessageHandler`|`register_message_handler`|
|регистрирует обработчик кнопки|`IButtonHandler`|`register_button_handler`|
|регистрирует запасной обработчик кнопок|`IButtonHandler<TData = serde_json::Value, TMetaData = serde_json::Value>`|`register_default_button_handler`|
|регистрирует обработчик внутренней нотификации бота|`IInternalBotNotificationHandler`|`register_internal_notification_handler`|
|регистрирует запасной обработчик внутренней нотификации бота|`IInternalBotNotificationHandler<TData = serde_json::Value, TOptions = serde_json::Value>`|`register_default_internal_notification_handler`|
|регистрирует обработчик событий smartapp|`ISmartappEventHandler`|`register_smartapp_event_handler`|
|регистрирует запасной обработчик событий smartapp|`ISmartappEventHandler<TData = serde_json::Value, TOptions = serde_json::Value>`|`register_default_smartapp_event_handler`|
|регистрирует обработчик событий добавления в чат|`IAddedToChatHandler`|`register_add_to_chat_handler`|
|регистрирует обработчик событий выхода из чата|`ILeftFromChatHandler`|`register_left_from_chat_handler`|
|регистрирует обработчик событий удаления из чата|`IDeletedFromChatHandler`|`register_delete_from_chat_handler`|
|регистрирует обработчик событий создания чата|`IChatCreatedHandler`|`register_chat_created_handler`|
|регистрирует обработчик событий входа в cts|`ICtsLoginHandler`|`register_cts_login_handler`|
|регистрирует обработчик событий выхода из cts|`ICtsLogoutHandler`|`register_cts_logout_handler`|
|регистрирует обработчик асинхронного результата события|`INotificationResultHandler`|`register_notification_callback_handler`|
|регистрирует обработчик запроса состояния бота|`IStatusHandler`|`register_status_handler`|
Для обработки кнопок TData и TMetadata обработчика должны примерять макрос `button_data`:
```rs
#[button_data]
pub struct ButtonData {
pub message: String,
}
```
Макрос button_data добавляет в Data и MetaData поле type_id в котором должен храниться тип объекта. По type_id происходит сопоставление кнопок и обработчиков. Объект в поле type_id имеет реализацию Default, по этому создание объектов data и metadata выполняется способом ниже:
```rs
let data = ButtonData { type_id: Default::default(), message: "test message".to_string() }
```
Сопоставление команд идет по указанному регулярному выражению
Сопоставление событий smartapp и внутренней бот нотификации происходит при помощи десериализации - если сообщение можно разобрать в объекты указанные в обработчике, значит этому обработчику будет передано событие
Для работы с api eXpress этот crate реэкспортирует crate botx-api. Используйте метод расширение для регистрации контекста api в контексте зависимостей, после чего его можно будет получить в каждом обработчике и выполнять запросы в eXpress
Базовая настройка приложения может выглядеть следующим образом
```rs
use actix_web::{
middleware::Logger,
web::{self, Data},
App, HttpServer,
};
use anthill_di::DependencyContext;
use botx_api::extensions::botx_api_context::IBotXApiContextExt;
use botx_api_framework::extensions::{anthill_di::IAnthillDiExt, actix::IActixHandlersExt};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let ioc_ctx = DependencyContext::new_root();
ioc_ctx.register_botx_api_context().await?;
ioc_ctx.register_botx_api_framework_context().await?;
HttpServer::new(move || {
App::new()
.wrap(Logger::default())
.app_data(Data::new(ioc_ctx.clone()))
.add_botx_api_handlers()
})
.bind(("127.0.0.1", "7856"))?
.run()
.await?;
Ok(())
}
```
## Вклад
Откройте issue с вопросом или предложением
## Лицензия
MIT, можно использовать в любых целях
## Статус проекта
|✅|Интеграция с actix-web|Веб сервер на основе actix-web|
|✅|Обработчик сообщения|Регистрация своего обработчика сообщений пользователей|
|✅|Определение своего детектора команд|Возможность задать свое регулярное выражения определения относится ли сообщение к командам|
|✅|Обработчик команды|Возможность создавать обработчики команд и назначать им регулярные выражения для сопоставления|
|✅|Обработчик не обработанных команды|Возможность создавать обработчик для команд для которых не найден обработчик|
|✅|Обработчик кнопок|Возможность создавать обработчики кнопок и сопоставлять кнопки сообщений с обработчиками через data и metadata которые может обработать обработчик|
|✅|Обработчик не обработанных кнопок|Возможность создавать обработчик кнопок для кнопок для которых не найден обработчик|
|✅|Обработчик события добавления в чат|Возможность создавать обработчики события добавления в чат|
|✅|Обработчик события выхода из чата|Возможность создавать обработчики события выхода из чата|
|✅|Обработчик события удаления из чата|Возможность создавать обработчики события удаления из чата|
|✅|Обработчик события создания чата|Возможность создавать обработчики события создания чата|
|✅|Обработчик события выхода с cts|Возможность создавать обработчики события выхода из cts|
|✅|Обработчик события входа в cts|Возможность создавать обработчики события входа в cts|
|✅|Обработчик события нотификации бота|Возможность создавать обработчики событий от других ботов|
|✅|Обработчик события не обработанных нотификаций бота|Возможность создавать обработчики событий от других ботов для которых не найден обработчик|
|✅|Обработчик событий smartapp|Возможность создавать обработчики событий от smartapp и сопоставлять с обработчиками через data и metadata которые может обработать обработчик|
|✅|Обработчик не обработанных событий smartapp|Возможность создавать обработчики событий от smartapp для которых не были найдены обработчики|
|✅|Обработчик событий асинхронного результатов|Возможность создавать общий обработчик события асинхронного результата|
|✅|Обработчик событий status|Возможность создавать обработчик запроса состояния бота|
|✅|Написать тесты для всех обработчиков||