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

mqttxx/__init__.py

@@ -9,15 +9,14 @@
 - 异常系统: 统一错误码和异常层次
 """
 
-__version__ = "3.1.0"
+__version__ = "3.2.0"
 __author__ = "MQTTX Team"
 
 # 核心客户端
-from .client import MQTTClient, RawAPI
+from .client import MQTTClient
 
 # RPC 管理器
 from .rpc import RPCManager
-from .conventions import ConventionalRPCManager
 
 # Event Channel 管理器
 from .events import EventChannelManager, EventMessage
@@ -58,10 +57,8 @@ from .exceptions import (
 __all__ = [
     # MQTT 客户端
     "MQTTClient",
-    "RawAPI",  # Raw API (逃生通道)
     # RPC 管理器
     "RPCManager",
-    "ConventionalRPCManager",  # 约定式 RPC（强约束系统）
     # Event Channel 管理器
     "EventChannelManager",
     "EventMessage",

mqttxx/client.py

@@ -3,7 +3,7 @@
 import asyncio
 import os
 import ssl
-from typing import Callable, Optional, Any, TYPE_CHECKING
+from typing import Callable, Optional, TYPE_CHECKING, Any
 from loguru import logger
 import aiomqtt
 from paho.mqtt.matcher import MQTTMatcher
@@ -14,155 +14,6 @@ if TYPE_CHECKING:
     from .client import MQTTClient
 
 
-class RawAPI:
-    """Raw MQTT API (逃生通道)
-
-    绕过协议层，直接操作 bytes。
-
-    警告:
-        这是逃生通道，仅在以下场景使用:
-        - 自定义协议 (非 JSON/RPC)
-        - 性能敏感场景 (避免编解码)
-        - 与第三方系统集成
-
-    示例:
-        # 订阅原始 bytes
-        client.raw.subscribe("sensor/+", lambda t, b: process(b))
-
-        # 发布原始 bytes
-        await client.raw.publish("topic", b"\\x01\\x02\\x03")
-    """
-
-    def __init__(self, client: "MQTTClient"):
-        """初始化 Raw API
-
-        Args:
-            client: MQTTClient 实例
-        """
-        self._client = client
-
-    def subscribe(self, pattern: str, handler: Callable[[str, bytes], Any]):
-        """订阅原始消息 (bytes)
-
-        Args:
-            pattern: MQTT topic pattern (支持通配符 +/#)
-            handler: 回调函数
-                - 签名: async def handler(topic: str, payload: bytes)
-                - topic: 实际收到消息的 topic
-                - payload: 原始 bytes 数据 (未解码)
-
-        并发行为:
-            - 同一 pattern 的多个 handlers 按注册顺序**顺序调用**（非并发）
-            - 如需并发处理，请在 handler 内部使用 asyncio.create_task()
-
-        示例:
-            # 基础用法
-            async def on_message(topic: str, payload: bytes):
-                data = json.loads(payload.decode('utf-8'))
-                print(f"收到消息: {topic} -> {data}")
-
-            client.raw.subscribe("sensor/+/data", on_message)
-
-            # 顺序处理（默认）
-            async def handler_seq(topic: str, payload: bytes):
-                await process_data(payload)  # 阻塞后续 handlers
-
-            # 并发处理（手动）
-            async def handler_async(topic: str, payload: bytes):
-                asyncio.create_task(process_async(payload))  # 不阻塞
-        """
-        # 追踪 handlers (辅助结构)
-        if pattern not in self._client._raw_handlers:
-            self._client._raw_handlers[pattern] = []
-        self._client._raw_handlers[pattern].append(handler)
-
-        # 同步到 MQTTMatcher (核心匹配引擎)
-        self._client._raw_matcher[pattern] = self._client._raw_handlers[pattern]
-
-        # 订阅 MQTT topic
-        self._client._subscriptions.add(pattern)
-        if self._client._client:
-            asyncio.create_task(self._client._do_subscribe(pattern))
-        else:
-            logger.info(f"Raw 订阅已队列化 (等待连接) - pattern: {pattern}")
-
-        logger.debug(f"Raw 订阅成功 - pattern: {pattern}")
-
-    async def publish(self, topic: str, payload: bytes, qos: int = 0):
-        """发布原始消息 (bytes)
-
-        Args:
-            topic: 目标主题
-            payload: 消息载荷 (bytes)
-            qos: QoS 等级 (0/1/2)
-
-        异常:
-            aiomqtt.MqttError: 发布失败
-        """
-        if not self._client._client:
-            logger.warning(f"发布失败：客户端未连接 - topic: {topic}")
-            return
-
-        try:
-            await self._client._client.publish(topic, payload, qos=qos)
-        except aiomqtt.MqttError as e:
-            logger.error(f"发布失败 - topic: {topic}, error: {e}")
-
-    def unsubscribe(self, pattern: str, handler: Optional[Callable] = None):
-        """取消订阅（修复 P0-B）
-
-        Args:
-            pattern: MQTT topic pattern
-            handler: 要移除的 handler（None = 移除所有）
-
-        示例:
-            # 移除特定 handler
-            client.raw.unsubscribe("test/+", my_handler)
-
-            # 移除所有 handler
-            client.raw.unsubscribe("test/+")
-        """
-        if pattern not in self._client._raw_handlers:
-            logger.debug(f"Raw 取消订阅失败：pattern 不存在 - {pattern}")
-            return
-
-        if handler is None:
-            # 移除所有 handler
-            del self._client._raw_handlers[pattern]
-            del self._client._raw_matcher[pattern]
-            self._client._subscriptions.discard(pattern)
-
-            # 发送 MQTT UNSUBSCRIBE
-            if self._client._client:
-                asyncio.create_task(self._client._client.unsubscribe(pattern))
-
-            logger.debug(f"Raw 取消订阅（全部）- pattern: {pattern}")
-        else:
-            # 移除特定 handler
-            handlers = self._client._raw_handlers[pattern]
-            if handler in handlers:
-                handlers.remove(handler)
-
-                # 如果没有 handler 了，完全取消订阅
-                if not handlers:
-                    del self._client._raw_handlers[pattern]
-                    del self._client._raw_matcher[pattern]
-                    self._client._subscriptions.discard(pattern)
-
-                    if self._client._client:
-                        asyncio.create_task(self._client._client.unsubscribe(pattern))
-
-                    logger.debug(
-                        f"Raw 取消订阅（全部，最后一个 handler）- pattern: {pattern}"
-                    )
-                else:
-                    logger.debug(
-                        f"Raw 取消订阅（部分）- pattern: {pattern}, 剩余 {len(handlers)} 个 handler"
-                    )
-            else:
-                logger.debug(f"Raw 取消订阅失败：handler 不存在 - pattern: {pattern}")
-
-
 class MQTTClient:
     """基于 aiomqtt 的 MQTT 客户端
 
@@ -171,11 +22,6 @@ class MQTTClient:
     - 不自动重连，需要手动实现重连循环（官方推荐模式）
     - 使用 `async for message in client.messages` 异步迭代器
 
-    设计约束:
-        - **单 Event Loop 设计**: 所有方法（subscribe/unsubscribe/handler）
-          必须在同一个 asyncio event loop 中调用
-        - **不支持多线程/多 loop 并发**: 如果需要在多个线程中使用，
-          请为每个线程创建独立的 MQTTClient 实例
 
     并发安全:
         - ✅ 单 loop 内并发调用 subscribe/unsubscribe：安全
@@ -185,20 +31,9 @@ class MQTTClient:
         async def main():
             client = MQTTClient(config)
             await client.connect()
-            client.raw.subscribe("topic", handler1)  # 安全
-            client.raw.subscribe("topic", handler2)  # 安全
-
-        # ❌ 错误：多线程
-        def thread1():
-            client.raw.subscribe("topic", handler1)  # 不安全
-
-        def thread2():
-            client.raw.subscribe("topic", handler2)  # 不安全
+            client.subscribe("topic", handler1)  # 安全
+            client.subscribe("topic", handler2)  # 安全
 
-        # ✅ 正确：多线程各自创建实例
-        def thread1():
-            client1 = MQTTClient(config)
-            asyncio.run(client1.connect())
     """
 
     def __init__(self, config: MQTTConfig):
@@ -221,11 +56,12 @@ class MQTTClient:
         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（修复 P0-A）
+        # 消息处理队列和 Workers（
         self._message_queue: asyncio.Queue = asyncio.Queue(
             maxsize=config.message_queue_maxsize
         )
@@ -233,9 +69,6 @@ class MQTTClient:
         # Worker 数量：默认 CPU核数×2（IO-bound 最优）
         self._num_workers = config.num_workers or (os.cpu_count() or 1) * 2
 
-        # Raw API (逃生通道)
-        self._raw_api = RawAPI(self)
-
     async def connect(self):
         """连接到 MQTT Broker
 
@@ -248,22 +81,49 @@ 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)
-            logger.info(f"MQTT 已启动 {self._num_workers} 个消息处理 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 处理完队列（修复 P0-A）
+        # 等待 workers 处理完队列
         if self._workers:
             # 等待所有 workers 完成（最多 5 秒）
             _, pending = await asyncio.wait(self._workers, timeout=5.0)
@@ -289,9 +149,9 @@ class MQTTClient:
             except asyncio.CancelledError:
                 pass
 
-        # aiomqtt.Client 使用 async with 管理连接，退出时自动清理
-        # 不需要显式调用 disconnect()（该方法不存在）
+        # 清理 Client 和 TLS 上下文
         self._client = None
+        self._tls_context = None
 
         logger.info("MQTT 客户端已断开")
 
@@ -325,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
@@ -377,7 +218,6 @@ class MQTTClient:
 
             except aiomqtt.MqttError as e:
                 logger.error(f"MQTT 连接失败: {e}")
-                self._client = None
                 self._connected = False  # 修复 P0-2：标记为未连接
 
                 # 检查重连次数限制
@@ -405,7 +245,7 @@ class MQTTClient:
                 await asyncio.sleep(interval)
 
     async def _message_loop(self):
-        """消息接收循环（修复 P0-A：只负责接收，不处理）
+        """消息接收循环
 
         使用 async for 迭代消息，将消息放入队列由 workers 处理
 
@@ -458,24 +298,107 @@ class MQTTClient:
                 # 队列为空，继续等待
                 continue
             except asyncio.CancelledError:
-                logger.debug(f"Worker {worker_id} 被取消")
+                #  Worker {worker_id} 被取消
                 break
             except Exception as e:
                 logger.exception(f"Worker {worker_id} 异常: {e}")
                 # 继续运行，不退出
 
+    def subscribe(self, pattern: str, handler: Callable[[str, bytes], Any]):
+        """订阅原始消息 (bytes)
+
+        Args:
+            pattern: MQTT topic pattern (支持通配符 +/#)
+            handler: 回调函数
+                - 签名: async def handler(topic: str, payload: bytes)
+                - topic: 实际收到消息的 topic
+                - payload: 原始 bytes 数据 (未解码)
+
+        并发行为:
+            - 同一 pattern 的多个 handlers 按注册顺序**顺序调用**（非并发）
+            - 如需并发处理，请在 handler 内部使用 asyncio.create_task()
+
+        注意:
+            - 订阅在重连时自动恢复
+        """
+        if pattern not in self._raw_handlers:
+            self._raw_handlers[pattern] = []
+            self._raw_matcher[pattern] = self._raw_handlers[pattern]
+
+            # 立即向 MQTT broker 订阅
+            if self._client:
+                # 使用 asyncio.create_task 避免阻塞
+                asyncio.create_task(self._client.subscribe(pattern))
+
+        self._raw_handlers[pattern].append(handler)
+        self._subscriptions.add(pattern)
+
+        logger.debug(f"订阅已注册 - pattern: {pattern}")
+
     @property
-    def raw(self) -> RawAPI:
-        """访问 Raw MQTT API (逃生通道)
+    def raw(self) -> aiomqtt.Client:
+        """暴露底层 aiomqtt.Client，用于高级用法
 
-        Returns:
-            RawAPI 实例
+        使用场景：
+            await client.raw.publish(topic, payload, qos=1, retain=False)
 
-        示例:
-            client.raw.subscribe("topic", handler)
-            await client.raw.publish("topic", b"data")
+        Raises:
+            RuntimeError: 客户端未连接
+        """
+        if not self._client:
+            raise RuntimeError("Client not connected")
+        return self._client
+
+    def unsubscribe(self, pattern: str, handler: Optional[Callable] = None):
+        """取消订阅
+
+        Args:
+            pattern: MQTT topic pattern
+            handler: 要移除的 handler（None = 移除所有）
+
+        注意:
+            - 当某个 pattern 的最后一个 handler 被移除时：
+              - 若当前已连接，会向 broker 发送 MQTT UNSUBSCRIBE
+              - 无论是否连接，都会清理本地 matcher/handlers
         """
-        return self._raw_api
+        if pattern not in self._raw_handlers:
+            logger.debug(f"取消订阅失败：pattern 不存在 - {pattern}")
+            return
+
+        should_broker_unsubscribe = False
+
+        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:
+            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）
@@ -510,21 +433,6 @@ class MQTTClient:
                 except Exception as e:
                     logger.exception(f"Handler 异常 - topic: {topic_str}, error: {e}")
 
-    async def _do_subscribe(self, topic: str):
-        """执行订阅（内部方法）
-
-        Args:
-            topic: MQTT 主题
-        """
-        if not self._client:
-            return
-
-        try:
-            await self._client.subscribe(topic)
-            logger.success(f"订阅成功 - topic: {topic}")
-        except aiomqtt.MqttError as e:
-            logger.error(f"订阅失败 - topic: {topic}, error: {e}")
-
     async def _restore_subscriptions(self):
         """恢复所有订阅（重连后调用）
 
@@ -542,7 +450,10 @@ class MQTTClient:
         logger.info(f"恢复 {len(topics)} 个订阅...")
 
         for topic in topics:
-            await self._do_subscribe(topic)
+            try:
+                await self._client.subscribe(topic)
+            except aiomqtt.MqttError as e:
+                logger.error(f"恢复订阅失败 - topic: {topic}, error: {e}")
 
         logger.success("订阅恢复完成")
 

mqttxx/events.py

@@ -2,12 +2,12 @@
 
 import asyncio
 import time
-from typing import Callable, Any, Optional, Type
+from typing import Callable, Any, Optional, overload
 from dataclasses import dataclass
 from loguru import logger
 
 from .client import MQTTClient
-from .protocol import Codec, JSONCodec
+import json
 
 
 @dataclass
@@ -93,29 +93,29 @@ class EventMessage:
             source=data.get("source", ""),
         )
 
-    def encode(self, codec: Type[Codec] = JSONCodec) -> bytes:
-        """编码为 bytes
-
-        Args:
-            codec: 编解码器（默认 JSONCodec）
+    def encode(self) -> bytes:
+        """编码为 bytes（JSON 格式）
 
         Returns:
-            编码后的 bytes
+            UTF-8 编码的 JSON bytes
         """
-        return codec.encode(self)
+        return json.dumps(self.to_dict()).encode('utf-8')
 
     @classmethod
-    def decode(cls, data: bytes, codec: Type[Codec] = JSONCodec) -> "EventMessage":
-        """从 bytes 解码
+    def decode(cls, data: bytes) -> "EventMessage":
+        """从 bytes 解码（JSON 格式）
 
         Args:
-            data: 原始 bytes 数据
-            codec: 编解码器（默认 JSONCodec）
+            data: UTF-8 编码的 JSON bytes
 
         Returns:
             EventMessage 对象
+
+        Raises:
+            UnicodeDecodeError: UTF-8 解码失败
+            json.JSONDecodeError: JSON 解析失败
         """
-        obj = codec.decode(data)
+        obj = json.loads(data.decode('utf-8'))
         return cls.from_dict(obj)
 
 
@@ -175,6 +175,24 @@ class EventChannelManager:
 
         logger.info("EventChannelManager 已初始化")
 
+    @overload
+    def subscribe(
+        self,
+        pattern: str,
+        handler: None = None
+    ) -> Callable[[EventHandler], EventHandler]:
+        """装饰器模式：返回装饰器函数"""
+        ...
+
+    @overload
+    def subscribe(
+        self,
+        pattern: str,
+        handler: EventHandler
+    ) -> EventHandler:
+        """直接注册模式：返回处理器本身"""
+        ...
+
     def subscribe(self, pattern: str, handler: Optional[EventHandler] = None):
         """订阅事件主题（支持通配符）
 
@@ -211,8 +229,8 @@ class EventChannelManager:
                 async def dispatcher(topic: str, payload: bytes):
                     """专属 dispatcher（bytes → dict → handler）"""
                     try:
-                        # 解码（使用 JSONCodec）
-                        data = JSONCodec.decode(payload)
+                        # 解码（JSON 格式）
+                        data = json.loads(payload.decode('utf-8'))
 
                         # 分发到所有 handlers（使用 get 避免 KeyError）
                         for h in self._patterns.get(pattern, []):
@@ -231,8 +249,8 @@ class EventChannelManager:
                 # 保存 dispatcher 引用（修复 P0-B）
                 self._dispatchers[pattern] = dispatcher
 
-                # 注册到 MQTTClient 的 raw 层
-                self._client.raw.subscribe(pattern, dispatcher)
+                # 注册到 MQTTClient 层
+                self._client.subscribe(pattern, dispatcher)
 
             self._patterns[pattern].append(func)
             logger.debug(
@@ -253,7 +271,7 @@ class EventChannelManager:
             handler: 要移除的处理器（None = 移除所有）
 
         改进：
-            现在会真正调用 RawAPI.unsubscribe 来清理底层 MQTT 订阅
+            现在会真正调用 MQTTClient.unsubscribe 来清理底层 MQTT 订阅
             避免内存泄漏
         """
         if pattern not in self._patterns:
@@ -266,7 +284,7 @@ class EventChannelManager:
             # 清理 dispatcher（修复 P0-B）
             dispatcher = self._dispatchers.pop(pattern, None)
             if dispatcher:
-                self._client.raw.unsubscribe(pattern, dispatcher)
+                self._client.unsubscribe(pattern, dispatcher)
 
             logger.info(f"已取消订阅 - pattern: {pattern}")
         else:
@@ -280,11 +298,13 @@ class EventChannelManager:
 
                     dispatcher = self._dispatchers.pop(pattern, None)
                     if dispatcher:
-                        self._client.raw.unsubscribe(pattern, dispatcher)
+                        self._client.unsubscribe(pattern, dispatcher)
 
                     logger.info(f"已取消订阅（最后一个 handler）- pattern: {pattern}")
                 else:
-                    logger.debug(f"已移除处理器 - pattern: {pattern}, 剩余 {len(self._patterns[pattern])} 个")
+                    logger.debug(
+                        f"已移除处理器 - pattern: {pattern}, 剩余 {len(self._patterns[pattern])} 个"
+                    )
 
     async def publish(
         self,
@@ -328,13 +348,12 @@ class EventChannelManager:
         """
         # 编码消息
         if isinstance(message, EventMessage):
-            payload = message.encode(JSONCodec)
+            payload = message.encode()
         elif isinstance(message, dict):
-            payload = JSONCodec.encode(message)
+            payload = json.dumps(message).encode('utf-8')
         else:
             # 其他类型自动包装
-            payload = JSONCodec.encode({"data": message})
+            payload = json.dumps({"data": message}).encode('utf-8')
 
         # 直接发布（零开销）
         await self._client.raw.publish(topic, payload, qos=qos)
-        logger.debug(f"事件已发布 - topic: {topic}, qos: {qos}")