clasp-router 4.1.0

CLASP message router and server
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! # CLASP Router
//!
//! The router is the central message hub for CLASP (Creative Low-Latency Application Streaming Protocol).
//!
//! ## Core Responsibilities
//!
//! - **Session Management**: Track connected clients, handle authentication, manage session lifecycle
//! - **Message Routing**: Route messages between clients based on address patterns
//! - **State Management**: Maintain parameter state with revision tracking
//! - **Subscription Handling**: Match published messages to subscriber patterns
//! - **Protocol Bridging**: Interface with external protocols via bridges
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
//! │   Client A  │     │   Client B  │     │   Client C  │
//! └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
//!        │                   │                   │
//!        └───────────────────┼───────────────────┘
//!                            │
//!                    ┌───────▼───────┐
//!                    │    Router     │
//!                    │  ┌─────────┐  │
//!                    │  │  State  │  │  Parameter storage
//!                    │  └─────────┘  │
//!                    │  ┌─────────┐  │
//!                    │  │Subscr.  │  │  Subscription matching
//!                    │  └─────────┘  │
//!                    │  ┌─────────┐  │
//!                    │  │Sessions │  │  Client tracking
//!                    │  └─────────┘  │
//!                    └───────────────┘
//! ```
//!
//! ## Transport Support
//!
//! The router is transport-agnostic and can accept connections from:
//!
//! - **WebSocket** (default): Universal, works in browsers and all platforms
//! - **QUIC**: High-performance for native apps (requires UDP)
//!
//! ## Quick Start
//!
//! ```no_run
//! use clasp_router::{Router, RouterConfig};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create router with default configuration
//!     let router = Router::new(RouterConfig::default());
//!
//!     // Start WebSocket server on default port
//!     router.serve_websocket("0.0.0.0:7330").await?;
//!     Ok(())
//! }
//! ```
//!
//! ## Configuration
//!
//! ```no_run
//! use clasp_router::{Router, RouterConfig};
//!
//! let config = RouterConfig {
//!     max_sessions: 1000,
//!     max_subscriptions_per_session: 1000,
//!     session_timeout: 300,
//!     ..Default::default()
//! };
//!
//! let router = Router::new(config);
//! ```
//!
//! ## Message Flow
//!
//! 1. Client connects and sends HELLO
//! 2. Router responds with WELCOME (includes session ID, server time)
//! 3. Client subscribes to patterns
//! 4. Client sends SET/PUBLISH messages
//! 5. Router stores state (for SET) and routes to matching subscribers
//!
//! ## Module Overview
//!
//! - [`router`] - Main Router struct and message handling
//! - [`session`] - Client session management
//! - [`state`] - Parameter state storage
//! - [`subscription`] - Pattern-based subscription matching
//! - [`p2p`] - Peer-to-peer mesh networking support
//! - [`gesture`] - Gesture move coalescing for bandwidth optimization
//! - [`error`] - Error types

pub mod error;
pub mod gesture;
pub mod handlers;
pub mod p2p;
pub mod router;
pub mod session;
pub mod state;
pub mod subscription;

// Protocol adapters (feature-gated)
#[cfg(any(feature = "mqtt-server", feature = "osc-server"))]
pub mod adapters;

pub use error::{Result, RouterError};
pub use gesture::{GestureRegistry, GestureResult};
pub use p2p::{analyze_address, P2PAddressType, P2PCapabilities};
#[cfg(feature = "quic")]
pub use router::QuicServerConfig;
pub use router::{
    MultiProtocolConfig, Router, RouterConfig, RouterConfigBuilder, SnapshotFilter,
    TransportConfig, WriteValidator,
};
pub use session::{Session, SessionId};
pub use state::{RouterState, RouterStateConfig};
pub use subscription::SubscriptionManager;

#[cfg(feature = "rules")]
pub use router::execute_rule_actions;

// Re-export adapter configs
#[cfg(feature = "mqtt-server")]
pub use adapters::{MqttServerAdapter, MqttServerConfig};
#[cfg(feature = "osc-server")]
pub use adapters::{OscServerAdapter, OscServerConfig};