Coverage for src / zmqtt / _internal / packets / codec.py: 91%

385 statements  

« prev     ^ index     » next       coverage.py v7.13.4, created at 2026-11-12 08:49 +0000

1"""I/O-free encode/decode dispatcher for MQTT 3.1.1 and 5.0 packets.""" 

2 

3import struct 

4from typing import Literal 

5 

6from zmqtt._internal.packets._wire import ( 

7 decode_bytes_field, 

8 decode_str, 

9 decode_varint, 

10 encode_bytes_field, 

11 encode_str, 

12 encode_varint, 

13) 

14from zmqtt._internal.packets.auth import Auth 

15from zmqtt._internal.packets.connect import ConnAck, Connect, Will 

16from zmqtt._internal.packets.disconnect import Disconnect 

17from zmqtt._internal.packets.ping import PingReq, PingResp 

18from zmqtt._internal.packets.properties import ( 

19 decode_auth_properties, 

20 decode_connack_properties, 

21 decode_connect_properties, 

22 decode_disconnect_properties, 

23 decode_puback_properties, 

24 decode_publish_properties, 

25 decode_suback_properties, 

26 decode_subscribe_properties, 

27 decode_unsuback_properties, 

28 decode_unsubscribe_properties, 

29 decode_will_properties, 

30 encode_auth_properties, 

31 encode_connack_properties, 

32 encode_connect_properties, 

33 encode_disconnect_properties, 

34 encode_puback_properties, 

35 encode_publish_properties, 

36 encode_suback_properties, 

37 encode_subscribe_properties, 

38 encode_unsuback_properties, 

39 encode_unsubscribe_properties, 

40 encode_will_properties, 

41) 

42from zmqtt._internal.packets.publish import PubAck, PubComp, Publish, PubRec, PubRel 

43from zmqtt._internal.packets.subscribe import ( 

44 SubAck, 

45 Subscribe, 

46 SubscriptionRequest, 

47 UnsubAck, 

48 Unsubscribe, 

49) 

50from zmqtt._internal.packets.types import PacketType 

51from zmqtt._internal.types.qos import QoS 

52from zmqtt._internal.types.retain_handling import RetainHandling 

53 

54# Re-export wire helpers so existing callers of ``from zmqtt._internal.packets.codec import …`` keep working. 

55__all__ = [ 

56 "PacketTooLargeError", 

57 "decode", 

58 "decode_varint", 

59 "encode", 

60 "encode_varint", 

61] 

62 

63 

64class PacketTooLargeError(ValueError): 

65 """An incoming packet is larger than the receiver's Maximum Packet Size.""" 

66 

67 def __init__(self, size: int, limit: int) -> None: 

68 self.size = size 

69 self.limit = limit 

70 super().__init__(f"Packet of {size} bytes exceeds the Maximum Packet Size of {limit} bytes") 

71 

72 

73AnyPacket = ( 

74 Connect 

75 | ConnAck 

76 | Publish 

77 | PubAck 

78 | PubRec 

79 | PubRel 

80 | PubComp 

81 | Subscribe 

82 | SubAck 

83 | Unsubscribe 

84 | UnsubAck 

85 | PingReq 

86 | PingResp 

87 | Disconnect 

88 | Auth 

89) 

90 

91 

92def _build_packet(packet_type: PacketType, flags: int, body: bytes) -> bytes: 

93 first_byte = (packet_type << 4) | (flags & 0x0F) 

94 return bytes([first_byte]) + encode_varint(len(body)) + body 

95 

96 

97def _packet_id_only(packet_type: PacketType, flags: int, packet_id: int) -> bytes: 

98 return _build_packet(packet_type, flags, struct.pack("!H", packet_id)) 

99 

100 

101def _encode_connect(packet: Connect, version: Literal["3.1.1", "5.0"]) -> bytes: 

102 flags = 0 

103 if packet.clean_session: 

104 flags |= 0x02 

105 if packet.will is not None: 

106 flags |= 0x04 

107 flags |= packet.will.qos << 3 

108 if packet.will.retain: 

109 flags |= 0x20 

110 if packet.username is not None: 

111 flags |= 0x80 

112 if packet.password is not None: 

113 flags |= 0x40 

114 

115 proto_level = 0x05 if version == "5.0" else 0x04 

116 var_header = encode_str("MQTT") + bytes([proto_level, flags]) + struct.pack("!H", packet.keepalive) 

117 

118 if version == "5.0": 

119 var_header += encode_connect_properties(packet.properties) 

120 

121 payload = encode_str(packet.client_id) 

122 if packet.will is not None: 

123 if version == "5.0": 

124 payload += encode_will_properties(packet.will.properties) 

125 payload += encode_str(packet.will.topic) 

126 payload += encode_bytes_field(packet.will.payload) 

127 if packet.username is not None: 

128 payload += encode_str(packet.username) 

129 if packet.password is not None: 

130 payload += encode_bytes_field(packet.password) 

131 

132 return _build_packet(PacketType.CONNECT, 0, var_header + payload) 

133 

134 

135def _encode_connack(packet: ConnAck, version: Literal["3.1.1", "5.0"]) -> bytes: 

136 sp = 0x01 if packet.session_present else 0x00 

137 body = bytes([sp, packet.return_code]) 

138 if version == "5.0": 

139 body += encode_connack_properties(packet.properties) 

140 return _build_packet(PacketType.CONNACK, 0, body) 

141 

142 

143def _encode_publish(packet: Publish, version: Literal["3.1.1", "5.0"]) -> bytes: 

144 flags = (packet.dup << 3) | (packet.qos << 1) | packet.retain 

145 body = encode_str(packet.topic) 

146 if packet.qos != QoS.AT_MOST_ONCE: 

147 if packet.packet_id is None: 

148 msg = "Cannot publish without packet id" 

149 raise ValueError(msg) 

150 body += struct.pack("!H", packet.packet_id) 

151 if version == "5.0": 

152 body += encode_publish_properties(packet.properties) 

153 body += packet.payload 

154 return _build_packet(PacketType.PUBLISH, flags, body) 

155 

156 

157def _encode_pub_ack_variant( 

158 packet_type: PacketType, 

159 flags: int, 

160 packet_id: int, 

161 reason_code: int, 

162 properties: object, 

163 version: Literal["3.1.1", "5.0"], 

164) -> bytes: 

165 if version == "5.0" and (reason_code != 0 or properties is not None): 

166 body = struct.pack("!HB", packet_id, reason_code) 

167 body += encode_puback_properties(properties) # type: ignore[arg-type] 

168 return _build_packet(packet_type, flags, body) 

169 return _packet_id_only(packet_type, flags, packet_id) 

170 

171 

172def _encode_subscribe(packet: Subscribe, version: Literal["3.1.1", "5.0"]) -> bytes: 

173 body = struct.pack("!H", packet.packet_id) 

174 if version == "5.0": 

175 body += encode_subscribe_properties(packet.properties) 

176 for sub in packet.subscriptions: 

177 body += encode_str(sub.topic_filter) 

178 if version == "5.0": 

179 options = sub.qos | (sub.no_local << 2) | (sub.retain_as_published << 3) | (sub.retain_handling << 4) 

180 else: 

181 options = sub.qos 

182 body += bytes([options]) 

183 return _build_packet(PacketType.SUBSCRIBE, 0b0010, body) 

184 

185 

186def _encode_suback(packet: SubAck, version: Literal["3.1.1", "5.0"]) -> bytes: 

187 body = struct.pack("!H", packet.packet_id) 

188 if version == "5.0": 

189 body += encode_suback_properties(packet.properties) 

190 body += bytes(packet.return_codes) 

191 return _build_packet(PacketType.SUBACK, 0, body) 

192 

193 

194def _encode_unsubscribe(packet: Unsubscribe, version: Literal["3.1.1", "5.0"]) -> bytes: 

195 body = struct.pack("!H", packet.packet_id) 

196 if version == "5.0": 

197 body += encode_unsubscribe_properties(packet.properties) 

198 for topic in packet.topic_filters: 

199 body += encode_str(topic) 

200 return _build_packet(PacketType.UNSUBSCRIBE, 0b0010, body) 

201 

202 

203def _encode_unsuback(packet: UnsubAck, version: Literal["3.1.1", "5.0"]) -> bytes: 

204 if version == "5.0": 

205 body = struct.pack("!H", packet.packet_id) 

206 body += encode_unsuback_properties(packet.properties) 

207 body += bytes(packet.reason_codes) 

208 return _build_packet(PacketType.UNSUBACK, 0, body) 

209 return _packet_id_only(PacketType.UNSUBACK, 0, packet.packet_id) 

210 

211 

212def _encode_disconnect(packet: Disconnect, version: Literal["3.1.1", "5.0"]) -> bytes: 

213 if version == "5.0" and (packet.reason_code != 0 or packet.properties is not None): 

214 body = bytes([packet.reason_code]) + encode_disconnect_properties( 

215 packet.properties, 

216 ) 

217 return _build_packet(PacketType.DISCONNECT, 0, body) 

218 return _build_packet(PacketType.DISCONNECT, 0, b"") 

219 

220 

221def encode(packet: AnyPacket, *, version: Literal["3.1.1", "5.0"]) -> bytes: 

222 match packet: 

223 case Connect(): 

224 return _encode_connect(packet, version) 

225 case ConnAck(): 

226 return _encode_connack(packet, version) 

227 case Publish(): 

228 return _encode_publish(packet, version) 

229 case PubAck(packet_id=pid, reason_code=rc, properties=props): 

230 return _encode_pub_ack_variant( 

231 PacketType.PUBACK, 

232 0, 

233 pid, 

234 rc, 

235 props, 

236 version, 

237 ) 

238 case PubRec(packet_id=pid, reason_code=rc, properties=props): 

239 return _encode_pub_ack_variant( 

240 PacketType.PUBREC, 

241 0, 

242 pid, 

243 rc, 

244 props, 

245 version, 

246 ) 

247 case PubRel(packet_id=pid, reason_code=rc, properties=props): 

248 return _encode_pub_ack_variant( 

249 PacketType.PUBREL, 

250 0b0010, 

251 pid, 

252 rc, 

253 props, 

254 version, 

255 ) 

256 case PubComp(packet_id=pid, reason_code=rc, properties=props): 

257 return _encode_pub_ack_variant( 

258 PacketType.PUBCOMP, 

259 0, 

260 pid, 

261 rc, 

262 props, 

263 version, 

264 ) 

265 case Subscribe(): 

266 return _encode_subscribe(packet, version) 

267 case SubAck(): 

268 return _encode_suback(packet, version) 

269 case Unsubscribe(): 

270 return _encode_unsubscribe(packet, version) 

271 case UnsubAck(): 

272 return _encode_unsuback(packet, version) 

273 case PingReq(): 

274 return _build_packet(PacketType.PINGREQ, 0, b"") 

275 case PingResp(): 

276 return _build_packet(PacketType.PINGRESP, 0, b"") 

277 case Disconnect(): 

278 return _encode_disconnect(packet, version) 

279 case Auth(): 

280 body = bytes([packet.reason_code]) + encode_auth_properties( 

281 packet.properties, 

282 ) 

283 return _build_packet(PacketType.AUTH, 0, body) 

284 case _: 

285 msg = f"Unknown packet type: {type(packet)}" 

286 raise ValueError(msg) 

287 

288 

289def _decode_connect(buf: bytes | memoryview) -> Connect: 

290 proto_name, pos = decode_str(buf, 0) 

291 if proto_name != "MQTT": 

292 msg = f"Invalid protocol name: {proto_name!r}" 

293 raise ValueError(msg) 

294 proto_level = buf[pos] 

295 if proto_level not in (0x04, 0x05): 

296 msg = f"Unsupported protocol level: {proto_level}" 

297 raise ValueError(msg) 

298 ver: Literal["3.1.1", "5.0"] = "5.0" if proto_level == 0x05 else "3.1.1" 

299 pos += 1 

300 

301 flags = buf[pos] 

302 pos += 1 

303 clean_session = bool(flags & 0x02) 

304 will_flag = bool(flags & 0x04) 

305 will_qos = QoS((flags >> 3) & 0x03) 

306 will_retain = bool(flags & 0x20) 

307 username_flag = bool(flags & 0x80) 

308 password_flag = bool(flags & 0x40) 

309 

310 (keepalive,) = struct.unpack_from("!H", buf, pos) 

311 pos += 2 

312 

313 connect_props = None 

314 if ver == "5.0": 

315 connect_props, n = decode_connect_properties(buf, pos) 

316 pos += n 

317 

318 client_id, n = decode_str(buf, pos) 

319 pos += n 

320 

321 will = None 

322 if will_flag: 

323 will_props = None 

324 if ver == "5.0": 

325 will_props, n = decode_will_properties(buf, pos) 

326 pos += n 

327 topic, n = decode_str(buf, pos) 

328 pos += n 

329 payload, n = decode_bytes_field(buf, pos) 

330 pos += n 

331 will = Will( 

332 topic=topic, 

333 payload=payload, 

334 qos=will_qos, 

335 retain=will_retain, 

336 properties=will_props, 

337 ) 

338 

339 username = None 

340 if username_flag: 

341 username, n = decode_str(buf, pos) 

342 pos += n 

343 

344 password = None 

345 if password_flag: 

346 password, n = decode_bytes_field(buf, pos) 

347 pos += n 

348 

349 return Connect( 

350 client_id=client_id, 

351 clean_session=clean_session, 

352 keepalive=keepalive, 

353 username=username, 

354 password=password, 

355 will=will, 

356 properties=connect_props, 

357 ) 

358 

359 

360def _decode_connack( 

361 buf: bytes | memoryview, 

362 version: Literal["3.1.1", "5.0"], 

363) -> ConnAck: 

364 if len(buf) < 2: 

365 msg = "CONNACK too short" 

366 raise ValueError(msg) 

367 session_present = bool(buf[0] & 0x01) 

368 return_code = buf[1] 

369 props = None 

370 if version == "5.0" and len(buf) > 2: 

371 props, _ = decode_connack_properties(buf, 2) 

372 return ConnAck( 

373 session_present=session_present, 

374 return_code=return_code, 

375 properties=props, 

376 ) 

377 

378 

379def _decode_publish( 

380 buf: bytes | memoryview, 

381 flags: int, 

382 version: Literal["3.1.1", "5.0"], 

383) -> Publish: 

384 dup = bool(flags & 0x08) 

385 qos = QoS((flags >> 1) & 0x03) 

386 retain = bool(flags & 0x01) 

387 

388 topic, pos = decode_str(buf, 0) 

389 

390 packet_id = None 

391 if qos != QoS.AT_MOST_ONCE: 

392 if pos + 2 > len(buf): 

393 msg = "PUBLISH too short for packet ID" 

394 raise ValueError(msg) 

395 (packet_id,) = struct.unpack_from("!H", buf, pos) 

396 pos += 2 

397 

398 props = None 

399 if version == "5.0": 

400 props, n = decode_publish_properties(buf, pos) 

401 pos += n 

402 

403 return Publish( 

404 topic=topic, 

405 payload=bytes(buf[pos:]), 

406 qos=qos, 

407 retain=retain, 

408 dup=dup, 

409 packet_id=packet_id, 

410 properties=props, 

411 ) 

412 

413 

414def _decode_pub_ack_variant( 

415 buf: bytes | memoryview, 

416 version: Literal["3.1.1", "5.0"], 

417) -> tuple[int, int, object]: 

418 """Returns (packet_id, reason_code, properties).""" 

419 if len(buf) < 2: 

420 msg = "Packet too short for packet ID" 

421 raise ValueError(msg) 

422 (packet_id,) = struct.unpack_from("!H", buf, 0) 

423 reason_code = 0 

424 props = None 

425 if version == "5.0" and len(buf) > 2: 

426 reason_code = buf[2] 

427 if len(buf) > 3: 

428 props, _ = decode_puback_properties(buf, 3) 

429 return packet_id, reason_code, props 

430 

431 

432def _decode_subscribe( 

433 buf: bytes | memoryview, 

434 version: Literal["3.1.1", "5.0"], 

435) -> Subscribe: 

436 if len(buf) < 2: 

437 msg = "SUBSCRIBE too short" 

438 raise ValueError(msg) 

439 (packet_id,) = struct.unpack_from("!H", buf, 0) 

440 pos = 2 

441 

442 props = None 

443 if version == "5.0": 

444 props, n = decode_subscribe_properties(buf, pos) 

445 pos += n 

446 

447 subscriptions: list[SubscriptionRequest] = [] 

448 while pos < len(buf): 

449 topic_filter, n = decode_str(buf, pos) 

450 pos += n 

451 if pos >= len(buf): 

452 msg = "SUBSCRIBE missing options byte" 

453 raise ValueError(msg) 

454 options = buf[pos] 

455 pos += 1 

456 qos = QoS(options & 0x03) 

457 if version == "5.0": 

458 no_local = bool(options & 0x04) 

459 retain_as_published = bool(options & 0x08) 

460 retain_handling = RetainHandling((options >> 4) & 0x03) 

461 subscriptions.append( 

462 SubscriptionRequest( 

463 topic_filter=topic_filter, 

464 qos=qos, 

465 no_local=no_local, 

466 retain_as_published=retain_as_published, 

467 retain_handling=retain_handling, 

468 ), 

469 ) 

470 else: 

471 subscriptions.append( 

472 SubscriptionRequest(topic_filter=topic_filter, qos=qos), 

473 ) 

474 return Subscribe( 

475 packet_id=packet_id, 

476 subscriptions=tuple(subscriptions), 

477 properties=props, 

478 ) 

479 

480 

481def _decode_suback(buf: bytes | memoryview, version: Literal["3.1.1", "5.0"]) -> SubAck: 

482 if len(buf) < 2: 

483 msg = "SUBACK too short" 

484 raise ValueError(msg) 

485 (packet_id,) = struct.unpack_from("!H", buf, 0) 

486 pos = 2 

487 props = None 

488 if version == "5.0": 

489 props, n = decode_suback_properties(buf, pos) 

490 pos += n 

491 return SubAck(packet_id=packet_id, return_codes=tuple(buf[pos:]), properties=props) 

492 

493 

494def _decode_unsubscribe( 

495 buf: bytes | memoryview, 

496 version: Literal["3.1.1", "5.0"], 

497) -> Unsubscribe: 

498 if len(buf) < 2: 

499 msg = "UNSUBSCRIBE too short" 

500 raise ValueError(msg) 

501 (packet_id,) = struct.unpack_from("!H", buf, 0) 

502 pos = 2 

503 props = None 

504 if version == "5.0": 

505 props, n = decode_unsubscribe_properties(buf, pos) 

506 pos += n 

507 topic_filters: list[str] = [] 

508 while pos < len(buf): 

509 topic_filter, n = decode_str(buf, pos) 

510 pos += n 

511 topic_filters.append(topic_filter) 

512 return Unsubscribe( 

513 packet_id=packet_id, 

514 topic_filters=tuple(topic_filters), 

515 properties=props, 

516 ) 

517 

518 

519def _decode_unsuback( 

520 buf: bytes | memoryview, 

521 version: Literal["3.1.1", "5.0"], 

522) -> UnsubAck: 

523 if len(buf) < 2: 

524 msg = "UNSUBACK too short" 

525 raise ValueError(msg) 

526 (packet_id,) = struct.unpack_from("!H", buf, 0) 

527 if version == "5.0": 

528 pos = 2 

529 props, n = decode_unsuback_properties(buf, pos) 

530 pos += n 

531 return UnsubAck( 

532 packet_id=packet_id, 

533 reason_codes=tuple(buf[pos:]), 

534 properties=props, 

535 ) 

536 return UnsubAck(packet_id=packet_id) 

537 

538 

539def _decode_disconnect( 

540 buf: bytes | memoryview, 

541 version: Literal["3.1.1", "5.0"], 

542) -> Disconnect: 

543 reason_code = 0 

544 props = None 

545 if version == "5.0" and len(buf) >= 1: 

546 reason_code = buf[0] 

547 if len(buf) > 1: 

548 props, _ = decode_disconnect_properties(buf, 1) 

549 return Disconnect(reason_code=reason_code, properties=props) 

550 

551 

552def decode( 

553 buffer: bytes | memoryview, 

554 *, 

555 version: Literal["3.1.1", "5.0"] = "3.1.1", 

556 max_packet_size: int | None = None, 

557) -> tuple[AnyPacket, int] | None: 

558 """Decode one packet from buffer. 

559 

560 Returns (packet, bytes_consumed) or None if the buffer holds fewer bytes 

561 than the next complete packet requires. Pass version="5.0" when operating 

562 in an MQTT 5.0 session (CONNECT auto-detects its own version regardless). 

563 

564 Raises PacketTooLargeError as soon as the fixed header shows a packet 

565 larger than *max_packet_size*, before its body has to be buffered. 

566 """ 

567 if len(buffer) < 2: 

568 return None 

569 

570 first_byte = buffer[0] 

571 packet_type_val = (first_byte >> 4) & 0x0F 

572 flags = first_byte & 0x0F 

573 

574 # Inline varint decode so we can return None on incomplete data. 

575 remaining_length = 0 

576 multiplier = 1 

577 varint_bytes = 0 

578 for i in range(4): 

579 if 1 + i >= len(buffer): 

580 return None # fixed header not fully received 

581 byte = buffer[1 + i] 

582 remaining_length += (byte & 0x7F) * multiplier 

583 varint_bytes += 1 

584 if byte & 0x80 == 0: 

585 break 

586 multiplier *= 128 

587 else: 

588 msg = "Remaining-length varint exceeds 4 bytes" 

589 raise ValueError(msg) 

590 

591 total = 1 + varint_bytes + remaining_length 

592 if max_packet_size is not None and total > max_packet_size: 

593 raise PacketTooLargeError(total, max_packet_size) 

594 if len(buffer) < total: 

595 return None # packet body not yet fully received 

596 

597 try: 

598 packet_type = PacketType(packet_type_val) 

599 except ValueError as e: 

600 msg = f"Unknown MQTT packet type: {packet_type_val}" 

601 raise ValueError(msg) from e 

602 

603 body = buffer[1 + varint_bytes : total] 

604 

605 match packet_type: 

606 case PacketType.CONNECT: 

607 packet: AnyPacket = _decode_connect(body) 

608 case PacketType.CONNACK: 

609 packet = _decode_connack(body, version) 

610 case PacketType.PUBLISH: 

611 packet = _decode_publish(body, flags, version) 

612 case PacketType.PUBACK: 

613 pid, rc, props = _decode_pub_ack_variant(body, version) 

614 packet = PubAck(packet_id=pid, reason_code=rc, properties=props) # type: ignore[arg-type] 

615 case PacketType.PUBREC: 

616 pid, rc, props = _decode_pub_ack_variant(body, version) 

617 packet = PubRec(packet_id=pid, reason_code=rc, properties=props) # type: ignore[arg-type] 

618 case PacketType.PUBREL: 

619 pid, rc, props = _decode_pub_ack_variant(body, version) 

620 packet = PubRel(packet_id=pid, reason_code=rc, properties=props) # type: ignore[arg-type] 

621 case PacketType.PUBCOMP: 

622 pid, rc, props = _decode_pub_ack_variant(body, version) 

623 packet = PubComp(packet_id=pid, reason_code=rc, properties=props) # type: ignore[arg-type] 

624 case PacketType.SUBSCRIBE: 

625 packet = _decode_subscribe(body, version) 

626 case PacketType.SUBACK: 

627 packet = _decode_suback(body, version) 

628 case PacketType.UNSUBSCRIBE: 

629 packet = _decode_unsubscribe(body, version) 

630 case PacketType.UNSUBACK: 

631 packet = _decode_unsuback(body, version) 

632 case PacketType.PINGREQ: 

633 packet = PingReq() 

634 case PacketType.PINGRESP: 

635 packet = PingResp() 

636 case PacketType.DISCONNECT: 

637 packet = _decode_disconnect(body, version) 

638 case PacketType.AUTH: 

639 if len(body) < 1: 

640 msg = "AUTH too short" 

641 raise ValueError(msg) 

642 auth_rc = body[0] 

643 auth_props = None 

644 if len(body) > 1: 

645 auth_props, _ = decode_auth_properties(body, 1) 

646 packet = Auth(reason_code=auth_rc, properties=auth_props) 

647 case _: 

648 msg = f"Unsupported packet type: {packet_type}" 

649 raise ValueError(msg) 

650 

651 return packet, total