mqttxx 2.0.2__py3-none-any.whl

mqttxx/config.py

@@ -0,0 +1,190 @@
+# MQTT 客户端配置对象
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class TLSConfig:
+    """TLS/SSL 配置
+
+    用于配置 MQTT 连接的加密传输层
+
+    Attributes:
+        enabled: 是否启用 TLS/SSL
+        ca_certs: CA 证书路径（用于验证服务器证书）
+        certfile: 客户端证书路径（双向认证）
+        keyfile: 客户端私钥路径（双向认证）
+        verify_mode: 证书验证模式（"CERT_REQUIRED" | "CERT_OPTIONAL" | "CERT_NONE"）
+        check_hostname: 是否验证服务器主机名
+
+    示例:
+        # 单向 TLS（仅验证服务器）
+        tls = TLSConfig(
+            enabled=True,
+            ca_certs=Path("/path/to/ca.crt")
+        )
+
+        # 双向 TLS（客户端证书认证）
+        tls = TLSConfig(
+            enabled=True,
+            ca_certs=Path("/path/to/ca.crt"),
+            certfile=Path("/path/to/client.crt"),
+            keyfile=Path("/path/to/client.key")
+        )
+    """
+
+    enabled: bool = False
+    ca_certs: Optional[Path] = None
+    certfile: Optional[Path] = None
+    keyfile: Optional[Path] = None
+    verify_mode: str = "CERT_REQUIRED"
+    check_hostname: bool = True
+
+
+@dataclass
+class AuthConfig:
+    """MQTT 认证配置
+
+    用于配置 MQTT Broker 的用户名密码认证
+
+    Attributes:
+        username: MQTT 用户名
+        password: MQTT 密码
+
+    示例:
+        auth = AuthConfig(
+            username="device_123",
+            password="secret_password"
+        )
+    """
+
+    username: Optional[str] = None
+    password: Optional[str] = None
+
+
+@dataclass
+class ReconnectConfig:
+    """重连配置
+
+    配置 MQTT 连接断开后的自动重连行为
+
+    Attributes:
+        enabled: 是否启用自动重连
+        interval: 初始重连间隔（秒）
+        max_attempts: 最大重连次数（0 = 无限重试）
+        backoff_multiplier: 指数退避倍数（每次重连失败后，间隔乘以此倍数）
+        max_interval: 最大重连间隔（秒）
+
+    示例:
+        # 无限重试，指数退避
+        reconnect = ReconnectConfig(
+            enabled=True,
+            interval=5,
+            max_attempts=0,
+            backoff_multiplier=1.5,
+            max_interval=60
+        )
+
+        # 固定间隔，最多重试 10 次
+        reconnect = ReconnectConfig(
+            interval=5,
+            max_attempts=10,
+            backoff_multiplier=1.0  # 不使用指数退避
+        )
+    """
+
+    enabled: bool = True
+    interval: int = 5
+    max_attempts: int = 0
+    backoff_multiplier: float = 1.5
+    max_interval: int = 60
+
+
+@dataclass
+class MQTTConfig:
+    """MQTT 客户端完整配置
+
+    所有 MQTT 连接相关的配置参数
+
+    Attributes:
+        broker_host: MQTT Broker 地址
+        broker_port: MQTT Broker 端口（1883=明文, 8883=TLS）
+        client_id: 客户端标识符（空字符串=自动生成）
+        keepalive: 心跳保活时间（秒）
+        clean_session: 是否清除会话（False=服务器保持订阅）
+        tls: TLS/SSL 配置
+        auth: 认证配置
+        reconnect: 重连配置
+        max_queued_messages: 最大排队消息数（0=无限）
+        max_payload_size: 最大消息载荷大小（字节，防止 DoS 攻击）
+        log_level: 日志级别（DEBUG|INFO|WARNING|ERROR）
+
+    示例:
+        # 基础配置（明文连接）
+        config = MQTTConfig(
+            broker_host="localhost",
+            client_id="device_123"
+        )
+
+        # 生产配置（TLS + 认证 + 自动重连）
+        config = MQTTConfig(
+            broker_host="mqtt.example.com",
+            broker_port=8883,
+            client_id="device_123",
+            clean_session=False,  # 保持会话
+            tls=TLSConfig(
+                enabled=True,
+                ca_certs=Path("/etc/ssl/ca.crt")
+            ),
+            auth=AuthConfig(
+                username="device_123",
+                password="secret"
+            ),
+            reconnect=ReconnectConfig(
+                interval=5,
+                max_attempts=0  # 无限重试
+            )
+        )
+    """
+
+    # 连接参数
+    broker_host: str
+    broker_port: int = 1883
+    client_id: str = ""
+    keepalive: int = 60
+    clean_session: bool = False
+
+    # 子配置对象
+    tls: TLSConfig = field(default_factory=TLSConfig)
+    auth: AuthConfig = field(default_factory=AuthConfig)
+    reconnect: ReconnectConfig = field(default_factory=ReconnectConfig)
+
+    # 消息限制
+    max_queued_messages: int = 0  # 0 = 无限
+    max_payload_size: int = 1024 * 1024  # 1MB
+
+    # 日志级别
+    log_level: str = "INFO"
+
+
+@dataclass
+class RPCConfig:
+    """RPC 配置
+
+    RPC 调用相关的配置参数
+
+    Attributes:
+        default_timeout: 默认超时时间（秒）
+        max_concurrent_calls: 最大并发 RPC 调用数
+
+    示例:
+        rpc_config = RPCConfig(
+            default_timeout=30.0,
+            max_concurrent_calls=100
+        )
+    """
+
+    default_timeout: float = 30.0
+    max_concurrent_calls: int = 100

mqttxx/conventions.py

@@ -0,0 +1,145 @@
+# 约定式 RPC 管理器 - 去角色设计
+
+from typing import Any, Optional
+from loguru import logger
+
+from .client import MQTTClient
+from .config import RPCConfig
+from .rpc import RPCManager, AuthCallback
+
+
+class ConventionalRPCManager(RPCManager):
+    """约定式 RPC 管理器
+
+    设计原则：
+    - 约定优于配置
+    - 自动订阅本地 topic
+    - 自动注入 reply_to
+
+    核心功能：
+    1. 初始化时自动订阅 `my_topic`
+    2. 调用时自动将 `my_topic` 注入到 `reply_to`
+
+    适用场景：
+    - 边缘设备 ↔ 云端（edge/xxx ↔ cloud/xxx）
+    - 微服务之间（auth-service ↔ user-service）
+    - IoT 网关 ↔ 设备（gateway/001 ↔ device/123）
+    - 任何需要简化 RPC 调用的场景
+
+    示例:
+        # 边缘设备
+        rpc = ConventionalRPCManager(client, my_topic="edge/device_123")
+
+        @rpc.register("get_status")
+        async def get_status(params):
+            return {"status": "online"}
+
+        # 调用云端（自动注入 reply_to="edge/device_123"）
+        config = await rpc.call("cloud/config-service", "get_config")
+
+        # 云端服务
+        rpc = ConventionalRPCManager(client, my_topic="cloud/config-service")
+
+        # 调用边缘设备（自动注入 reply_to="cloud/config-service"）
+        status = await rpc.call("edge/device_123", "execute_command")
+    """
+
+    def __init__(
+        self,
+        client: MQTTClient,
+        my_topic: str,
+        config: Optional[RPCConfig] = None,
+        auth_callback: Optional[AuthCallback] = None,
+    ):
+        """初始化约定式 RPC 管理器
+
+        Args:
+            client: MQTTClient 实例
+            my_topic: 本节点的 topic（自动订阅，自动注入到 reply_to）
+            config: RPC 配置（可选）
+            auth_callback: 权限检查回调（可选）
+
+        自动行为：
+        - 自动订阅 my_topic
+        - 自动绑定消息处理器
+
+        示例:
+            # 边缘设备
+            rpc = ConventionalRPCManager(client, my_topic="edge/device_123")
+
+            # 云端服务
+            rpc = ConventionalRPCManager(client, my_topic="cloud/server_001")
+
+            # 微服务
+            rpc = ConventionalRPCManager(client, my_topic="auth-service")
+
+            # 多层级
+            rpc = ConventionalRPCManager(client, my_topic="region/zone/device")
+        """
+        super().__init__(client, config, auth_callback)
+
+        self._my_topic = my_topic
+
+        # 自动订阅
+        client.subscribe(my_topic, self.handle_rpc_message)
+
+        logger.info(f"ConventionalRPCManager 已初始化 - my_topic: {my_topic}")
+
+    async def call(
+        self,
+        topic: str,
+        method: str,
+        params: Any = None,
+        timeout: Optional[float] = None,
+        reply_to: Optional[str] = None,
+    ) -> Any:
+        """调用远程方法（自动注入 reply_to）
+
+        Args:
+            topic: 对方的 topic
+            method: 方法名
+            params: 参数（可选）
+            timeout: 超时时间（可选）
+            reply_to: 响应 topic（可选，默认使用 my_topic）
+
+        Returns:
+            方法返回值
+
+        Raises:
+            MQTTXError: 客户端未连接
+            RPCTimeoutError: 调用超时
+            RPCRemoteError: 远程执行失败
+
+        示例:
+            # 边缘设备调用云端
+            rpc = ConventionalRPCManager(client, my_topic="edge/device_123")
+            result = await rpc.call("cloud/server_001", "get_config")
+            # 等价于：await super().call("cloud/server_001", "get_config", reply_to="edge/device_123")
+
+            # 云端调用边缘设备
+            rpc = ConventionalRPCManager(client, my_topic="cloud/server_001")
+            result = await rpc.call("edge/device_123", "execute_command", params={"cmd": "restart"})
+
+            # 微服务调用
+            rpc = ConventionalRPCManager(client, my_topic="auth-service")
+            user = await rpc.call("user-service", "get_user", params={"id": 123})
+        """
+        # 自动注入 reply_to
+        reply_to = reply_to or self._my_topic
+
+        return await super().call(
+            topic=topic,
+            method=method,
+            params=params,
+            timeout=timeout,
+            reply_to=reply_to,
+        )
+
+    @property
+    def my_topic(self) -> str:
+        """获取当前节点的 topic
+
+        Returns:
+            当前节点订阅的 topic
+        """
+        return self._my_topic

mqttxx/exceptions.py

@@ -0,0 +1,160 @@
+# MQTTX 异常定义和错误码
+
+from enum import IntEnum
+
+
+class ErrorCode(IntEnum):
+    """错误码定义（遵循 HTTP 风格分类）
+
+    错误码范围：
+    - 1xxx: 连接错误
+    - 2xxx: 消息错误
+    - 3xxx: RPC 错误
+    - 4xxx: 权限错误
+    """
+
+    # 连接错误 (1xxx)
+    NOT_CONNECTED = 1001
+    CONNECTION_FAILED = 1002
+    CONNECTION_LOST = 1003
+    SUBSCRIBE_FAILED = 1004
+    PUBLISH_FAILED = 1005
+
+    # 消息错误 (2xxx)
+    INVALID_JSON = 2001
+    INVALID_UTF8 = 2002
+    PAYLOAD_TOO_LARGE = 2003
+    INVALID_MESSAGE_TYPE = 2004
+    MISSING_REQUIRED_FIELD = 2005
+
+    # RPC 错误 (3xxx)
+    METHOD_NOT_FOUND = 3001
+    RPC_TIMEOUT = 3002
+    RPC_EXECUTION_ERROR = 3003
+    TOO_MANY_PENDING_CALLS = 3004
+    INVALID_RPC_REQUEST = 3005
+    INVALID_RPC_RESPONSE = 3006
+
+    # 权限错误 (4xxx)
+    PERMISSION_DENIED = 4001
+    AUTHENTICATION_FAILED = 4002
+
+
+class MQTTXError(Exception):
+    """MQTTX 基础异常
+
+    所有 MQTTX 异常的基类，包含错误码和消息
+
+    Attributes:
+        message: 错误消息
+        code: 错误码（ErrorCode 枚举）
+
+    示例:
+        raise MQTTXError("连接失败", ErrorCode.CONNECTION_FAILED)
+    """
+
+    def __init__(self, message: str, code: ErrorCode):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"[{self.code.name}] {self.message}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(code={self.code}, message={self.message!r})"
+
+
+class ConnectionError(MQTTXError):
+    """连接相关异常
+
+    用于表示 MQTT 连接、订阅、发布等操作失败
+
+    示例:
+        raise ConnectionError("客户端未连接", ErrorCode.NOT_CONNECTED)
+    """
+    pass
+
+
+class MessageError(MQTTXError):
+    """消息处理异常
+
+    用于表示消息解析、验证失败
+
+    示例:
+        raise MessageError("JSON 解析失败", ErrorCode.INVALID_JSON)
+    """
+    pass
+
+
+class RPCError(MQTTXError):
+    """RPC 基础异常
+
+    所有 RPC 相关异常的基类
+    """
+    pass
+
+
+class RPCTimeoutError(RPCError):
+    """RPC 超时异常
+
+    当 RPC 调用超过指定时间未收到响应时抛出
+
+    示例:
+        raise RPCTimeoutError("RPC 调用超时: get_status")
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message, ErrorCode.RPC_TIMEOUT)
+
+
+class RPCRemoteError(RPCError):
+    """远程执行失败异常
+
+    当远程方法执行过程中抛出异常时，封装该异常并返回
+
+    示例:
+        raise RPCRemoteError("远程方法执行失败: division by zero")
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message, ErrorCode.RPC_EXECUTION_ERROR)
+
+
+class RPCMethodNotFoundError(RPCError):
+    """方法未找到异常
+
+    当调用的 RPC 方法未在远程节点注册时抛出
+
+    示例:
+        raise RPCMethodNotFoundError("方法未找到: unknown_method")
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message, ErrorCode.METHOD_NOT_FOUND)
+
+
+class PermissionDeniedError(RPCError):
+    """权限拒绝异常
+
+    当 RPC 调用未通过权限检查时抛出
+
+    示例:
+        raise PermissionDeniedError("权限拒绝: delete_user")
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message, ErrorCode.PERMISSION_DENIED)
+
+
+class TooManyConcurrentCallsError(RPCError):
+    """并发调用过多异常
+
+    当并发 RPC 调用数量超过限制时抛出
+
+    示例:
+        raise TooManyConcurrentCallsError("并发调用超限: 100/100")
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message, ErrorCode.TOO_MANY_PENDING_CALLS)

mqttxx/protocol.py

@@ -0,0 +1,201 @@
+# MQTT RPC 消息协议定义
+
+from dataclasses import dataclass
+from typing import Any, Optional, Literal
+
+from .exceptions import MessageError, ErrorCode
+
+
+@dataclass
+class RPCRequest:
+    """RPC 请求消息
+
+    客户端发起 RPC 调用时构造的消息格式
+
+    Attributes:
+        request_id: 请求唯一标识符（UUID）
+        method: 远程方法名
+        type: 消息类型（固定为 "rpc_request"）
+        params: 方法参数（任意类型）
+        reply_to: 响应主题（用于接收响应）
+        caller_id: 调用者标识符（用于权限检查）
+
+    示例:
+        request = RPCRequest(
+            request_id="123e4567-e89b-12d3-a456-426614174000",
+            method="get_status",
+            params={"device_id": "dev_001"},
+            reply_to="client/response",
+            caller_id="client_123"
+        )
+
+        # 序列化为字典（用于 JSON 发送）
+        data = request.to_dict()
+    """
+
+    # 必填字段（无默认值）
+    request_id: str
+    method: str
+    # 可选字段（有默认值）
+    type: Literal["rpc_request"] = "rpc_request"
+    params: Any = None
+    reply_to: str = ""
+    caller_id: str = ""
+
+    def to_dict(self) -> dict:
+        """转为字典（用于 JSON 序列化）
+
+        Returns:
+            包含所有字段的字典
+        """
+        return {
+            "type": self.type,
+            "request_id": self.request_id,
+            "method": self.method,
+            "params": self.params,
+            "reply_to": self.reply_to,
+            "caller_id": self.caller_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "RPCRequest":
+        """从字典构造（用于 JSON 反序列化）
+
+        Args:
+            data: 包含消息字段的字典
+
+        Returns:
+            RPCRequest 实例
+
+        Raises:
+            MessageError: 缺少必需字段时抛出
+        """
+        try:
+            return cls(
+                request_id=data["request_id"],
+                method=data["method"],
+                params=data.get("params"),
+                reply_to=data.get("reply_to", ""),
+                caller_id=data.get("caller_id", ""),
+            )
+        except KeyError as e:
+            raise MessageError(
+                f"RPC 请求缺少必需字段: {e}",
+                ErrorCode.MISSING_REQUIRED_FIELD
+            )
+
+
+@dataclass
+class RPCResponse:
+    """RPC 响应消息
+
+    服务端处理 RPC 请求后返回的消息格式
+
+    Attributes:
+        type: 消息类型（固定为 "rpc_response"）
+        request_id: 对应请求的唯一标识符
+        result: 方法返回值（成功时）
+        error: 错误消息（失败时）
+
+    注意:
+        result 和 error 只能有一个非空
+
+    示例:
+        # 成功响应
+        response = RPCResponse(
+            request_id="123e4567-e89b-12d3-a456-426614174000",
+            result={"status": "online", "temperature": 25.5}
+        )
+
+        # 错误响应
+        response = RPCResponse(
+            request_id="123e4567-e89b-12d3-a456-426614174000",
+            error="方法未找到: unknown_method"
+        )
+    """
+
+    type: Literal["rpc_response"] = "rpc_response"
+    request_id: str = ""
+    result: Any = None
+    error: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """转为字典（用于 JSON 序列化）
+
+        Returns:
+            包含所有字段的字典
+        """
+        data = {
+            "type": self.type,
+            "request_id": self.request_id,
+        }
+
+        if self.error is not None:
+            data["error"] = self.error
+        else:
+            data["result"] = self.result
+
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "RPCResponse":
+        """从字典构造（用于 JSON 反序列化）
+
+        Args:
+            data: 包含消息字段的字典
+
+        Returns:
+            RPCResponse 实例
+
+        Raises:
+            MessageError: 缺少必需字段时抛出
+        """
+        try:
+            return cls(
+                request_id=data["request_id"],
+                result=data.get("result"),
+                error=data.get("error"),
+            )
+        except KeyError as e:
+            raise MessageError(
+                f"RPC 响应缺少必需字段: {e}",
+                ErrorCode.MISSING_REQUIRED_FIELD
+            )
+
+
+def parse_message(data: dict) -> RPCRequest | RPCResponse:
+    """解析 RPC 消息（带类型验证）
+
+    根据消息的 type 字段自动判断消息类型并解析
+
+    Args:
+        data: JSON 解析后的字典
+
+    Returns:
+        RPCRequest 或 RPCResponse 实例
+
+    Raises:
+        MessageError: 未知消息类型或解析失败
+
+    示例:
+        data = json.loads(payload)
+        message = parse_message(data)
+
+        if isinstance(message, RPCRequest):
+            # 处理请求
+            pass
+        elif isinstance(message, RPCResponse):
+            # 处理响应
+            pass
+    """
+    msg_type = data.get("type")
+
+    if msg_type == "rpc_request":
+        return RPCRequest.from_dict(data)
+    elif msg_type == "rpc_response":
+        return RPCResponse.from_dict(data)
+    else:
+        raise MessageError(
+            f"未知消息类型: {msg_type}",
+            ErrorCode.INVALID_MESSAGE_TYPE
+        )