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
« 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)
16from typing_extensions import Self, overload, override
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
36from .call_item import (
37 CallsCollection,
38 HandlerItem,
39)
40from .utils import MultiLock, default_filter
42if TYPE_CHECKING:
43 from fast_depends.dependencies import Dependant
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
61 from .specification import SubscriberSpecification
64class _CallOptions(NamedTuple):
65 parser: Optional["CustomCallable"]
66 decoder: Optional["CustomCallable"]
67 dependencies: Sequence["Dependant"]
68 codec: Optional["CodecProto"] = None
71class SubscriberUsecase(Endpoint, Generic[MsgType]):
72 """A class representing an asynchronous handler."""
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 )
88 lock: "AbstractContextManager[Any]"
89 graceful_timeout: float | None
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)
100 self.calls = calls
101 self.specification = specification
103 self._no_reply = config.no_reply
104 self._parser = config.parser
105 self._decoder = config.decoder
107 self.ack_policy = config.ack_policy
108 self.__auto_ack_disabled = config.auto_ack_disabled
110 self._call_options = _CallOptions(
111 parser=None,
112 decoder=None,
113 dependencies=(),
114 codec=None,
115 )
117 self._call_decorators: tuple[Decorator, ...] = ()
119 self.running = False
120 self.lock = nullcontext()
122 @property
123 def _broker_middlewares(self) -> Sequence["BrokerMiddleware[MsgType]"]:
124 return self._outer_config.broker_middlewares
126 async def __aenter__(self) -> Self:
127 await self.start()
128 return self
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()
138 async def start(self) -> None:
139 """Private method to start subscriber by broker."""
140 self.lock = MultiLock()
142 self._build_fastdepends_model()
144 self._outer_config.logger.log(
145 f"`{self.specification.call_name}` waiting for messages",
146 extra=self.get_log_context(None),
147 )
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.
156 First priority
157 >>> sub = broker.subscriber()
158 >>>
159 >>> @sub(parser=P0_parser)
160 >>> async def handler(): ...
162 Second priority
163 >>> sub = broker.subscriber(parser=P1_parser)
165 Third priority
166 >>> Broker(parser=P2_parser)
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
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 )
188 if codec and decoder:
189 msg = "Cannot use both 'codec' and 'decoder' — 'codec' replaces 'decoder'."
190 raise ValueError(msg)
192 is_batch = getattr(self._decoder, "__name__", "") == "decode_batch"
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
210 return async_parser, async_decoder
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 )
221 for call in self.calls:
222 async_parser, async_decoder = self._get_parser_and_decoder(
223 call.item_parser, call.item_decoder
224 )
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 )
234 if driver_annotations and call.dependant is not None:
235 check_context_annotations(call.dependant, driver_annotations)
237 call.handler.refresh(with_mock=False)
239 def _post_start(self) -> None:
240 self.running = True
242 @abstractmethod
243 async def stop(self) -> None:
244 """Stop message consuming.
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
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)
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
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]": ...
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 ]: ...
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 )
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)
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 )
334 return handler
336 if func is None:
337 return real_wrapper
339 return real_wrapper(func)
341 async def consume(self, msg: MsgType) -> Any:
342 """Consume a message asynchronously."""
343 if not self.running:
344 return None
346 try:
347 return await self.process_message(msg)
349 except StopConsume:
350 # Stop handler at StopConsume exception
351 await self.stop()
353 except SystemExit:
354 # Stop handler at `exit()` call
355 await self.stop()
357 if app := self._outer_config.context.get("app"):
358 app.exit()
360 except Exception: # nosec B110 # ruff: ignore[try-except-pass]
361 # All other exceptions were logged by CriticalLogMiddleware
362 pass
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
369 async with AsyncExitStack() as stack:
370 stack.enter_context(self.lock)
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 )
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())
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)
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
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 )
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 )
423 if not result_msg.correlation_id:
424 result_msg.correlation_id = message.correlation_id
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 )
437 # Return data for tests
438 return result_msg
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
446 error_msg = f"There is no suitable handler for {msg=}"
447 raise SubscriberNotFound(error_msg)
449 # An error was raised and processed by some middleware
450 return ensure_response(None)
452 def __build__middlewares_stack(self) -> tuple["BrokerMiddleware[MsgType]", ...]:
453 logger_state = self._outer_config.logger
455 if self.__auto_ack_disabled:
456 broker_middlewares = (
457 CriticalLogMiddleware(logger_state),
458 *self._broker_middlewares,
459 )
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 )
472 return broker_middlewares
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 ()
481 return self._make_response_publisher(message)
483 @abstractmethod
484 def _make_response_publisher(
485 self,
486 message: "StreamMessage[MsgType]",
487 ) -> Iterable["PublisherProto"]:
488 raise NotImplementedError
490 @abstractmethod
491 async def get_one(self, *, timeout: float = 5) -> Optional["StreamMessage[MsgType]"]:
492 raise NotImplementedError
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
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 }
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 )
525 def schema(self) -> dict[str, "SubscriberSpec"]:
526 self._build_fastdepends_model()
527 return self.specification.get_schema()