clasp_federation/lib.rs
1//! Router federation for CLASP
2//!
3//! This crate enables CLASP routers to connect to each other and share
4//! state across network boundaries. Federation links appear as normal
5//! client sessions, using the standard CLASP protocol for communication.
6//!
7//! # Architecture
8//!
9//! Federation works by:
10//! 1. Each router declares its owned **namespace patterns** (e.g., `/site-a/**`)
11//! 2. Routers connect to each other and exchange namespace declarations
12//! 3. Messages matching a peer's namespace are forwarded via the federation link
13//! 4. Loop prevention uses an `origin` field -- messages are never forwarded
14//! back to the router they came from
15//!
16//! # Modes
17//!
18//! - **Hub**: Central router that accepts leaf connections (star topology)
19//! - **Leaf**: Edge router that connects to a single hub
20//! - **Mesh**: Peer-to-peer connections between multiple routers
21//!
22//! # Example
23//!
24//! ```no_run
25//! use clasp_federation::{FederationManager, FederationConfig, FederationMode};
26//!
27//! # async fn example() {
28//! let config = FederationConfig {
29//! mode: FederationMode::Leaf {
30//! hub_endpoint: "wss://hub.example.com:7330".to_string(),
31//! },
32//! router_id: "site-a".to_string(),
33//! owned_namespaces: vec!["/site-a/**".to_string()],
34//! ..Default::default()
35//! };
36//!
37//! let manager = FederationManager::new(config);
38//! // Create links for each peer connection...
39//! # }
40//! ```
41
42pub mod config;
43pub mod error;
44pub mod link;
45pub mod manager;
46pub mod namespace;
47
48pub use config::{FederationConfig, FederationMode, PeerInfo, PeerState};
49pub use error::{FederationError, Result};
50pub use link::{FederationLink, LinkEvent};
51pub use manager::FederationManager;
52pub use namespace::NamespaceManager;