Crate walle_core

Source

Expand description

§Walle-core

Walle-core 是一个 Rust OneBot Lib ( 不同于 libonebot 他同样可以应用于 OneBot 应用端 )

Walle 的名字来源于机械总动员的 WALL-E ( A Rusty Bot )

§功能

提供 OneBot v12 标准 Event、Action、ActionResp 序列化与反序列化功能，并支持自定义扩展
提供 OneBot v12 实现端标准网络通讯协议
提供 OneBot v12 应用端标准网络通讯协议（Http HttpWebhook 未支持）

§features

http: 启用 Http 与 HttpWebhook 通讯协议
websocket: 启用正向 WebSocket 与反向 WebSocket 通讯协议
impl-obc: 启用实现端 obc
app-obc: 启用应用端 obc
alt: 启用 ColoredAlt trait 着色输出纯文本 alt
full: 启用所有 features

§How to use

仅展示最小实例

§Implementation

use std::sync::Arc;
use walle_core::action::Action;
use walle_core::alt::TracingHandler;
use walle_core::config::ImplConfig;
use walle_core::event::Event;
use walle_core::obc::ImplOBC;
use walle_core::resp::Resp;
use walle_core::OneBot;

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();
    let ob = Arc::new(OneBot::new(
        TracingHandler::<Event, Action, Resp>::default(),
        ImplOBC::new("impl".to_string()),
    ));
    let tasks = ob.start((), ImplConfig::default(), true).await.unwrap();
    for task in tasks {
        task.await.unwrap()
    }
}

§Application

use std::sync::Arc;
use walle_core::action::Action;
use walle_core::alt::TracingHandler;
use walle_core::config::AppConfig;
use walle_core::event::Event;
use walle_core::obc::AppOBC;
use walle_core::resp::Resp;
use walle_core::OneBot;

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();
    let ob = Arc::new(OneBot::new(
        AppOBC::new(),
        TracingHandler::<Event, Action, Resp>::default(),
    ));
    let tasks = ob.start(AppConfig::default(), (), true).await.unwrap();
    for task in tasks {
        task.await.unwrap()
    }
}

§Event

walle_core::event::Event 为序列化使用标准类型，该模型仅确保 event 基础模型各字段。

walle_core::event::BaseEvent<T, D, S, P, I> 为扩展模型，其中五个泛型依次为 type detail_type sub_type platform impl 五个层级的扩展字段

需要实现 Event -> BaseEvent 转化时，扩展字段需要 impl TryFromEvent<T> trait ，通常在应用端使用

需要实现 BaseEvent -> Event 转化时，扩展字段需要 impl PushtoValueMap 和 ToEvent<T> trait ，通常在协议端使用

其中 T 标识不同扩展级别，分别为 TypeLevel | DetailTypeLevel | SubTypeLevel | PlatformLevel | ImplLevel

或者直接使用本 crate 提供的派生宏

定义一个 type 级别扩展字段（ ob12 理论上不支持该级别扩展）:

use walle_core::prelude::{PushToValueMap, ToEvent, TryFromEvent};

#[derive(ToEvent, PushToValueMap, TryFromEvent)]
#[event(type)]
pub struct Message {
    pub message_id: String,
    pub message: crate::message::Message,
    pub alt_message: String,
    pub user_id: String,
}

或者定义一个 detail_type 级别扩展字段

#[derive(PushToValueMap, TryFromEvent, ToEvent)]
#[event(detail_type = "group")]
pub struct Group_ {
    pub group_id: String,
}

// TryFromEvent 支持 enum 类型的扩展
#[derive(TryFromEvent)]
#[event(detail_type)]
pub enum Details {
    Group(Group), // Group 应 impl TryFromValue
    Private,
}

§Action

walle_core::action::Action 为序列化使用标准类型，该模型仅确保 action 与 params 字段存在且类型正确

实现 Action -> BaseAction 或 Action -> T 转化时，扩展字段需要 impl TryFromAction trait

实现 BaseAction -> Action 或 T -> Action 转化时，扩展字段需要 impl PushtoValueMap 和 ToAction trait

或者直接使用本 crate 提供的派生宏

#[derive(ToAction, PushToValueMap, TryFromAction)]
pub struct GetFile {
    pub file_id: String,
    pub ty: String,
}

或者

#[derive(ToAction, TryFromAction, PushToValueMap)]
#[action("upload_file")]
pub struct UploadFile_ {
    pub ty: String,
    pub name: String,
    pub url: Option<String>,
    pub headers: Option<std::collections::HashMap<String, String>>,
    pub path: Option<String>,
    pub data: Option<OneBotBytes>,
    pub sha256: Option<String>,
}

想要同时支持多种 Action ? 没问题!

#[derive(TryFromAction)]
pub enum MyAction {
    GetUserInfo(GetUserInfo), // GetUserInfo 应 impl TryFromValue
    GetGroupInfo { group_id: String },
}

§Resp (Value)

walle_core::resp::Resp 为序列化使用标准类型

同时本库还提供了 RespError 用于构造失败的 Resp，可以使用 <Resp>.as_result()

实现 Value -> T 转化时，需要 impl TryFromValue trait

实现 T -> Value 转化时，需要 impl PushToValueMap trait (仅支持 struct )

当然还是可以使用宏

#[derive(PushToValueMap, TryFromValue)]
pub struct Status {
    pub good: bool,
    pub online: bool,
}

同时实现了 Value 的结构体可以作为其他宏的字段使用。

§MessageSegment

基本与 Action 模型相同，唯一的不同是序列化使用的模型是 walle_core::message::MessageSegment，该模型同时也是一个 Value ，因此可以从 Event 或 Action 中获取。

#[derive(PushToValueMap, TryFromMsgSegment, ToMsgSegment)]
pub struct Text {
    pub text: String,
}

§Notice

由于与 Rust 保留字冲突，宏将会对以下字段自动转义：

"type" -> ty
"impl" -> implt
"selft" -> self

Re-exports§

pub use crate::error::WalleError;
pub use crate::error::WalleResult;

Modules§

action: Action 相关模型定义
alt
config: OBC 配置项
error
event: Event 相关模型定义
obc: OBC
prelude
resp: ActionResp 相关模型定义
segment: MsgSegment 相关模型定义
structs: 通用 Value 模型定义
util

Macros§

error_type: RespError 构造函数声明
value: Value 声明宏，类似于serde_json::json!
value_map: ValueMap 声明宏
value_vec: Vec 声明宏

Structs§

OneBot: 基础抽象模型，持有 ActionHandler 与 EventHandler

Constants§

WALLE_CORE: “Walle-core”

Traits§

ActionHandler: ActionHandler 接收 Action, 产生 Event
EventHandler: EventHandler 接收 Event, 产生 Action
GetSelfs: supertrait for ActionHandler
GetStatus: supertrait for ActionHandler
GetVersion

Crate walle_coreCopy item path