ws_kit/lib.rs
1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3
4//! # ws-kit
5//!
6//! Generic authenticated typed WebSocket toolkit.
7//!
8//! Provides:
9//! - [`config::WsConfig`] — heartbeat, broadcast capacity, connection limits, Origin allow-list with builder.
10//! - [`hub::BroadcastHub`] — typed `broadcast::Sender<T>` wrapper with connection counting, generic over `T: Clone + Serialize`.
11//! - [`room::RoomManager`] / [`room::Room`] — DashMap-backed room isolation with participant tracking.
12//! - [`extractor::TokenExtractor`] — configurable token extraction (`Authorization: Bearer`, `?token=`, `?access_token=`, `Cookie`).
13//! - [`origin_allowed_in_parts`] — Origin validation for the upgrade handshake (CSWSH defense, REQ-WSKIT-200).
14//! - [`codec::Codec`] / [`codec::JsonCodec`] — JSON encode/decode via serde.
15//!
16//! ## Quick start
17//!
18//! ```rust
19//! use ws_kit::{config::WsConfig, hub::BroadcastHub, room::RoomManager, codec::Codec};
20//! use serde::{Serialize, Deserialize};
21//!
22//! #[derive(Clone, Serialize, Deserialize, Debug, PartialEq)]
23//! struct ChatMsg { user: String, body: String }
24//!
25//! # tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap().block_on(async {
26//! let hub = BroadcastHub::<ChatMsg>::new(1024);
27//! let mut rx = hub.subscribe();
28//! hub.broadcast(ChatMsg { user: "alice".into(), body: "hi".into() }).unwrap();
29//! let msg = rx.recv().await.unwrap();
30//! assert_eq!(msg.user, "alice");
31//! # });
32//! ```
33//!
34//! ## Features
35//!
36//! - `std` (default): enables `std` support for `thiserror`.
37//! - `axum` (default): enables `axum` WebSocket and `tower` deps, and `TokenExtractor::extract_token(&Parts, _)`
38//! - `tracing`: enables tracing instrumentation.
39
40pub mod codec;
41pub mod config;
42mod counter;
43pub mod error;
44pub mod extractor;
45pub mod hub;
46pub mod origin;
47pub mod room;
48
49// Model-checking tests for `counter` — compiled only under `--cfg loom`.
50#[cfg(loom)]
51mod loom_tests;
52
53// Re-exports for ergonomic use
54pub use codec::{Codec, JsonCodec};
55pub use config::{WsConfig, WsConfigBuilder};
56pub use error::WsError;
57pub use extractor::{TokenExtractor, TokenSourceKind, WsAuthError};
58pub use hub::BroadcastHub;
59pub use origin::{normalize_origin, origin_allowed};
60pub use room::{Room, RoomManager};
61
62#[cfg(feature = "axum")]
63pub use origin::origin_allowed_in_parts;