Flare Core

Rust 长连接通信库（Tokio async），面向即时通讯、聊天室与实时推送。支持 WebSocket、QUIC、TCP，以及 Protobuf/JSON 协商、压缩加密、心跳重连、多设备策略与 Token 认证。

英文 API 文档：docs.rs/flare-core

特性

• 传输：WebSocket（含 TLS）、QUIC；Native 客户端支持多协议竞速（Hybrid）；TCP 需 --features tcp
• 协商：Protobuf / JSON；Gzip / Zstd；CONNECT → CONNECT_ACK → NEGOTIATION_READY
• 连接：协商完成后心跳、活跃检测、自动重连、设备冲突策略
• 构建模式：ClientBuilder / ServerBuilder（闭包）、Observer、Flare（生产推荐）
• 扩展：可注册自定义序列化器、压缩器、加密器

依赖引入

当前版本见 Cargo.toml（crates.io 或 monorepo path 均可）。

# 默认：Native 客户端 + 服务端，WebSocket + QUIC + Gzip + AES-GCM
[dependencies]
flare-core = "0.1.3"

# 仅服务端（网关 / 接入层）
flare-core = { version = "0.1.3", default-features = false, features = [
    "server", "websocket", "quic", "compression-gzip", "encryption-aes-gcm",
] }

# 仅 Native 客户端
flare-core = { version = "0.1.3", default-features = false, features = [
    "client", "websocket", "quic", "compression-gzip", "encryption-aes-gcm",
] }

# 启用 TCP，或一次性全开
flare-core = { version = "0.1.3", features = ["tcp"] }
# flare-core = { version = "0.1.3", features = ["full"] }

# WASM / Web 客户端
flare-core = { version = "0.1.3", default-features = false, features = ["wasm"] }
# cargo build --target wasm32-unknown-unknown --no-default-features --features wasm

Cargo Features

运行时可通过 flare_core::common::FeatureSet::current() 查看当前构建能力。

架构

Application   ServerEventHandler · MessageListener · Authenticator
      ↓
Core          ServerCore / ClientCore · ConnectionManager · 消息管道 / 中间件
      ↓
Transport     HybridServer / HybridClient · WebSocket · QUIC · TCP

连接生命周期

1. 建立传输连接（WS / QUIC / TCP）
2. CONNECT 协商：序列化格式、压缩、加密
3. CONNECT_ACK → 双方解析器对齐 → NEGOTIATION_READY
4. 启动心跳，进入消息收发
5. 断开 / 重连（客户端可配置策略）

构建模式

快速开始

最小服务端（Flare 模式）：

use async_trait::async_trait;
use flare_core::common::protocol::{Frame, PayloadCommand};
use flare_core::server::events::handler::ServerEventHandler;
use flare_core::server::FlareServerBuilder;
use std::sync::Arc;

struct Handler;

#[async_trait]
impl ServerEventHandler for Handler {
    async fn handle_message(
        &self,
        _command: &PayloadCommand,
        _connection_id: &str,
    ) -> flare_core::common::error::Result<Option<Frame>> {
        Ok(None)
    }
}

#[tokio::main]
async fn main() -> flare_core::common::error::Result<()> {
    let server = FlareServerBuilder::new("0.0.0.0:8080", Arc::new(Handler)).build()?;
    server.run().await
}

联调聊天室（推荐从这里上手）：

# 终端 1：服务端
RUST_LOG=info cargo run --example flare_chat_server

# 终端 2：客户端（协议竞速 WS + QUIC）
RUST_LOG=info cargo run --example flare_chat_client -- user1

# TCP 联调（需 --features tcp）
cargo run --example flare_chat_server --features tcp
RUST_LOG=info cargo run --example tcp_client --features tcp

更多示例（Simple / Observer / QUIC / WASM / 自定义扩展）见 examples/README.md。

Native / WASM

WASM 侧使用 FlareClientBuilder::build_with_race，连接状态请用 is_connected_async。本地 E2E 建议：

FLARE_WS_ONLY=1 cargo run --example flare_chat_server

浏览器示例见 examples/wasm_websocket_client/。

质量门禁

在 flare-core 目录执行：

./scripts/verify.sh

性能基线（传输层）

仅覆盖 Frame 编解码、消息管道、连接生命周期与内存 fanout，不含 IM 语义（seq / sync / push 等）。完整报告：docs/performance-baseline.md

测试环境（硬件 / 软件）

以上为跑基准时的实测机器配置，用于结果对照；flare-core 本身无固定硬件门槛，实际吞吐会随 CPU 架构、核数、内存带宽与并发连接数变化。跨环境对比时请固定 release 模式并记录 CPU/内存规格。

结果摘要

xychart-beta
    title "flare-core transport throughput (ops/sec)"
    x-axis ["Protobuf", "JSON", "Gzip", "Pipeline", "Conn lifecycle"]
    y-axis "ops/sec" 0 --> 1400000
    bar [1017824, 197954, 51015, 1405371, 1457953]

xychart-beta
    title "ConnectionManager broadcast fanout"
    x-axis ["Bytes", "Frame"]
    y-axis "broadcasts/sec" 0 --> 5000
    bar [4188, 2789]

cargo bench --bench perf_baseline

结论：默认传输帧用 Protobuf；小消息慎用 Gzip；连接管理器 fanout 已改为发送前快照连接句柄，Frame fanout 在显式 parser 场景会单次序列化并批量更新活跃时间。超时清理按连接/用户分片批量移除，避免超时风暴下反复查表。配置共享 middleware / processor 时，ServerCore 会按协商 profile 复用 MessagePipeline，降低大量长连接的重复分配。Broadcast 项为内存 mock 连接 fanout，不代表真实网络带宽；真实瓶颈通常会转移到 socket 写队列、背压与慢消费者处理。

文档

许可

MIT License。问题反馈：GitHub Issues