Expand description
§Rust SocketCluster-Inspired WebSocket Server
This library provides scalable SocketCluster protocol v1 server implementation. It’s built on top of Axum and Tokio, offering a robust foundation for real-time applications.
§Features
- WebSocket-based real-time communication
- Publish/Subscribe pattern for efficient message distribution
- Customizable middleware for packet processing
- Authentication support
- Ping/Pong mechanism for connection health monitoring
§Main Components
AppState
: Manages the global state of the application, including active connections and subscriptions.Handlers
: Processes WebSocket events and messages.Middleware
: Allows for custom processing of packets before they reach the main application logic.Models
: Defines the core data structures used in communication.Config
: Handles server configuration.
§Getting Started
To use this library, add it to your Cargo.toml
:
[dependencies]
rust_socketcluster = "0.1.0"
Then, you can start using it in your project. Here’s a basic example:
use socketcluster_server::{create_socketcluster_state, ServerConfig, ws_handler};
use axum::{Router, routing::get};
use tokio::net::TcpListener;
use std::net::SocketAddr;
#[tokio::main]
async fn main() {
// Load configuration
let config = ServerConfig {
ping_interval: std::time::Duration::from_secs(30),
ping_timeout: std::time::Duration::from_secs(5),
port: 8080,
host: "127.0.0.1".to_string(),
jwt_secret: "your-secret-key".to_string(),
};
// Create application state
let state = create_socketcluster_state(config.clone());
// Set up router
let app = Router::new()
.route("/ws", get(ws_handler))
.with_state(state);
// Start the server
let addr = format!("{}:{}", config.host, config.port);
let listener = TcpListener::bind(&addr).await.unwrap();
println!("Server listening on: {}", addr);
axum::serve(listener, app.into_make_service_with_connect_info::<SocketAddr>()).await.unwrap();
}
§Advanced Usage
§Custom Middleware
You can add custom middleware to process packets before they reach the main application logic:
use socketcluster_server::{Middleware, Packet, AuthData};
use async_trait::async_trait;
struct MyMiddleware;
#[async_trait]
impl Middleware for MyMiddleware {
async fn handle(&self, packet: &mut Packet, auth_data: &AuthData) -> bool {
// Custom packet processing logic
println!("Processing packet: {:?}", packet);
true // Allow the packet to proceed
}
}
// In your main function:
let mut state = create_socketcluster_state(config);
state.add_middleware(Arc::new(MyMiddleware));
§Best Practices
- Use the
AppState
to manage shared resources and avoid race conditions. - Implement proper error handling and logging in your application.
- Use SSL/TLS for secure WebSocket connections in production (for example by Haproxy SSL termination).
§Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Structs§
- AppState
- Represents the global application state.
- Auth
Data - Holds authentication-related data for a socket connection.
- Packet
- Represents a packet of data exchanged in the WebSocket communication.
- Server
Config - Server configuration struct.
- Socket
Data - Holds data associated with a socket connection.
- WebSocket
Receiver - Implements the
Receiver
trait for the WebSocket stream. - WebSocket
Sender - Implements the
Sender
trait for the WebSocket sink.
Enums§
- Event
- Represents different types of events in the WebSocket communication.
Traits§
- Middleware
- Trait for implementing middleware functionality.
- Receiver
- Trait for receiving WebSocket messages.
- Sender
- Trait for sending WebSocket messages.
Functions§
- create_
socketcluster_ state - Creates a new
AppState
instance for the SocketCluster server. - ws_
handler - Handles incoming WebSocket connection requests.