Crate reinhardt_websockets 

WebSocket support for Reinhardt framework

This crate provides comprehensive WebSocket support for the Reinhardt framework, including connection management, room-based messaging, authentication, rate limiting, middleware integration, and distributed channel layers.

Features

• Connection Management: Robust WebSocket connection handling with lifecycle hooks
• Room-Based Messaging: Group connections into rooms for targeted broadcasting
• Authentication & Authorization: Token-based auth and permission-based authorization
• Rate Limiting: Connection and message rate limiting to prevent abuse
• Middleware Integration: Pre-processing and post-processing of connections and messages
• WebSocket Routing: URL-based WebSocket endpoint registration
• Channel Layers: Distributed messaging for multi-instance deployments
• Consumer Classes: Django Channels-inspired message handling patterns

Basic Usage

use reinhardt_websockets::{WebSocketConnection, Message};
use tokio::sync::mpsc;
use std::sync::Arc;

let (tx, mut rx) = mpsc::unbounded_channel();
let conn = Arc::new(WebSocketConnection::new("user_1".to_string(), tx));

conn.send_text("Hello, WebSocket!".to_string()).await.unwrap();

let msg = rx.recv().await.unwrap();
match msg {
    Message::Text { data } => println!("Received: {}", data),
    _ => {}
}

Advanced Features

Message Compression

The compression feature enables gzip, deflate, and brotli compression for WebSocket messages:

[dependencies]
reinhardt-websockets = { version = "0.1", features = ["compression"] }

Automatic Reconnection

The reconnection module provides automatic reconnection with exponential backoff:

use reinhardt_websockets::reconnection::{ReconnectionConfig, ReconnectionStrategy};
use std::time::Duration;

let config = ReconnectionConfig::default()
    .with_max_attempts(5)
    .with_initial_delay(Duration::from_secs(1));

let mut strategy = ReconnectionStrategy::new(config);

Redis Channel Layer

The redis-channel feature enables distributed messaging via Redis:

[dependencies]
reinhardt-websockets = { version = "0.1", features = ["redis-channel"] }

Metrics and Monitoring

The metrics module provides comprehensive WebSocket metrics:

use reinhardt_websockets::metrics::{WebSocketMetrics, MetricsCollector};

let metrics = WebSocketMetrics::new();
metrics.record_connection();
metrics.record_message_sent();

let snapshot = metrics.snapshot();
println!("{}", snapshot.summary());

Integration with reinhardt-pages

The pages-integration feature enables seamless integration with reinhardt-pages, allowing WebSocket connections to use the same Cookie/session-based authentication as the HTTP layer:

[dependencies]
reinhardt-websockets = { version = "0.1", features = ["pages-integration"] }

Server-side setup:

use reinhardt_websockets::{PagesAuthenticator, WebSocketRouter, WebSocketRoute};
use std::sync::Arc;

// Create authenticator that integrates with reinhardt-pages sessions
let authenticator = Arc::new(PagesAuthenticator::new());

// Register WebSocket routes
let mut router = WebSocketRouter::new();
router.register_route(WebSocketRoute::new(
    "/ws/chat".to_string(),
    Some("websocket:chat".to_string()),
)).await.unwrap();

Client-side usage (WASM):

On the client side, use the use_websocket hook from reinhardt-pages:

use reinhardt_pages::reactive::hooks::{use_websocket, UseWebSocketOptions};

let ws = use_websocket("ws://localhost:8000/ws/chat", UseWebSocketOptions::default());

// Send message
ws.send_text("Hello, server!".to_string()).ok();

// Monitor connection state
use_effect({
    let ws = ws.clone();
    move || {
        match ws.connection_state().get() {
            ConnectionState::Open => log!("Connected"),
            ConnectionState::Closed => log!("Disconnected"),
            _ => {}
        }
        None::<fn()>
    }
});

The authentication cookies from the user’s HTTP session are automatically included in the WebSocket handshake, allowing the server to authenticate the connection.

Re-exports

pub use auth::AuthError;

pub use auth::AuthResult;

pub use auth::AuthUser;

pub use auth::AuthenticatedConnection;

pub use auth::AuthorizationPolicy;

pub use auth::PermissionBasedPolicy;

pub use auth::SimpleAuthUser;

pub use auth::TokenAuthenticator;

pub use auth::WebSocketAuthenticator;

pub use channels::ChannelError;

pub use channels::ChannelLayer;

pub use channels::ChannelLayerWrapper;

pub use channels::ChannelMessage;

pub use channels::ChannelResult;

pub use channels::InMemoryChannelLayer;

pub use connection::ConnectionConfig;

pub use connection::ConnectionTimeoutMonitor;

pub use connection::HeartbeatConfig;

pub use connection::HeartbeatMonitor;

pub use connection::Message;

pub use connection::PingPongConfig;

pub use connection::WebSocketConnection;

pub use connection::WebSocketError;

pub use connection::WebSocketResult;

pub use consumers::BroadcastConsumer;

pub use consumers::ConsumerChain;

pub use consumers::ConsumerContext;

pub use consumers::EchoConsumer;

pub use consumers::JsonConsumer;

pub use consumers::WebSocketConsumer;

pub use handler::WebSocketHandler;

pub use metrics::MetricsCollector;

pub use metrics::MetricsSnapshot;

pub use metrics::PeriodicReporter;

pub use metrics::WebSocketMetrics;

pub use middleware::ConnectionContext;

pub use middleware::ConnectionMiddleware;

pub use middleware::IpFilterMiddleware;

pub use middleware::LoggingMiddleware;

pub use middleware::MessageMiddleware;

pub use middleware::MessageSizeLimitMiddleware;

pub use middleware::MiddlewareChain;

pub use middleware::MiddlewareError;

pub use middleware::MiddlewareResult;

pub use origin::OriginPolicy;

pub use origin::OriginValidationConfig;

pub use origin::OriginValidationMiddleware;

pub use origin::validate_origin;

pub use protocol::DEFAULT_MAX_FRAME_SIZE;

pub use protocol::DEFAULT_MAX_MESSAGE_SIZE;

pub use protocol::default_websocket_config;

pub use protocol::websocket_config_with_limits;

pub use reconnection::AutoReconnectHandler;

pub use reconnection::ReconnectionConfig;

pub use reconnection::ReconnectionState;

pub use reconnection::ReconnectionStrategy;

pub use room::BroadcastResult;

pub use room::Room;

pub use room::RoomError;

pub use room::RoomManager;

pub use room::RoomResult;

pub use throttling::CombinedThrottler;

pub use throttling::ConnectionRateLimiter;

pub use throttling::ConnectionThrottler;

pub use throttling::RateLimitConfig;

pub use throttling::RateLimitMiddleware;

pub use throttling::RateLimiter;

pub use throttling::ThrottleError;

pub use throttling::ThrottleResult;

pub use throttling::WebSocketRateLimitConfig;

Modules

auth

Token-based authentication and authorization for WebSocket connections. WebSocket authentication and authorization

channels

Channel layer abstraction for cross-process messaging. Channel layers for distributed WebSocket systems

connection

WebSocket connection management and ping/pong keepalive.

consumers

Django Channels-inspired consumer classes for message handling. WebSocket consumers for advanced message handling patterns

endpoint

Compile-time endpoint metadata and URL parameter substitution. WebSocket endpoint metadata — re-exported from reinhardt-core::ws.

handler

WebSocket upgrade handler and connection lifecycle. WebSocket handler

metrics

WebSocket connection and message metrics. WebSocket metrics and monitoring

middleware

WebSocket middleware for pre/post-processing. WebSocket middleware integration

origin

Origin validation for WebSocket handshake requests. Origin header validation for WebSocket handshake

protocol

WebSocket protocol frame handling. Protocol-level WebSocket configuration

reconnection

Automatic reconnection with exponential backoff. WebSocket automatic reconnection support

room

Room-based connection grouping for targeted broadcasts. WebSocket room management with advanced features

routing

URL-based WebSocket endpoint routing. WebSocket routing — re-exported from reinhardt-core::ws.

throttling

Connection and message rate limiting. WebSocket rate limiting and throttling

Structs

WebSocketEndpointMetadata

Inventory metadata submitted by #[websocket] at compile time.

WebSocketRoute

A registered WebSocket route (path + optional name + metadata).

WebSocketRouter

WebSocket router: build-time registration + runtime lookup.

Enums

RouteError

Routing errors for WebSocket routes

Traits

WebSocketEndpointInfo

Compile-time WebSocket endpoint metadata.

Functions

clear_websocket_router

Clears the process-wide WebSocket router (primarily for tests).

get_websocket_router

Returns a clone of the current process-wide WebSocket router, if set.

register_websocket_router

Installs router as the process-wide WebSocket router.

reverse_websocket_url

Resolves a registered or pending WebSocket URL by route name.

substitute_ws_params

Substitute path parameters in a WebSocket URL pattern.

Type Aliases

RouteResult

Routing result type