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
« 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."""
3import asyncio
4from dataclasses import dataclass, field
5from typing import Protocol, TypeAlias
7from zmqtt._internal.types.message import Message
8from zmqtt.errors import MQTTDisconnectedError
10_RequestKey: TypeAlias = tuple[str, bytes]
13class _ResponseSubscriptionManager(Protocol):
14 async def add_response_observer(self, topic: str) -> None: ...
16 async def remove_response_observer(self, topic: str) -> None: ...
19@dataclass(slots=True)
20class _PendingRequest:
21 """A registered response waiter with explicit, idempotent cleanup."""
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)
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()
40@dataclass(slots=True)
41class _TopicInterest:
42 """Shared broker-subscription readiness for one response topic."""
44 refcount: int = 0
45 ready: asyncio.Task[None] | None = None
48@dataclass(slots=True)
49class _ClaimedResponse:
50 """A response reserved for one pending request on one connection."""
52 dispatcher: "_RequestDispatcher"
53 pending: _PendingRequest
54 key: _RequestKey
55 message: Message
56 generation: int
58 def deliver(self) -> None:
59 self.dispatcher.complete(self)
62class _RequestDispatcher:
63 """Route matching responses exclusively to request futures.
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 """
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
80 @property
81 def pending_count(self) -> int:
82 return len(self._pending)
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
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))
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()
109 interest = self._topics.get(topic)
110 if interest is None:
111 interest = _TopicInterest()
112 self._topics[topic] = interest
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)
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
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 )
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)
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
170 removed = True
171 del self._pending[key]
172 if not pending.future.done():
173 pending.future.cancel()
175 topic = key[0]
176 interest = self._topics[topic]
177 interest.refcount -= 1
178 if interest.refcount > 0:
179 return
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()
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)
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
223 def _require_protocol(self) -> _ResponseSubscriptionManager:
224 if self._protocol is None:
225 msg = "Not connected"
226 raise MQTTDisconnectedError(msg)
227 return self._protocol
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)