Walle-core

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

Walle 的名字来源于《机器人总动员》中的WALL-E ( 一款Rusty机器人 )

功能

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

特性

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

使用方法

仅展示最小实例

实现

use std::sync::Arc;
use walle_core::alt::TracingHandler;
use walle_core::config::ImplConfig;
use walle_core::obc::ImplOBC;
use walle_core::prelude::*;

#[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()),
        walle_core::structs::Version {
            implt: walle_core::WALLE_CORE.to_owned(),
            version: walle_core::VERSION.to_owned(),
            onebot_version: 12.to_string(),
        },
    ));
    ob.start((), ImplConfig::default(), true).await.unwrap();
    // ob.wait_all().await;
    ob.shutdown(true).await.ok();
}

应用

use std::sync::Arc;
use walle_core::alt::TracingHandler;
use walle_core::config::AppConfig;
use walle_core::obc::AppOBC;
use walle_core::prelude::*;

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();
    let ob = Arc::new(OneBot::new(
        AppOBC::new(),
        TracingHandler::<Event, Action, Resp>::default(),
        Version {
            implt: walle_core::WALLE_CORE.to_owned(),
            version: walle_core::VERSION.to_owned(),
            onebot_version: 12.to_string(),
        },
    ));
    ob.start(AppConfig::default(), (), true).await.unwrap();
    // ob.wait_all().await;
    ob.shutdown(true).await.ok();
}

事件

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

walle_core::event::BaseEvent 为扩展模型，其中五个泛型依次为 type detail_type sub_type platform impl 五个层级的扩展字段

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

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

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

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

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

use walle_core::prelude::*;

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

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

use walle_core::prelude::*;

#[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(walle_core::event::Group), // Group 应 impl TryFromValue
    Private,
}

操作

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

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

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

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

use walle_core::prelude::*;

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

或者

use walle_core::prelude::*;

#[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 ? 没问题!

use walle_core::prelude::*;
use walle_core::action::GetUserInfo;

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

响应 (值)

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

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

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

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

当然还是可以使用宏

use walle_core::prelude::*;

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

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

MessageSegment

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

use walle_core::prelude::*;

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

Notice

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

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