mqttxx 2.0.2__py3-none-any.whl → 3.1.2__py3-none-any.whl

mqttxx/events.py

@@ -0,0 +1,340 @@
+# Event Channel 层 - 高吞吐、低耦合的事件广播通道
+
+import asyncio
+import time
+from typing import Callable, Any, Optional, Type
+from dataclasses import dataclass
+from loguru import logger
+
+from .client import MQTTClient
+from .protocol import Codec, JSONCodec
+
+
+@dataclass
+class EventMessage:
+    """事件消息（可选的结构化格式）
+
+    这是一个**可选**的辅助工具类，用户可以选择：
+    1. 使用 EventMessage 发布（带时间戳、事件类型）
+    2. 直接发布原始字典（零开销）
+
+    订阅者会根据消息是否包含 "type": "event" 自动区分
+
+    Attributes:
+        type: 消息类型标识（固定为 "event"）
+        event_type: 事件类型（如 "sensor.temperature", "user.login"）
+        data: 事件数据（任意 JSON 可序列化对象）
+        timestamp: Unix 时间戳（秒，自动填充）
+        source: 事件源（可选，发布者标识）
+
+    示例:
+        # 创建事件消息
+        msg = EventMessage(
+            event_type="temperature.changed",
+            data={"value": 25.5, "unit": "C"},
+            source="sensor_001"
+        )
+
+        # 序列化
+        data = msg.to_dict()
+        # {
+        #     "type": "event",
+        #     "event_type": "temperature.changed",
+        #     "data": {"value": 25.5, "unit": "C"},
+        #     "timestamp": 1673456789.123,
+        #     "source": "sensor_001"
+        # }
+    """
+
+    # 固定字段（用于区分事件消息和 RPC 消息）
+    type: str = "event"
+
+    # 事件核心字段
+    event_type: str = ""  # 事件类型
+    data: Any = None  # 事件数据
+
+    # 元数据（自动填充）
+    timestamp: float = 0.0  # Unix 时间戳（秒）
+    source: str = ""  # 事件源
+
+    def __post_init__(self):
+        """自动填充时间戳"""
+        if self.timestamp == 0.0:
+            self.timestamp = time.time()
+
+    def to_dict(self) -> dict:
+        """序列化为字典
+
+        Returns:
+            包含所有字段的字典
+        """
+        return {
+            "type": self.type,
+            "event_type": self.event_type,
+            "data": self.data,
+            "timestamp": self.timestamp,
+            "source": self.source,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "EventMessage":
+        """从字典反序列化
+
+        Args:
+            data: 包含事件字段的字典
+
+        Returns:
+            EventMessage 实例
+        """
+        return cls(
+            event_type=data.get("event_type", ""),
+            data=data.get("data"),
+            timestamp=data.get("timestamp", 0.0),
+            source=data.get("source", ""),
+        )
+
+    def encode(self, codec: Type[Codec] = JSONCodec) -> bytes:
+        """编码为 bytes
+
+        Args:
+            codec: 编解码器（默认 JSONCodec）
+
+        Returns:
+            编码后的 bytes
+        """
+        return codec.encode(self)
+
+    @classmethod
+    def decode(cls, data: bytes, codec: Type[Codec] = JSONCodec) -> "EventMessage":
+        """从 bytes 解码
+
+        Args:
+            data: 原始 bytes 数据
+            codec: 编解码器（默认 JSONCodec）
+
+        Returns:
+            EventMessage 对象
+        """
+        obj = codec.decode(data)
+        return cls.from_dict(obj)
+
+
+# 事件处理器类型定义
+# 参数：(topic: str, message: dict)
+EventHandler = Callable[[str, dict], Any]
+
+
+class EventChannelManager:
+    """Event Channel 管理器 - 极薄的发布订阅层
+
+    核心特性：
+    1. 发布：零包装，直接转发到 MQTT（可选 EventMessage 格式化）
+    2. 订阅：支持通配符，自动区分结构化/原始消息
+    3. 过滤：基于 topic 模式匹配（MQTT 原生支持）
+    4. 无返回值：明确告诉使用者"这不是 RPC"
+
+    与 RPC 的共存：
+    - RPC 消息：type = "rpc_request" | "rpc_response"
+    - Event 消息：type = "event" | 原始字典（无 type 字段）
+    - 通过 type 字段自动分流（在 MQTTClient._handle_message 中）
+
+    使用示例:
+        # 创建管理器
+        events = EventChannelManager(client)
+
+        # 订阅事件（支持通配符）
+        @events.subscribe("sensors/+/temperature")
+        async def on_temperature(topic, message):
+            print(f"温度更新: {topic} -> {message}")
+
+        # 发布结构化事件
+        await events.publish(
+            "sensors/room1/temperature",
+            EventMessage(
+                event_type="temperature.changed",
+                data={"value": 25.5, "unit": "C"}
+            )
+        )
+
+        # 发布原始事件（零开销）
+        await events.publish(
+            "sensors/room1/humidity",
+            {"value": 60.2, "unit": "%"}
+        )
+    """
+
+    def __init__(self, client: MQTTClient):
+        """初始化 Event Channel 管理器
+
+        Args:
+            client: MQTTClient 实例（必须已连接或准备连接）
+        """
+        self._client = client
+        self._patterns: dict[str, list[EventHandler]] = {}  # pattern → handlers
+        self._dispatchers: dict[str, Callable] = {}  # 保存 dispatcher 引用（修复 P0-B）
+
+        logger.info("EventChannelManager 已初始化")
+
+    def subscribe(self, pattern: str, handler: Optional[EventHandler] = None):
+        """订阅事件主题（支持通配符）
+
+        核心设计：
+        1. 支持 MQTT 通配符（+ 和 #）
+        2. 一个 pattern 可以有多个处理器（广播模式）
+        3. 自动在 MQTTClient 层注册订阅
+
+        Args:
+            pattern: MQTT 主题模式（支持通配符）
+                - "+": 单级通配符（sensors/+/temperature）
+                - "#": 多级通配符（sensors/#）
+            handler: 事件处理器（可选，也可以用作装饰器）
+
+        返回：
+            装饰器函数（如果 handler 为 None）
+
+        使用示例:
+            # 方式 1: 装饰器
+            @events.subscribe("sensors/+/temperature")
+            async def on_temp(topic, message):
+                pass
+
+            # 方式 2: 直接注册
+            events.subscribe("sensors/+/temperature", on_temp)
+        """
+
+        def decorator(func: EventHandler):
+            # 添加到处理器列表
+            if pattern not in self._patterns:
+                self._patterns[pattern] = []
+
+                # 第一次订阅这个 pattern，创建专属 dispatcher（修复 P0-B：避免闭包泄漏）
+                async def dispatcher(topic: str, payload: bytes):
+                    """专属 dispatcher（bytes → dict → handler）"""
+                    try:
+                        # 解码（使用 JSONCodec）
+                        data = JSONCodec.decode(payload)
+
+                        # 分发到所有 handlers（使用 get 避免 KeyError）
+                        for h in self._patterns.get(pattern, []):
+                            try:
+                                if asyncio.iscoroutinefunction(h):
+                                    await h(topic, data)
+                                else:
+                                    h(topic, data)
+                            except Exception as e:
+                                logger.exception(
+                                    f"Event handler 异常 - pattern: {pattern}, error: {e}"
+                                )
+                    except Exception as e:
+                        logger.error(f"事件消息解码失败 - topic: {topic}, error: {e}")
+
+                # 保存 dispatcher 引用（修复 P0-B）
+                self._dispatchers[pattern] = dispatcher
+
+                # 注册到 MQTTClient 的 raw 层
+                self._client.raw.subscribe(pattern, dispatcher)
+
+            self._patterns[pattern].append(func)
+            logger.debug(
+                f"事件订阅成功 - pattern: {pattern}, handlers: {len(self._patterns[pattern])}"
+            )
+            return func
+
+        if handler is None:
+            return decorator
+        else:
+            return decorator(handler)
+
+    def unsubscribe(self, pattern: str, handler: Optional[EventHandler] = None):
+        """取消订阅（修复 P0-B：真正清理底层订阅）
+
+        Args:
+            pattern: MQTT 主题模式
+            handler: 要移除的处理器（None = 移除所有）
+
+        改进：
+            现在会真正调用 RawAPI.unsubscribe 来清理底层 MQTT 订阅
+            避免内存泄漏
+        """
+        if pattern not in self._patterns:
+            return
+
+        if handler is None:
+            # 移除所有处理器
+            del self._patterns[pattern]
+
+            # 清理 dispatcher（修复 P0-B）
+            dispatcher = self._dispatchers.pop(pattern, None)
+            if dispatcher:
+                self._client.raw.unsubscribe(pattern, dispatcher)
+
+            logger.info(f"已取消订阅 - pattern: {pattern}")
+        else:
+            # 移除指定处理器
+            if handler in self._patterns[pattern]:
+                self._patterns[pattern].remove(handler)
+
+                # 如果没有处理器了，清理 dispatcher（修复 P0-B）
+                if not self._patterns[pattern]:
+                    del self._patterns[pattern]
+
+                    dispatcher = self._dispatchers.pop(pattern, None)
+                    if dispatcher:
+                        self._client.raw.unsubscribe(pattern, dispatcher)
+
+                    logger.info(f"已取消订阅（最后一个 handler）- pattern: {pattern}")
+                else:
+                    logger.debug(f"已移除处理器 - pattern: {pattern}, 剩余 {len(self._patterns[pattern])} 个")
+
+    async def publish(
+        self,
+        topic: str,
+        message: EventMessage | dict | Any,
+        qos: int = 0,
+    ):
+        """发布事件（极薄包装）
+
+        设计原则：
+        - 不创建 Future（无返回值）
+        - 不等待确认（fire-and-forget）
+        - 直接调用 client.publish()
+
+        Args:
+            topic: 目标主题
+            message: 事件消息
+                - EventMessage: 自动序列化为 JSON
+                - dict: 直接序列化为 JSON
+                - 其他类型: 包装为 {"data": message}
+            qos: QoS 等级（0 = 最多一次，1 = 至少一次，2 = 恰好一次）
+
+        使用示例:
+            # 结构化事件
+            await events.publish(
+                "sensors/room1/temperature",
+                EventMessage(event_type="temp.changed", data={"value": 25.5})
+            )
+
+            # 原始字典
+            await events.publish(
+                "sensors/room1/humidity",
+                {"value": 60.2, "unit": "%"}
+            )
+
+            # 简单值（自动包装）
+            await events.publish(
+                "alerts/fire",
+                "Fire detected in room 3!"
+            )
+        """
+        # 编码消息
+        if isinstance(message, EventMessage):
+            payload = message.encode(JSONCodec)
+        elif isinstance(message, dict):
+            payload = JSONCodec.encode(message)
+        else:
+            # 其他类型自动包装
+            payload = JSONCodec.encode({"data": message})
+
+        # 直接发布（零开销）
+        await self._client.raw.publish(topic, payload, qos=qos)
+        logger.debug(f"事件已发布 - topic: {topic}, qos: {qos}")

mqttxx/protocol.py

@@ -1,11 +1,109 @@
 # MQTT RPC 消息协议定义
 
+import json
 from dataclasses import dataclass
-from typing import Any, Optional, Literal
+from typing import Any, Optional, Literal, Protocol as TypingProtocol, Type, runtime_checkable
 
 from .exceptions import MessageError, ErrorCode
 
 
+# ============================================================================
+# 编解码器接口（可插拔协议支持）
+# ============================================================================
+
+@runtime_checkable
+class Codec(TypingProtocol):
+    """编解码器接口（协议无关）
+
+    实现此接口可支持不同的序列化协议（JSON、MessagePack、Protobuf 等）
+    """
+
+    @staticmethod
+    def encode(obj: Any) -> bytes:
+        """对象 → bytes
+
+        Args:
+            obj: 要编码的对象（RPCRequest/RPCResponse/EventMessage/dict）
+
+        Returns:
+            编码后的 bytes
+
+        Raises:
+            ValueError: 无法编码的类型
+        """
+        ...
+
+    @staticmethod
+    def decode(data: bytes) -> dict:
+        """bytes → dict
+
+        Args:
+            data: 原始 bytes 数据
+
+        Returns:
+            解码后的 dict
+
+        Raises:
+            UnicodeDecodeError: UTF-8 解码失败
+            JSONDecodeError: JSON 解析失败（或其他格式解析失败）
+        """
+        ...
+
+
+class JSONCodec:
+    """JSON 编解码器（默认实现）
+
+    使用标准 JSON 格式进行序列化/反序列化
+    支持 Pydantic BaseModel 自动序列化
+    """
+
+    @staticmethod
+    def encode(obj: Any) -> bytes:
+        """对象 → bytes
+
+        支持：
+        - 有 to_dict() 方法的对象（RPCRequest/RPCResponse/EventMessage）
+        - Pydantic BaseModel（自动调用 model_dump()）
+        - dict 对象
+
+        Args:
+            obj: 要编码的对象
+
+        Returns:
+            UTF-8 编码的 JSON bytes
+
+        Raises:
+            ValueError: 无法编码的类型
+        """
+        if hasattr(obj, 'to_dict'):
+            data = obj.to_dict()
+        elif hasattr(obj, 'model_dump'):
+            data = obj.model_dump()
+        elif isinstance(obj, dict):
+            data = obj
+        else:
+            raise ValueError(f"无法编码类型: {type(obj)}")
+
+        return json.dumps(data).encode('utf-8')
+
+    @staticmethod
+    def decode(data: bytes) -> dict:
+        """bytes → dict
+
+        Args:
+            data: UTF-8 编码的 JSON bytes
+
+        Returns:
+            解码后的 dict
+
+        Raises:
+            UnicodeDecodeError: UTF-8 解码失败
+            json.JSONDecodeError: JSON 解析失败
+        """
+        text = data.decode('utf-8')
+        return json.loads(text)
+
+
 @dataclass
 class RPCRequest:
     """RPC 请求消息
@@ -48,11 +146,16 @@ class RPCRequest:
         Returns:
             包含所有字段的字典
         """
+        # 处理 Pydantic 模型
+        params = self.params
+        if hasattr(params, 'model_dump'):
+            params = params.model_dump()
+
         return {
             "type": self.type,
             "request_id": self.request_id,
             "method": self.method,
-            "params": self.params,
+            "params": params,
             "reply_to": self.reply_to,
             "caller_id": self.caller_id,
         }
@@ -84,6 +187,44 @@ class RPCRequest:
                 ErrorCode.MISSING_REQUIRED_FIELD
             )
 
+    def encode(self, codec: Type[Codec] = JSONCodec) -> bytes:
+        """编码为 bytes
+
+        Args:
+            codec: 编解码器（默认 JSONCodec）
+
+        Returns:
+            编码后的 bytes
+
+        示例:
+            request = RPCRequest(request_id="123", method="test")
+            payload = request.encode()  # 使用默认 JSONCodec
+            # 或自定义 codec
+            payload = request.encode(MessagePackCodec)
+        """
+        return codec.encode(self)
+
+    @classmethod
+    def decode(cls, data: bytes, codec: Type[Codec] = JSONCodec) -> "RPCRequest":
+        """从 bytes 解码
+
+        Args:
+            data: 原始 bytes 数据
+            codec: 编解码器（默认 JSONCodec）
+
+        Returns:
+            RPCRequest 对象
+
+        Raises:
+            MessageError: 解码失败或缺少必需字段
+
+        示例:
+            payload = b'{"type":"rpc_request","request_id":"123",...}'
+            request = RPCRequest.decode(payload)
+        """
+        obj = codec.decode(data)
+        return cls.from_dict(obj)
+
 
 @dataclass
 class RPCResponse:
@@ -133,7 +274,11 @@ class RPCResponse:
         if self.error is not None:
             data["error"] = self.error
         else:
-            data["result"] = self.result
+            # 处理 Pydantic 模型
+            result = self.result
+            if hasattr(result, 'model_dump'):
+                result = result.model_dump()
+            data["result"] = result
 
         return data
 
@@ -162,24 +307,53 @@ class RPCResponse:
                 ErrorCode.MISSING_REQUIRED_FIELD
             )
 
+    def encode(self, codec: Type[Codec] = JSONCodec) -> bytes:
+        """编码为 bytes
+
+        Args:
+            codec: 编解码器（默认 JSONCodec）
+
+        Returns:
+            编码后的 bytes
+        """
+        return codec.encode(self)
+
+    @classmethod
+    def decode(cls, data: bytes, codec: Type[Codec] = JSONCodec) -> "RPCResponse":
+        """从 bytes 解码
+
+        Args:
+            data: 原始 bytes 数据
+            codec: 编解码器（默认 JSONCodec）
+
+        Returns:
+            RPCResponse 对象
+
+        Raises:
+            MessageError: 解码失败或缺少必需字段
+        """
+        obj = codec.decode(data)
+        return cls.from_dict(obj)
 
-def parse_message(data: dict) -> RPCRequest | RPCResponse:
-    """解析 RPC 消息（带类型验证）
 
-    根据消息的 type 字段自动判断消息类型并解析
+def parse_message_from_bytes(data: bytes, codec: Type[Codec] = JSONCodec) -> RPCRequest | RPCResponse:
+    """从 bytes 解析 RPC 消息
 
     Args:
-        data: JSON 解析后的字典
+        data: 原始 bytes 数据
+        codec: 编解码器（默认 JSONCodec）
 
     Returns:
-        RPCRequest 或 RPCResponse 实例
+        RPCRequest 或 RPCResponse 对象
 
     Raises:
-        MessageError: 未知消息类型或解析失败
+        MessageError: 解码失败或消息类型无效
+        UnicodeDecodeError: UTF-8 解码失败
+        json.JSONDecodeError: JSON 解析失败
 
     示例:
-        data = json.loads(payload)
-        message = parse_message(data)
+        payload = b'{"type":"rpc_request","request_id":"123",...}'
+        message = parse_message_from_bytes(payload)
 
         if isinstance(message, RPCRequest):
             # 处理请求
@@ -188,12 +362,13 @@ def parse_message(data: dict) -> RPCRequest | RPCResponse:
             # 处理响应
             pass
     """
-    msg_type = data.get("type")
+    obj = codec.decode(data)
+    msg_type = obj.get("type")
 
     if msg_type == "rpc_request":
-        return RPCRequest.from_dict(data)
+        return RPCRequest.from_dict(obj)
     elif msg_type == "rpc_response":
-        return RPCResponse.from_dict(data)
+        return RPCResponse.from_dict(obj)
     else:
         raise MessageError(
             f"未知消息类型: {msg_type}",