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 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//! - [`codec::Codec`] / [`codec::JsonCodec`] — JSON encode/decode via serde.
14//!
15//! ## Quick start
16//!
17//! ```rust
18//! use ws_kit::{config::WsConfig, hub::BroadcastHub, room::RoomManager, codec::Codec};
19//! use serde::{Serialize, Deserialize};
20//!
21//! #[derive(Clone, Serialize, Deserialize, Debug, PartialEq)]
22//! struct ChatMsg { user: String, body: String }
23//!
24//! # tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap().block_on(async {
25//! let hub = BroadcastHub::<ChatMsg>::new(1024);
26//! let mut rx = hub.subscribe();
27//! hub.broadcast(ChatMsg { user: "alice".into(), body: "hi".into() }).unwrap();
28//! let msg = rx.recv().await.unwrap();
29//! assert_eq!(msg.user, "alice");
30//! # });
31//! ```
32//!
33//! ## Features
34//!
35//! - `std` (default): enables `std` support for `thiserror`.
36//! - `axum` (default): enables `axum` WebSocket and `tower` deps, and `TokenExtractor::extract_token(&Parts, _)`
37//! - `tracing`: enables tracing instrumentation.
38
39pub mod codec;
40pub mod config;
41mod counter;
42pub mod error;
43pub mod extractor;
44pub mod hub;
45pub mod room;
46
47// Model-checking tests for `counter` — compiled only under `--cfg loom`.
48#[cfg(loom)]
49mod loom_tests;
50
51// Re-exports for ergonomic use
52pub use codec::{Codec, JsonCodec};
53pub use config::{WsConfig, WsConfigBuilder};
54pub use error::WsError;
55pub use extractor::{TokenExtractor, TokenSourceKind, WsAuthError};
56pub use hub::BroadcastHub;
57pub use room::{Room, RoomManager};