Coverage for faststream/nats/subscriber/usecases/stream_pull_subscriber.py: 90%

114 statements  

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

1from collections.abc import AsyncIterator, Awaitable, Callable, Coroutine 

2from contextlib import suppress 

3from time import monotonic 

4from typing import TYPE_CHECKING, Any, Optional, cast 

5 

6import anyio 

7from nats.errors import ConnectionClosedError, TimeoutError 

8from nats.js.errors import ServiceUnavailableError 

9from typing_extensions import override 

10 

11from faststream._internal.endpoint.subscriber.mixins import ConcurrentMixin, TasksMixin 

12from faststream._internal.endpoint.utils import process_msg 

13from faststream.nats.parser import ( 

14 BatchParser, 

15) 

16 

17from .basic import DefaultSubscriber 

18from .stream_basic import StreamSubscriber 

19 

20if TYPE_CHECKING: 

21 from nats.aio.msg import Msg 

22 from nats.js import JetStreamContext 

23 

24 from faststream._internal.basic_types import SendableMessage 

25 from faststream._internal.endpoint.subscriber import SubscriberSpecification 

26 from faststream._internal.endpoint.subscriber.call_item import CallsCollection 

27 from faststream.nats.message import NatsMessage 

28 from faststream.nats.schemas import JStream, PullSub 

29 from faststream.nats.subscriber.config import NatsSubscriberConfig 

30 

31 

32class PullStreamSubscriber( 

33 TasksMixin, 

34 StreamSubscriber, 

35): 

36 __slots__ = () 

37 

38 subscription: Optional["JetStreamContext.PullSubscription"] 

39 

40 def __init__( 

41 self, 

42 config: "NatsSubscriberConfig", 

43 specification: "SubscriberSpecification[Any, Any]", 

44 calls: "CallsCollection[Msg]", 

45 *, 

46 queue: str, 

47 pull_sub: "PullSub", 

48 stream: "JStream", 

49 ) -> None: 

50 super().__init__( 

51 config, 

52 specification, 

53 calls, 

54 # basic args 

55 queue=queue, 

56 stream=stream, 

57 ) 

58 

59 self.pull_sub = pull_sub 

60 

61 @override 

62 async def _create_subscription(self) -> None: 

63 """Create NATS subscription and start consume task.""" 

64 if self.subscription: 64 ↛ 65line 64 didn't jump to line 65 because the condition on line 64 was never true

65 return 

66 

67 self.subscription = await self.jetstream.pull_subscribe( 

68 subject=self.subject.broker_address, 

69 config=self.config, 

70 **self.extra_options, 

71 ) 

72 self.add_task(self._consume_pull, func_kwargs={"cb": self.consume}) 

73 

74 async def _consume_pull( 

75 self, 

76 cb: Callable[["Msg"], Coroutine[Any, Any, "SendableMessage"]], 

77 ) -> None: 

78 """Endless task consuming messages using NATS Pull subscriber.""" 

79 assert self.subscription 

80 

81 while self.running: # pragma: no branch 

82 messages = [] 

83 with suppress(TimeoutError, ConnectionClosedError, ServiceUnavailableError): 

84 messages = await self.subscription.fetch( 

85 batch=self.pull_sub.batch_size, 

86 timeout=self.pull_sub.timeout, 

87 ) 

88 

89 if messages: 89 ↛ 81line 89 didn't jump to line 81 because the condition on line 89 was always true

90 async with anyio.create_task_group() as tg: 

91 for msg in messages: 

92 _ = tg.start_soon(cb, msg) 

93 

94 

95class ConcurrentPullStreamSubscriber(ConcurrentMixin["Msg"], PullStreamSubscriber): 

96 __slots__ = () 

97 

98 @override 

99 async def _consume_pull( 

100 self, 

101 cb: Callable[["Msg"], Awaitable["SendableMessage"]], 

102 ) -> None: 

103 """Hold a worker slot from the pull request through message processing.""" 

104 if not self.running: 104 ↛ 105line 104 didn't jump to line 105 because the condition on line 104 was never true

105 return 

106 

107 assert self.subscription 

108 fetch_error: Exception | None = None 

109 

110 async with anyio.create_task_group() as tg: 

111 while self.running: # pragma: no branch 

112 await self.limiter.acquire() 

113 slot_reserved = True 

114 

115 try: 

116 if not self.running: 

117 continue 

118 

119 try: 

120 # Batch fetches can leave extra server pulls active (see issue #2563). 

121 (msg,) = await self.subscription.fetch( 

122 batch=1, 

123 timeout=self.pull_sub.timeout, 

124 ) 

125 except ( 

126 TimeoutError, 

127 ConnectionClosedError, 

128 ServiceUnavailableError, 

129 ): 

130 continue 

131 except Exception as exc: 

132 fetch_error = exc 

133 break 

134 

135 _ = tg.start_soon(self._consume_with_release, cb, msg) 

136 slot_reserved = False 

137 

138 finally: 

139 if slot_reserved: 

140 self.limiter.release() 

141 

142 if fetch_error is not None and self.running: 

143 raise fetch_error 

144 

145 async def _consume_with_release( 

146 self, 

147 cb: Callable[["Msg"], Awaitable["SendableMessage"]], 

148 msg: "Msg", 

149 ) -> None: 

150 """Release reserved capacity only after message processing finishes.""" 

151 try: 

152 await cb(msg) 

153 finally: 

154 self.limiter.release() 

155 

156 

157class BatchPullStreamSubscriber( 

158 TasksMixin, 

159 DefaultSubscriber[list["Msg"]], 

160): 

161 """Batch-message consumer class.""" 

162 

163 __slots__ = () 

164 

165 subscription: Optional["JetStreamContext.PullSubscription"] 

166 _fetch_sub: Optional["JetStreamContext.PullSubscription"] 

167 

168 def __init__( 

169 self, 

170 config: "NatsSubscriberConfig", 

171 specification: "SubscriberSpecification[Any, Any]", 

172 calls: "CallsCollection[list[Msg]]", 

173 *, 

174 stream: "JStream", 

175 pull_sub: "PullSub", 

176 ) -> None: 

177 parser = BatchParser(pattern=config.subject) 

178 config.decoder = parser.decode_batch 

179 config.parser = parser.parse_batch 

180 super().__init__(config, specification, calls) 

181 

182 self.stream = stream 

183 self.pull_sub = pull_sub 

184 

185 @override 

186 async def get_one( 

187 self, 

188 *, 

189 timeout: float = 5, 

190 ) -> Optional["NatsMessage"]: 

191 assert not self.calls, ( 

192 "You can't use `get_one` method if subscriber has registered handlers." 

193 ) 

194 

195 if not self._fetch_sub: 195 ↛ 202line 195 didn't jump to line 202 because the condition on line 195 was always true

196 fetch_sub = self._fetch_sub = await self.jetstream.pull_subscribe( 

197 subject=self.subject.broker_address, 

198 config=self.config, 

199 **self.extra_options, 

200 ) 

201 else: 

202 fetch_sub = self._fetch_sub 

203 

204 try: 

205 raw_message = await fetch_sub.fetch( 

206 batch=1, 

207 timeout=timeout, 

208 ) 

209 except TimeoutError: 

210 return None 

211 

212 context = self._outer_config.context 

213 async_parser, async_decoder = self._get_parser_and_decoder() 

214 

215 return cast( 

216 "NatsMessage", 

217 await process_msg( 

218 msg=raw_message, 

219 middlewares=( 

220 m(raw_message, context=context) for m in self._broker_middlewares 

221 ), 

222 parser=async_parser, 

223 decoder=async_decoder, 

224 ), 

225 ) 

226 

227 @override 

228 async def __aiter__(self) -> AsyncIterator["NatsMessage"]: 

229 assert not self.calls, ( 

230 "You can't use iterator if subscriber has registered handlers." 

231 ) 

232 

233 if not self._fetch_sub: 233 ↛ 240line 233 didn't jump to line 240 because the condition on line 233 was always true

234 fetch_sub = self._fetch_sub = await self.jetstream.pull_subscribe( 

235 subject=self.subject.broker_address, 

236 config=self.config, 

237 **self.extra_options, 

238 ) 

239 else: 

240 fetch_sub = self._fetch_sub 

241 

242 context = self._outer_config.context 

243 async_parser, async_decoder = self._get_parser_and_decoder() 

244 

245 while True: 

246 raw_message = await fetch_sub.fetch(batch=1) 

247 

248 yield cast( 

249 "NatsMessage", 

250 await process_msg( 

251 msg=raw_message, 

252 middlewares=( 

253 m(raw_message, context=context) for m in self._broker_middlewares 

254 ), 

255 parser=async_parser, 

256 decoder=async_decoder, 

257 ), 

258 ) 

259 

260 @override 

261 async def _create_subscription(self) -> None: 

262 """Create NATS subscription and start consume task.""" 

263 if self.subscription: 263 ↛ 264line 263 didn't jump to line 264 because the condition on line 263 was never true

264 return 

265 

266 self.subscription = await self.jetstream.pull_subscribe( 

267 subject=self.subject.broker_address, 

268 config=self.config, 

269 **self.extra_options, 

270 ) 

271 self.add_task(self._consume_pull) 

272 

273 async def _consume_pull(self) -> None: 

274 """Endless task consuming messages using NATS Pull subscriber.""" 

275 assert self.subscription, "You should call `create_subscription` at first." 

276 

277 batch_size = self.pull_sub.batch_size 

278 timeout = self.pull_sub.timeout 

279 

280 while self.running: # pragma: no branch 

281 deadline = monotonic() + timeout if timeout is not None else None 

282 messages: list[Msg] = [] 

283 remaining = None if deadline is None else deadline - monotonic() 

284 

285 # nats-py may return a partial batch before timeout; keep fetching. 

286 # See https://github.com/nats-io/nats.py/issues/1034. 

287 while ( 

288 len(messages) < batch_size 

289 and (remaining is None or remaining > 0) 

290 and self.running 

291 ): 

292 try: 

293 messages += await self.subscription.fetch( 

294 batch=batch_size - len(messages), 

295 timeout=remaining, 

296 ) 

297 except TimeoutError: 

298 break 

299 except (ConnectionClosedError, ServiceUnavailableError): 

300 # Unprocessed messages stay unacknowledged for server redelivery. 

301 messages.clear() 

302 break 

303 

304 remaining = None if deadline is None else deadline - monotonic() 

305 

306 if messages and self.running: 306 ↛ 280line 306 didn't jump to line 280 because the condition on line 306 was always true

307 await self.consume(messages)