1pub mod connection;
25pub mod message;
26pub mod session;
27
28use async_trait::async_trait;
29use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade};
30use axum::http::StatusCode;
31use axum::response::IntoResponse;
32use futures::future::BoxFuture;
33use futures::sink::SinkExt;
34use futures::stream::StreamExt;
35use std::sync::atomic::{AtomicU64, Ordering};
36use std::sync::{Arc, OnceLock};
37use tokio::sync::{mpsc, watch, Semaphore};
38use tracing::{debug, error, info, warn};
39use wordval_core::Result;
40
41pub use connection::ConnectionManager;
43#[cfg(feature = "foxglove")]
44pub use foxglove::{
45 AuthCtx, AuthHandler, AuthIdentity, AuthRejection, ClientPublishHandler, ConnCtx,
46 ConnectHandler, DisconnectHandler, FoxgloveServer, FoxgloveServerConfig,
47 FoxgloveServerError, RateLimit, ServiceCallHandler, SubscribeHandler,
48};
49pub use message::Connection;
50pub use message::WsMessage;
51#[cfg(feature = "cluster")]
52pub use cluster::ClusterConfig;
53pub use session::SessionExpiredHandler;
54pub use session::SessionInfo;
55pub use session::SessionManager;
56
57#[cfg(feature = "foxglove")]
64pub mod foxglove;
65
66#[cfg(feature = "cluster")]
69pub mod cluster;
70
71pub fn ws_conns() -> &'static Arc<ConnectionManager> {
81 connection::get()
82}
83
84pub fn try_ws_conns() -> Option<&'static Arc<ConnectionManager>> {
86 connection::try_get()
87}
88
89pub fn ws_sessions() -> &'static Arc<SessionManager> {
97 session::get()
98}
99
100pub fn try_ws_sessions() -> Option<&'static Arc<SessionManager>> {
102 session::try_get()
103}
104
105pub type MessageHandler = Arc<dyn Fn(WsMessage, u64) -> BoxFuture<'static, ()> + Send + Sync>;
112
113const WS_CHANNEL_CAPACITY: usize = 1024;
121
122const WS_MAX_IN_FLIGHT_HANDLERS: usize = 256;
128
129pub const WS_MAX_MESSAGE_SIZE: usize = 4 * 1024 * 1024;
136
137const TOUCH_DEBOUNCE: std::time::Duration = std::time::Duration::from_secs(1);
143
144pub const DEFAULT_MAINTENANCE_INTERVAL_SECS: u64 = 30;
146pub const DEFAULT_STALE_TIMEOUT_SECS: u64 = 90;
148
149pub async fn ws_upgrade(ws: WebSocketUpgrade, user_id: u64) -> impl IntoResponse {
174 if let Some(mgr) = connection::try_get() {
175 if mgr.count() as u64 >= mgr.max_connections() {
176 return (StatusCode::SERVICE_UNAVAILABLE, "too many connections").into_response();
177 }
178 }
179 ws.max_message_size(WS_MAX_MESSAGE_SIZE)
180 .max_frame_size(WS_MAX_MESSAGE_SIZE)
181 .on_upgrade(move |socket| handle_socket(socket, user_id, None))
182}
183
184pub async fn ws_upgrade_with_handler(
189 ws: WebSocketUpgrade,
190 user_id: u64,
191 handler: MessageHandler,
192) -> impl IntoResponse {
193 if let Some(mgr) = connection::try_get() {
194 if mgr.count() as u64 >= mgr.max_connections() {
195 return (StatusCode::SERVICE_UNAVAILABLE, "too many connections").into_response();
196 }
197 }
198 ws.max_message_size(WS_MAX_MESSAGE_SIZE)
199 .max_frame_size(WS_MAX_MESSAGE_SIZE)
200 .on_upgrade(move |socket| handle_socket(socket, user_id, Some(handler)))
201}
202
203async fn handle_socket(socket: WebSocket, user_id: u64, handler: Option<MessageHandler>) {
207 let conn_mgr = match connection::try_get() {
209 Some(mgr) => mgr,
210 None => {
211 error!("ConnectionManager 未初始化,无法处理 WebSocket 连接");
212 return;
213 }
214 };
215
216 let conn_id = conn_mgr.next_conn_id();
217
218 let (mut ws_sender, mut ws_receiver) = socket.split();
220
221 let (tx, rx) = mpsc::channel::<WsMessage>(WS_CHANNEL_CAPACITY);
225
226 if conn_mgr.try_add(conn_id, user_id, tx).is_none() {
228 warn!(
229 conn_id,
230 user_id,
231 "WebSocket 连接数已达上限 {},拒绝新连接",
232 conn_mgr.max_connections()
233 );
234 let _ = ws_sender.send(Message::Close(None)).await;
236 return;
237 }
238
239 if user_id != 0 {
242 if let Some(sess_mgr) = session::try_get() {
243 sess_mgr.attach_conn(user_id, conn_id);
244 }
245 #[cfg(feature = "cluster")]
247 crate::cluster::on_conn_attached(user_id).await;
248 }
249
250 info!(conn_id, user_id, "WebSocket 连接已建立");
251
252 let (write_done_tx, mut write_done_rx) = watch::channel(false);
257
258 let mut write_ws_sender = ws_sender;
260 let mut write_task = tokio::spawn(async move {
261 let mut rx = rx;
262 while let Some(msg) = rx.recv().await {
263 let ws_msg = ws_message_to_axum(msg);
264 match write_ws_sender.send(ws_msg).await {
265 Ok(()) => {}
266 Err(e) => {
267 warn!(error = %e, "WebSocket 写入失败,结束写任务");
268 break;
269 }
270 }
271 }
272 let _ = write_ws_sender.flush().await;
277 debug!(conn_id, "写任务结束");
278 let _ = write_done_tx.send(true);
279 });
280
281 let handler_slots = Arc::new(Semaphore::new(WS_MAX_IN_FLIGHT_HANDLERS));
283 let dropped_inbound = AtomicU64::new(0);
284 let mut last_touch: Option<std::time::Instant> = None;
286 loop {
287 let msg = tokio::select! {
288 _ = write_done_rx.changed() => {
289 info!(conn_id, user_id, "连接已被移除或写任务已退出,读循环终止");
290 break;
291 }
292 msg = ws_receiver.next() => msg,
293 };
294
295 if matches!(msg, Some(Ok(_))) {
299 let now = std::time::Instant::now();
300 if last_touch.map_or(true, |t| now.duration_since(t) >= TOUCH_DEBOUNCE) {
301 last_touch = Some(now);
302 conn_mgr.touch_heartbeat(conn_id);
303 if user_id != 0 {
304 if let Some(sess_mgr) = session::try_get() {
305 sess_mgr.touch(user_id);
306 }
307 }
308 }
309 }
310
311 match msg {
312 Some(Ok(Message::Text(text))) => {
313 if let Some(ref h) = handler {
314 dispatch_handler(h, WsMessage::Text(text), user_id, &handler_slots, &dropped_inbound, conn_id);
315 }
316 }
317 Some(Ok(Message::Binary(data))) => {
318 if let Some(ref h) = handler {
319 dispatch_handler(h, WsMessage::Binary(data), user_id, &handler_slots, &dropped_inbound, conn_id);
320 }
321 }
322 Some(Ok(Message::Ping(payload))) => {
323 conn_mgr.send_to_conn(conn_id, &WsMessage::Pong(payload.to_vec()));
327 }
328 Some(Ok(Message::Pong(_payload))) => {
329 debug!(conn_id, user_id, "收到 pong");
330 }
331 Some(Ok(Message::Close(_frame))) => {
332 info!(conn_id, user_id, "客户端请求关闭连接");
333 conn_mgr.send_to_conn(conn_id, &WsMessage::Close);
337 break;
338 }
339 Some(Err(e)) => {
340 warn!(conn_id, user_id, error = %e, "WebSocket 读取错误");
341 break;
342 }
343 None => {
344 info!(conn_id, user_id, "WebSocket 流已结束");
345 break;
346 }
347 }
348 }
349
350 let dropped_inbound_total = dropped_inbound.load(Ordering::Relaxed);
352 if dropped_inbound_total > 0 {
353 warn!(
354 conn_id,
355 user_id,
356 dropped_inbound_total, "连接关闭:入站处理超限累计丢弃的消息数"
357 );
358 }
359 info!(conn_id, user_id, "WebSocket 连接关闭中");
360
361 conn_mgr.remove(conn_id);
363
364 if user_id != 0 {
368 if let Some(sess_mgr) = session::try_get() {
369 let fully_disconnected = sess_mgr.detach_conn(user_id);
370 if fully_disconnected {
371 debug!(user_id, "用户全部连接已断开,会话进入宽限期");
372 #[cfg(feature = "cluster")]
374 crate::cluster::on_conn_detached(user_id).await;
375 }
376 }
377 }
378
379 if tokio::time::timeout(std::time::Duration::from_secs(2), &mut write_task)
382 .await
383 .is_err()
384 {
385 write_task.abort();
386 }
387}
388
389fn dispatch_handler(
394 handler: &MessageHandler,
395 msg: WsMessage,
396 user_id: u64,
397 slots: &Arc<Semaphore>,
398 dropped: &AtomicU64,
399 conn_id: u64,
400) {
401 match slots.clone().try_acquire_owned() {
402 Ok(permit) => {
403 let h = Arc::clone(handler);
404 tokio::spawn(async move {
405 h(msg, user_id).await;
406 drop(permit);
407 });
408 }
409 Err(_) => {
410 let n = dropped.fetch_add(1, Ordering::Relaxed) + 1;
411 if n == 1 || n % 1024 == 0 {
413 warn!(conn_id, user_id, dropped = n, "入站处理任务已达上限,丢弃消息");
414 }
415 }
416 }
417}
418
419fn ws_message_to_axum(msg: WsMessage) -> Message {
423 match msg {
424 WsMessage::Text(s) => Message::Text(s),
425 WsMessage::Binary(data) => Message::Binary(data),
426 WsMessage::Close => Message::Close(None),
427 WsMessage::Ping(payload) => Message::Ping(payload.into()),
428 WsMessage::Pong(payload) => Message::Pong(payload.into()),
429 }
430}
431
432pub struct WsPlugin {
441 max_connections: u64,
443 maintenance_interval_secs: u64,
445 stale_timeout_secs: u64,
447 #[cfg(feature = "cluster")]
449 cluster: Option<cluster::ClusterConfig>,
450}
451
452impl WsPlugin {
453 pub fn new() -> Self {
454 Self {
455 max_connections: connection::DEFAULT_MAX_WS_CONNECTIONS,
456 maintenance_interval_secs: DEFAULT_MAINTENANCE_INTERVAL_SECS,
457 stale_timeout_secs: DEFAULT_STALE_TIMEOUT_SECS,
458 #[cfg(feature = "cluster")]
459 cluster: None,
460 }
461 }
462
463 pub fn with_max_connections(mut self, n: u64) -> Self {
465 self.max_connections = n.max(1);
466 self
467 }
468
469 pub fn with_maintenance_interval(mut self, secs: u64) -> Self {
476 self.maintenance_interval_secs = secs.max(1);
477 self
478 }
479
480 pub fn with_stale_timeout(mut self, secs: u64) -> Self {
483 self.stale_timeout_secs = secs.max(1);
484 self
485 }
486
487 #[cfg(feature = "cluster")]
491 pub fn with_cluster(mut self, config: cluster::ClusterConfig) -> Self {
492 self.cluster = Some(config);
493 self
494 }
495}
496
497impl Default for WsPlugin {
498 fn default() -> Self {
499 Self::new()
500 }
501}
502
503pub fn init_ws_infrastructure() {
513 static STARTED: OnceLock<()> = OnceLock::new();
514 let first = STARTED.set(()).is_ok();
515 if first {
516 connection::init();
517 session::init();
518 if tokio::runtime::Handle::try_current().is_err() {
519 warn!(
520 "init_ws_infrastructure 在无 tokio runtime 的上下文调用:\
521 后台维护任务将在下一次(runtime 内)调用时补启动"
522 );
523 }
524 }
525 if tokio::runtime::Handle::try_current().is_ok() {
529 spawn_maintenance_task(
530 DEFAULT_MAINTENANCE_INTERVAL_SECS,
531 DEFAULT_STALE_TIMEOUT_SECS,
532 );
533 }
534}
535
536#[async_trait]
537impl wordval_core::Plugin for WsPlugin {
538 fn name(&self) -> &str {
539 "ws"
540 }
541
542 async fn start(&self) -> Result<()> {
543 info!("WsPlugin 启动中...");
544 spawn_maintenance_task(self.maintenance_interval_secs, self.stale_timeout_secs);
547 init_ws_infrastructure();
548 if let Some(mgr) = connection::try_get() {
549 mgr.set_max_connections(self.max_connections);
550 }
551 #[cfg(feature = "cluster")]
553 if let Some(cfg) = &self.cluster {
554 cluster::enable(cfg.clone())?;
555 }
556 info!("WsPlugin 已启动 (连接管理器 + 会话管理器)");
557 Ok(())
558 }
559
560 async fn stop(&self) -> Result<()> {
561 info!("WsPlugin 停止中...");
562
563 if let Some(mgr) = connection::try_get() {
565 mgr.close_all();
566 }
567
568 if let Some(mgr) = session::try_get() {
570 mgr.clear_all();
571 }
572
573 info!("WsPlugin 已停止");
574 Ok(())
575 }
576}
577
578pub fn spawn_maintenance_task(interval_secs: u64, stale_timeout_secs: u64) {
589 static STARTED: OnceLock<()> = OnceLock::new();
591 if STARTED.set(()).is_err() {
592 return;
593 }
594
595 let interval = std::time::Duration::from_secs(interval_secs);
596 let timeout = std::time::Duration::from_secs(stale_timeout_secs);
597
598 tokio::spawn(async move {
599 loop {
600 tokio::time::sleep(interval).await;
601
602 let tick = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
605 if let Some(conn_mgr) = connection::try_get() {
608 conn_mgr.send_heartbeat_pings();
609 }
610
611 if let Some(conn_mgr) = connection::try_get() {
612 let purged = conn_mgr.purge_stale(timeout);
613 if purged > 0 {
614 info!(purged, "后台清理了 {} 个过期连接", purged);
615 }
616 }
617
618 if let Some(sess_mgr) = session::try_get() {
619 let cleaned = sess_mgr.cleanup_expired();
620 if cleaned > 0 {
621 info!(cleaned, "后台清理了 {} 个过期会话", cleaned);
622 }
623 }
624 }));
625 if tick.is_err() {
626 error!("ws 维护任务本拍 panic(已隔离,循环继续)");
627 }
628
629 #[cfg(feature = "cluster")]
633 match tokio::spawn(crate::cluster::refresh_presence()).await {
634 Ok(()) => {}
635 Err(e) if e.is_panic() => {
636 error!("ws 集群 presence 续期 panic(已隔离,循环继续)");
637 }
638 Err(e) => {
639 error!(error = %e, "ws 集群 presence 续期任务异常取消");
640 }
641 }
642 }
643 });
644}
645
646#[cfg(test)]
647mod tests {
648 use super::*;
649
650 #[test]
651 fn test_ws_message_conversion_text() {
652 let ws_msg = WsMessage::text("hello");
653 let axum_msg = ws_message_to_axum(ws_msg);
654 assert!(matches!(axum_msg, Message::Text(ref s) if *s == "hello"));
655 }
656
657 #[test]
658 fn test_ws_message_conversion_binary() {
659 let ws_msg = WsMessage::binary(vec![1, 2, 3]);
660 let axum_msg = ws_message_to_axum(ws_msg);
661 assert!(matches!(axum_msg, Message::Binary(ref b) if **b == [1, 2, 3]));
662 }
663
664 #[test]
665 fn test_ws_message_conversion_close() {
666 let ws_msg = WsMessage::Close;
667 let axum_msg = ws_message_to_axum(ws_msg);
668 assert!(matches!(axum_msg, Message::Close(None)));
669 }
670
671 #[test]
672 fn test_ws_message_conversion_ping_pong() {
673 let ws_msg = WsMessage::Ping(vec![4, 5, 6]);
674 let axum_msg = ws_message_to_axum(ws_msg);
675 assert!(matches!(axum_msg, Message::Ping(ref b) if **b == [4, 5, 6]));
676
677 let ws_msg = WsMessage::Pong(vec![7, 8, 9]);
678 let axum_msg = ws_message_to_axum(ws_msg);
679 assert!(matches!(axum_msg, Message::Pong(ref b) if **b == [7, 8, 9]));
680 }
681
682 #[test]
683 fn test_ws_message_json_constructor() {
684 let data = serde_json::json!({"type": "chat", "content": "hi"});
685 let msg = WsMessage::json(&data).unwrap();
686 assert!(matches!(msg, WsMessage::Text(ref s) if s.contains("chat")));
687 }
688
689 #[test]
690 fn test_ws_message_from_string() {
691 let msg: WsMessage = "hello".into();
692 assert!(matches!(msg, WsMessage::Text(ref s) if s.as_str() == "hello"));
693
694 let msg: WsMessage = String::from("world").into();
695 assert!(matches!(msg, WsMessage::Text(ref s) if s.as_str() == "world"));
696 }
697
698 #[test]
699 fn test_ws_message_clone_shares_payload() {
700 let msg = WsMessage::text("shared payload");
702 let cloned = msg.clone();
703 match (&msg, &cloned) {
704 (WsMessage::Text(a), WsMessage::Text(b)) => {
705 assert_eq!(a.as_ptr(), b.as_ptr());
707 }
708 _ => panic!("expected text messages"),
709 }
710 }
711}