Coverage for src / zmqtt / _internal / protocol.py: 92%
511 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"""Protocol engine: ties codec, transport, and session state together."""
3import asyncio
4import contextlib
5import dataclasses
6import logging
7from collections.abc import AsyncGenerator, Iterable
8from typing import Final, Literal
10from zmqtt._internal import topic_matching
11from zmqtt._internal._compat import wait_for
12from zmqtt._internal.inbound import InboundPublishFlow
13from zmqtt._internal.packets.auth import Auth
14from zmqtt._internal.packets.codec import AnyPacket, PacketTooLargeError, encode
15from zmqtt._internal.packets.connect import ConnAck, Connect
16from zmqtt._internal.packets.disconnect import Disconnect
17from zmqtt._internal.packets.ping import PingReq, PingResp
18from zmqtt._internal.packets.properties import SubscribeProperties
19from zmqtt._internal.packets.publish import PubAck, PubComp, Publish, PubRec, PubRel
20from zmqtt._internal.packets.reader import PacketBuffer
21from zmqtt._internal.packets.subscribe import (
22 SubAck,
23 Subscribe,
24 SubscriptionRequest,
25 UnsubAck,
26 Unsubscribe,
27)
28from zmqtt._internal.routing import InboundRecipient, RequestRouter
29from zmqtt._internal.state import (
30 OutboundQoS2Flight,
31 OutboundQoS2State,
32 QoS1Flight,
33 SessionState,
34)
35from zmqtt._internal.subscription_index import SubscriptionEntry
36from zmqtt._internal.transport.base import Transport
37from zmqtt._internal.types.message import Message
38from zmqtt._internal.types.qos import QoS
39from zmqtt.errors import (
40 MQTTConnectError,
41 MQTTDisconnectedError,
42 MQTTProtocolError,
43 MQTTPublishError,
44 MQTTQoSExceededError,
45 MQTTRetainNotAvailableError,
46 MQTTSubscribeError,
47 MQTTTimeoutError,
48)
50log = logging.getLogger("zmqtt.protocol")
52# see: https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901124
53_PUBLISH_REASON_NAMES: Final[dict[int, str]] = {
54 0x00: "Success",
55 0x10: "No matching subscribers",
56 0x80: "Unspecified error",
57 0x83: "Implementation specific error",
58 0x87: "Not authorized",
59 0x90: "Topic Name invalid",
60 0x91: "Packet Identifier in use",
61 0x97: "Quota exceeded",
62 0x99: "Payload format invalid",
63}
65# MQTT 5.0 §3.11.3
66_UNSUBACK_REASON_NAMES: Final[dict[int, str]] = {
67 0x80: "Unspecified error",
68 0x83: "Implementation specific error",
69 0x87: "Not authorized",
70 0x8F: "Topic Filter invalid",
71 0x91: "Packet Identifier in use",
72}
74# MQTT 5.0 §3.1.2.11.4: DISCONNECT reason code for a packet above the client's Maximum Packet Size.
75_PACKET_TOO_LARGE: Final = 0x95
78class _SubscriptionGuard:
79 def __init__(self) -> None:
80 self.lock = asyncio.Lock()
81 self.users = 0
84class _SubscriptionGuards:
85 """Serialize ownership changes only when topic filters overlap exactly."""
87 def __init__(self) -> None:
88 self._guards: dict[str, _SubscriptionGuard] = {}
90 @contextlib.asynccontextmanager
91 async def hold(self, filters: Iterable[str]) -> AsyncGenerator[None]:
92 entries: list[tuple[str, _SubscriptionGuard]] = []
93 for filter_ in sorted(set(filters)):
94 guard = self._guards.setdefault(filter_, _SubscriptionGuard())
95 guard.users += 1
96 entries.append((filter_, guard))
98 acquired = 0
99 try:
100 for _, guard in entries:
101 await guard.lock.acquire()
102 acquired += 1
103 yield
104 finally:
105 for _, guard in reversed(entries[:acquired]):
106 guard.lock.release()
107 for filter_, guard in entries:
108 guard.users -= 1
109 if guard.users == 0:
110 self._guards.pop(filter_, None)
113def _raise_on_rejected_filters(filters: list[SubscriptionRequest], suback: SubAck) -> None:
114 """Surface SUBACK failure codes (>= 0x80) instead of ignoring them.
116 A rejected filter — most commonly an authorization denial — otherwise looks
117 exactly like a successful subscription and silently never receives anything.
118 Return codes map to filters by position (MQTT 3.1.1 §3.9.3, 5.0 §3.9.2.1).
119 """
120 # strict=False: a non-conforming broker answering with a short code list
121 # should not turn into a ValueError here.
122 failures = {req.topic_filter: code for req, code in zip(filters, suback.return_codes, strict=False) if code >= 0x80}
123 if failures:
124 raise MQTTSubscribeError(failures)
127def _warn_on_rejected_unsubscribe(filters: list[str], unsuback: UnsubAck) -> None:
128 rejected = [
129 f"{f!r} (0x{code:02X} {_UNSUBACK_REASON_NAMES.get(code, 'Unknown')})"
130 for f, code in zip(filters, unsuback.reason_codes, strict=False)
131 if code >= 0x80
132 ]
133 if not rejected:
134 return
135 reason_string = unsuback.properties.reason_string if unsuback.properties is not None else None
136 log.warning(
137 "Broker rejected unsubscribe of %s%s; it may keep delivering messages on these filters",
138 ", ".join(rejected),
139 f" ({reason_string})" if reason_string else "",
140 )
143def _publish_error(packet: PubAck | PubRec) -> MQTTPublishError:
144 return MQTTPublishError(
145 packet.reason_code,
146 _PUBLISH_REASON_NAMES.get(packet.reason_code),
147 packet.properties.reason_string if packet.properties is not None else None,
148 )
151def _raise_on_rejected_puback(puback: PubAck) -> None:
152 """Surface PUBACK failure codes (>= 0x80) instead of ignoring them.
154 A rejected publish otherwise looks exactly like a successful publish.
155 """
156 if puback.reason_code >= 0x80:
157 err = _publish_error(puback)
158 log.debug("QoS 1 ack received with error for packet_id=%d: %s", puback.packet_id, err)
159 raise err
162class MQTTProtocol:
163 """MQTT protocol engine.
165 Lifecycle:
166 1. ``await protocol.connect(packet)`` — handshake, returns ConnAck
167 2. ``await protocol.run()`` — read loop + ping loop (runs until disconnect)
168 3. ``await protocol.disconnect()`` — clean shutdown
170 QoS flows and subscription management are available between steps 1 and 3.
171 """
173 _DEFAULT_SEND_QUOTA: Final = 65_535
175 def __init__(
176 self,
177 transport: Transport,
178 state: SessionState,
179 keepalive: int = 60,
180 ping_timeout: float = 10.0,
181 connect_timeout: float = 30.0,
182 version: Literal["3.1.1", "5.0"] = "3.1.1",
183 stripped_prefixes: tuple[str, ...] = topic_matching._DEFAULT_STRIPPED_PREFIXES,
184 request_router: RequestRouter | None = None,
185 session_replay_buffer_size: int = 1000,
186 session_replay_timeout: float = 30.0,
187 # Inbound limits to enforce; must match those advertised in CONNECT.
188 receive_maximum: int | None = None,
189 maximum_packet_size: int | None = None,
190 ) -> None:
191 self._send_quota = asyncio.Semaphore(self._DEFAULT_SEND_QUOTA)
192 self._send_quota_waiters: set[asyncio.Task[object]] = set()
193 self._transport = transport
194 self._state = state
195 self._keepalive = keepalive
196 self._effective_keepalive = keepalive
197 self._ping_timeout = ping_timeout
198 self._connect_timeout = connect_timeout
199 self._version: Final = version
200 self._stripped_prefixes = stripped_prefixes
201 self.inbound = InboundPublishFlow(
202 connection=self,
203 state=state,
204 request_router=request_router,
205 session_replay_buffer_size=session_replay_buffer_size,
206 session_replay_timeout=session_replay_timeout,
207 receive_maximum=receive_maximum,
208 )
209 self._buf = PacketBuffer(version=version, max_packet_size=maximum_packet_size)
210 self._ping_waiters: list[asyncio.Future[None]] = []
211 self._subscription_guards = _SubscriptionGuards()
212 self._disconnecting = False
213 self._dead = False
214 self._death_cause: Exception | None = None
215 # MQTT 5 §3.2.2.3.4: absent Maximum QoS means the server accepts QoS 2,
216 # and 3.1.1 has no CONNACK properties at all — default to EXACTLY_ONCE
217 # so publish() never has to branch on None.
218 self._max_publish_qos: QoS = QoS.EXACTLY_ONCE
219 # MQTT 5 §3.2.2.3.5: absent Retain Available means retain is supported.
220 self._retain_available = True
221 self.started_event = asyncio.Event()
223 async def connect(self, packet: Connect) -> ConnAck:
224 """Send CONNECT, read and return CONNACK. Raises on failure.
226 Per MQTT 5.0 section 3.2, if the CONNACK is not received within
227 ``connect_timeout`` seconds the connection is presumed dead and
228 ``MQTTTimeoutError`` is raised (mirrors ``ping()``'s PINGRESP timeout).
229 """
230 log.debug("Connecting client %r", packet.client_id)
231 await self._send(self._encode(packet))
232 try:
233 # No asyncio.shield (unlike ping): on timeout the transport is closed and
234 # replaced by _connect_with_retry, so keeping the read coroutine alive is pointless.
235 return await wait_for(self._await_connack(), timeout=self._connect_timeout)
236 except asyncio.TimeoutError as e:
237 msg = "CONNACK not received within timeout"
238 raise MQTTTimeoutError(msg) from e
240 async def _await_connack(self) -> ConnAck:
241 async with self._rejecting_oversized_packets():
242 while True:
243 data = await self._transport.read(4096)
244 self._buf.feed(data)
245 for pkt in self._buf:
246 if not isinstance(pkt, ConnAck):
247 msg = f"Expected CONNACK, got {pkt!r}"
248 raise MQTTProtocolError(msg)
249 if pkt.return_code != 0:
250 raise MQTTConnectError(pkt.return_code, properties=pkt.properties)
251 log.info("Connected with session_present=%s", pkt.session_present)
252 self._effective_keepalive = self._keepalive
253 send_quota = self._DEFAULT_SEND_QUOTA
254 if self._version == "5.0" and pkt.properties is not None:
255 if pkt.properties.server_keep_alive is not None:
256 self._effective_keepalive = pkt.properties.server_keep_alive
257 # Properties present but Maximum QoS absent: spec default is QoS 2.
258 max_qos = pkt.properties.maximum_qos
259 self._max_publish_qos = QoS.EXACTLY_ONCE if max_qos is None else QoS(max_qos)
260 self._retain_available = pkt.properties.retain_available is not False
261 if pkt.properties.receive_maximum is not None:
262 send_quota = pkt.properties.receive_maximum
263 else: # 3.1.1 has no CONNACK properties: no limit.
264 self._max_publish_qos = QoS.EXACTLY_ONCE
265 self._retain_available = True
266 self._send_quota = asyncio.Semaphore(send_quota)
267 self.inbound.begin_session(session_present=pkt.session_present)
268 return pkt
270 @contextlib.asynccontextmanager
271 async def _rejecting_oversized_packets(self) -> AsyncGenerator[None]:
272 """Close with DISCONNECT 0x95 when the broker exceeds our Maximum Packet Size."""
273 try:
274 yield
275 except PacketTooLargeError as e:
276 await self.abort(_PACKET_TOO_LARGE)
277 msg = f"Broker sent a packet of {e.size} bytes, exceeding the Maximum Packet Size of {e.limit} bytes"
278 raise MQTTProtocolError(msg) from e
280 async def run(self) -> None:
281 """Run read loop and ping loop concurrently until disconnection."""
282 read_task = asyncio.create_task(self._read_loop())
283 ping_task = asyncio.create_task(self._ping_loop())
284 self.started_event.set()
285 try:
286 await asyncio.gather(read_task, ping_task)
287 except MQTTProtocolError as e:
288 log.error("Protocol error, closing connection: %s", e) # noqa: TRY400
289 self._death_cause = e
290 raise
291 except Exception as e:
292 self._death_cause = e
293 raise
294 finally:
295 read_task.cancel()
296 ping_task.cancel()
297 await asyncio.gather(read_task, ping_task, return_exceptions=True)
298 self.started_event.clear()
299 self._dead = True
300 self._cancel_pending()
302 async def disconnect(self) -> None:
303 """Send DISCONNECT and close the transport."""
304 self._disconnecting = True
305 with contextlib.suppress(Exception):
306 await self._send(self._encode(Disconnect()))
307 await self._transport.close()
308 log.info("Disconnected")
310 def _cancel_pending(self) -> None: # noqa: C901
311 """Fail all futures awaiting broker responses — called when run() exits."""
312 exc = MQTTDisconnectedError("Connection lost")
313 exc.__cause__ = self._death_cause
314 for sub_f in self._state.pending_subs.values():
315 if not sub_f.done():
316 sub_f.set_exception(exc)
317 for unsub_f in self._state.pending_unsubs.values():
318 if not unsub_f.done():
319 unsub_f.set_exception(exc)
320 for q1_flight in self._state.inflight_qos1.values():
321 if not q1_flight.future.done():
322 q1_flight.future.set_exception(exc)
323 for q2_flight in self._state.inflight_qos2_out.values():
324 if not q2_flight.future.done():
325 q2_flight.future.set_exception(exc)
326 for ping_f in self._ping_waiters:
327 if not ping_f.done():
328 ping_f.set_exception(exc)
329 self._ping_waiters.clear()
330 self.inbound.clear()
331 for waiter in self._send_quota_waiters:
332 waiter.cancel()
333 self._send_quota_waiters.clear()
335 def _ensure_alive(self) -> None:
336 """Refuse new operations once the run loop has exited.
338 _cancel_pending() fails every future that existed when the loop died, but
339 an operation started afterwards would create a fresh future that nothing
340 will ever resolve — the caller would hang forever (a dead client used to
341 hang even in __aexit__, inside unsubscribe()).
342 """
343 if self._dead:
344 msg = "Connection lost"
345 raise MQTTDisconnectedError(msg) from self._death_cause
347 async def _acquire_send_quota(self) -> None:
348 self._ensure_alive()
349 waiter = asyncio.current_task()
350 if waiter is None:
351 msg = "Cannot acquire send quota outside an asyncio task"
352 raise RuntimeError(msg)
353 self._send_quota_waiters.add(waiter)
354 try:
355 await self._send_quota.acquire()
356 except asyncio.CancelledError:
357 self._ensure_alive()
358 raise
359 finally:
360 self._send_quota_waiters.discard(waiter)
362 try:
363 self._ensure_alive()
364 except MQTTDisconnectedError:
365 self._send_quota.release()
366 raise
368 async def publish(self, packet: Publish) -> PubAck | PubComp | None:
369 """
370 Publish a message. Returns PubAck (QoS 1), PubComp (QoS 2), or None (QoS 0).
371 """
372 self._ensure_alive()
373 max_qos = self._max_publish_qos
374 if packet.qos > max_qos:
375 raise MQTTQoSExceededError(requested=int(packet.qos), maximum=int(max_qos))
376 if packet.retain and not self._retain_available:
377 raise MQTTRetainNotAvailableError
378 match packet.qos:
379 case QoS.AT_MOST_ONCE:
380 await self._send(self._encode(packet))
381 log.debug("Published QoS 0 to topic %r", packet.topic)
382 return None
384 case QoS.AT_LEAST_ONCE:
385 await self._acquire_send_quota()
386 qos1_pid: int | None = None
387 try:
388 loop = asyncio.get_running_loop()
389 qos1_pid = self._state.packet_ids.acquire()
390 packet = dataclasses.replace(packet, packet_id=qos1_pid)
391 future: asyncio.Future[PubAck] = loop.create_future()
392 self._state.inflight_qos1[qos1_pid] = QoS1Flight(
393 packet_id=qos1_pid,
394 publish=packet,
395 future=future,
396 )
397 encode_result = self._encode(packet)
398 except Exception:
399 if qos1_pid is not None:
400 self._state.inflight_qos1.pop(qos1_pid, None)
401 self._state.packet_ids.release(qos1_pid)
402 self._send_quota.release()
403 raise
405 await self._send(encode_result)
406 log.debug("Published QoS 1 to topic %r with packet_id=%d", packet.topic, qos1_pid)
407 ack = await future
408 _raise_on_rejected_puback(ack)
409 return ack
411 case QoS.EXACTLY_ONCE:
412 await self._acquire_send_quota()
413 qos2_pid: int | None = None
414 try:
415 loop = asyncio.get_running_loop()
416 qos2_pid = self._state.packet_ids.acquire()
417 packet = dataclasses.replace(packet, packet_id=qos2_pid)
418 future2: asyncio.Future[PubComp] = loop.create_future()
419 self._state.inflight_qos2_out[qos2_pid] = OutboundQoS2Flight(
420 packet_id=qos2_pid,
421 publish=packet,
422 state=OutboundQoS2State.PENDING_PUBREC,
423 future=future2,
424 )
425 encode_result = self._encode(packet)
426 except Exception:
427 if qos2_pid is not None:
428 self._state.inflight_qos2_out.pop(qos2_pid, None)
429 self._state.packet_ids.release(qos2_pid)
430 self._send_quota.release()
431 raise
433 await self._send(encode_result)
434 log.debug("Published QoS 2 to topic %r with packet_id=%d", packet.topic, qos2_pid)
435 return await future2
437 async def subscribe(
438 self,
439 filters: list[SubscriptionRequest],
440 *,
441 queue: asyncio.Queue[Message],
442 auto_ack: bool = True,
443 subscription_identifier: int | None = None,
444 ) -> tuple[SubAck, dict[str, asyncio.Queue[Message]]]:
445 """Send SUBSCRIBE and return (SubAck, {filter: queue}) after broker ACK.
447 Queues are registered before SUBSCRIBE is sent so no messages are lost.
448 Duplicate filters (already subscribed) are logged as warnings and skipped;
449 they are still included in the SUBSCRIBE packet sent to the broker.
451 ``queue`` is shared by all entries in this subscription. When it is full,
452 delivery blocks, which stalls the read loop and ultimately pushes back on
453 the broker through the TCP window.
455 ``subscription_identifier`` (MQTT 5) is sent in the SUBSCRIBE properties;
456 the broker echoes it on every PUBLISH this subscription causes, which lets
457 ``_deliver`` attribute the message to the exact subscription that matched
458 instead of guessing by filter specificity.
459 """
460 async with self._subscription_guards.hold(req.topic_filter for req in filters):
461 result = await self._subscribe(
462 filters,
463 auto_ack=auto_ack,
464 queue=queue,
465 subscription_identifier=subscription_identifier,
466 )
467 await self.inbound.drain()
468 return result
470 async def _subscribe(
471 self,
472 filters: list[SubscriptionRequest],
473 *,
474 auto_ack: bool,
475 queue: asyncio.Queue[Message],
476 subscription_identifier: int | None,
477 ) -> tuple[SubAck, dict[str, asyncio.Queue[Message]]]:
478 new_entries: dict[str, SubscriptionEntry] = {}
480 for req in filters:
481 f = req.topic_filter
482 existing = self._state.subscriptions.get(f)
483 if existing is not None and existing.detached:
484 log.warning(
485 "Filter %r is detached; the new subscription will not receive messages. "
486 "Disconnect and connect the client before subscribing again.",
487 f,
488 )
489 elif existing is not None:
490 log.warning("Filter %r already subscribed (ignored)", f)
491 else:
492 new_entries[f] = SubscriptionEntry(
493 queue=queue,
494 auto_ack=auto_ack,
495 actual_filter=topic_matching._shared_filter_to_actual(f, self._stripped_prefixes),
496 subscription_identifier=subscription_identifier,
497 )
499 self._state.subscriptions.add_many(new_entries)
500 subscribed = False
501 try:
502 suback = await self._send_subscribe(filters, subscription_identifier)
503 subscribed = True
504 return suback, {f: entry.queue for f, entry in new_entries.items()}
505 finally:
506 if not subscribed:
507 for f in new_entries:
508 self._state.subscriptions.remove(f)
510 async def unsubscribe(self, filters: list[str]) -> tuple[tuple[str, ...], UnsubAck] | None:
511 """Remove queues and unsubscribe filters without response observers.
513 Returns the filters sent to the broker with its UNSUBACK, or ``None``
514 when every broker subscription must stay active for request/response
515 routing.
516 """
517 async with self._subscription_guards.hold(filters):
518 return await self._unsubscribe(filters)
520 def detach(self, filters: list[str]) -> dict[str, SubscriptionEntry]:
521 """Keep broker filters while disabling their local delivery."""
522 detached: dict[str, SubscriptionEntry] = {}
523 for filter_ in filters:
524 entry = self._state.subscriptions.get(filter_)
525 if entry is not None:
526 entry.detached = True
527 detached[filter_] = entry
528 return detached
530 def restore_detached(self, entries: dict[str, SubscriptionEntry]) -> None:
531 """Restore local ACK suppression without sending SUBSCRIBE."""
532 self._state.subscriptions.add_many(entries)
534 async def _unsubscribe(self, filters: list[str]) -> tuple[tuple[str, ...], UnsubAck] | None:
535 self._ensure_alive()
536 observed_filters = [f for f in filters if self._state.subscriptions.has_response_observer(f)]
537 broker_filters = [f for f in filters if f not in observed_filters]
538 for f in filters:
539 self._state.subscriptions.remove(f)
541 acknowledged = None
542 if broker_filters:
543 unsuback = await self._send_unsubscribe(broker_filters)
544 _warn_on_rejected_unsubscribe(broker_filters, unsuback)
545 acknowledged = (tuple(broker_filters), unsuback)
546 if observed_filters:
547 requests = [SubscriptionRequest(topic_filter=f, qos=QoS.AT_MOST_ONCE) for f in observed_filters]
548 try:
549 await self._send_subscribe(requests, subscription_identifier=None)
550 except Exception: # noqa: BLE001 - must not discard the UNSUBACK already received
551 log.warning("Restoring response observers %s failed", observed_filters, exc_info=True)
552 return acknowledged
554 async def add_response_observer(self, topic: str) -> None:
555 """Keep an exact response topic subscribed for pending requests."""
556 async with self._subscription_guards.hold([topic]):
557 await self._add_response_observer(topic)
559 async def _add_response_observer(self, topic: str) -> None:
560 self._ensure_alive()
561 if not self._state.subscriptions.add_response_observer(topic):
562 return
563 if self._state.subscriptions.contains(topic):
564 return
565 request = SubscriptionRequest(topic_filter=topic, qos=QoS.AT_MOST_ONCE)
566 subscribed = False
567 try:
568 await self._send_subscribe([request], subscription_identifier=None)
569 subscribed = True
570 finally:
571 if not subscribed:
572 self._state.subscriptions.remove_response_observer(topic)
574 async def remove_response_observer(self, topic: str) -> None:
575 """Release an exact response topic unless an application owns it."""
576 async with self._subscription_guards.hold([topic]):
577 await self._remove_response_observer(topic)
579 async def _remove_response_observer(self, topic: str) -> None:
580 if not self._state.subscriptions.remove_response_observer(topic):
581 return
582 if self._state.subscriptions.contains(topic) or self._dead:
583 return
584 unsuback = await self._send_unsubscribe([topic])
585 _warn_on_rejected_unsubscribe([topic], unsuback)
587 async def _send_subscribe(
588 self,
589 filters: list[SubscriptionRequest],
590 subscription_identifier: int | None,
591 ) -> SubAck:
592 self._ensure_alive()
593 loop = asyncio.get_running_loop()
594 pid = self._state.packet_ids.acquire()
595 future: asyncio.Future[SubAck] = loop.create_future()
596 self._state.pending_subs[pid] = future
597 properties = (
598 SubscribeProperties(subscription_identifier=subscription_identifier)
599 if subscription_identifier is not None
600 else None
601 )
602 try:
603 await self._send(
604 self._encode(
605 Subscribe(packet_id=pid, subscriptions=tuple(filters), properties=properties),
606 ),
607 )
608 log.debug("Sent SUBSCRIBE with packet_id=%d", pid)
609 suback = await future
610 _raise_on_rejected_filters(filters, suback)
611 return suback
612 finally:
613 self._state.pending_subs.pop(pid, None)
614 self._state.packet_ids.release(pid)
616 async def _send_unsubscribe(self, filters: list[str]) -> UnsubAck:
617 self._ensure_alive()
618 pid = self._state.packet_ids.acquire()
619 loop = asyncio.get_running_loop()
620 future: asyncio.Future[UnsubAck] = loop.create_future()
621 self._state.pending_unsubs[pid] = future
622 try:
623 await self._send(
624 encode(
625 Unsubscribe(packet_id=pid, topic_filters=tuple(filters)),
626 version=self._version,
627 ),
628 )
629 log.debug("Sent UNSUBSCRIBE with packet_id=%d", pid)
630 return await future
631 finally:
632 self._state.pending_unsubs.pop(pid, None)
633 self._state.packet_ids.release(pid)
635 async def ping(self, timeout: float | None = None) -> float:
636 """Send PINGREQ and return RTT in seconds when PINGRESP is received."""
637 loop = asyncio.get_running_loop()
638 future: asyncio.Future[None] = loop.create_future()
639 self._ping_waiters.append(future)
640 t0 = loop.time()
641 await self._send(self._encode(PingReq()))
642 log.debug("Sent PINGREQ")
643 try:
644 await wait_for(asyncio.shield(future), timeout=timeout)
645 except asyncio.TimeoutError as e:
646 self._ping_waiters.remove(future)
647 msg = "PINGRESP not received within timeout"
648 raise MQTTTimeoutError(msg) from e
649 return loop.time() - t0
651 async def send_auth(self, packet: Auth) -> None:
652 """Send an AUTH packet (MQTT 5.0 enhanced authentication)."""
653 if self._version != "5.0":
654 msg = f"Feature is not supported for mqtt protocol version {self._version}"
655 raise RuntimeError(
656 msg,
657 )
658 await self._send(self._encode(packet))
659 log.debug("Sent AUTH with reason_code=%d", packet.reason_code)
661 async def _read_loop(self) -> None:
662 async with self._rejecting_oversized_packets():
663 while True:
664 for packet in self._buf:
665 await self._dispatch(packet)
666 try:
667 data = await self._transport.read(4096)
668 except MQTTDisconnectedError:
669 if self._disconnecting:
670 return
671 raise
672 self._buf.feed(data)
674 async def _ping_loop(self) -> None:
675 if self._effective_keepalive == 0:
676 return
677 while True:
678 await asyncio.sleep(self._effective_keepalive)
679 await self.ping(timeout=self._ping_timeout)
681 async def _dispatch(self, packet: AnyPacket) -> None: # noqa: C901
682 log.debug("Received %r", packet)
683 match packet:
684 case Publish():
685 await self._handle_publish(packet)
686 case PubAck():
687 await self._handle_puback(packet)
688 case PubRec():
689 await self._handle_pubrec(packet)
690 case PubRel():
691 await self._handle_pubrel(packet)
692 case PubComp():
693 await self._handle_pubcomp(packet)
694 case SubAck():
695 await self._handle_suback(packet)
696 case UnsubAck():
697 await self._handle_unsuback(packet)
698 case PingResp():
699 self._handle_pingresp()
700 case Disconnect(reason_code=reason_code):
701 # A broker-initiated DISCONNECT (session takeover, keepalive timeout,
702 # admin kick) is a disconnection, not a protocol violation — raise it
703 # as MQTTDisconnectedError so it takes the reconnect path.
704 msg = f"Broker sent DISCONNECT (reason code 0x{reason_code:02X})"
705 raise MQTTDisconnectedError(msg)
706 case Auth():
707 if self._version != "5.0":
708 msg = "Received AUTH packet in MQTT 3.1.1 session"
709 raise MQTTProtocolError(
710 msg,
711 )
712 # AUTH exchange is handled by the caller via auth(); ignore here.
713 case _:
714 msg = f"Unexpected packet from broker: {packet!r}"
715 raise MQTTProtocolError(msg)
717 def _select_recipient(self, publish: Publish) -> InboundRecipient:
718 return self.inbound.select_recipient(publish)
720 async def _handle_publish(self, packet: Publish) -> None:
721 await self.inbound.handle_publish(packet)
723 async def _handle_pubrel(self, packet: PubRel) -> None:
724 await self.inbound.handle_pubrel(packet)
726 async def _handle_puback(self, packet: PubAck) -> None:
727 flight = self._state.inflight_qos1.pop(packet.packet_id, None)
728 if flight is None:
729 msg = f"PUBACK for unknown packet_id {packet.packet_id}"
730 raise MQTTProtocolError(msg)
731 self._state.packet_ids.release(packet.packet_id)
732 self._send_quota.release()
733 if not flight.future.done():
734 flight.future.set_result(packet)
735 log.debug("QoS 1 ack received for packet_id=%d", packet.packet_id)
737 async def _handle_pubrec(self, packet: PubRec) -> None:
738 flight = self._state.inflight_qos2_out.get(packet.packet_id)
739 if flight is None:
740 msg = f"PUBREC for unknown packet_id {packet.packet_id}"
741 raise MQTTProtocolError(msg)
742 if flight.state is not OutboundQoS2State.PENDING_PUBREC:
743 msg = f"PUBREC in wrong state {flight.state} for packet_id {packet.packet_id}"
744 raise MQTTProtocolError(
745 msg,
746 )
747 # Unlike PUBACK/SUBACK, a negative PUBREC has no follow-up packet — MQTT 5
748 # terminates the QoS 2 flow here instead of sending PUBCOMP. The error must
749 # be raised from the handler because it also decides not to send PUBREL below.
750 if packet.reason_code >= 0x80:
751 self._state.inflight_qos2_out.pop(packet.packet_id, None)
752 self._state.packet_ids.release(packet.packet_id)
753 err = _publish_error(packet)
754 self._send_quota.release()
755 if not flight.future.done():
756 flight.future.set_exception(err)
757 log.debug("QoS 2 ack received with error for packet_id=%d: %s", packet.packet_id, err)
758 return
760 flight.state = OutboundQoS2State.PENDING_PUBCOMP
761 await self._send(self._encode(PubRel(packet_id=packet.packet_id)))
762 log.debug("QoS 2 PUBREC received, sent PUBREL for packet_id=%d", packet.packet_id)
764 async def _handle_pubcomp(self, packet: PubComp) -> None:
765 flight = self._state.inflight_qos2_out.pop(packet.packet_id, None)
766 if flight is None:
767 msg = f"PUBCOMP for unknown packet_id {packet.packet_id}"
768 raise MQTTProtocolError(msg)
769 self._state.packet_ids.release(packet.packet_id)
770 self._send_quota.release()
771 if not flight.future.done():
772 flight.future.set_result(packet)
773 log.debug("QoS 2 complete for packet_id=%d", packet.packet_id)
775 async def _handle_suback(self, packet: SubAck) -> None:
776 future = self._state.pending_subs.get(packet.packet_id)
777 if future is None:
778 msg = f"SUBACK for unknown packet_id {packet.packet_id}"
779 raise MQTTProtocolError(msg)
780 future.set_result(packet)
782 async def _handle_unsuback(self, packet: UnsubAck) -> None:
783 future = self._state.pending_unsubs.get(packet.packet_id)
784 if future is None:
785 msg = f"UNSUBACK for unknown packet_id {packet.packet_id}"
786 raise MQTTProtocolError(
787 msg,
788 )
789 future.set_result(packet)
791 def _handle_pingresp(self) -> None:
792 if self._ping_waiters:
793 f = self._ping_waiters.pop(0)
794 if not f.done():
795 f.set_result(None)
796 log.debug("PINGRESP received")
798 def _encode(self, packet: AnyPacket) -> bytes:
799 return encode(packet, version=self._version)
801 async def send_packet(self, packet: AnyPacket) -> None:
802 """Send an encoded packet on behalf of an internal protocol flow."""
803 await self._send(self._encode(packet))
805 async def abort(self, reason_code: int | None = None) -> None:
806 """Close the transport after a terminal failure.
808 On MQTT 5.0, *reason_code* is first sent in a best-effort DISCONNECT.
809 """
810 if reason_code is not None and self._version == "5.0":
811 with contextlib.suppress(Exception):
812 await self._send(self._encode(Disconnect(reason_code=reason_code)))
813 await self._transport.close()
815 async def _send(self, data: bytes) -> None:
816 log.debug("Sending %d bytes", len(data))
817 await self._transport.write(data)