flare_core/
lib.rs

1//! Production-oriented long-connection primitives for realtime Rust systems.
2//!
3//! `flare-core` provides the transport foundation used by Flare IM and other
4//! realtime applications. It focuses on connection-oriented infrastructure:
5//! WebSocket, QUIC, optional TCP, negotiation, heartbeat policy, reconnection,
6//! message parsing, compression, encryption, and extensible middleware.
7//!
8//! The crate intentionally stays transport-centric and business-neutral.
9//! Product semantics such as message sequence allocation, inbox sync, push
10//! delivery, moderation, and tenant-specific policy should live in higher-level
11//! services or extension crates.
12//!
13//! # Main Modules
14//!
15//! - [`common`] contains protocol frames, parsers, codecs, compression,
16//!   encryption, errors, feature discovery, and shared configuration types.
17//! - [`transport`] contains transport events, framing helpers, and concrete
18//!   transport implementations.
19//! - [`client`] contains client builders, connection orchestration, heartbeat
20//!   handling, reconnect support, and native or wasm WebSocket clients.
21//! - `server` contains native server builders, connection management,
22//!   negotiation, event handling, and transport listeners.
23//!
24//! # Feature Flags
25//!
26//! - `client`: client builders and transport clients.
27//! - `server`: native server builders and connection management.
28//! - `websocket`: WebSocket transport.
29//! - `quic`: native QUIC transport.
30//! - `tcp`: optional length-prefixed TCP transport.
31//! - `wasm`: wasm32 WebSocket client support.
32//! - `compression-gzip`: Gzip compression support.
33//! - `encryption-aes-gcm`: AES-256-GCM encryption support.
34//! - `full`: default feature set plus TCP.
35//!
36//! # Runtime Model
37//!
38//! A typical connection goes through transport establishment, CONNECT
39//! negotiation, parser alignment, NEGOTIATION_READY, heartbeat startup, message
40//! exchange, and disconnect or reconnect cleanup. The public builders hide most
41//! of this lifecycle while keeping failure semantics explicit through typed
42//! errors and connection events.
43//!
44//! # Choosing An Entry Point
45//!
46//! - Start with `client::FlareClientBuilder` or `server::FlareServerBuilder`
47//!   for production integrations that need traits, middleware, and connection
48//!   lifecycle hooks.
49//! - Use `client::ClientBuilder` or `server::ServerBuilder` for compact
50//!   examples and closure-based prototypes.
51//! - Use [`transport`] directly only when building a custom runtime adapter or
52//!   transport-level integration.
53//!
54//! # Minimal Server Sketch
55//!
56//! ```no_run
57//! use async_trait::async_trait;
58//! use flare_core::common::error::Result;
59//! use flare_core::common::protocol::{Frame, PayloadCommand};
60//! use flare_core::server::events::handler::ServerEventHandler;
61//! use flare_core::server::FlareServerBuilder;
62//! use std::sync::Arc;
63//!
64//! struct Handler;
65//!
66//! #[async_trait]
67//! impl ServerEventHandler for Handler {
68//!     async fn handle_message(
69//!         &self,
70//!         _command: &PayloadCommand,
71//!         _connection_id: &str,
72//!     ) -> Result<Option<Frame>> {
73//!         Ok(None)
74//!     }
75//! }
76//!
77//! # #[cfg(all(feature = "server", not(target_arch = "wasm32")))]
78//! # async fn run() -> Result<()> {
79//! let server = FlareServerBuilder::new("0.0.0.0:8080", Arc::new(Handler)).build()?;
80//! server.start().await?;
81//! # Ok(())
82//! # }
83//! ```
84//!
85//! # Documentation
86//!
87//! See the repository README for installation, examples, performance baselines,
88//! and release verification guidance:
89//! <https://github.com/flare-im/flare-core>.
90
91pub mod common;
92
93#[cfg(all(feature = "server", not(target_arch = "wasm32")))]
94pub mod server;
95
96#[cfg(feature = "client")]
97pub mod client;
98pub mod transport;
99
100#[cfg(all(
101    feature = "client",
102    not(target_arch = "wasm32"),
103    any(feature = "websocket", feature = "quic", feature = "tcp")
104))]
105pub use client::HybridClient;
106#[cfg(all(
107    feature = "server",
108    not(target_arch = "wasm32"),
109    any(feature = "websocket", feature = "quic", feature = "tcp")
110))]
111pub use server::HybridServer;
112
113#[cfg(all(feature = "client", not(target_arch = "wasm32")))]
114pub use client::{ClientBuilder, ObserverClient, ObserverClientBuilder, SimpleClient};
115#[cfg(all(feature = "server", not(target_arch = "wasm32")))]
116pub use server::{
117    DefaultServerHandle, MessageContext, ObserverServer, ObserverServerBuilder, ServerBuilder,
118    ServerHandle, SimpleServer,
119};
120
121#[cfg(all(feature = "client", target_arch = "wasm32"))]
122pub use client::{
123    ClientBuilder, FlareClient, FlareClientBuilder, MessageListener, SimpleClient, WebSocketClient,
124};
125
126pub use common::conversation::*;
flare_core/lib.rs

flare_core/
lib.rs
