Oxidebot

Oxidebot is a lightweight yet powerful chatbot framework based on Rust and the Tokio runtime. It aims to provide developers with a flexible and extensible environment for bot development through modular design.

Available Bots

Available Handlers

china_unicom_oxidebot

Example Usage

oxidebot_example

Core Concepts

Bot

Bot is the core component of the framework, responsible for providing Events and offering basic API methods for developers to call. It serves as the bridge between the framework and external platforms (such as QQ, Telegram, etc.).

The common API is complemented by PlatformApiRequest. Every adapter can expose its complete native API through the same lossless JSON request, response, and multipart-file abstraction. This second layer deliberately retains platform-only capabilities even when no honest cross-platform semantic model exists. Unsupported adapters return a downcastable UnsupportedPlatformApiError by default, while callers can inspect platform_api_methods or supports_platform_api_method before calling a platform-only feature.

Event

Event is the object that the framework processes, representing the various events received by the bot. Event types include:

MessageEvent: Message events
NoticeEvent: Notification events
RequestEvent: Request events
MetaEvent: Meta events
AnyEvent: Generalized events

Matcher

Matcher is an abstraction over Bot and Event, simplifying event handling and API calls. It provides convenient methods to extract key information from events (such as users, messages, groups) and easily call related APIs.

Handler

Handler is the core component for event processing, divided into two types:

EventHandler: Handles incoming Events and is triggered only when an event occurs.
ActiveHandler: Suitable for proactive processing scenarios, it can run continuously, execute scheduled tasks, or perform other background operations.

A Handler can include either an EventHandler or an ActiveHandler, or both.

Filter

Filter is a global event filter used to process and intercept events before they reach the Handler. The Filter has a higher priority than the Handler.

OxideBotManager

OxideBotManager is the manager of the framework, the entry point for starting and running the bot. Developers should call its run_block method at the end of the main function to launch the entire framework along with all registered Bots, Filters, and Handlers.

Auxiliary Tools for Handler Writer

Wait

Include a restricted BroadcastSender that can only use subscribe fn in your handler

use oxidebot::manager::BroadcastSender;

pub struct WaitHandler {
    pub broadcast_sender: BroadcastSender,
}

Then use wait in your HandlerTrait implementation. You can find the provided wait methods in utils::wait or define your own.

use std::time::Duration;

use anyhow::Result;
use oxidebot::{manager::BroadcastSender, matcher::Matcher, wait_user_text_generic};

async fn wait_for_number(
    matcher: &Matcher,
    broadcast_sender: &BroadcastSender,
) -> Result<()> {
    let (number, matcher) = wait_user_text_generic::<u8>(
        matcher,
        broadcast_sender,
        Duration::from_secs(30),
        3,
        Some("Please send an unsigned 8-bit integer".to_string()),
    )
    .await?;
    # let _ = (number, matcher);
    Ok(())
}

License

MIT OR Apache-2.0

oxidebot 0.1.7