Flare Core

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 MIT License.