flare_core/server/events/
handler.rs

1//! 服务端事件处理器 Trait
2//!
3//! 提供细化的命令处理方法，支持按命令类型处理
4
5use crate::common::error::Result;
6use crate::common::protocol::{
7    Frame, NotificationCommand, PayloadCommand, flare::core::commands::CustomCommand,
8};
9use async_trait::async_trait;
10
11/// 服务端事件处理器
12///
13/// 提供细化的命令处理方法，每个命令类型对应一个方法
14/// 用户可以实现这个 trait 来自定义业务逻辑
15#[async_trait]
16pub trait ServerEventHandler: Send + Sync {
17    /// 处理 CONNECT 系统命令（协商）
18    ///
19    /// 默认实现返回 None，表示使用默认处理
20    async fn handle_connect(&self, frame: &Frame, connection_id: &str) -> Result<Option<Frame>> {
21        let _ = (frame, connection_id);
22        Ok(None)
23    }
24
25    /// 处理 PING 系统命令
26    ///
27    /// 默认实现返回 None，表示使用默认处理（自动回复 PONG）
28    async fn handle_ping(&self, frame: &Frame, connection_id: &str) -> Result<Option<Frame>> {
29        let _ = (frame, connection_id);
30        Ok(None)
31    }
32
33    /// 处理 PONG 系统命令
34    ///
35    /// 默认实现返回 None，表示使用默认处理（更新连接活跃时间）
36    async fn handle_pong(&self, frame: &Frame, connection_id: &str) -> Result<Option<Frame>> {
37        let _ = (frame, connection_id);
38        Ok(None)
39    }
40
41    /// 处理 MESSAGE 载荷命令（业务消息，需 ACK）
42    async fn handle_message(
43        &self,
44        command: &PayloadCommand,
45        connection_id: &str,
46    ) -> Result<Option<Frame>> {
47        let _ = (command, connection_id);
48        Ok(None)
49    }
50
51    /// 处理 EVENT 载荷命令（事件）
52    async fn handle_event(
53        &self,
54        command: &PayloadCommand,
55        connection_id: &str,
56    ) -> Result<Option<Frame>> {
57        let _ = (command, connection_id);
58        Ok(None)
59    }
60
61    /// 处理 ACK 载荷命令（确认）
62    async fn handle_ack(
63        &self,
64        command: &PayloadCommand,
65        connection_id: &str,
66    ) -> Result<Option<Frame>> {
67        let _ = (command, connection_id);
68        Ok(None)
69    }
70
71    /// 处理 DATA 载荷命令（普通数据传输）
72    async fn handle_data(
73        &self,
74        command: &PayloadCommand,
75        connection_id: &str,
76    ) -> Result<Option<Frame>> {
77        let _ = (command, connection_id);
78        Ok(None)
79    }
80
81    /// 处理通知命令
82    ///
83    /// # 参数
84    /// - `command`: 通知命令
85    /// - `connection_id`: 连接 ID
86    ///
87    /// # 返回
88    /// 可选回复 Frame
89    async fn handle_notification_command(
90        &self,
91        command: &NotificationCommand,
92        connection_id: &str,
93    ) -> Result<Option<Frame>> {
94        let _ = (command, connection_id);
95        Ok(None)
96    }
97
98    /// 处理连接断开事件
99    ///
100    /// # 参数
101    /// - `connection_id`: 连接 ID
102    /// - `reason`: 断开原因（如果有）
103    async fn on_disconnect(&self, connection_id: &str, reason: Option<&str>) -> Result<()> {
104        let _ = (connection_id, reason);
105        Ok(())
106    }
107
108    /// 处理连接错误事件
109    ///
110    /// # 参数
111    /// - `connection_id`: 连接 ID
112    /// - `error`: 错误信息
113    async fn on_error(&self, connection_id: &str, error: &str) -> Result<()> {
114        let _ = (connection_id, error);
115        Ok(())
116    }
117
118    /// 处理自定义命令
119    ///
120    /// # 参数
121    /// - `command`: 自定义命令
122    /// - `connection_id`: 连接 ID
123    ///
124    /// # 返回
125    /// 可选回复 Frame
126    ///
127    /// # 说明
128    /// 默认实现返回 None，表示不处理自定义命令
129    /// 如果需要处理自定义命令，可以重写此方法
130    async fn handle_custom_command(
131        &self,
132        command: &CustomCommand,
133        connection_id: &str,
134    ) -> Result<Option<Frame>> {
135        let _ = (command, connection_id);
136        Ok(None)
137    }
138
139    /// 处理连接建立完成事件（在 CONNECT 协商完成后调用）
140    ///
141    /// # 参数
142    /// - `connection_id`: 连接 ID
143    ///
144    /// # 说明
145    /// 此方法在 CONNECT 协商完成后调用，用于处理连接建立后的业务逻辑
146    /// 默认实现为空，如果需要处理连接建立逻辑，可以重写此方法
147    async fn on_connect(&self, connection_id: &str) -> Result<()> {
148        let _ = connection_id;
149        Ok(())
150    }
151
152    /// 处理系统事件（System::Event）
153    ///
154    /// # 参数
155    /// - `frame`: 包含系统事件的 Frame
156    /// - `connection_id`: 连接 ID
157    ///
158    /// # 返回
159    /// 可选回复 Frame
160    ///
161    /// # 说明
162    /// 默认实现返回 None，表示不处理系统事件
163    /// 如果需要处理系统事件，可以重写此方法
164    async fn handle_system_event(
165        &self,
166        frame: &Frame,
167        connection_id: &str,
168    ) -> Result<Option<Frame>> {
169        let _ = (frame, connection_id);
170        Ok(None)
171    }
172}
flare_core/server/events/handler.rs

flare_core/server/events/
handler.rs
