Flare Core

Flare Core 是一个高性能、可靠的即时通讯长连接工具包，专为 Rust 设计。它提供了简洁的 API 和强大的功能，让开发者能够轻松构建实时通信应用。

注意: 本文档使用中文编写。For English documentation, please refer to docs.rs/flare-core.

✨ 核心特性

🚀 多协议支持

• WebSocket - 基于标准 WebSocket 协议，支持 Web 和移动端
• QUIC - 基于 UDP 的现代传输协议，提供更低的延迟和更好的性能
• 协议竞速 - 客户端可以同时尝试多个协议，自动选择最快的连接

🔐 认证与安全

• Token 认证 - 支持可配置的 token 验证机制
• 自定义认证器 - 实现 Authenticator trait 提供自定义验证逻辑
• 认证超时 - 可配置的认证超时时间
• 连接状态管理 - 只有已验证的连接才能收发业务消息

📱 多设备管理

• 设备冲突策略 - 支持多种设备管理策略：
  • 平台互斥：同一用户同一平台只能有一个设备在线
  • 移动端互斥：同一用户只能有一个移动端设备在线
  • 完全互斥：同一用户只能有一个设备在线
  • 移动端和PC共存：移动端之间互斥，PC端之间互斥，但移动端和PC端可以同时在线
  • 完全开放：允许所有设备同时在线
• 设备信息 - 支持设备ID、平台、型号、版本等信息

🔄 序列化协商

• 多格式支持 - 支持 Protobuf 和 JSON 序列化格式
• 压缩算法 - 支持 None、Gzip、Zstd 压缩算法
• 协商机制 - 客户端和服务端自动协商最优的序列化格式和压缩算法
• 强制模式 - 客户端可以强制指定格式（适用于不支持某些格式的平台）

💓 心跳检测

• 自动心跳 - 服务端自动检测连接超时
• 客户端心跳 - 客户端自动发送心跳保持连接
• 可配置 - 心跳间隔和超时时间可配置

🏗️ 灵活的构建模式

• 观察者模式 - 实现 ConnectionHandler/ConnectionObserver trait 处理消息
• 简单模式 - 使用闭包定义消息处理逻辑
• 事件处理器 - 支持细化的命令处理和事件观察

📦 模块化设计

• 清晰的架构 - 协议层、核心层、业务层分离
• 易于扩展 - 支持自定义认证器、事件处理器、设备管理器等
• 类型安全 - 充分利用 Rust 的类型系统保证安全性

📦 安装

使用 Cargo

[dependencies]
flare-core = "0.1.0"

功能特性

当前版本包含以下特性（可通过 features 启用，未来版本）：

• default - 默认功能集（当前包含所有功能）

🚀 快速开始

服务端示例

观察者模式（推荐）

use flare_core::server::*;
use flare_core::common::*;
use std::sync::Arc;

// 实现 ConnectionHandler
struct MyHandler;

#[async_trait::async_trait]
impl ConnectionHandler for MyHandler {
    async fn handle_frame(&self, frame: &Frame, connection_id: &str) -> Result<Option<Frame>> {
        // 处理消息
        Ok(None)
    }

    async fn on_connect(&self, connection_id: &str) -> Result<()> {
        println!("新连接: {}", connection_id);
        Ok(())
    }

    async fn on_disconnect(&self, connection_id: &str) -> Result<()> {
        println!("连接断开: {}", connection_id);
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    let handler = Arc::new(MyHandler);
    
    let mut server = ObserverServerBuilder::new("0.0.0.0:8080")
        .with_handler(handler)
        .build()?;
    
    server.start().await?;
    tokio::signal::ctrl_c().await?;
    server.stop().await?;
    Ok(())
}

简单模式

use flare_core::server::*;
use flare_core::common::*;

#[tokio::main]
async fn main() -> Result<()> {
    let mut server = ServerBuilder::new("0.0.0.0:8080")
        .on_message(|frame, ctx| async move {
            // 处理消息
            Ok(None)
        })
        .on_connect(|conn_id, ctx| async move {
            println!("新连接: {}", conn_id);
            Ok(())
        })
        .build()?;
    
    server.start().await?;
    tokio::signal::ctrl_c().await?;
    server.stop().await?;
    Ok(())
}

客户端示例

观察者模式（推荐）

use flare_core::client::*;
use flare_core::transport::events::*;
use std::sync::Arc;

// 实现 ConnectionObserver
struct MyObserver;

impl ConnectionObserver for MyObserver {
    fn on_event(&self, event: &ConnectionEvent) {
        match event {
            ConnectionEvent::Connected => println!("已连接"),
            ConnectionEvent::Disconnected(reason) => println!("断开: {}", reason),
            ConnectionEvent::Message(data) => {
                // 处理消息
            }
            ConnectionEvent::Error(e) => eprintln!("错误: {:?}", e),
        }
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    let observer = Arc::new(MyObserver);
    
    let mut client = ObserverClientBuilder::new("ws://127.0.0.1:8080")
        .with_observer(observer)
        .build_with_race()
        .await?;
    
    // 发送消息
    let frame = /* ... */;
    client.send_frame(&frame).await?;
    
    tokio::signal::ctrl_c().await?;
    client.disconnect().await?;
    Ok(())
}

简单模式

use flare_core::client::*;

#[tokio::main]
async fn main() -> Result<()> {
    let mut client = ClientBuilder::new("ws://127.0.0.1:8080")
        .on_message(|frame| {
            println!("收到消息: {:?}", frame);
            Ok(())
        })
        .on_event(|event| {
            println!("事件: {:?}", event);
        })
        .build_with_race()
        .await?;
    
    // 使用客户端...
    Ok(())
}

📚 核心模块

服务端模块 (server)

• HybridServer - 混合服务端，支持多协议监听
• ServerBuilder / ObserverServerBuilder - 服务端构建器
• ConnectionManager - 连接管理器
• ServerCore - 服务端核心功能（连接管理、心跳检测、协商处理）
• Authenticator - 认证器接口
• DeviceManager - 设备管理器
• ServerEventHandler - 事件处理器接口

客户端模块 (client)

• HybridClient - 混合客户端，支持协议竞速
• ClientBuilder / ObserverClientBuilder - 客户端构建器
• ClientCore - 客户端核心功能（状态管理、心跳管理、消息路由）
• ConnectionObserver - 连接观察者接口
• ClientEventHandler - 事件处理器接口

公共模块 (common)

• MessageParser - 消息解析器（支持 Protobuf 和 JSON）
• CompressionAlgorithm - 压缩算法（None、Gzip、Zstd）
• SerializationFormat - 序列化格式（Protobuf、JSON）
• DeviceInfo - 设备信息
• DeviceConflictStrategy - 设备冲突策略
• FlareError - 统一错误类型

传输模块 (transport)

• Connection - 连接接口
• ConnectionEvent - 连接事件
• WebSocketTransport - WebSocket 传输实现
• QUICTransport - QUIC 传输实现

🔧 高级功能

认证配置

use flare_core::server::*;

// 自定义认证器
struct MyAuthenticator;

#[async_trait::async_trait]
impl Authenticator for MyAuthenticator {
    async fn authenticate(
        &self,
        token: &str,
        connection_id: &str,
        device_info: Option<&DeviceInfo>,
        metadata: Option<&HashMap<String, Vec<u8>>>,
    ) -> Result<AuthResult> {
        // 验证 token
        if token == "valid_token" {
            Ok(AuthResult::success(Some("user123".to_string())))
        } else {
            Ok(AuthResult::failure("Token 无效".to_string()))
        }
    }
}

let authenticator = Arc::new(MyAuthenticator);
let server = ObserverServerBuilder::new("0.0.0.0:8080")
    .enable_auth()
    .with_authenticator(authenticator)
    .with_auth_timeout(Duration::from_secs(30))
    .build()?;

设备管理

use flare_core::server::*;
use flare_core::common::device::*;

let device_manager = Arc::new(DeviceManager::new(
    DeviceConflictStrategyBuilder::new()
        .platform_exclusive() // 平台互斥
        .build()
));

let server = ObserverServerBuilder::new("0.0.0.0:8080")
    .with_device_manager(device_manager)
    .build()?;

序列化协商

// 服务端：设置默认格式
let server = ObserverServerBuilder::new("0.0.0.0:8080")
    .with_default_format(SerializationFormat::Protobuf)
    .with_default_compression(CompressionAlgorithm::Gzip)
    .build()?;

// 客户端：设置首选格式（协商模式）
let client = ObserverClientBuilder::new("ws://127.0.0.1:8080")
    .with_format(SerializationFormat::Protobuf)
    .with_compression(CompressionAlgorithm::Gzip)
    .build_with_race()
    .await?;

// 客户端：强制指定格式（不协商）
let client = ObserverClientBuilder::new("ws://127.0.0.1:8080")
    .force_format(SerializationFormat::Json) // 强制使用 JSON
    .build_with_race()
    .await?;

协议竞速

use flare_core::common::config_types::TransportProtocol;

let client = ObserverClientBuilder::new("127.0.0.1:8080")
    .with_protocol_race(vec![
        TransportProtocol::QUIC,      // 优先级 0（最高）
        TransportProtocol::WebSocket,  // 优先级 1
    ])
    .with_protocol_url(TransportProtocol::WebSocket, "ws://127.0.0.1:8080".to_string())
    .with_protocol_url(TransportProtocol::QUIC, "quic://127.0.0.1:8081".to_string())
    .build_with_race()
    .await?;

📖 文档

API 文档

完整的 API 文档请查看 docs.rs/flare-core

示例

项目包含丰富的示例，位于 examples/ 目录：

• 基础示例

  • websocket_server.rs / websocket_client.rs - WebSocket 基础示例
  • quic_server.rs / quic_client.rs - QUIC 基础示例
  • hybrid_server.rs / hybrid_client.rs - 混合协议示例

• 高级示例

  • negotiation_server.rs / negotiation_client.rs - 序列化协商和设备管理示例
  • auth_server.rs / auth_client.rs - 认证示例
  • simple_server.rs / simple_client.rs - 简单模式示例

运行示例：

# 查看所有示例
cargo run --example <example_name>

# 查看示例说明
cat examples/README.md

🏗️ 架构设计

模块分层

┌─────────────────────────────────────────┐
│          应用层 (Application)            │
│  - ConnectionHandler / ConnectionObserver │
│  - EventHandler                          │
│  - Authenticator                         │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│          核心层 (Core)                    │
│  - ServerCore / ClientCore               │
│  - ConnectionManager                     │
│  - HeartbeatDetector / HeartbeatManager  │
│  - DeviceManager                         │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│          协议层 (Protocol)                │
│  - WebSocketServer / WebSocketClient     │
│  - QUICServer / QUICClient               │
│  - HybridServer / HybridClient           │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│          传输层 (Transport)                │
│  - WebSocketTransport                    │
│  - QUICTransport                         │
│  - Connection trait                      │
└─────────────────────────────────────────┘

核心组件

1. ServerCore / ClientCore

   • 统一管理连接状态、心跳、消息路由
   • 处理协商、设备冲突、认证等核心逻辑

2. ConnectionManager

   • 管理所有活跃连接
   • 支持按连接ID、用户ID查询
   • 维护连接状态和元数据

3. MessageParser

   • 支持 Protobuf 和 JSON 自动检测
   • 支持压缩/解压缩
   • 协商后动态更新解析器

4. DeviceManager

   • 管理用户设备
   • 实现设备冲突策略
   • 处理设备踢出逻辑

🔒 安全性

• 认证机制 - 支持可配置的 token 验证
• 连接状态 - 只有已验证的连接才能收发业务消息
• TLS 支持 - 支持 TLS/SSL 加密（WebSocket 和 QUIC）
• 错误处理 - 完善的错误处理和日志记录

📊 性能特性

• 异步架构 - 基于 Tokio 的高性能异步运行时
• 零拷贝 - 尽可能减少数据拷贝
• 连接复用 - 高效的连接管理
• 协议竞速 - 自动选择最快的协议

📦 发布到 crates.io

安装

cargo add flare-core

发布准备

发布前请确保：

1. ✅ 所有代码已通过测试和 lint 检查
2. ✅ 文档已更新
3. ✅ 版本号已更新
4. ✅ README.md 和 Cargo.toml 已完善

详细发布指南请查看 PUBLISH.md。

发布命令

# 1. 登录 crates.io（首次发布需要）
cargo login <your-token>

# 2. 检查打包
cargo package

# 3. 发布
cargo publish

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详细信息。

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🔗 相关链接

• 文档
• GitHub 仓库
• 问题反馈
• crates.io

📝 版本历史

0.1.0 (当前版本)

• ✨ 初始发布
• 支持 WebSocket 和 QUIC 协议
• 支持协议竞速
• 支持序列化协商（Protobuf/JSON）
• 支持压缩算法（None/Gzip/Zstd）
• 支持多设备管理
• 支持 Token 认证
• 提供观察者模式和简单模式两种构建方式
• 完善的事件处理机制

Flare Core - 让实时通信变得简单 🚀