Coverage for src / zmqtt / _internal / request_response.py: 90%

143 statements  

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

1"""Correlation-based routing for MQTT 5.0 request/response messages.""" 

2 

3import asyncio 

4from dataclasses import dataclass, field 

5from typing import Protocol, TypeAlias 

6 

7from zmqtt._internal.types.message import Message 

8from zmqtt.errors import MQTTDisconnectedError 

9 

10_RequestKey: TypeAlias = tuple[str, bytes] 

11 

12 

13class _ResponseSubscriptionManager(Protocol): 

14 async def add_response_observer(self, topic: str) -> None: ... 

15 

16 async def remove_response_observer(self, topic: str) -> None: ... 

17 

18 

19@dataclass(slots=True) 

20class _PendingRequest: 

21 """A registered response waiter with explicit, idempotent cleanup.""" 

22 

23 future: asyncio.Future[Message] 

24 _dispatcher: "_RequestDispatcher" 

25 _key: _RequestKey 

26 _closed: bool = field(default=False, init=False) 

27 claimed: bool = field(default=False, init=False) 

28 

29 async def close(self) -> None: 

30 if self._closed: 

31 return 

32 self._closed = True 

33 try: 

34 await self._dispatcher.unregister(self._key, self) 

35 finally: 

36 if self.future.done() and not self.future.cancelled(): 

37 self.future.exception() 

38 

39 

40@dataclass(slots=True) 

41class _TopicInterest: 

42 """Shared broker-subscription readiness for one response topic.""" 

43 

44 refcount: int = 0 

45 ready: asyncio.Task[None] | None = None 

46 

47 

48@dataclass(slots=True) 

49class _ClaimedResponse: 

50 """A response reserved for one pending request on one connection.""" 

51 

52 dispatcher: "_RequestDispatcher" 

53 pending: _PendingRequest 

54 key: _RequestKey 

55 message: Message 

56 generation: int 

57 

58 def deliver(self) -> None: 

59 self.dispatcher.complete(self) 

60 

61 

62class _RequestDispatcher: 

63 """Route matching responses exclusively to request futures. 

64 

65 Only active waiters are retained. Incoming messages without a matching 

66 waiter are not buffered here and remain available to ordinary subscription 

67 routing, so late and unsolicited responses cannot grow dispatcher state. 

68 """ 

69 

70 def __init__(self, max_pending_requests: int) -> None: 

71 if max_pending_requests <= 0: 

72 msg = "max_pending_requests must be positive" 

73 raise ValueError(msg) 

74 self._capacity = asyncio.Semaphore(max_pending_requests) 

75 self._pending: dict[_RequestKey, _PendingRequest] = {} 

76 self._topics: dict[str, _TopicInterest] = {} 

77 self._protocol: _ResponseSubscriptionManager | None = None 

78 self._generation = 0 

79 

80 @property 

81 def pending_count(self) -> int: 

82 return len(self._pending) 

83 

84 def bind(self, protocol: _ResponseSubscriptionManager) -> None: 

85 """Bind the dispatcher to the current connection's protocol engine.""" 

86 self._protocol = protocol 

87 self._generation += 1 

88 for pending in self._pending.values(): 

89 pending.claimed = False 

90 for interest in self._topics.values(): 

91 interest.ready = None 

92 

93 async def restore(self) -> None: 

94 """Restore response-topic interests after protocol reconnection.""" 

95 for topic, interest in tuple(self._topics.items()): 

96 if interest.refcount > 0: 

97 await asyncio.shield(self._ensure_topic_ready(topic, interest)) 

98 

99 async def register(self, topic: str, correlation_data: bytes) -> _PendingRequest: 

100 """Register a bounded response waiter before its request is published.""" 

101 await self._capacity.acquire() 

102 key = (topic, correlation_data) 

103 pending: _PendingRequest | None = None 

104 registered = False 

105 try: 

106 self._ensure_unique(key) 

107 self._require_protocol() 

108 

109 interest = self._topics.get(topic) 

110 if interest is None: 

111 interest = _TopicInterest() 

112 self._topics[topic] = interest 

113 

114 pending = _PendingRequest( 

115 future=asyncio.get_running_loop().create_future(), 

116 _dispatcher=self, 

117 _key=key, 

118 ) 

119 self._pending[key] = pending 

120 interest.refcount += 1 

121 await asyncio.shield(self._ensure_topic_ready(topic, interest)) 

122 registered = True 

123 return pending 

124 finally: 

125 if not registered: 

126 if pending is None: 

127 self._capacity.release() 

128 else: 

129 await self.unregister(key, pending) 

130 

131 def claim(self, message: Message) -> _ClaimedResponse | None: 

132 """Atomically reserve a matching waiter and return the claimed response.""" 

133 properties = message.properties 

134 if properties is None or properties.correlation_data is None: 

135 return None 

136 

137 key = (message.topic, properties.correlation_data) 

138 pending = self._pending.get(key) 

139 if pending is None or pending.claimed or pending.future.done(): 

140 return None 

141 pending.claimed = True 

142 return _ClaimedResponse( 

143 dispatcher=self, 

144 pending=pending, 

145 key=key, 

146 message=message, 

147 generation=self._generation, 

148 ) 

149 

150 def complete(self, response: _ClaimedResponse) -> None: 

151 """Deliver a claimed response if it still belongs to this connection.""" 

152 if ( 

153 self._generation == response.generation 

154 and self._pending.get(response.key) is response.pending 

155 and not response.pending.future.done() 

156 ): 

157 response.pending.future.set_result(response.message) 

158 

159 async def unregister( 

160 self, 

161 key: _RequestKey, 

162 pending: _PendingRequest, 

163 ) -> None: 

164 """Remove one waiter and release its response-topic interest.""" 

165 removed = False 

166 try: 

167 if self._pending.get(key) is not pending: 

168 return 

169 

170 removed = True 

171 del self._pending[key] 

172 if not pending.future.done(): 

173 pending.future.cancel() 

174 

175 topic = key[0] 

176 interest = self._topics[topic] 

177 interest.refcount -= 1 

178 if interest.refcount > 0: 

179 return 

180 

181 observer_active = False 

182 try: 

183 ready = interest.ready 

184 if ready is not None: 

185 await asyncio.shield(ready) 

186 observer_active = True 

187 finally: 

188 # A new waiter may have joined while the initial SUBACK was 

189 # pending. In that case it inherits the same topic interest. 

190 if interest.refcount == 0 and self._topics.get(topic) is interest: 

191 del self._topics[topic] 

192 protocol = self._protocol 

193 if observer_active and protocol is not None: 

194 await protocol.remove_response_observer(topic) 

195 finally: 

196 if removed: 

197 self._capacity.release() 

198 

199 async def cancel_pending(self) -> None: 

200 """Fail and forget every waiter when the client shuts down.""" 

201 pending = tuple(self._pending.values()) 

202 ready_tasks = tuple(interest.ready for interest in self._topics.values() if interest.ready is not None) 

203 self._pending.clear() 

204 self._topics.clear() 

205 self._protocol = None 

206 self._generation += 1 

207 for request in pending: 

208 if not request.future.done(): 

209 request.future.set_exception(MQTTDisconnectedError("Client disconnected")) 

210 self._capacity.release() 

211 for task in ready_tasks: 

212 task.cancel() 

213 await asyncio.gather(*ready_tasks, return_exceptions=True) 

214 

215 def _ensure_topic_ready(self, topic: str, interest: _TopicInterest) -> asyncio.Task[None]: 

216 ready = interest.ready 

217 if ready is None: 

218 protocol = self._require_protocol() 

219 ready = asyncio.create_task(protocol.add_response_observer(topic)) 

220 interest.ready = ready 

221 return ready 

222 

223 def _require_protocol(self) -> _ResponseSubscriptionManager: 

224 if self._protocol is None: 

225 msg = "Not connected" 

226 raise MQTTDisconnectedError(msg) 

227 return self._protocol 

228 

229 def _ensure_unique(self, key: _RequestKey) -> None: 

230 if key in self._pending: 

231 msg = "correlation_data is already in use for this response_topic" 

232 raise ValueError(msg)