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
« 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."""
3import struct
4from typing import Literal
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
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]
64class PacketTooLargeError(ValueError):
65 """An incoming packet is larger than the receiver's Maximum Packet Size."""
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")
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)
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
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))
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
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)
118 if version == "5.0":
119 var_header += encode_connect_properties(packet.properties)
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)
132 return _build_packet(PacketType.CONNECT, 0, var_header + payload)
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)
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)
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)
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)
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)
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)
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)
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"")
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)
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
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)
310 (keepalive,) = struct.unpack_from("!H", buf, pos)
311 pos += 2
313 connect_props = None
314 if ver == "5.0":
315 connect_props, n = decode_connect_properties(buf, pos)
316 pos += n
318 client_id, n = decode_str(buf, pos)
319 pos += n
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 )
339 username = None
340 if username_flag:
341 username, n = decode_str(buf, pos)
342 pos += n
344 password = None
345 if password_flag:
346 password, n = decode_bytes_field(buf, pos)
347 pos += n
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 )
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 )
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)
388 topic, pos = decode_str(buf, 0)
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
398 props = None
399 if version == "5.0":
400 props, n = decode_publish_properties(buf, pos)
401 pos += n
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 )
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
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
442 props = None
443 if version == "5.0":
444 props, n = decode_subscribe_properties(buf, pos)
445 pos += n
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 )
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)
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 )
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)
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)
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.
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).
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
570 first_byte = buffer[0]
571 packet_type_val = (first_byte >> 4) & 0x0F
572 flags = first_byte & 0x0F
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)
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
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
603 body = buffer[1 + varint_bytes : total]
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)
651 return packet, total