flare_core/server/handle/
default.rs

1//! ServerHandle trait 及其默认实现
2//!
3//! 提供消息发送和连接管理的轻量级接口
4
5use crate::common::error::Result;
6use crate::common::protocol::Frame;
7use crate::server::connection::ConnectionManagerTrait;
8use async_trait::async_trait;
9use std::sync::Arc;
10
11/// 服务器操作处理器
12///
13/// 提供消息发送和连接管理的轻量级接口
14/// 可以在任何需要发送消息或管理连接的地方注入此 trait，而不需要注入整个 Server
15///
16/// # 示例
17///
18/// ```rust
19/// use flare_core::server::ServerHandle;
20/// use std::sync::Arc;
21///
22/// struct MyHandler {
23///     server_handle: Arc<dyn ServerHandle>,
24/// }
25///
26/// impl MyHandler {
27///     async fn send_message(&self, connection_id: &str, frame: &Frame) -> Result<()> {
28///         self.server_handle.send_to(connection_id, frame).await
29///     }
30/// }
31/// ```
32#[async_trait]
33pub trait ServerHandle: Send + Sync {
34    /// 向指定连接发送消息
35    ///
36    /// # 参数
37    /// - `connection_id`: 目标连接 ID
38    /// - `frame`: 要发送的 Frame
39    ///
40    /// # 返回
41    /// 发送成功返回 `Ok(())`，失败返回错误
42    async fn send_to(&self, connection_id: &str, frame: &Frame) -> Result<()>;
43
44    /// 向指定用户的所有连接发送消息
45    ///
46    /// # 参数
47    /// - `user_id`: 目标用户 ID
48    /// - `frame`: 要发送的 Frame
49    ///
50    /// # 返回
51    /// 发送成功返回 `Ok(())`，失败返回错误
52    async fn send_to_user(&self, user_id: &str, frame: &Frame) -> Result<()>;
53
54    /// 广播消息到所有连接
55    ///
56    /// # 参数
57    /// - `frame`: 要广播的 Frame
58    ///
59    /// # 返回
60    /// 广播成功返回 `Ok(())`，失败返回错误
61    async fn broadcast(&self, frame: &Frame) -> Result<()>;
62
63    /// 广播消息到所有连接，排除指定的连接
64    ///
65    /// # 参数
66    /// - `frame`: 要广播的 Frame
67    /// - `exclude_connection_id`: 要排除的连接 ID
68    ///
69    /// # 返回
70    /// 广播成功返回 `Ok(())`，失败返回错误
71    async fn broadcast_except(&self, frame: &Frame, exclude_connection_id: &str) -> Result<()>;
72
73    /// 断开指定连接
74    ///
75    /// # 参数
76    /// - `connection_id`: 要断开的连接 ID
77    ///
78    /// # 返回
79    /// 断开成功返回 `Ok(())`，失败返回错误
80    async fn disconnect(&self, connection_id: &str) -> Result<()>;
81
82    /// 获取连接数量
83    ///
84    /// # 返回
85    /// 当前连接数量
86    fn connection_count(&self) -> usize;
87
88    /// 获取用户数量
89    ///
90    /// # 返回
91    /// 当前用户数量
92    fn user_count(&self) -> usize;
93}
94
95/// ServerHandle 的默认实现
96///
97/// 基于连接管理器和消息解析器实现，轻量级且易于使用
98///
99/// # 示例
100///
101/// ```rust
102/// use flare_core::server::DefaultServerHandle;
103/// use flare_core::server::connection::ConnectionManager;
104/// use std::sync::Arc;
105///
106/// let connection_manager = Arc::new(ConnectionManager::new());
107/// let handle = Arc::new(DefaultServerHandle::new(
108///     connection_manager as Arc<dyn ConnectionManagerTrait>,
109/// ));
110/// ```
111pub struct DefaultServerHandle {
112    /// 连接管理器
113    connection_manager: Arc<dyn ConnectionManagerTrait>,
114}
115
116impl DefaultServerHandle {
117    /// 创建新的 ServerHandle 实例
118    ///
119    /// # 参数
120    /// - `connection_manager`: 连接管理器 trait 对象
121    ///
122    /// # 返回
123    /// 返回新的 `DefaultServerHandle` 实例
124    pub fn new(connection_manager: Arc<dyn ConnectionManagerTrait>) -> Self {
125        Self { connection_manager }
126    }
127}
128
129#[async_trait]
130impl ServerHandle for DefaultServerHandle {
131    async fn send_to(&self, connection_id: &str, frame: &Frame) -> Result<()> {
132        // 传入 None，让 ConnectionManager 根据连接的协商信息创建 parser
133        self.connection_manager
134            .send_frame_to(connection_id, frame, None)
135            .await
136    }
137
138    async fn send_to_user(&self, user_id: &str, frame: &Frame) -> Result<()> {
139        // 传入 None，让 ConnectionManager 为每个连接使用其协商的格式
140        self.connection_manager
141            .send_frame_to_user(user_id, frame, None)
142            .await
143    }
144
145    async fn broadcast(&self, frame: &Frame) -> Result<()> {
146        // 传入 None，让 ConnectionManager 为每个连接使用其协商的格式
147        self.connection_manager.broadcast_frame(frame, None).await
148    }
149
150    async fn broadcast_except(&self, frame: &Frame, exclude_connection_id: &str) -> Result<()> {
151        // 传入 None，让 ConnectionManager 为每个连接使用其协商的格式
152        self.connection_manager
153            .broadcast_frame_except(frame, exclude_connection_id, None)
154            .await
155    }
156
157    async fn disconnect(&self, connection_id: &str) -> Result<()> {
158        self.connection_manager
159            .remove_connection(connection_id)
160            .await
161    }
162
163    fn connection_count(&self) -> usize {
164        // 同步快照：廉价原子读，禁止阻塞/网络（见 ConnectionManagerTrait::connection_count_snapshot）。
165        self.connection_manager.connection_count_snapshot()
166    }
167
168    fn user_count(&self) -> usize {
169        self.connection_manager.user_count_snapshot()
170    }
171}
flare_core/server/handle/default.rs

flare_core/server/handle/
default.rs
