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

1"""Protocol engine: ties codec, transport, and session state together.""" 

2 

3import asyncio 

4import contextlib 

5import dataclasses 

6import logging 

7from collections.abc import AsyncGenerator, Iterable 

8from typing import Final, Literal 

9 

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) 

49 

50log = logging.getLogger("zmqtt.protocol") 

51 

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} 

64 

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} 

73 

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 

76 

77 

78class _SubscriptionGuard: 

79 def __init__(self) -> None: 

80 self.lock = asyncio.Lock() 

81 self.users = 0 

82 

83 

84class _SubscriptionGuards: 

85 """Serialize ownership changes only when topic filters overlap exactly.""" 

86 

87 def __init__(self) -> None: 

88 self._guards: dict[str, _SubscriptionGuard] = {} 

89 

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)) 

97 

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) 

111 

112 

113def _raise_on_rejected_filters(filters: list[SubscriptionRequest], suback: SubAck) -> None: 

114 """Surface SUBACK failure codes (>= 0x80) instead of ignoring them. 

115 

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) 

125 

126 

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 ) 

141 

142 

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 ) 

149 

150 

151def _raise_on_rejected_puback(puback: PubAck) -> None: 

152 """Surface PUBACK failure codes (>= 0x80) instead of ignoring them. 

153 

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 

160 

161 

162class MQTTProtocol: 

163 """MQTT protocol engine. 

164 

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 

169 

170 QoS flows and subscription management are available between steps 1 and 3. 

171 """ 

172 

173 _DEFAULT_SEND_QUOTA: Final = 65_535 

174 

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() 

222 

223 async def connect(self, packet: Connect) -> ConnAck: 

224 """Send CONNECT, read and return CONNACK. Raises on failure. 

225 

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 

239 

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 

269 

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 

279 

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() 

301 

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") 

309 

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() 

334 

335 def _ensure_alive(self) -> None: 

336 """Refuse new operations once the run loop has exited. 

337 

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 

346 

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) 

361 

362 try: 

363 self._ensure_alive() 

364 except MQTTDisconnectedError: 

365 self._send_quota.release() 

366 raise 

367 

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 

383 

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 

404 

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 

410 

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 

432 

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 

436 

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. 

446 

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. 

450 

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. 

454 

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 

469 

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] = {} 

479 

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 ) 

498 

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) 

509 

510 async def unsubscribe(self, filters: list[str]) -> tuple[tuple[str, ...], UnsubAck] | None: 

511 """Remove queues and unsubscribe filters without response observers. 

512 

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) 

519 

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 

529 

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) 

533 

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) 

540 

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 

553 

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) 

558 

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) 

573 

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) 

578 

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) 

586 

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) 

615 

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) 

634 

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 

650 

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) 

660 

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) 

673 

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) 

680 

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) 

716 

717 def _select_recipient(self, publish: Publish) -> InboundRecipient: 

718 return self.inbound.select_recipient(publish) 

719 

720 async def _handle_publish(self, packet: Publish) -> None: 

721 await self.inbound.handle_publish(packet) 

722 

723 async def _handle_pubrel(self, packet: PubRel) -> None: 

724 await self.inbound.handle_pubrel(packet) 

725 

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) 

736 

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 

759 

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) 

763 

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) 

774 

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) 

781 

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) 

790 

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") 

797 

798 def _encode(self, packet: AnyPacket) -> bytes: 

799 return encode(packet, version=self._version) 

800 

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)) 

804 

805 async def abort(self, reason_code: int | None = None) -> None: 

806 """Close the transport after a terminal failure. 

807 

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() 

814 

815 async def _send(self, data: bytes) -> None: 

816 log.debug("Sending %d bytes", len(data)) 

817 await self._transport.write(data)