Skip to main content

Crate wordval_bus

Crate wordval_bus 

Source
Expand description

§wordval-bus

Wordval 事件总线(Bus):以统一 API 封装进程内事件分发与 NATS 扇出, 并可通过 register_backend 接入任意第三方消息中间件(Kafka / Redis / RabbitMQ …), 单机部署零依赖、分布式部署换驱动即可,业务代码不变。

更名说明:本 crate 原名 wordval-queue(历史遗留),2026-09-28 起 更名为 wordval-bus——它封装的是发布-订阅事件总线 (at-most-once,见下),并非可靠消息队列——无 ack、无重投、无留存。 需要可靠队列请使用中间件原生能力(如 NATS JetStream consumer)。

§驱动选择

  • local — 进程内事件分发(默认,零依赖,有界通道)
    • 每主题单订阅者;无订阅者的事件直接丢弃;
    • 处理失败仅记录日志,不重投(at-most-once)。
  • nats — NATS(需启用 nats feature 且 NatsPlugin 已启动)
    • 同主题不同消费组各收一份(扇出),同组内负载均衡。
  • 其他 — 由 register_backend 注册的自定义后端

§语义契约

  • at-most-once:无消费者的事件直接丢弃,处理失败仅记录日志, 不重投、不留存;
  • 顺序:local 驱动同一主题内事件按发布顺序严格 FIFO 串行处理 (每主题单任务);NATS 驱动单服务器部署按送达序串行处理,集群部署 无全局顺序保证;跨主题、跨消费组无顺序保证;
  • handler 约束:处理函数应快速返回——慢 handler 会拖死该主题并使 通道积压(local 触发发布背压 / Bus::try_publish 满即拒); 阻塞型工作请用 tokio::task::spawn_blocking 包装或拆分主题并行消费。

§快速开始

ⓘ
use wordval_bus::{Bus, Message};

let bus = Bus::new("local")?;
bus.subscribe("topic", |msg: Message| async move {
    println!("收到事件: {:?}", msg);
    Ok(())
}).await?;
bus.publish("topic", b"hello").await?;

§插件模式

ⓘ
use wordval_bus::BusPlugin;
use wordval_core::PluginManager;

let mgr = PluginManager::new()
    .add(NatsPlugin::new())
    .add(BusPlugin::new().with_driver("nats"));
mgr.start_all().await?;

wordval_bus::bus().publish("topic", b"hello").await?;

Re-exports§

pub use backend::boxed_handler;
pub use backend::register_backend;
pub use backend::BusBackend;
pub use backend::Handler;

Modules§

backend
总线后端抽象与可插拔注册表

Structs§

Bus
统一事件总线外观:持有一个 BusBackend 并暴露高级 API
BusConfig
总线配置,驱动名 + 可选参数
BusPlugin
总线插件:管理全局 Bus 的生命周期
LocalBus
基于有界 mpsc 通道的进程内事件总线

Constants§

DEFAULT_GROUP
默认消费组名(BusConfig::default_group 与 BusPlugin 共用)

Functions§

bus
获取全局 Bus 引用
try_bus
尝试获取全局 Bus 引用(不 panic)

Type Aliases§

Message
总线事件体,基于 Bytes 的零拷贝引用计数切片。