MoonBit MQTT 3.1.1 Packet Codec

MoonBit MQTT 是一个面向 MQTT 3.1.1 常用控制包的字节级编解码基础库。它提供固定头、Remaining Length、MQTT UTF-8 String、Binary Data，以及常用控制包的编码、解码和基础合法性校验。

当前版本聚焦 MQTT packet codec；网络传输、客户端运行时、Broker 会话、QoS 运行时状态、TLS/SSL 和 MQTT 5.0 可作为后续独立扩展方向。

当前范围

能力	当前状态
Remaining Length	编码、解码、范围校验
MQTT UTF-8 String	编码、解码、UTF-8 校验
MQTT Binary Data	编码、解码，适用于 CONNECT password / will message 等二进制字段
Fixed Header	解码；各控制包解码时校验消息类型、QoS/retain/DUP 保留位和包长
Packet framing	根据固定头计算单个 MQTT packet 总长度，判断缓冲区是否已经包含一个可解码 packet
Generic packet encoder/decoder	在 Packet 枚举和各控制包编解码函数之间进行分发
CONNECT	编码、解码
CONNACK	编码、解码
PUBLISH	QoS 0/1/2 数据包编码、解码；重传状态机属于运行时扩展
PUBACK / PUBREC / PUBREL / PUBCOMP	编码、解码 packet identifier
SUBSCRIBE	编码、解码 topic filter 与 requested QoS
SUBACK	编码、解码返回码
UNSUBSCRIBE	编码、解码 topic filter
UNSUBACK	编码、解码 packet identifier
PINGREQ / PINGRESP / DISCONNECT	编码、解码空控制包

当前版本边界

以下能力不属于当前 packet codec 的实现范围，可作为后续独立扩展方向：

• 网络传输层：不建立 TCP/WebSocket 连接，不发送或接收网络数据。
• 客户端运行时：不包含 MQTT 客户端对象、连接管理、自动重连、心跳调度或订阅回调。
• Broker 与会话语义：不包含 Broker、会话持久化、保留消息或遗嘱投递语义。
• QoS 运行时状态：不包含 QoS 1/2 重发、确认队列、状态机或消息去重。
• 安全传输：不包含 TLS/SSL。
• MQTT 5.0：不包含 MQTT 5.0 属性、原因码或扩展控制包。

安装

发布到 Mooncakes 后，可在 MoonBit 项目中添加依赖：

moon add zbhzs1/moonbit-mqtt

从源码验证当前版本：

git clone https://github.com/zbhzs1/moonbit-mqtt.git
cd moonbit-mqtt
moon check
moon build
moon test

使用示例

仓库提供可运行的最小示例：

moon run examples/basic

编码 CONNECT

let packet = encode_connect({
  client_id: "moon",
  username: None,
  password: None,
  will_topic: None,
  will_message: None,
  keep_alive: 60,
  flags: {
    username: false,
    password: false,
    will_retain: false,
    will_qos: QoS0,
    will_flag: false,
    clean_session: true,
  },
})

编码和解码 PUBLISH

let encoded = encode_publish({
  topic: "sensor/temp",
  payload: b"24.5",
  qos: QoS1,
  message_id: Some(7),
  retain: false,
  dup: false,
})

let decoded = match encoded {
  Ok(packet) => decode_publish(packet)
  Err(e) => Err(e)
}

解码 SUBACK

let suback = decode_suback([0x90, 0x04, 0x00, 0x09, 0x00, 0x80])

本地验证

moon check
moon build
moon test
moon run examples/basic

当前测试包含 20 个字节级测试，覆盖 Remaining Length、字符串和二进制字段、packet framing、generic packet encoder/decoder、CONNECT、CONNACK、PUBLISH QoS 0/1/2、QoS 确认包、SUBSCRIBE、SUBACK、UNSUBSCRIBE、UNSUBACK、PINGREQ、PINGRESP、DISCONNECT，以及部分非法固定头和包长错误。

项目定位

本项目适合作为 MoonBit MQTT 客户端、Broker、协议测试工具或教学示例的底层包编解码组件。上层网络传输、会话和重传逻辑需要在本库之外实现。

License

Apache-2.0