Flare Core

English · 中文

ℹ This is communication infrastructure, not a ready-to-use IM product

Up front, so you don't discover after cloning that you can't log in: the open-source part does not include an account system (no registration/login, friend relationships, group roles/approval/muting, or moments/feed).

It does ship a complete, pluggable authentication contract, and both paths live on the open-source side:

• CoreJwtTokenValidator — validates JWTs locally. Hand-sign a token and you can run a demo / POC, without any user system.
• HttpHookTokenValidator — POSTs the token to your own endpoint. This is the entry point for integrating your own user system.

Business rules work the same way: flare-im-core/crates/flare-im-hooks provides 9 extension points (PreSend / PostSend / Delivery / Recall / MessageRead / MessageReaction / ConversationLifecycle / ConversationMember / GetConversationParticipants).

To go to production, you implement your own user system and wire it in via the contracts above — the same "bring your own identity" model as Sendbird / Twilio Conversations, the difference being that Flare can be self-hosted and its protocol and core are auditable.

See GOVERNANCE.md for the boundary details.

flare-core is a production-oriented long-connection toolkit for Rust. It provides the transport foundation for realtime systems such as instant messaging gateways, chat rooms, push channels, collaboration tools, and low-latency application backends.

The crate focuses on transport-level concerns: WebSocket, QUIC, TCP, connection negotiation, heartbeats, reconnection, serialization, compression, encryption, and extensible message pipelines. IM product semantics such as sequence allocation, inbox sync, push policy, and business rules should live in higher-level crates or services.

API documentation: docs.rs/flare-core

Highlights

• Transports: WebSocket, QUIC, optional TCP, and native protocol racing.
• Negotiation: CONNECT / CONNECT_ACK / NEGOTIATION_READY flow for format, compression, and encryption alignment.
• Codecs: Protobuf and JSON with pluggable serializers.
• Reliability basics: heartbeat policy, active detection, reconnect hooks, connection snapshots, and slow-consumer isolation.
• Security hooks: token authentication, TLS support, certificate pinning, and AES-256-GCM encryption when enabled.
• Runtime targets: native Tokio applications and wasm32 WebSocket clients.
• Extension points: custom serializers, compressors, encryptors, middleware, observers, and server event handlers.

Installation

[dependencies]
flare-core = "1.0.1"

Server-only gateway:

flare-core = { version = "1.0.1", default-features = false, features = [
    "server",
    "websocket",
    "quic",
    "compression-gzip",
    "encryption-aes-gcm",
] }

Native client:

flare-core = { version = "1.0.1", default-features = false, features = [
    "client",
    "websocket",
    "quic",
    "compression-gzip",
    "encryption-aes-gcm",
] }

TCP and full feature sets:

flare-core = { version = "1.0.1", features = ["tcp"] }
flare-core = { version = "1.0.1", features = ["full"] }

WASM WebSocket client:

flare-core = { version = "1.0.1", default-features = false, features = ["wasm"] }

cargo build --target wasm32-unknown-unknown --no-default-features --features wasm

Feature Flags

At runtime, use flare_core::common::FeatureSet::current() to inspect the compiled capability set.

Architecture

Application   ServerEventHandler | MessageListener | Authenticator
      |
Core          ServerCore | ClientCore | ConnectionManager | MessagePipeline
      |
Transport     HybridServer | HybridClient | WebSocket | QUIC | TCP

Connection lifecycle:

1. Establish a transport connection.
2. Send CONNECT metadata for serialization, compression, encryption, and authentication.
3. Receive CONNECT_ACK and align both parser profiles.
4. Emit NEGOTIATION_READY and start heartbeat processing.
5. Exchange application frames.
6. Disconnect, reconnect, or clean up connection state.

Builder families:

Quick Start

Minimal Flare-mode server:

use async_trait::async_trait;
use flare_core::common::error::Result;
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,
    ) -> Result<Option<Frame>> {
        Ok(None)
    }
}

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

Run the chat examples from the repository checkout:

RUST_LOG=info cargo run --example flare_chat_server
RUST_LOG=info cargo run --example flare_chat_client -- user1

TCP example:

cargo run --example flare_chat_server --features tcp
RUST_LOG=info cargo run --example tcp_client --features tcp

More examples are documented in the repository: examples/README.md.

Native And WASM Support

For browser demos, see examples/wasm_websocket_client.

Verification

The repository verification script runs formatting, linting, native tests, feature matrix checks, wasm checks, and example builds:

./scripts/verify.sh

For a focused pre-publish check:

cargo test --lib --tests --examples --all-features
cargo doc --no-deps --all-features
cargo publish --dry-run

Note: historical doctest snippets in lower-level module comments are not used as the release gate yet. The public README and crate-level docs are kept in English for crates.io and docs.rs.

Performance Baseline

The current baseline covers frame encoding, message parsing, pipeline processing, connection lifecycle, and in-memory fanout. It does not model higher-level IM semantics such as sequence allocation, sync, inbox storage, or push delivery.

Test environment for the published baseline:

Summary:

Full report: docs/performance-baseline.md.

Documentation

License

Licensed under the Apache License 2.0.

下一步

需要账号体系与社交能力时

开源部分是通信基础设施。如果你需要的是现成的账号、好友关系、群治理（角色 / 入群审批 / 禁言）、朋友圈， 这些在商业模块里 —— 自研这一层通常要数月，且都是与通信无关的重复劳动。

企业场景另有 SSO / 组织架构 / 审计导出 / 数据驻留 / SLA 支持。

咨询：flare1522@163.com

边界划分与不变承诺见 GOVERNANCE。 简言之：已开源的不会被收回，鉴权与 hooks 契约永远开源、不会为逼迫付费而阉割。