soketi_rs/lib.rs
1//! # Soketi-RS: Pusher Protocol Server in Rust
2//!
3//! A high-performance, feature-complete implementation of the Pusher protocol server in Rust.
4//!
5//! ## Overview
6//!
7//! Soketi-RS provides a complete implementation of the Pusher WebSocket protocol with support for:
8//! - WebSocket connections with full Pusher protocol support
9//! - HTTP REST API for triggering events and querying channels
10//! - Multiple adapter types for horizontal scaling
11//! - Flexible app management with multiple backend options
12//! - Caching, rate limiting, and queue processing
13//! - Webhook delivery with HTTP and AWS Lambda support
14//! - Prometheus metrics export
15//!
16//! ## Quick Start
17//!
18//! ```no_run
19//! use soketi_rs::server::Server;
20//! use soketi_rs::config::ServerConfig;
21//! use soketi_rs::app::App;
22//!
23//! #[tokio::main]
24//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
25//! // Create configuration
26//! let mut config = ServerConfig::default();
27//!
28//! // Add an app
29//! let app = App::new(
30//! "app-id".to_string(),
31//! "app-key".to_string(),
32//! "app-secret".to_string(),
33//! );
34//! config.app_manager.array.apps = vec![app];
35//!
36//! // Create and initialize server
37//! let mut server = Server::new(config);
38//! server.initialize().await?;
39//!
40//! // Start the server
41//! server.start().await?;
42//!
43//! Ok(())
44//! }
45//! ```
46//!
47//! ## Architecture
48//!
49//! The server is built around several key components:
50//!
51//! ### Core Components
52//!
53//! - **Server**: Main entry point that initializes and manages all components
54//! - **AppState**: Shared state containing all managers and configuration
55//! - **WsHandler**: Handles WebSocket connections and Pusher protocol messages
56//! - **HttpHandler**: Handles REST API requests
57//!
58//! ### Managers
59//!
60//! - **Adapter**: Manages socket connections and message distribution
61//! - Local: Single-instance deployment
62//! - Cluster: Multi-instance with UDP discovery
63//! - Redis: Horizontal scaling with Redis pub/sub
64//! - NATS: Horizontal scaling with NATS messaging
65//!
66//! - **AppManager**: Manages application configurations
67//! - Array: Static configuration
68//! - DynamoDB: AWS DynamoDB backend
69//! - MySQL: MySQL database backend
70//! - PostgreSQL: PostgreSQL database backend
71//!
72//! - **CacheManager**: Provides caching functionality
73//! - Memory: In-memory caching
74//! - Redis: Distributed caching with Redis
75//!
76//! - **RateLimiter**: Enforces rate limits
77//! - Local: Single-instance rate limiting
78//! - Cluster: Cluster-wide rate limiting
79//! - Redis: Distributed rate limiting with Redis
80//!
81//! - **QueueManager**: Manages webhook job processing
82//! - Sync: Immediate processing
83//! - Redis: BullMQ-compatible queue
84//! - SQS: AWS SQS queue
85//!
86//! - **MetricsManager**: Collects and exposes metrics
87//! - Prometheus: Prometheus metrics export
88//!
89//! - **WebhookSender**: Sends webhook notifications
90//! - HTTP webhooks
91//! - AWS Lambda invocation
92//!
93//! ## Channel Types
94//!
95//! Soketi-RS supports all Pusher channel types:
96//!
97//! - **Public channels**: No authentication required
98//! - **Private channels**: Require authentication signature
99//! - **Encrypted private channels**: End-to-end encryption
100//! - **Presence channels**: Track channel members
101//!
102//! ## Configuration
103//!
104//! Configuration can be loaded from multiple sources:
105//!
106//! 1. Command-line arguments (highest priority)
107//! 2. Environment variables (with `PUSHER_` prefix)
108//! 3. Configuration files (JSON, YAML, TOML)
109//! 4. Default values (lowest priority)
110//!
111//! See the [`options`] module for configuration loading and the [`config`] module
112//! for configuration structures.
113//!
114//! ## Examples
115//!
116//! ### Basic Server Setup
117//!
118//! ```no_run
119//! use soketi_rs::server::Server;
120//! use soketi_rs::options::Options;
121//!
122//! #[tokio::main]
123//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
124//! // Load configuration from all sources
125//! let config = Options::load()?;
126//!
127//! // Create and initialize server
128//! let mut server = Server::new(config);
129//! server.initialize().await?;
130//!
131//! // Start the server
132//! server.start().await?;
133//!
134//! Ok(())
135//! }
136//! ```
137//!
138//! ### Custom Configuration
139//!
140//! ```no_run
141//! use soketi_rs::server::Server;
142//! use soketi_rs::config::{ServerConfig, AdapterDriver, CacheDriver};
143//! use soketi_rs::app::App;
144//!
145//! #[tokio::main]
146//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
147//! let mut config = ServerConfig::default();
148//!
149//! // Configure server
150//! config.host = "0.0.0.0".to_string();
151//! config.port = 6001;
152//! config.debug = true;
153//!
154//! // Use Redis adapter for horizontal scaling
155//! config.adapter.driver = AdapterDriver::Redis;
156//! config.adapter.redis.host = "redis.example.com".to_string();
157//!
158//! // Use Redis cache
159//! config.cache.driver = CacheDriver::Redis;
160//!
161//! // Add apps
162//! let app = App::new(
163//! "app-1".to_string(),
164//! "key-1".to_string(),
165//! "secret-1".to_string(),
166//! );
167//! config.app_manager.array.apps = vec![app];
168//!
169//! // Create and start server
170//! let mut server = Server::new(config);
171//! server.initialize().await?;
172//! server.start().await?;
173//!
174//! Ok(())
175//! }
176//! ```
177//!
178//! ## Feature Flags
179//!
180//! This crate does not currently use feature flags, but all functionality is included by default.
181//!
182//! ## Requirements
183//!
184//! This implementation validates against the following requirements:
185//! - Requirements 1.1-1.7: Core server architecture
186//! - Requirements 2.1-2.10: WebSocket handler
187//! - Requirements 3.1-3.14: HTTP REST API
188//! - Requirements 4.1-4.10: Adapter system
189//! - Requirements 5.1-5.9: App manager system
190//! - Requirements 6.1-6.6: Cache manager system
191//! - Requirements 7.1-7.10: Channel types
192//! - Requirements 8.1-8.8: Rate limiting
193//! - Requirements 9.1-9.6: Queue system
194//! - Requirements 10.1-10.10: Webhook sender
195//! - Requirements 11.1-11.7: Metrics system
196//! - Requirements 12.1-12.7: Authentication and security
197//! - Requirements 13.1-13.9: Error handling
198//! - Requirements 14.1-14.10: Configuration
199//! - Requirements 15.1-15.7: Client event handling
200//! - Requirements 16.1-16.6: User authentication
201//! - Requirements 17.1-17.5: Cluster discovery
202//! - Requirements 18.1-18.4: Database connection pooling
203//! - Requirements 19.1-19.7: Message validation
204//! - Requirements 20.1-20.7: Logging and debugging
205
206pub mod adapters;
207pub mod api;
208pub mod app;
209pub mod app_managers;
210pub mod auth;
211pub mod cache_managers;
212pub mod channels;
213pub mod config;
214pub mod error;
215pub mod log;
216pub mod metrics;
217pub mod namespace;
218pub mod options;
219pub mod pusher;
220pub mod queues;
221pub mod rate_limiters;
222pub mod server;
223pub mod state;
224pub mod validation;
225pub mod webhook_sender;
226pub mod ws;
227pub mod ws_handler;