Coverage for faststream/kafka/publisher/usecase.py: 97%

65 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-17 21:20 +0000

1from collections.abc import Callable, Iterable, Mapping 

2from typing import TYPE_CHECKING, Any, Literal, Union, cast, overload 

3 

4from typing_extensions import override 

5 

6from faststream._internal.endpoint.publisher import PublisherUsecase 

7from faststream._internal.kafka import KafkaCallAssertions 

8from faststream._internal.types import P_HandlerParams, T_HandlerReturn 

9from faststream.kafka.call_wrapper import KafkaHandlerCallWrapper 

10from faststream.kafka.response import KafkaPublishCommand 

11from faststream.response.publish_type import PublishType 

12 

13if TYPE_CHECKING: 

14 import asyncio 

15 

16 from aiokafka.structs import RecordMetadata 

17 

18 from faststream._internal.basic_types import SendableMessage 

19 from faststream._internal.endpoint.publisher import PublisherSpecification 

20 from faststream._internal.types import PublisherMiddleware 

21 from faststream.kafka.message import KafkaMessage 

22 from faststream.kafka.types import KafkaSendableMessage 

23 from faststream.response.response import PublishCommand 

24 

25 from .config import KafkaPublisherConfig 

26 from .producer import AioKafkaFastProducer 

27 

28 

29class LogicPublisher(KafkaCallAssertions, PublisherUsecase): 

30 """A class to publish messages to a Kafka topic.""" 

31 

32 __slots__ = ( 

33 "_topic", 

34 "headers", 

35 "partition", 

36 "reply_to", 

37 ) 

38 

39 _call_wrapper_class = KafkaHandlerCallWrapper 

40 _read_field = KafkaHandlerCallWrapper._read_field 

41 

42 def __init__( 

43 self, 

44 config: "KafkaPublisherConfig", 

45 specification: "PublisherSpecification[Any, Any]", 

46 ) -> None: 

47 super().__init__(config, specification) 

48 

49 self._topic = config.topic 

50 self.partition = config.partition 

51 self.reply_to = config.reply_to 

52 self.headers = dict(config.headers or {}) 

53 

54 @override 

55 def __call__( 

56 self, 

57 func: Callable[P_HandlerParams, T_HandlerReturn], 

58 ) -> "KafkaHandlerCallWrapper[P_HandlerParams, T_HandlerReturn]": 

59 # The base builds the wrapper from `_call_wrapper_class`; this only narrows the name 

60 return cast( 

61 "KafkaHandlerCallWrapper[P_HandlerParams, T_HandlerReturn]", 

62 super().__call__(func), 

63 ) 

64 

65 @property 

66 def topic(self) -> str: 

67 return f"{self._outer_config.prefix}{self._topic}" 

68 

69 @override 

70 async def request( 

71 self, 

72 message: "SendableMessage", 

73 topic: str = "", 

74 *, 

75 key: bytes | Any | None = None, 

76 partition: int | None = None, 

77 timestamp_ms: int | None = None, 

78 headers: Mapping[str, str | bytes | None] | None = None, 

79 correlation_id: str | None = None, 

80 timeout: float = 0.5, 

81 ) -> "KafkaMessage": 

82 """Send a request message to Kafka topic. 

83 

84 Args: 

85 message: Message body to send. 

86 topic: Topic where the message will be published. 

87 key: A key to associate with the message. Can be used to 

88 determine which partition to send the message to. If partition 

89 is `None` (and producer's partitioner config is left as default), 

90 then messages with the same key will be delivered to the same 

91 partition (but if key is `None`, partition is chosen randomly). 

92 Must be type `bytes`, or be serializable to bytes via configured 

93 `key_serializer`. 

94 partition: Specify a partition. If not set, the partition will be 

95 selected using the configured `partitioner`. 

96 timestamp_ms: Epoch milliseconds (from Jan 1 1970 UTC) to use as 

97 the message timestamp. Defaults to current time. 

98 headers: Message headers to store metainformation. 

99 correlation_id: Manual message **correlation_id** setter. 

100 **correlation_id** is a useful option to trace messages. 

101 timeout: Timeout to send RPC request. 

102 

103 Returns: 

104 KafkaMessage: The response message. 

105 """ 

106 cmd = KafkaPublishCommand( 

107 message, 

108 topic=topic or self.topic, 

109 key=key, 

110 partition=partition if partition is not None else self.partition, 

111 headers=self.headers | dict(headers or {}), 

112 correlation_id=correlation_id or self._outer_config.id_generator(), 

113 timestamp_ms=timestamp_ms, 

114 timeout=timeout, 

115 _publish_type=PublishType.REQUEST, 

116 ) 

117 

118 msg: KafkaMessage = await self._basic_request( 

119 cmd, 

120 producer=self._outer_config.producer, 

121 ) 

122 return msg 

123 

124 async def flush(self) -> None: 

125 producer = cast("AioKafkaFastProducer", self._outer_config.producer) 

126 await producer.flush() 

127 

128 

129class DefaultPublisher(LogicPublisher): 

130 __slots__ = () 

131 

132 def __init__( 

133 self, 

134 config: "KafkaPublisherConfig", 

135 specification: "PublisherSpecification[Any, Any]", 

136 ) -> None: 

137 super().__init__(config, specification) 

138 

139 self.key = config.key 

140 

141 @overload 

142 async def publish( 

143 self, 

144 message: "SendableMessage", 

145 topic: str = "", 

146 *, 

147 key: bytes | Any | None = None, 

148 partition: int | None = None, 

149 timestamp_ms: int | None = None, 

150 headers: Mapping[str, str | bytes | None] | None = None, 

151 correlation_id: str | None = None, 

152 reply_to: str = "", 

153 no_confirm: Literal[False] = False, 

154 ) -> "RecordMetadata": ... 

155 

156 @overload 

157 async def publish( 

158 self, 

159 message: "SendableMessage", 

160 topic: str = "", 

161 *, 

162 key: bytes | Any | None = None, 

163 partition: int | None = None, 

164 timestamp_ms: int | None = None, 

165 headers: Mapping[str, str | bytes | None] | None = None, 

166 correlation_id: str | None = None, 

167 reply_to: str = "", 

168 no_confirm: Literal[True] = ..., 

169 ) -> "asyncio.Future[RecordMetadata]": ... 

170 

171 @overload 

172 async def publish( 

173 self, 

174 message: "SendableMessage", 

175 topic: str = "", 

176 *, 

177 key: bytes | Any | None = None, 

178 partition: int | None = None, 

179 timestamp_ms: int | None = None, 

180 headers: Mapping[str, str | bytes | None] | None = None, 

181 correlation_id: str | None = None, 

182 reply_to: str = "", 

183 no_confirm: bool = False, 

184 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]: ... 

185 

186 @override 

187 async def publish( 

188 self, 

189 message: "SendableMessage", 

190 topic: str = "", 

191 *, 

192 key: bytes | Any | None = None, 

193 partition: int | None = None, 

194 timestamp_ms: int | None = None, 

195 headers: Mapping[str, str | bytes | None] | None = None, 

196 correlation_id: str | None = None, 

197 reply_to: str = "", 

198 no_confirm: bool = False, 

199 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]: 

200 """Publishes a message to Kafka. 

201 

202 Args: 

203 message: 

204 Message body to send. 

205 topic: 

206 Topic where the message will be published. 

207 key: 

208 A key to associate with the message. Can be used to 

209 determine which partition to send the message to. If partition 

210 is `None` (and producer's partitioner config is left as default), 

211 then messages with the same key will be delivered to the same 

212 partition (but if key is `None`, partition is chosen randomly). 

213 Must be type `bytes`, or be serializable to bytes via configured 

214 `key_serializer` 

215 partition: 

216 Specify a partition. If not set, the partition will be 

217 selected using the configured `partitioner` 

218 timestamp_ms: 

219 Epoch milliseconds (from Jan 1 1970 UTC) to use as 

220 the message timestamp. Defaults to current time. 

221 headers: 

222 Message headers to store metainformation. 

223 correlation_id: 

224 Manual message **correlation_id** setter. 

225 **correlation_id** is a useful option to trace messages. 

226 reply_to: 

227 Reply message topic name to send response. 

228 no_confirm: 

229 Do not wait for Kafka publish confirmation. 

230 

231 Returns: 

232 `asyncio.Future[RecordMetadata]` if no_confirm = True. 

233 `RecordMetadata` if no_confirm = False. 

234 """ 

235 cmd = KafkaPublishCommand( 

236 message, 

237 topic=topic or self.topic, 

238 key=key or self.key, 

239 partition=partition if partition is not None else self.partition, 

240 reply_to=reply_to or self.reply_to, 

241 headers=self.headers | dict(headers or {}), 

242 correlation_id=correlation_id or self._outer_config.id_generator(), 

243 timestamp_ms=timestamp_ms, 

244 no_confirm=no_confirm, 

245 _publish_type=PublishType.PUBLISH, 

246 ) 

247 return await self._basic_publish( 

248 cmd, 

249 producer=self._outer_config.producer, 

250 _extra_middlewares=(), 

251 ) 

252 

253 @override 

254 async def _publish( 

255 self, 

256 cmd: Union["PublishCommand", "KafkaPublishCommand"], 

257 *, 

258 _extra_middlewares: Iterable["PublisherMiddleware"], 

259 ) -> None: 

260 """This method should be called in subscriber flow only.""" 

261 cmd = KafkaPublishCommand.from_cmd(cmd) 

262 

263 cmd.destination = self.topic 

264 cmd.add_headers(self.headers, override=False) 

265 cmd.reply_to = cmd.reply_to or self.reply_to 

266 

267 cmd.partition = cmd.partition if cmd.partition is not None else self.partition 

268 cmd.key = cmd.key or self.key 

269 

270 await self._basic_publish( 

271 cmd, 

272 producer=self._outer_config.producer, 

273 _extra_middlewares=_extra_middlewares, 

274 ) 

275 

276 @override 

277 async def request( 

278 self, 

279 message: "SendableMessage", 

280 topic: str = "", 

281 *, 

282 key: bytes | Any | None = None, 

283 partition: int | None = None, 

284 timestamp_ms: int | None = None, 

285 headers: Mapping[str, str | bytes | None] | None = None, 

286 correlation_id: str | None = None, 

287 timeout: float = 0.5, 

288 ) -> "KafkaMessage": 

289 """Send a request message and wait for a response. 

290 

291 Args: 

292 message: Message body to send. 

293 topic: Topic where the message will be published. 

294 key: A key to associate with the message. Can be used to 

295 determine which partition to send the message to. If partition 

296 is `None` (and producer's partitioner config is left as default), 

297 then messages with the same key will be delivered to the same 

298 partition (but if key is `None`, partition is chosen randomly). 

299 Must be type `bytes`, or be serializable to bytes via configured 

300 `key_serializer`. 

301 partition: Specify a partition. If not set, the partition will be 

302 selected using the configured `partitioner`. 

303 timestamp_ms: Epoch milliseconds (from Jan 1 1970 UTC) to use as 

304 the message timestamp. Defaults to current time. 

305 headers: Message headers to store metainformation. 

306 correlation_id: Manual message **correlation_id** setter. 

307 **correlation_id** is a useful option to trace messages. 

308 timeout: Timeout to send RPC request. 

309 

310 Returns: 

311 The response message. 

312 """ 

313 return await super().request( 

314 message, 

315 topic=topic, 

316 key=key or self.key, 

317 partition=partition, 

318 timestamp_ms=timestamp_ms, 

319 headers=headers, 

320 correlation_id=correlation_id, 

321 timeout=timeout, 

322 ) 

323 

324 

325class BatchPublisher(LogicPublisher): 

326 __slots__ = () 

327 

328 def __init__( 

329 self, 

330 config: "KafkaPublisherConfig", 

331 specification: "PublisherSpecification[Any, Any]", 

332 ) -> None: 

333 super().__init__(config, specification) 

334 self.key = config.key 

335 

336 @overload 

337 async def publish( 

338 self, 

339 *messages: "KafkaSendableMessage", 

340 topic: str = "", 

341 key: bytes | Any | None = None, 

342 partition: int | None = None, 

343 timestamp_ms: int | None = None, 

344 headers: Mapping[str, str | bytes | None] | None = None, 

345 reply_to: str = "", 

346 correlation_id: str | None = None, 

347 no_confirm: Literal[False] = False, 

348 ) -> "RecordMetadata": ... 

349 

350 @overload 

351 async def publish( 

352 self, 

353 *messages: "KafkaSendableMessage", 

354 topic: str = "", 

355 key: bytes | Any | None = None, 

356 partition: int | None = None, 

357 timestamp_ms: int | None = None, 

358 headers: Mapping[str, str | bytes | None] | None = None, 

359 reply_to: str = "", 

360 correlation_id: str | None = None, 

361 no_confirm: Literal[True] = ..., 

362 ) -> "asyncio.Future[RecordMetadata]": ... 

363 

364 @overload 

365 async def publish( 

366 self, 

367 *messages: "KafkaSendableMessage", 

368 topic: str = "", 

369 key: bytes | Any | None = None, 

370 partition: int | None = None, 

371 timestamp_ms: int | None = None, 

372 headers: Mapping[str, str | bytes | None] | None = None, 

373 reply_to: str = "", 

374 correlation_id: str | None = None, 

375 no_confirm: bool = False, 

376 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]: ... 

377 

378 @override 

379 async def publish( 

380 self, 

381 *messages: "KafkaSendableMessage", 

382 topic: str = "", 

383 key: bytes | Any | None = None, 

384 partition: int | None = None, 

385 timestamp_ms: int | None = None, 

386 headers: Mapping[str, str | bytes | None] | None = None, 

387 reply_to: str = "", 

388 correlation_id: str | None = None, 

389 no_confirm: bool = False, 

390 ) -> Union["asyncio.Future[RecordMetadata]", "RecordMetadata"]: 

391 """Publish a message batch as a single request to broker. 

392 

393 Args: 

394 *messages: 

395 Messages bodies to send. 

396 topic: 

397 Topic where the message will be published. 

398 key: 

399 A single key to associate with every message in this batch. If a 

400 partition is not specified and the producer uses the default 

401 partitioner, messages with the same key will be routed to the 

402 same partition. Must be bytes or serializable to bytes via the 

403 configured key serializer. If omitted, falls back to the 

404 publisher's default key (if configured). 

405 partition: 

406 Specify a partition. If not set, the partition will be 

407 selected using the configured `partitioner` 

408 timestamp_ms: 

409 Epoch milliseconds (from Jan 1 1970 UTC) to use as 

410 the message timestamp. Defaults to current time. 

411 headers: 

412 Message headers to store metainformation. 

413 reply_to: 

414 Reply message topic name to send response. 

415 correlation_id: 

416 Manual message **correlation_id** setter. 

417 **correlation_id** is a useful option to trace messages. 

418 no_confirm: 

419 Do not wait for Kafka publish confirmation. 

420 

421 Returns: 

422 `asyncio.Future[RecordMetadata]` if no_confirm = True. 

423 `RecordMetadata` if no_confirm = False. 

424 """ 

425 cmd = KafkaPublishCommand( 

426 *messages, 

427 key=key or self.key, 

428 topic=topic or self.topic, 

429 partition=partition if partition is not None else self.partition, 

430 reply_to=reply_to or self.reply_to, 

431 headers=self.headers | dict(headers or {}), 

432 correlation_id=correlation_id or self._outer_config.id_generator(), 

433 timestamp_ms=timestamp_ms, 

434 no_confirm=no_confirm, 

435 _publish_type=PublishType.PUBLISH, 

436 ) 

437 

438 return await self._basic_publish_batch( 

439 cmd, 

440 producer=self._outer_config.producer, 

441 _extra_middlewares=(), 

442 ) 

443 

444 @override 

445 async def _publish( 

446 self, 

447 cmd: Union["PublishCommand", "KafkaPublishCommand"], 

448 *, 

449 _extra_middlewares: Iterable["PublisherMiddleware"], 

450 ) -> None: 

451 """This method should be called in subscriber flow only.""" 

452 cmd = KafkaPublishCommand.from_cmd(cmd, batch=True) 

453 

454 if not cmd.batch_bodies: 

455 # Match the non-batch publisher: an empty result is one empty message, 

456 # not a batch of zero, which no broker can express (see issue #3056). 

457 cmd.batch_bodies = (b"",) 

458 

459 cmd.destination = self.topic 

460 cmd.add_headers(self.headers, override=False) 

461 cmd.reply_to = cmd.reply_to or self.reply_to 

462 

463 cmd.partition = cmd.partition if cmd.partition is not None else self.partition 

464 cmd.key = cmd.key or self.key 

465 

466 await self._basic_publish_batch( 

467 cmd, 

468 producer=self._outer_config.producer, 

469 _extra_middlewares=_extra_middlewares, 

470 )