mqttxx 2.0.3__py3-none-any.whl → 3.2.1__py3-none-any.whl

mqttxx/__init__.py

@@ -3,12 +3,13 @@
 提供：
 - MQTTClient: MQTT 连接管理（自动重连、订阅队列化、TLS/SSL 支持）
 - RPCManager: 双向对等 RPC 调用（超时控制、权限检查、并发限制）
+- EventChannelManager: 高吞吐事件广播通道（单向、无返回值）
 - 配置对象: MQTTConfig, TLSConfig, AuthConfig, RPCConfig 等
-- 协议定义: RPCRequest, RPCResponse
+- 协议定义: RPCRequest, RPCResponse, EventMessage
 - 异常系统: 统一错误码和异常层次
 """
 
-__version__ = "2.0.0"
+__version__ = "3.2.0"
 __author__ = "MQTTX Team"
 
 # 核心客户端
@@ -16,7 +17,9 @@ from .client import MQTTClient
 
 # RPC 管理器
 from .rpc import RPCManager
-from .conventions import ConventionalRPCManager
+
+# Event Channel 管理器
+from .events import EventChannelManager, EventMessage
 
 # 配置对象
 from .config import (
@@ -31,7 +34,7 @@ from .config import (
 from .protocol import (
     RPCRequest,
     RPCResponse,
-    parse_message,
+    # parse_message 是内部 API，不再导出
 )
 
 # 异常系统
@@ -56,7 +59,9 @@ __all__ = [
     "MQTTClient",
     # RPC 管理器
     "RPCManager",
-    "ConventionalRPCManager",  # 约定式 RPC（强约束系统）
+    # Event Channel 管理器
+    "EventChannelManager",
+    "EventMessage",
     # 配置对象
     "MQTTConfig",
     "TLSConfig",
@@ -66,7 +71,7 @@ __all__ = [
     # 协议定义
     "RPCRequest",
     "RPCResponse",
-    "parse_message",
+    # parse_message 已移除 - 内部 API
     # 异常系统
     "ErrorCode",
     "MQTTXError",

mqttxx/client.py

@@ -1,15 +1,17 @@
 # aiomqtt 高级封装 - 基于纯 async/await 架构
 
 import asyncio
-import json
+import os
 import ssl
-from typing import Callable, Optional
+from typing import Callable, Optional, TYPE_CHECKING, Any
 from loguru import logger
 import aiomqtt
+from paho.mqtt.matcher import MQTTMatcher
 
 from .config import MQTTConfig
-from .exceptions import MessageError
-from .protocol import parse_message
+
+if TYPE_CHECKING:
+    from .client import MQTTClient
 
 
 class MQTTClient:
@@ -19,6 +21,19 @@ class MQTTClient:
     - aiomqtt 基于 paho-mqtt 封装，成熟稳定
     - 不自动重连，需要手动实现重连循环（官方推荐模式）
     - 使用 `async for message in client.messages` 异步迭代器
+
+
+    并发安全:
+        - ✅ 单 loop 内并发调用 subscribe/unsubscribe：安全
+
+    示例:
+        # ✅ 正确：单 loop
+        async def main():
+            client = MQTTClient(config)
+            await client.connect()
+            client.subscribe("topic", handler1)  # 安全
+            client.subscribe("topic", handler2)  # 安全
+
     """
 
     def __init__(self, config: MQTTConfig):
@@ -33,11 +48,26 @@ class MQTTClient:
         self.config = config
         self._client: Optional[aiomqtt.Client] = None
         self._subscriptions: set[str] = set()  # 订阅列表（用于重连恢复）
-        self._message_handlers: dict[str, Callable] = {}  # topic → handler 映射
+
+        # Raw 订阅（使用 MQTTMatcher 进行通配符匹配）
+        # _raw_matcher 是核心匹配引擎（用于 iter_match）
+        # _raw_handlers 是辅助追踪结构（因 MQTTMatcher 不支持 getitem/contains）
+        self._raw_matcher = MQTTMatcher()
+        self._raw_handlers: dict[str, list[Callable]] = {}
+
         self._running = False
-        self._connected = False  # 修复 P0-2：真实连接状态标志
+        self._connected = False  # 真实连接状态标志
         self._reconnect_task: Optional[asyncio.Task] = None
         self._message_task: Optional[asyncio.Task] = None
+        self._tls_context: Optional[ssl.SSLContext] = None  # TLS 上下文（复用）
+
+        # 消息处理队列和 Workers（
+        self._message_queue: asyncio.Queue = asyncio.Queue(
+            maxsize=config.message_queue_maxsize
+        )
+        self._workers: list[asyncio.Task] = []
+        # Worker 数量：默认 CPU核数×2（IO-bound 最优）
+        self._num_workers = config.num_workers or (os.cpu_count() or 1) * 2
 
     async def connect(self):
         """连接到 MQTT Broker
@@ -51,14 +81,56 @@ class MQTTClient:
 
         self._running = True
 
+        # 创建 TLS 上下文（只创建一次，可复用）
+        if self.config.tls.enabled:
+            self._tls_context = self._create_tls_context()
+
+        # 创建 aiomqtt.Client（只创建一次，在重连循环中复用）
+        self._client = aiomqtt.Client(
+            hostname=self.config.broker_host,
+            port=self.config.broker_port,
+            username=self.config.auth.username,
+            password=self.config.auth.password,
+            identifier=self.config.client_id or None,
+            clean_session=self.config.clean_session,
+            keepalive=self.config.keepalive,
+            tls_context=self._tls_context,
+            max_queued_outgoing_messages=self.config.max_queued_messages or None,
+        )
+
+        # 启动消息处理 workers
+        for i in range(self._num_workers):
+            worker = asyncio.create_task(self._worker(i), name=f"mqtt_worker_{i}")
+            self._workers.append(worker)
+
         self._reconnect_task = asyncio.create_task(
             self._reconnect_loop(), name="mqtt_reconnect"
         )
 
+        # 等待首次连接建立（最多 60 秒）
+        for _ in range(600):  # 60 秒超时，每次检查 0.1 秒
+            if self._connected:
+                break
+            await asyncio.sleep(0.1)
+        else:
+            self._running = False  # 清理状态
+            raise TimeoutError(
+                f"MQTT 连接超时（60秒）：{self.config.broker_host}:{self.config.broker_port}"
+            )
+
     async def disconnect(self):
         """断开连接并清理资源"""
         self._running = False
-        self._connected = False  # 修复 P0-2：标记为未连接
+        self._connected = False  # ：标记为未连接
+
+        # 等待 workers 处理完队列
+        if self._workers:
+            # 等待所有 workers 完成（最多 5 秒）
+            _, pending = await asyncio.wait(self._workers, timeout=5.0)
+            # 取消未完成的 workers
+            for w in pending:
+                w.cancel()
+            self._workers.clear()
 
         # 取消后台任务
         if self._reconnect_task:
@@ -68,15 +140,18 @@ class MQTTClient:
             except asyncio.CancelledError:
                 pass
 
-        # 取消消息处理任务
+        # 取消消息处理任务（修复 P0-D）
+        # 这会导致 _reconnect_loop 中的 async with 块退出，aiomqtt 自动清理连接
         if self._message_task:
             self._message_task.cancel()
             try:
                 await self._message_task
             except asyncio.CancelledError:
                 pass
-        if self._client:
-            self._client = None
+
+        # 清理 Client 和 TLS 上下文
+        self._client = None
+        self._tls_context = None
 
         logger.info("MQTT 客户端已断开")
 
@@ -110,40 +185,21 @@ class MQTTClient:
         异常处理：
         - aiomqtt.MqttError：连接/协议错误，触发重连
         - asyncio.CancelledError：任务被取消，退出循环
+
+        关键改进：
+        - Client 在 connect() 中创建（只创建一次）
+        - 循环内只使用 async with self._client: 来连接
+        - 符合 aiomqtt 官方推荐模式
         """
         attempt = 0
         interval = self.config.reconnect.interval
 
         while self._running:
             try:
-                # 创建 TLS 上下文
-                tls_context = (
-                    self._create_tls_context() if self.config.tls.enabled else None
-                )
-
-                # region 调用代码溯源(aiomqtt.Client)
-                # aiomqtt.Client 是异步上下文管理器
-                # 文档：https://aiomqtt.bo3hm.com/reconnection.html
-                # 进入上下文时自动连接
-                # endregion
-                async with aiomqtt.Client(
-                    hostname=self.config.broker_host,
-                    port=self.config.broker_port,
-                    username=self.config.auth.username,
-                    password=self.config.auth.password,
-                    identifier=self.config.client_id
-                    or None,  # 空字符串 → None = 自动生成
-                    clean_session=self.config.clean_session,
-                    keepalive=self.config.keepalive,
-                    tls_context=tls_context,
-                    max_queued_outgoing_messages=self.config.max_queued_messages
-                    or None,
-                ) as client:
-                    self._client = client
+                # 使用已创建的 Client（在 connect() 中创建）
+                # async with 会连接，退出时会自动断开
+                async with self._client:
                     self._connected = True  # 修复 P0-2：标记为已连接
-                    logger.success(
-                        f"MQTT 连接成功 - {self.config.broker_host}:{self.config.broker_port}"
-                    )
 
                     # 重置重连计数
                     attempt = 0
@@ -162,7 +218,6 @@ class MQTTClient:
 
             except aiomqtt.MqttError as e:
                 logger.error(f"MQTT 连接失败: {e}")
-                self._client = None
                 self._connected = False  # 修复 P0-2：标记为未连接
 
                 # 检查重连次数限制
@@ -190,14 +245,14 @@ class MQTTClient:
                 await asyncio.sleep(interval)
 
     async def _message_loop(self):
-        """消息处理循环（aiomqtt 核心模式）
+        """消息接收循环
 
-        使用 async for 迭代消息，替代 gmqtt 的 on_message 回调
+        使用 async for 迭代消息，将消息放入队列由 workers 处理
 
-        关键特性：
-        - 非阻塞：异步迭代器自动 yield 控制权
-        - 顺序处理：每条消息按顺序处理
-        - 并发处理：每条消息在独立 Task 中处理（不阻塞迭代器）
+        关键改进：
+        - 接收和处理分离：避免高吞吐下任务爆炸
+        - 有界队列：maxsize 可配置（默认 100k），作为保险丝
+        - 队列满时阻塞：形成自然背压，CPU/延迟会变明显（扩容信号）
 
         异常处理：
         - asyncio.CancelledError：任务被取消，退出循环
@@ -208,19 +263,9 @@ class MQTTClient:
             return
 
         try:
-            # region 调用代码溯源(aiomqtt.Client.messages)
-            # aiomqtt.Client.messages 是一个异步迭代器
-            # 内部调用：
-            #   paho.mqtt.client.Client._handle_on_message()
-            #   → 将消息放入队列
-            #   → aiomqtt 从队列中取出消息
-            # GitHub：https://github.com/sbtinstruments/aiomqtt/blob/main/aiomqtt/client.py#L400
-            # endregion
             async for message in self._client.messages:
-                # 异步处理消息（不阻塞迭代器）
-                asyncio.create_task(
-                    self._handle_message(message), name=f"handle_{message.topic}"
-                )
+                # 将消息放入队列（阻塞等待，形成自然背压）
+                await self._message_queue.put(message)
         except asyncio.CancelledError:
             logger.info("消息处理任务已取消")
             raise
@@ -230,138 +275,163 @@ class MQTTClient:
         except Exception as e:
             logger.exception(f"消息循环异常: {e}")
 
-    async def _handle_message(self, message: aiomqtt.Message):
-        """处理单条消息
-        Args:
-            message: aiomqtt.Message 对象
+    async def _worker(self, worker_id: int):
+        """消息处理 Worker
 
-        消息处理流程：
-        1. 检查 payload 大小
-        2. 解码 UTF-8
-        3. 解析 JSON
-        4. 使用 protocol.parse_message() 验证和解析
-        5. 路由到对应处理器
-        """
+        从队列中取消息并处理，支持并发控制
 
-        try:
-            # 检查 payload 大小（防御 DoS）
-            if len(message.payload) > self.config.max_payload_size:
-                logger.warning(
-                    f"Payload 过大，已忽略 - "
-                    f"topic: {message.topic}, size: {len(message.payload)}"
-                )
-                return
+        Args:
+            worker_id: Worker ID（用于日志）
 
+        设计要点：
+        - 并发上限可控（默认 16 个 worker）
+        - 异常隔离（worker 崩溃不影响其他 worker）
+        - 优雅退出（_running=False 时退出）
+        """
+        while self._running:
             try:
-                text = message.payload.decode("utf-8")
-                data = json.loads(text)
-            except UnicodeDecodeError as e:
-                logger.error(
-                    f"UTF-8 解码失败 - topic: {message.topic}, error: {e!r}, "
-                    f"preview: {message.payload[:100]}"
-                )
-                return
-            except json.JSONDecodeError as e:
-                logger.error(
-                    f"JSON 解析失败 - topic: {message.topic}, error: {e!r}, "
-                    f"preview: {text[:100]}"
-                )
-                return
+                # 从队列取消息（带超时，避免无法退出） asyncio.Queue 是原子安全的
+                message = await asyncio.wait_for(self._message_queue.get(), timeout=1.0)
+                # 处理消息
+                await self._handle_message(message)
+            except asyncio.TimeoutError:
+                # 队列为空，继续等待
+                continue
+            except asyncio.CancelledError:
+                #  Worker {worker_id} 被取消
+                break
+            except Exception as e:
+                logger.exception(f"Worker {worker_id} 异常: {e}")
+                # 继续运行，不退出
 
-            # 解析消息类型（使用 dataclass 替代 Box）
-            msg = parse_message(data)
+    def subscribe(self, pattern: str, handler: Callable[[str, bytes], Any]):
+        """订阅原始消息 (bytes)
 
-            # 路由到对应处理器
-            topic_str = str(message.topic)
-            handler = self._message_handlers.get(topic_str)
+        Args:
+            pattern: MQTT topic pattern (支持通配符 +/#)
+            handler: 回调函数
+                - 签名: async def handler(topic: str, payload: bytes)
+                - topic: 实际收到消息的 topic
+                - payload: 原始 bytes 数据 (未解码)
 
-            if handler:
-                # 调用处理器
-                if asyncio.iscoroutinefunction(handler):
-                    await handler(topic_str, msg)
-                else:
-                    handler(topic_str, msg)
-            else:
-                # 修复 P0-3：RPC 请求无处理器时，立即返回错误响应（防止调用方超时）
-                from .protocol import RPCRequest, RPCResponse
+        并发行为:
+            - 同一 pattern 的多个 handlers 按注册顺序**顺序调用**（非并发）
+            - 如需并发处理，请在 handler 内部使用 asyncio.create_task()
 
-                if isinstance(msg, RPCRequest):
-                    logger.warning(
-                        f"收到 RPC 请求但无处理器 - topic: {topic_str}, method: {msg.method}"
-                    )
-                    # 立即发送错误响应
-                    error_response = RPCResponse(
-                        request_id=msg.request_id,
-                        error=f"No RPC handler registered for topic: {topic_str}",
-                    )
-                    await self.publish(
-                        msg.reply_to, json.dumps(error_response.to_dict()), qos=1
-                    )
-                else:
-                    logger.debug(f"收到消息（无处理器）- topic: {topic_str}")
+        注意:
+            - 订阅在重连时自动恢复
+        """
+        if pattern not in self._raw_handlers:
+            self._raw_handlers[pattern] = []
+            self._raw_matcher[pattern] = self._raw_handlers[pattern]
 
-        except MessageError as e:
-            logger.error(f"消息解析失败: {e}")
-        except Exception as e:
-            logger.exception(f"消息处理失败: {e}")
+            # 立即向 MQTT broker 订阅
+            if self._client:
+                # 使用 asyncio.create_task 避免阻塞
+                asyncio.create_task(self._client.subscribe(pattern))
 
-    def subscribe(self, topic: str, handler: Optional[Callable] = None):
-        """订阅主题
+        self._raw_handlers[pattern].append(handler)
+        self._subscriptions.add(pattern)
 
-        修复点：
-        - ✅ P0-1: 未连接时不崩溃，队列化订阅
+        logger.debug(f"订阅已注册 - pattern: {pattern}")
 
-        Args:
-            topic: MQTT 主题（支持通配符 +/#）
-            handler: 消息处理器
-                签名：async def handler(topic: str, message: RPCRequest | RPCResponse)
-                或：def handler(topic: str, message: RPCRequest | RPCResponse)
+    @property
+    def raw(self) -> aiomqtt.Client:
+        """暴露底层 aiomqtt.Client，用于高级用法
 
-        设计决策：
-        - 记录订阅到 _subscriptions set（用于重连恢复）
-        - 如果已连接，立即订阅
-        - 如果未连接，等待连接后自动订阅
+        使用场景：
+            await client.raw.publish(topic, payload, qos=1, retain=False)
 
-        示例:
-            # 同步处理器
-            def my_handler(topic, message):
-                print(f"收到消息: {topic} - {message}")
+        Raises:
+            RuntimeError: 客户端未连接
+        """
+        if not self._client:
+            raise RuntimeError("Client not connected")
+        return self._client
 
-            client.subscribe("test/topic", my_handler)
+    def unsubscribe(self, pattern: str, handler: Optional[Callable] = None):
+        """取消订阅
 
-            # 异步处理器
-            async def my_async_handler(topic, message):
-                await process_message(message)
+        Args:
+            pattern: MQTT topic pattern
+            handler: 要移除的 handler（None = 移除所有）
 
-            client.subscribe("test/topic", my_async_handler)
+        注意:
+            - 当某个 pattern 的最后一个 handler 被移除时：
+              - 若当前已连接，会向 broker 发送 MQTT UNSUBSCRIBE
+              - 无论是否连接，都会清理本地 matcher/handlers
         """
-        # 记录订阅（用于重连恢复）
-        self._subscriptions.add(topic)
+        if pattern not in self._raw_handlers:
+            logger.debug(f"取消订阅失败：pattern 不存在 - {pattern}")
+            return
 
-        # 注册处理器
-        if handler:
-            self._message_handlers[topic] = handler
+        should_broker_unsubscribe = False
 
-        # 如果已连接，立即订阅
-        if self._client:
-            asyncio.create_task(self._do_subscribe(topic))
+        if handler is None:
+            del self._raw_handlers[pattern]
+            del self._raw_matcher[pattern]
+            self._subscriptions.discard(pattern)
+            logger.debug(f"取消订阅（全部）- pattern: {pattern}")
+            should_broker_unsubscribe = True
         else:
-            logger.info(f"订阅已队列化（等待连接）- topic: {topic}")
+            handlers = self._raw_handlers[pattern]
+            if handler in handlers:
+                handlers.remove(handler)
+
+                if not handlers:
+                    del self._raw_handlers[pattern]
+                    del self._raw_matcher[pattern]
+                    self._subscriptions.discard(pattern)
+                    logger.debug(
+                        f"取消订阅（全部，最后一个 handler）- pattern: {pattern}"
+                    )
+                    should_broker_unsubscribe = True
+                else:
+                    logger.debug(
+                        f"取消订阅（部分）- pattern: {pattern}, 剩余 {len(handlers)} 个 handler"
+                    )
+            else:
+                logger.debug(f"取消订阅失败：handler 不存在 - pattern: {pattern}")
+
+        if should_broker_unsubscribe and self._client and self.is_connected:
+            asyncio.create_task(
+                self._client.unsubscribe(pattern),
+                name=f"mqtt_unsub_{pattern}",
+            )
+            logger.debug(f"已向 broker 发送 UNSUBSCRIBE - pattern: {pattern}")
+
+    async def _handle_message(self, message: aiomqtt.Message):
+        """处理单条消息（传输层，只处理 bytes）
 
-    async def _do_subscribe(self, topic: str):
-        """执行订阅（内部方法）
+        核心改变：
+        1. 不再解析 JSON/协议
+        2. 将 payload (bytes) 分发给 raw handlers
+        3. 不再区分 RPC/Event（让上层处理）
 
         Args:
-            topic: MQTT 主题
+            message: aiomqtt.Message 对象
         """
-        if not self._client:
+        topic_str = str(message.topic)
+        payload = message.payload  # bytes 类型
+
+        # 检查 payload 大小（防御 DoS）
+        if len(payload) > self.config.max_payload_size:
+            logger.warning(
+                f"Payload 过大，已忽略 - topic: {topic_str}, size: {len(payload)}"
+            )
             return
 
-        try:
-            await self._client.subscribe(topic)
-            logger.success(f"订阅成功 - topic: {topic}")
-        except aiomqtt.MqttError as e:
-            logger.error(f"订阅失败 - topic: {topic}, error: {e}")
+        # === 唯一职责：将 bytes 分发给所有匹配的 handlers ===
+        # MQTTMatcher.iter_match 返回值列表，不是 (pattern, handlers) 元组
+        for handlers in self._raw_matcher.iter_match(topic_str):
+            for handler in handlers:
+                try:
+                    if asyncio.iscoroutinefunction(handler):
+                        await handler(topic_str, payload)  # 传递 bytes！
+                    else:
+                        handler(topic_str, payload)
+                except Exception as e:
+                    logger.exception(f"Handler 异常 - topic: {topic_str}, error: {e}")
 
     async def _restore_subscriptions(self):
         """恢复所有订阅（重连后调用）
@@ -375,32 +445,18 @@ class MQTTClient:
         if not self._subscriptions:
             return
 
-        logger.info(f"恢复 {len(self._subscriptions)} 个订阅...")
+        # 创建快照，避免遍历时被修改（修复 P0-C）
+        topics = list(self._subscriptions)
+        logger.info(f"恢复 {len(topics)} 个订阅...")
 
-        for topic in self._subscriptions:
-            await self._do_subscribe(topic)
+        for topic in topics:
+            try:
+                await self._client.subscribe(topic)
+            except aiomqtt.MqttError as e:
+                logger.error(f"恢复订阅失败 - topic: {topic}, error: {e}")
 
         logger.success("订阅恢复完成")
 
-    async def publish(self, topic: str, payload: str, qos: int = 0):
-        """发布消息
-        Args:
-            topic: 目标主题
-            payload: 消息载荷（字符串）
-            qos: QoS 等级（0/1/2）
-
-        异常:
-            aiomqtt.MqttError: 发布失败
-        """
-        if not self._client:
-            logger.warning(f"发布失败：客户端未连接 - topic: {topic}")
-            return
-
-        try:
-            await self._client.publish(topic, payload, qos=qos)
-        except aiomqtt.MqttError as e:
-            logger.error(f"发布失败 - topic: {topic}, error: {e}")
-
     def _create_tls_context(self) -> ssl.SSLContext:
         """创建 TLS 上下文
 

mqttxx/config.py

@@ -119,6 +119,16 @@ class MQTTConfig:
         reconnect: 重连配置
         max_queued_messages: 最大排队消息数（0=无限）
         max_payload_size: 最大消息载荷大小（字节，防止 DoS 攻击）
+        message_queue_maxsize: 消息队列大小限制（默认 100,000）
+            - 语义："几乎无限"，仅作保险丝防止 OOM
+            - 队列满时行为：阻塞等待（背压信号）
+            - 触发背压时：CPU/延迟升高 → 扩容信号
+            - Python 字面量分隔符：100_000 = 100000（下划线仅用于可读性）
+        num_workers: Worker 数量（默认 None = CPU核数×2）
+            - None（默认）：CPU核数 × 2（适合 IO-bound 负载）
+            - 自定义值：根据 handler 类型调整
+                - CPU-bound handler：设为 CPU核数
+                - IO-bound handler：设为 CPU核数 × 2~4
         log_level: 日志级别（DEBUG|INFO|WARNING|ERROR）
 
     示例:
@@ -165,6 +175,10 @@ class MQTTConfig:
     max_queued_messages: int = 0  # 0 = 无限
     max_payload_size: int = 1024 * 1024  # 1MB
 
+    # 消息处理（修复 P0-A）
+    message_queue_maxsize: int = 100_000  # 10W 条 队列最大容量（保险丝）
+    num_workers: Optional[int] = None  # Worker 数量（None = CPU核数×2）
+
     # 日志级别
     log_level: str = "INFO"