28 releases

0.7.4 Apr 6, 2023
0.7.3 Jan 13, 2023
0.7.1 Dec 21, 2022
0.7.0-a6 Sep 27, 2022
0.1.1 Nov 6, 2021

#25 in WebSocket

Download history 2/week @ 2024-03-08 9/week @ 2024-03-15 1/week @ 2024-03-22 67/week @ 2024-03-29 2/week @ 2024-04-05 204/week @ 2024-04-19 24/week @ 2024-04-26

120 downloads per month
Used in walle-v11

MIT license

195KB
5.5K SLoC

Walle-core

OneBot11 OneBot12 license

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 PushtoValueMapToEvent<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 PushtoValueMapToAction 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

Dependencies

~5–18MB
~201K SLoC