flare_core/common/
message_observer.rs

1//! 标准消息观察者接口
2//!
3//! 定义统一的消息观察者标准，支持服务端和客户端实现
4
5use crate::common::error::Result;
6use crate::common::protocol::Frame;
7use crate::transport::events::ConnectionEvent;
8use async_trait::async_trait;
9use std::sync::Arc;
10
11/// 消息观察者标准接口
12///
13/// 这是消息处理的核心接口，定义了如何处理不同类型的消息和事件。
14/// 服务端和客户端都可以实现这个接口来自定义消息处理逻辑。
15///
16/// # 设计原则
17/// 1. **分层处理**: 先处理系统命令，再处理业务命令
18/// 2. **可扩展性**: 支持自定义命令类型处理
19/// 3. **响应式**: 可以返回响应 Frame 用于请求-响应模式
20#[async_trait]
21pub trait MessageObserver: Send + Sync {
22    /// 处理收到的消息 Frame
23    ///
24    /// # 参数
25    /// - `frame`: 收到的消息 Frame
26    /// - `connection_id`: 连接 ID（服务端）或 None（客户端）
27    ///
28    /// # 返回
29    /// - `Ok(Some(Frame))`: 需要发送的响应 Frame（用于请求-响应模式）
30    /// - `Ok(None)`: 不需要响应
31    /// - `Err`: 处理失败
32    ///
33    /// # 说明
34    /// 这个方法会处理所有类型的命令（System、Message、Notification、Custom）
35    /// 默认实现会根据命令类型分发到对应的处理方法
36    async fn handle_frame(
37        &self,
38        frame: &Frame,
39        connection_id: Option<&str>,
40    ) -> Result<Option<Frame>> {
41        if let Some(cmd) = &frame.command {
42            match &cmd.r#type {
43                Some(crate::common::protocol::flare::core::commands::command::Type::System(
44                    sys_cmd,
45                )) => {
46                    self.handle_system_command(sys_cmd, frame, connection_id)
47                        .await
48                }
49                Some(crate::common::protocol::flare::core::commands::command::Type::Payload(
50                    msg_cmd,
51                )) => {
52                    self.handle_message_command(msg_cmd, frame, connection_id)
53                        .await
54                }
55                Some(
56                    crate::common::protocol::flare::core::commands::command::Type::Notification(
57                        notif_cmd,
58                    ),
59                ) => {
60                    self.handle_notification_command(notif_cmd, frame, connection_id)
61                        .await
62                }
63                Some(crate::common::protocol::flare::core::commands::command::Type::Custom(
64                    custom_cmd,
65                )) => {
66                    self.handle_custom_command(custom_cmd, frame, connection_id)
67                        .await
68                }
69                None => Ok(None),
70            }
71        } else {
72            Ok(None)
73        }
74    }
75
76    /// 处理系统命令
77    ///
78    /// 默认实现返回 None，子类可以重写此方法
79    async fn handle_system_command(
80        &self,
81        _sys_cmd: &crate::common::protocol::flare::core::commands::SystemCommand,
82        _frame: &Frame,
83        _connection_id: Option<&str>,
84    ) -> Result<Option<Frame>> {
85        Ok(None)
86    }
87
88    /// 处理消息命令
89    ///
90    /// 默认实现返回 None，子类可以重写此方法
91    async fn handle_message_command(
92        &self,
93        _msg_cmd: &crate::common::protocol::PayloadCommand,
94        _frame: &Frame,
95        _connection_id: Option<&str>,
96    ) -> Result<Option<Frame>> {
97        Ok(None)
98    }
99
100    /// 处理通知命令
101    ///
102    /// 默认实现返回 None，子类可以重写此方法
103    async fn handle_notification_command(
104        &self,
105        _notif_cmd: &crate::common::protocol::NotificationCommand,
106        _frame: &Frame,
107        _connection_id: Option<&str>,
108    ) -> Result<Option<Frame>> {
109        Ok(None)
110    }
111
112    /// 处理自定义命令（如 SyncMessages、ListSessions 等）
113    ///
114    /// 默认实现返回 None，子类可以重写此方法
115    async fn handle_custom_command(
116        &self,
117        _custom_cmd: &crate::common::protocol::CustomCommand,
118        _frame: &Frame,
119        _connection_id: Option<&str>,
120    ) -> Result<Option<Frame>> {
121        Ok(None)
122    }
123
124    /// 处理连接事件
125    ///
126    /// 当连接状态发生变化时调用
127    async fn handle_connection_event(
128        &self,
129        _event: &ConnectionEvent,
130        _connection_id: Option<&str>,
131    ) -> Result<()> {
132        Ok(())
133    }
134}
135
136/// 线程安全的消息观察者引用
137pub type ArcMessageObserver = Arc<dyn MessageObserver>;
flare_core/common/message_observer.rs

flare_core/common/
message_observer.rs
