Coverage for faststream/_internal/endpoint/subscriber/usecase.py: 94%

132 statements  

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

1from abc import abstractmethod 

2from collections.abc import AsyncIterator, Callable, Iterable, Sequence 

3from contextlib import AbstractContextManager, AsyncExitStack, ExitStack, nullcontext 

4from itertools import chain 

5from types import TracebackType 

6from typing import ( 

7 TYPE_CHECKING, 

8 Any, 

9 Generic, 

10 NamedTuple, 

11 Optional, 

12 Union, 

13 cast, 

14) 

15 

16from typing_extensions import Self, overload, override 

17 

18from faststream._internal.endpoint.subscriber.hints import ( 

19 check_context_annotations, 

20) 

21from faststream._internal.endpoint.usecase import Endpoint 

22from faststream._internal.endpoint.utils import ParserComposition 

23from faststream._internal.parser import BatchCodecProto 

24from faststream._internal.types import ( 

25 AsyncCallable, 

26 MsgType, 

27 P_HandlerParams, 

28 T_HandlerReturn, 

29) 

30from faststream._internal.utils.functions import to_async 

31from faststream.exceptions import StopConsume, SubscriberNotFound 

32from faststream.middlewares import AcknowledgementMiddleware 

33from faststream.middlewares.logging import CriticalLogMiddleware 

34from faststream.response import ensure_response 

35 

36from .call_item import ( 

37 CallsCollection, 

38 HandlerItem, 

39) 

40from .utils import MultiLock, default_filter 

41 

42if TYPE_CHECKING: 

43 from fast_depends.dependencies import Dependant 

44 

45 from faststream._internal.basic_types import Decorator 

46 from faststream._internal.configs import SubscriberUsecaseConfig 

47 from faststream._internal.endpoint.call_wrapper import HandlerCallWrapper 

48 from faststream._internal.endpoint.publisher import PublisherProto 

49 from faststream._internal.parser import CodecProto 

50 from faststream._internal.types import ( 

51 AsyncFilter, 

52 BrokerMiddleware, 

53 CustomCallable, 

54 Filter, 

55 ) 

56 from faststream.message import StreamMessage 

57 from faststream.middlewares import BaseMiddleware 

58 from faststream.response import Response 

59 from faststream.specification.schema import SubscriberSpec 

60 

61 from .specification import SubscriberSpecification 

62 

63 

64class _CallOptions(NamedTuple): 

65 parser: Optional["CustomCallable"] 

66 decoder: Optional["CustomCallable"] 

67 dependencies: Sequence["Dependant"] 

68 codec: Optional["CodecProto"] = None 

69 

70 

71class SubscriberUsecase(Endpoint, Generic[MsgType]): 

72 """A class representing an asynchronous handler.""" 

73 

74 __slots__ = ( 

75 "__auto_ack_disabled", 

76 "_call_decorators", 

77 "_call_options", 

78 "_decoder", 

79 "_no_reply", 

80 "_parser", 

81 "ack_policy", 

82 "calls", 

83 "lock", 

84 "running", 

85 "specification", 

86 ) 

87 

88 lock: "AbstractContextManager[Any]" 

89 graceful_timeout: float | None 

90 

91 def __init__( 

92 self, 

93 config: "SubscriberUsecaseConfig", 

94 specification: "SubscriberSpecification", 

95 calls: "CallsCollection[MsgType]", 

96 ) -> None: 

97 """Initialize a new instance of the class.""" 

98 super().__init__(config._outer_config) 

99 

100 self.calls = calls 

101 self.specification = specification 

102 

103 self._no_reply = config.no_reply 

104 self._parser = config.parser 

105 self._decoder = config.decoder 

106 

107 self.ack_policy = config.ack_policy 

108 self.__auto_ack_disabled = config.auto_ack_disabled 

109 

110 self._call_options = _CallOptions( 

111 parser=None, 

112 decoder=None, 

113 dependencies=(), 

114 codec=None, 

115 ) 

116 

117 self._call_decorators: tuple[Decorator, ...] = () 

118 

119 self.running = False 

120 self.lock = nullcontext() 

121 

122 @property 

123 def _broker_middlewares(self) -> Sequence["BrokerMiddleware[MsgType]"]: 

124 return self._outer_config.broker_middlewares 

125 

126 async def __aenter__(self) -> Self: 

127 await self.start() 

128 return self 

129 

130 async def __aexit__( 

131 self, 

132 exc_type: type[BaseException] | None, 

133 exc_value: BaseException | None, 

134 traceback: TracebackType | None, 

135 ) -> None: 

136 await self.stop() 

137 

138 async def start(self) -> None: 

139 """Private method to start subscriber by broker.""" 

140 self.lock = MultiLock() 

141 

142 self._build_fastdepends_model() 

143 

144 self._outer_config.logger.log( 

145 f"`{self.specification.call_name}` waiting for messages", 

146 extra=self.get_log_context(None), 

147 ) 

148 

149 def _get_parser_and_decoder( 

150 self, 

151 item_parser: Optional["CustomCallable"] = None, 

152 item_decoder: Optional["CustomCallable"] = None, 

153 ) -> tuple[AsyncCallable, AsyncCallable]: 

154 """Method to resolve parsers with priority. 

155 

156 First priority 

157 >>> sub = broker.subscriber() 

158 >>> 

159 >>> @sub(parser=P0_parser) 

160 >>> async def handler(): ... 

161 

162 Second priority 

163 >>> sub = broker.subscriber(parser=P1_parser) 

164 

165 Third priority 

166 >>> Broker(parser=P2_parser) 

167 

168 Default parser is `self._parser`. 

169 So, the final parser object is 

170 >>> ParserComposition(P0_parser or P1_parser or P2_parser, self._parser) 

171 """ 

172 if parser := ( 

173 item_parser or self._call_options.parser or self._outer_config.broker_parser 

174 ): 

175 async_parser: AsyncCallable = ParserComposition(parser, self._parser) 

176 else: 

177 async_parser = self._parser 

178 

179 # Codec takes priority over legacy decoder. 

180 # Having both is an error — it's ambiguous which takes effect. 

181 codec = self._call_options.codec or self._outer_config.broker_codec 

182 decoder = ( 

183 item_decoder 

184 or self._call_options.decoder 

185 or self._outer_config.broker_decoder 

186 ) 

187 

188 if codec and decoder: 

189 msg = "Cannot use both 'codec' and 'decoder' — 'codec' replaces 'decoder'." 

190 raise ValueError(msg) 

191 

192 is_batch = getattr(self._decoder, "__name__", "") == "decode_batch" 

193 

194 if codec: 

195 if is_batch: 

196 if isinstance(codec, BatchCodecProto): 

197 async_decoder: AsyncCallable = codec.decode_batch 

198 else: 

199 msg = ( 

200 "Batch subscriber requires a codec implementing BatchCodecProto." 

201 ) 

202 raise ValueError(msg) 

203 else: 

204 async_decoder = codec.decode 

205 elif decoder: 

206 async_decoder = ParserComposition(decoder, self._decoder) 

207 else: 

208 async_decoder = self._decoder 

209 

210 return async_parser, async_decoder 

211 

212 def _build_fastdepends_model(self) -> None: 

213 fd_config = self._outer_config.fd_config 

214 # nothing is injected without FastDepends, and FastAPI builds its own model 

215 driver_annotations = ( 

216 self._outer_config.resolved_underlying_driver_annotations 

217 if fd_config.use_fastdepends and not fd_config.get_dependent 

218 else {} 

219 ) 

220 

221 for call in self.calls: 

222 async_parser, async_decoder = self._get_parser_and_decoder( 

223 call.item_parser, call.item_decoder 

224 ) 

225 

226 call._setup( 

227 parser=async_parser, 

228 decoder=async_decoder, 

229 config=fd_config, 

230 broker_dependencies=self._outer_config.broker_dependencies, 

231 _call_decorators=self._call_decorators, 

232 ) 

233 

234 if driver_annotations and call.dependant is not None: 

235 check_context_annotations(call.dependant, driver_annotations) 

236 

237 call.handler.refresh(with_mock=False) 

238 

239 def _post_start(self) -> None: 

240 self.running = True 

241 

242 @abstractmethod 

243 async def stop(self) -> None: 

244 """Stop message consuming. 

245 

246 Blocks event loop up to graceful_timeout seconds. 

247 """ 

248 # set running false before releasing to stop new message reading 

249 self.running = False 

250 

251 # Wait for already consumed messages to be processed 

252 if isinstance(self.lock, MultiLock): 

253 await self.lock.wait_release(self._outer_config.graceful_timeout) 

254 

255 def add_call( 

256 self, 

257 *, 

258 parser_: Optional["CustomCallable"], 

259 decoder_: Optional["CustomCallable"], 

260 dependencies_: Sequence["Dependant"], 

261 codec_: Optional["CodecProto"] = None, 

262 ) -> Self: 

263 self._call_options = _CallOptions( 

264 parser=parser_, 

265 decoder=decoder_, 

266 dependencies=dependencies_, 

267 codec=codec_, 

268 ) 

269 return self 

270 

271 @overload 

272 def __call__( 

273 self, 

274 func: Callable[P_HandlerParams, T_HandlerReturn], 

275 *, 

276 filter: "Filter[Any]" = default_filter, 

277 parser: Optional["CustomCallable"] = None, 

278 decoder: Optional["CustomCallable"] = None, 

279 dependencies: Sequence["Dependant"] = (), 

280 ) -> "HandlerCallWrapper[P_HandlerParams, T_HandlerReturn]": ... 

281 

282 @overload 

283 def __call__( 

284 self, 

285 func: None = None, 

286 *, 

287 filter: "Filter[Any]" = default_filter, 

288 parser: Optional["CustomCallable"] = None, 

289 decoder: Optional["CustomCallable"] = None, 

290 dependencies: Sequence["Dependant"] = (), 

291 ) -> Callable[ 

292 [Callable[P_HandlerParams, T_HandlerReturn]], 

293 "HandlerCallWrapper[P_HandlerParams, T_HandlerReturn]", 

294 ]: ... 

295 

296 @override 

297 def __call__( 

298 self, 

299 func: Callable[P_HandlerParams, T_HandlerReturn] | None = None, 

300 *, 

301 filter: "Filter[Any]" = default_filter, 

302 parser: Optional["CustomCallable"] = None, 

303 decoder: Optional["CustomCallable"] = None, 

304 dependencies: Sequence["Dependant"] = (), 

305 ) -> Union[ 

306 "HandlerCallWrapper[P_HandlerParams, T_HandlerReturn]", 

307 Callable[ 

308 [Callable[P_HandlerParams, T_HandlerReturn]], 

309 "HandlerCallWrapper[P_HandlerParams, T_HandlerReturn]", 

310 ], 

311 ]: 

312 total_deps = (*self._call_options.dependencies, *dependencies) 

313 async_filter = cast( 

314 "AsyncFilter[StreamMessage[MsgType]]", 

315 to_async(filter), 

316 ) 

317 

318 def real_wrapper( 

319 func: Callable[P_HandlerParams, T_HandlerReturn], 

320 ) -> "HandlerCallWrapper[P_HandlerParams, T_HandlerReturn]": 

321 handler = super(SubscriberUsecase, self).__call__(func) 

322 handler._subscribers.append(self) 

323 

324 self.calls.add_call( 

325 HandlerItem[MsgType]( 

326 handler=handler, 

327 filter=async_filter, 

328 item_parser=parser, 

329 item_decoder=decoder, 

330 dependencies=total_deps, 

331 ), 

332 ) 

333 

334 return handler 

335 

336 if func is None: 

337 return real_wrapper 

338 

339 return real_wrapper(func) 

340 

341 async def consume(self, msg: MsgType) -> Any: 

342 """Consume a message asynchronously.""" 

343 if not self.running: 

344 return None 

345 

346 try: 

347 return await self.process_message(msg) 

348 

349 except StopConsume: 

350 # Stop handler at StopConsume exception 

351 await self.stop() 

352 

353 except SystemExit: 

354 # Stop handler at `exit()` call 

355 await self.stop() 

356 

357 if app := self._outer_config.context.get("app"): 

358 app.exit() 

359 

360 except Exception: # nosec B110 # ruff: ignore[try-except-pass] 

361 # All other exceptions were logged by CriticalLogMiddleware 

362 pass 

363 

364 async def process_message(self, msg: MsgType) -> "Response": 

365 """Execute all message processing stages.""" 

366 context = self._outer_config.context 

367 logger_state = self._outer_config.logger 

368 

369 async with AsyncExitStack() as stack: 

370 stack.enter_context(self.lock) 

371 

372 # Enter context before middlewares 

373 stack.enter_context( 

374 context.scopes( 

375 ( 

376 ("handler_", self), 

377 ("logger", logger_state.logger.logger), 

378 *self._outer_config.extra_context.items(), 

379 ), 

380 ), 

381 ) 

382 

383 # reserve place for context scope under the middlewares __aexit__ 

384 # because middlewares should be exited before context scope release 

385 message_scope = stack.enter_context(ExitStack()) 

386 

387 # enter all middlewares 

388 middlewares: list[BaseMiddleware] = [] 

389 for base_m in self.__build__middlewares_stack(): 

390 middleware = base_m(msg, context=context) 

391 middlewares.append(middleware) 

392 await stack.enter_async_context(middleware) 

393 

394 cache: dict[Any, Any] = {} 

395 parsing_error: Exception | None = None 

396 for h in self.calls: 396 ↛ 443line 396 didn't jump to line 443 because the loop on line 396 didn't complete

397 try: 

398 message = await h.is_suitable(msg, cache) 

399 except Exception as e: 

400 parsing_error = e 

401 break 

402 

403 if message is not None: 

404 message_scope.enter_context( 

405 context.scopes( 

406 ( 

407 ("log_context", self.get_log_context(message)), 

408 ("message", message), 

409 ), 

410 ), 

411 ) 

412 

413 result_msg = ensure_response( 

414 await h.call( 

415 message=message, 

416 # consumer middlewares 

417 _extra_middlewares=( 

418 m.consume_scope for m in middlewares[::-1] 

419 ), 

420 ), 

421 ) 

422 

423 if not result_msg.correlation_id: 

424 result_msg.correlation_id = message.correlation_id 

425 

426 for p in chain( 

427 self.__get_response_publisher(message), 

428 h.handler._publishers, 

429 ): 

430 await p._publish( 

431 result_msg.as_publish_command(), 

432 _extra_middlewares=( 

433 m.publish_scope for m in middlewares[::-1] 

434 ), 

435 ) 

436 

437 # Return data for tests 

438 return result_msg 

439 

440 # Suitable handler was not found or 

441 # parsing/decoding exception occurred. 

442 # Reraise it to catch in tests 

443 if parsing_error: 443 ↛ 446line 443 didn't jump to line 446 because the condition on line 443 was always true

444 raise parsing_error 

445 

446 error_msg = f"There is no suitable handler for {msg=}" 

447 raise SubscriberNotFound(error_msg) 

448 

449 # An error was raised and processed by some middleware 

450 return ensure_response(None) 

451 

452 def __build__middlewares_stack(self) -> tuple["BrokerMiddleware[MsgType]", ...]: 

453 logger_state = self._outer_config.logger 

454 

455 if self.__auto_ack_disabled: 

456 broker_middlewares = ( 

457 CriticalLogMiddleware(logger_state), 

458 *self._broker_middlewares, 

459 ) 

460 

461 else: 

462 broker_middlewares = ( 

463 AcknowledgementMiddleware( 

464 logger=logger_state, 

465 ack_policy=self.ack_policy, 

466 fallback_parser=self._parser, 

467 ), 

468 CriticalLogMiddleware(logger_state), 

469 *self._broker_middlewares, 

470 ) 

471 

472 return broker_middlewares 

473 

474 def __get_response_publisher( 

475 self, 

476 message: "StreamMessage[MsgType]", 

477 ) -> Iterable["PublisherProto"]: 

478 if not message.reply_to or self._no_reply: 

479 return () 

480 

481 return self._make_response_publisher(message) 

482 

483 @abstractmethod 

484 def _make_response_publisher( 

485 self, 

486 message: "StreamMessage[MsgType]", 

487 ) -> Iterable["PublisherProto"]: 

488 raise NotImplementedError 

489 

490 @abstractmethod 

491 async def get_one(self, *, timeout: float = 5) -> Optional["StreamMessage[MsgType]"]: 

492 raise NotImplementedError 

493 

494 @abstractmethod 

495 def __aiter__(self) -> AsyncIterator["StreamMessage[MsgType]"]: 

496 # NOTE: not `async def` on purpose. Implementations are async generators, 

497 # so calling `__aiter__()` returns the iterator itself, not a coroutine. 

498 # Declaring it `async` here would type it as `Coroutine[..., AsyncIterator]`, 

499 # which the `async for` protocol does not accept. 

500 raise NotImplementedError 

501 

502 def get_log_context( # ruff: ignore[no-self-use] 

503 self, 

504 message: Optional["StreamMessage[MsgType]"], 

505 ) -> dict[str, str]: 

506 """Generate log context.""" 

507 return { 

508 "message_id": getattr(message, "message_id", ""), 

509 } 

510 

511 def _log( 

512 self, 

513 log_level: int | None, 

514 message: str, 

515 extra: dict[str, Any] | None = None, 

516 exc_info: Exception | None = None, 

517 ) -> None: 

518 self._outer_config.logger.log( 

519 message, 

520 log_level, 

521 extra=extra, 

522 exc_info=exc_info, 

523 ) 

524 

525 def schema(self) -> dict[str, "SubscriberSpec"]: 

526 self._build_fastdepends_model() 

527 return self.specification.get_schema()