Coverage for src/robot_dispatch/messaging/broker.py: 100%

101 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-07 17:18 +0000

1from __future__ import annotations 

2 

3import asyncio 

4import json 

5from collections.abc import Awaitable, Callable 

6from datetime import UTC, datetime 

7from typing import Any 

8 

9import aio_pika 

10from aio_pika import DeliveryMode, ExchangeType, Message 

11from aio_pika.abc import ( 

12 AbstractChannel, 

13 AbstractExchange, 

14 AbstractIncomingMessage, 

15 AbstractQueue, 

16 AbstractRobustConnection, 

17) 

18 

19from robot_dispatch.logging_setup import get_logger 

20from robot_dispatch.messaging.messages import ( 

21 COMMANDS_EXCHANGE, 

22 DLQ_QUEUE, 

23 DLX_EXCHANGE, 

24 EVENTS_EXCHANGE, 

25 RESULTS_QUEUE, 

26 RETRY_QUEUE, 

27 command_queue_name, 

28 command_routing_key, 

29) 

30 

31logger = get_logger("broker") 

32 

33MessageHandler = Callable[[AbstractIncomingMessage], Awaitable[None]] 

34 

35 

36class Broker: 

37 """RabbitMQ topology for the dispatch service. 

38 

39 robot.commands (direct) --command.<robot_id>--> cmd.<robot_id> (one queue per robot) 

40 robot.events (topic) --result.#/heartbeat.#--> dispatch.results 

41 dispatch.results --reject without requeue--> dispatch.dlx --> dispatch.results.dlq 

42 dispatch.results.retry --per-message TTL--> robot.events/result.retried --> dispatch.results 

43 """ 

44 

45 def __init__( 

46 self, 

47 url: str, 

48 *, 

49 prefetch: int = 20, 

50 connect_retries: int = 10, 

51 connect_delay: float = 2.0, 

52 ) -> None: 

53 self._url = url 

54 self._prefetch = prefetch 

55 self._connect_retries = connect_retries 

56 self._connect_delay = connect_delay 

57 self._connection: AbstractRobustConnection | None = None 

58 self._channel: AbstractChannel | None = None 

59 self._exchanges: dict[str, AbstractExchange] = {} 

60 self.results_queue: AbstractQueue | None = None 

61 self.retry_queue: AbstractQueue | None = None 

62 

63 @property 

64 def connected(self) -> bool: 

65 return self._connection is not None and not self._connection.is_closed 

66 

67 async def connect(self) -> None: 

68 last_error: Exception | None = None 

69 for attempt in range(1, self._connect_retries + 1): 

70 try: 

71 self._connection = await aio_pika.connect_robust(self._url, timeout=30) 

72 self._channel = await self._connection.channel(publisher_confirms=True) 

73 await self._channel.set_qos(prefetch_count=self._prefetch) 

74 await self._declare_topology() 

75 logger.info("connected to rabbitmq", attempt=attempt) 

76 return 

77 except Exception as exc: # noqa: BLE001 - broker may not be up yet 

78 last_error = exc 

79 logger.warning("rabbitmq connection failed, retrying", attempt=attempt, error=str(exc)) 

80 await asyncio.sleep(self._connect_delay) 

81 raise RuntimeError(f"cannot connect to rabbitmq: {last_error}") 

82 

83 async def close(self) -> None: 

84 if self._connection is not None and not self._connection.is_closed: 

85 await self._connection.close() 

86 self._connection = None 

87 self._channel = None 

88 self._exchanges.clear() 

89 

90 async def _declare_topology(self) -> None: 

91 assert self._channel is not None 

92 channel = self._channel 

93 

94 commands = await channel.declare_exchange(COMMANDS_EXCHANGE, ExchangeType.DIRECT, durable=True) 

95 events = await channel.declare_exchange(EVENTS_EXCHANGE, ExchangeType.TOPIC, durable=True) 

96 dlx = await channel.declare_exchange(DLX_EXCHANGE, ExchangeType.DIRECT, durable=True) 

97 self._exchanges = {COMMANDS_EXCHANGE: commands, EVENTS_EXCHANGE: events, DLX_EXCHANGE: dlx} 

98 

99 dlq = await channel.declare_queue(DLQ_QUEUE, durable=True) 

100 await dlq.bind(dlx, routing_key="dead") 

101 

102 results = await channel.declare_queue( 

103 RESULTS_QUEUE, 

104 durable=True, 

105 arguments={"x-dead-letter-exchange": DLX_EXCHANGE, "x-dead-letter-routing-key": "dead"}, 

106 ) 

107 await results.bind(events, routing_key="result.#") 

108 await results.bind(events, routing_key="heartbeat.#") 

109 self.results_queue = results 

110 

111 retry = await channel.declare_queue( 

112 RETRY_QUEUE, 

113 durable=True, 

114 arguments={ 

115 "x-dead-letter-exchange": EVENTS_EXCHANGE, 

116 "x-dead-letter-routing-key": "result.retried", 

117 }, 

118 ) 

119 await retry.bind(events, routing_key="result.retry") 

120 self.retry_queue = retry 

121 

122 async def ensure_robot_queue(self, robot_id: Any) -> None: 

123 """Idempotently create the per-robot command queue.""" 

124 assert self._channel is not None 

125 queue = await self._channel.declare_queue( 

126 command_queue_name(robot_id), 

127 durable=True, 

128 arguments={"x-dead-letter-exchange": DLX_EXCHANGE, "x-dead-letter-routing-key": "dead"}, 

129 ) 

130 exchange = self._exchanges[COMMANDS_EXCHANGE] 

131 await queue.bind(exchange, routing_key=command_routing_key(robot_id)) 

132 

133 async def publish( 

134 self, 

135 *, 

136 exchange: str, 

137 routing_key: str, 

138 payload: dict[str, Any], 

139 message_id: str | None = None, 

140 headers: dict[str, Any] | None = None, 

141 expiration_ms: int | None = None, 

142 ) -> None: 

143 target = self._exchanges.get(exchange) 

144 if target is None: 

145 raise KeyError(f"unknown exchange {exchange}") 

146 message = Message( 

147 body=json.dumps(payload, default=str).encode(), 

148 content_type="application/json", 

149 delivery_mode=DeliveryMode.PERSISTENT, 

150 message_id=message_id, 

151 headers=_sanitize_headers(headers), 

152 expiration=expiration_ms, 

153 timestamp=datetime.now(tz=UTC), 

154 ) 

155 await target.publish(message, routing_key=routing_key) 

156 

157 async def publish_raw( 

158 self, 

159 *, 

160 queue: str, 

161 body: bytes, 

162 headers: dict[str, Any] | None = None, 

163 expiration_ms: int | None = None, 

164 message_id: str | None = None, 

165 ) -> None: 

166 """Publish straight to a queue through the default exchange (used for delayed retries).""" 

167 assert self._channel is not None 

168 message = Message( 

169 body=body, 

170 content_type="application/json", 

171 delivery_mode=DeliveryMode.PERSISTENT, 

172 message_id=message_id, 

173 headers=_sanitize_headers(headers), 

174 expiration=expiration_ms, 

175 timestamp=datetime.now(tz=UTC), 

176 ) 

177 await self._channel.default_exchange.publish(message, routing_key=queue) 

178 

179 async def consume(self, handler: MessageHandler) -> None: 

180 if self.results_queue is None: 

181 raise RuntimeError("broker is not connected") 

182 await self.results_queue.consume(handler, no_ack=False) 

183 

184 async def queue_depth(self, name: str) -> int | None: 

185 if self._channel is None: 

186 return None 

187 try: 

188 queue = await self._channel.declare_queue(name, durable=True, passive=True) 

189 except Exception: # noqa: BLE001 - queue may not exist yet 

190 return None 

191 declaration = queue.declaration_result 

192 return int(getattr(declaration, "message_count", 0) or 0) 

193 

194 

195def _sanitize_headers(headers: dict[str, Any] | None) -> dict[str, Any]: 

196 """AMQP headers must be primitives; UUIDs and enums are stringified.""" 

197 if not headers: 

198 return {} 

199 clean: dict[str, Any] = {} 

200 for key, value in headers.items(): 

201 if isinstance(value, (str, int, float, bool, bytes)) or value is None: 

202 clean[key] = value 

203 else: 

204 clean[key] = str(value) 

205 return clean