1use std::{
19 num::NonZeroUsize,
20 str::FromStr,
21 sync::{
22 Arc,
23 atomic::{AtomicBool, Ordering},
24 },
25 time::Duration,
26};
27
28use ahash::{AHashMap, AHashSet};
29use anyhow::Context;
30use futures_util::{StreamExt, pin_mut};
31use nautilus_common::{
32 clients::{DataClient, execute_bar_subscriptions, execute_instrument_subscriptions},
33 live::{runner::get_data_event_sender, sender::EventSender},
34 messages::{
35 DataEvent,
36 data::{
37 BarsResponse, BookResponse, CustomDataResponse, DataResponse, InstrumentResponse,
38 InstrumentsResponse, RequestBars, RequestBookSnapshot, RequestCustomData,
39 RequestInstrument, RequestInstruments, RequestTrades, SubscribeBars,
40 SubscribeBookDeltas, SubscribeBookDepth, SubscribeCustomData, SubscribeInstrument,
41 SubscribeInstruments, SubscribeQuotes, SubscribeTrades, TradesResponse,
42 UnsubscribeBars, UnsubscribeBookDeltas, UnsubscribeBookDepth, UnsubscribeCustomData,
43 UnsubscribeQuotes, UnsubscribeTrades, subscribe::SubscribeInstrumentStatus,
44 unsubscribe::UnsubscribeInstrumentStatus,
45 },
46 },
47};
48use nautilus_core::{
49 AtomicMap, Params,
50 datetime::datetime_to_unix_nanos,
51 nanos::UnixNanos,
52 time::{AtomicTime, get_atomic_clock_realtime},
53};
54use nautilus_live::{
55 SocketControlFactory,
56 task::{TaskGroup, TaskGroupGuard, TaskSpawner},
57};
58use nautilus_model::{
59 data::{
60 BookOrder, CustomData, Data, DataType, OrderBookDelta, OrderBookDeltas, QuoteTick,
61 depth::DEPTH10_LEN,
62 },
63 enums::{
64 AggregationSource, BookAction, BookType, MarketStatusAction, OrderSide, PriceType,
65 RecordFlag,
66 },
67 identifiers::{ClientId, InstrumentId, Venue},
68 instruments::{Instrument, InstrumentAny},
69 types::{Price, Quantity},
70};
71use parking_lot::Mutex;
72use tokio_util::sync::CancellationToken;
73use ustr::Ustr;
74
75use crate::{
76 book::{
77 BinanceBookError,
78 pacing::{SnapshotPacer, SnapshotPermit},
79 recovery::spawn_recovery,
80 sync::{BookSyncTracker, DepthSequencing, DepthSnapshot, DepthUpdate},
81 },
82 common::{
83 bar::{binance_bar_data_type, binance_bars_to_custom_data, parse_binance_bar_type},
84 consts::{
85 BINANCE_PARTIAL_BOOK_DEPTH,
86 BINANCE_SPOT_REQUEST_WEIGHT_PER_MINUTE as SNAPSHOT_WEIGHT_PER_MINUTE, BINANCE_VENUE,
87 BINANCE_WS_HEARTBEAT_SECS,
88 },
89 credential::resolve_credentials,
90 enums::{BinanceEnvironment, BinanceProductType},
91 http_weights::depth_weight_spot as depth_request_weight,
92 parse::{bar_spec_to_binance_interval, quote_to_l1_deltas},
93 status::diff_and_emit_statuses,
94 urls::{get_http_base_url_with_us, get_ws_base_url_with_us},
95 websocket::{chain_command, send_book_snapshot},
96 },
97 config::{BinanceDataClientConfig, BinanceSpotMarketDataMode},
98 data_types::register_binance_custom_data,
99 spot::{
100 http::{BinanceDepth, BinanceSpotHttpError, DepthParams, client::BinanceSpotHttpClient},
101 websocket::{
102 public_json::{
103 BinanceSpotPublicJsonWebSocketClient,
104 messages::BinanceSpotPublicWsMessage,
105 parse::{
106 parse_book_ticker as parse_json_book_ticker,
107 parse_depth_diff as parse_json_depth_diff,
108 parse_depth_snapshot as parse_json_depth_snapshot,
109 parse_kline as parse_json_kline, parse_ticker as parse_json_ticker,
110 parse_trade as parse_json_trade,
111 },
112 },
113 streams::{
114 client::BinanceSpotWebSocketClient,
115 messages::BinanceSpotWsMessage,
116 parse::{
117 parse_bbo_event, parse_depth_diff, parse_depth_snapshot, parse_trades_event,
118 },
119 },
120 },
121 },
122};
123
124const BOOK_DEPTHS_JSON: [usize; 3] = [5, 10, 20];
125
126const SNAPSHOT_DEPTH: u32 = 5000;
128
129#[derive(Debug)]
131pub struct BinanceSpotDataClient {
132 clock: &'static AtomicTime,
133 client_id: ClientId,
134 config: BinanceDataClientConfig,
135 http_client: BinanceSpotHttpClient,
136 ws_client: SpotWsClient,
137 spot_market_data_mode: BinanceSpotMarketDataMode,
138 is_connected: AtomicBool,
139 cancellation_token: CancellationToken,
140 session_tasks: TaskGroup,
141 command_tasks: TaskGroup,
142 shutdown_errors: Vec<String>,
143 data_sender: EventSender<DataEvent>,
144 instruments: Arc<AtomicMap<InstrumentId, InstrumentAny>>,
145 status_cache: Arc<AtomicMap<InstrumentId, MarketStatusAction>>,
146 instrument_update_lock: Arc<tokio::sync::Mutex<()>>,
147 book_sync: BookSyncTracker,
148 book_subscriptions: Arc<AtomicMap<InstrumentId, String>>,
149 book_deltas: AHashSet<InstrumentId>,
150 book_depths: Arc<AtomicMap<InstrumentId, usize>>,
151 l1_book_subscriptions: Arc<AtomicMap<InstrumentId, u32>>,
152 quote_refs: Arc<AtomicMap<InstrumentId, u32>>,
153 ticker_refs: Arc<AtomicMap<InstrumentId, u32>>,
154 book_command_tail: Mutex<Option<tokio::sync::oneshot::Receiver<()>>>,
155}
156
157impl BinanceSpotDataClient {
158 pub fn new(client_id: ClientId, config: BinanceDataClientConfig) -> anyhow::Result<Self> {
164 config.validate()?;
165 let clock = get_atomic_clock_realtime();
166 let spot_market_data_mode = config.spot_market_data_mode;
167 let base_url_http = config.base_url_http.clone().or_else(|| {
168 config.us.then(|| {
169 get_http_base_url_with_us(config.product_type, config.environment, true).to_string()
170 })
171 });
172 let api_key = config
173 .api_key
174 .as_ref()
175 .map(|value| value.expose_secret().to_owned());
176 let api_secret = config
177 .api_secret
178 .as_ref()
179 .map(|value| value.expose_secret().to_owned());
180 let proxy_url = config
181 .proxy_url
182 .as_ref()
183 .map(|value| value.expose_secret().to_owned());
184
185 let http_client = BinanceSpotHttpClient::new_with_json_responses(
186 config.environment,
187 clock,
188 api_key.clone(),
189 api_secret.clone(),
190 base_url_http,
191 Some(config.recv_window_ms),
192 None, proxy_url.clone(),
194 config.us,
195 )?
196 .with_retry_config(config.retry_config());
197
198 let creds = if spot_market_data_mode == BinanceSpotMarketDataMode::Sbe {
199 resolve_credentials(api_key, api_secret, config.environment, config.product_type)
200 .inspect_err(|e| {
201 log::warn!(
202 "Failed to resolve Binance API credentials ({e}). \
203 Spot SBE WebSocket streams require an Ed25519 API key. \
204 Set the appropriate env vars for your environment, \
205 or provide api_key/api_secret in the data client config"
206 );
207 })
208 .ok()
209 } else {
210 None
211 };
212
213 let socket_factory = SocketControlFactory::new(client_id, Some(*BINANCE_VENUE));
214 let ws_client = match spot_market_data_mode {
215 BinanceSpotMarketDataMode::Sbe => SpotWsClient::Sbe(
217 BinanceSpotWebSocketClient::new(
218 config.base_url_ws.clone(),
219 creds.as_ref().map(|(k, _)| k.clone()),
220 creds.as_ref().map(|(_, s)| s.clone()),
221 Some(BINANCE_WS_HEARTBEAT_SECS),
222 config.transport_backend,
223 )?
224 .with_proxy(proxy_url)
225 .with_socket_control(socket_factory, "binance-spot-sbe-data-streams"),
226 ),
227 BinanceSpotMarketDataMode::Json => SpotWsClient::JsonPublic(
228 BinanceSpotPublicJsonWebSocketClient::new(
229 Some(resolve_spot_json_ws_url(
230 config.base_url_ws.clone(),
231 config.environment,
232 config.us,
233 )),
234 Some(BINANCE_WS_HEARTBEAT_SECS),
235 config.transport_backend,
236 )
237 .with_proxy(proxy_url)
238 .with_socket_control(socket_factory, "binance-spot-json-data-streams"),
239 ),
240 };
241 let data_sender = get_data_event_sender();
242 let snapshot_pacer = Arc::new(SnapshotPacer::new(SNAPSHOT_WEIGHT_PER_MINUTE));
243 let book_sync =
244 BookSyncTracker::new(DepthSequencing::Spot, data_sender.clone(), snapshot_pacer);
245
246 log::debug!("Configured Spot market data mode: {spot_market_data_mode:?}");
247
248 let session_tasks = TaskGroup::new();
249 let command_tasks = TaskGroup::new();
250
251 Ok(Self {
252 clock,
253 client_id,
254 config,
255 http_client,
256 ws_client,
257 spot_market_data_mode,
258 is_connected: AtomicBool::new(false),
259 cancellation_token: session_tasks.cancellation_token(),
260 session_tasks,
261 command_tasks,
262 shutdown_errors: Vec::new(),
263 data_sender,
264 instruments: Arc::new(AtomicMap::new()),
265 status_cache: Arc::new(AtomicMap::new()),
266 instrument_update_lock: Arc::new(tokio::sync::Mutex::new(())),
267 book_sync,
268 book_subscriptions: Arc::new(AtomicMap::new()),
269 book_deltas: AHashSet::new(),
270 book_depths: Arc::new(AtomicMap::new()),
271 l1_book_subscriptions: Arc::new(AtomicMap::new()),
272 quote_refs: Arc::new(AtomicMap::new()),
273 ticker_refs: Arc::new(AtomicMap::new()),
274 book_command_tail: Mutex::new(None),
275 })
276 }
277
278 fn venue(&self) -> Venue {
279 *BINANCE_VENUE
280 }
281
282 fn send_data(sender: &EventSender<DataEvent>, data: Data) {
283 if let Err(e) = sender.send(DataEvent::Data(data)) {
284 log::error!("Failed to emit data event: {e}");
285 }
286 }
287
288 fn spawn_ws<F>(&self, fut: F, context: &'static str)
289 where
290 F: std::future::Future<Output = anyhow::Result<()>> + Send + 'static,
291 {
292 let future = async move {
293 if let Err(e) = fut.await {
294 log::error!("{context}: {e:?}");
295 }
296 };
297
298 if let Err(e) = self.command_tasks.spawn(future) {
299 log::warn!("Skipping Binance Spot {context} after shutdown began: {e}");
300 }
301 }
302
303 fn spawn_command<F>(&self, future: F)
304 where
305 F: std::future::Future<Output = ()> + Send + 'static,
306 {
307 if let Err(e) = self.command_tasks.spawn(future) {
308 log::warn!("Skipping Binance Spot data command after shutdown began: {e}");
309 }
310 }
311
312 async fn finish_tasks(&self) -> anyhow::Result<()> {
313 let (session_result, command_result) = tokio::join!(
314 self.session_tasks
315 .finish_shutdown(Duration::from_secs(1), Duration::from_secs(2)),
316 self.command_tasks
317 .finish_shutdown(Duration::from_secs(1), Duration::from_secs(2)),
318 );
319 let mut errors = Vec::new();
320 if let Err(e) = session_result {
321 errors.push(format!(
322 "failed to finish Binance Spot data session tasks: {e}"
323 ));
324 }
325
326 if let Err(e) = command_result {
327 errors.push(format!(
328 "failed to finish Binance Spot data command tasks: {e}"
329 ));
330 }
331
332 if !errors.is_empty() {
333 anyhow::bail!(errors.join("; "));
334 }
335 Ok(())
336 }
337
338 async fn prepare_task_groups(&mut self) -> anyhow::Result<()> {
339 if !self.session_tasks.is_open() || !self.command_tasks.is_open() {
340 self.teardown_partial_connect().await?;
341 self.session_tasks
342 .start_generation()
343 .context("failed to start Binance Spot data session task generation")?;
344 self.command_tasks
345 .start_generation()
346 .context("failed to start Binance Spot data command task generation")?;
347 self.cancellation_token = self.session_tasks.cancellation_token();
348 }
349 Ok(())
350 }
351
352 async fn teardown_partial_connect(&mut self) -> anyhow::Result<()> {
353 self.session_tasks.begin_shutdown();
354 self.command_tasks.begin_shutdown();
355 self.ws_client.begin_shutdown();
356 if let Err(e) = self.ws_client.close().await {
357 self.shutdown_errors
358 .push(format!("WebSocket close failed: {e}"));
359 }
360
361 if let Err(e) = self.finish_tasks().await {
362 self.shutdown_errors.push(e.to_string());
363 }
364 self.is_connected.store(false, Ordering::Release);
365
366 if !self.shutdown_errors.is_empty() {
367 let errors = std::mem::take(&mut self.shutdown_errors);
368 anyhow::bail!("Binance Spot data teardown failed: {}", errors.join("; "));
369 }
370 Ok(())
371 }
372
373 #[expect(clippy::too_many_arguments)]
374 async fn refresh_instrument_catalog(
375 http: &BinanceSpotHttpClient,
376 provider: &crate::config::BinanceInstrumentProviderConfig,
377 us: bool,
378 instruments_cache: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
379 status_cache: &Arc<AtomicMap<InstrumentId, MarketStatusAction>>,
380 instrument_update_lock: &tokio::sync::Mutex<()>,
381 ws: &SpotWsClient,
382 sender: &EventSender<DataEvent>,
383 clock: &'static AtomicTime,
384 emit_status_changes: bool,
385 ) -> anyhow::Result<Vec<InstrumentAny>> {
386 let _guard = instrument_update_lock.lock().await;
387 let instruments = http
388 .request_instruments_with_config(provider, us)
389 .await
390 .context("failed to request Binance Spot instruments")?;
391 let venue_statuses = http
392 .request_symbol_statuses(us)
393 .await
394 .context("failed to request Binance Spot instrument statuses")?;
395
396 let instrument_map = instruments
397 .iter()
398 .map(|instrument| (instrument.id(), instrument.clone()))
399 .collect::<AHashMap<_, _>>();
400 let status_map = venue_statuses
401 .into_iter()
402 .filter(|(instrument_id, _)| instrument_map.contains_key(instrument_id))
403 .collect::<AHashMap<_, _>>();
404
405 instruments_cache.store(instrument_map);
406 ws.replace_instruments(&instruments);
407
408 if emit_status_changes {
409 let mut cached_statuses = (**status_cache.load()).clone();
410 let ts = clock.get_time_ns();
411 diff_and_emit_statuses(&status_map, &mut cached_statuses, sender, ts, ts);
412 status_cache.store(cached_statuses);
413 } else {
414 status_cache.store(status_map);
415 }
416
417 for instrument in &instruments {
418 if let Err(e) = sender.send(DataEvent::Data(instrument.clone().into())) {
419 log::warn!("Failed to send refreshed Binance Spot instrument: {e}");
420 }
421 }
422
423 Ok(instruments)
424 }
425
426 #[expect(clippy::too_many_arguments)]
427 fn handle_ws_message(
428 msg: BinanceSpotWsMessage,
429 data_sender: &EventSender<DataEvent>,
430 instruments: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
431 ws_instruments: &Arc<AtomicMap<Ustr, InstrumentAny>>,
432 book_sync: &BookSyncTracker,
433 l1_book_subscriptions: &Arc<AtomicMap<InstrumentId, u32>>,
434 book_depths: &AtomicMap<InstrumentId, usize>,
435 http_client: &BinanceSpotHttpClient,
436 snapshot_timeout: Duration,
437 clock: &'static AtomicTime,
438 command_spawner: &TaskSpawner,
439 ) {
440 let ts_init = clock.get_time_ns();
441
442 match msg {
443 BinanceSpotWsMessage::Trades(ref event) => {
444 let symbol = event.symbol;
445 let cache = ws_instruments.load();
446 if let Some(instrument) = cache.get(&symbol) {
447 match parse_trades_event(event, instrument, ts_init) {
448 Ok(trades) => {
449 for data in trades {
450 Self::send_data(data_sender, data);
451 }
452 }
453 Err(e) => log::warn!("Failed to parse Spot SBE trades: {e}"),
454 }
455 }
456 }
457 BinanceSpotWsMessage::BestBidAsk(ref event) => {
458 let symbol = event.symbol;
459 let cache = ws_instruments.load();
460 if let Some(instrument) = cache.get(&symbol) {
461 match parse_bbo_event(event, instrument, ts_init) {
462 Ok(quote) => Self::send_top_of_book(
463 data_sender,
464 l1_book_subscriptions,
465 quote,
466 event.book_update_id as u64,
467 ),
468 Err(e) => log::warn!("Failed to parse Spot SBE best bid/ask: {e}"),
469 }
470 }
471 }
472 BinanceSpotWsMessage::DepthSnapshot(ref event) => {
473 let symbol = event.symbol;
474 let cache = ws_instruments.load();
475 if let Some(instrument) = cache.get(&symbol) {
476 match parse_depth_snapshot(event, instrument, ts_init) {
477 Ok(deltas) => {
478 send_book_snapshot(data_sender, book_depths, deltas);
479 }
480 Err(e) => log::warn!("Failed to parse Spot SBE depth snapshot: {e}"),
481 }
482 }
483 }
484 BinanceSpotWsMessage::DepthDiff(ref event) => {
485 let symbol = event.symbol;
486 let cache = ws_instruments.load();
487 if let Some(instrument) = cache.get(&symbol) {
488 match parse_depth_diff(event, instrument, ts_init) {
489 Ok(deltas) => {
490 let update = DepthUpdate {
491 first_update_id: event.first_book_update_id as u64,
492 final_update_id: event.last_book_update_id as u64,
493 prev_final_update_id: None,
494 deltas,
495 };
496
497 Self::route_depth_diff(
498 instrument.id(),
499 update,
500 book_sync,
501 instruments,
502 http_client,
503 snapshot_timeout,
504 clock,
505 command_spawner,
506 );
507 }
508 Err(e) => log::warn!("Failed to parse Spot SBE depth update: {e}"),
509 }
510 }
511 }
512 BinanceSpotWsMessage::ServerShutdown(ref msg) => {
513 log::warn!(
514 "Binance server shutdown notice (event_time={}); disconnect expected within ~10 minutes",
515 msg.event_time,
516 );
517 }
518 BinanceSpotWsMessage::RawBinary(data) => {
519 log::debug!("Unhandled binary message: {} bytes", data.len());
520 }
521 BinanceSpotWsMessage::RawJson(value) => {
522 log::debug!("Unhandled JSON message: {value:?}");
523 }
524 BinanceSpotWsMessage::Error(e) => {
525 log::warn!("Binance WebSocket error: code={}, msg={}", e.code, e.msg);
526 }
527 BinanceSpotWsMessage::Reconnected => {
528 log::info!("WebSocket reconnected, rebuilding order book snapshots");
529 book_sync.reset_on_reconnect();
530 }
531 }
532 }
533
534 #[expect(clippy::too_many_arguments)]
535 fn handle_public_json_ws_message(
536 msg: BinanceSpotPublicWsMessage,
537 data_sender: &EventSender<DataEvent>,
538 instruments: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
539 ws_instruments: &Arc<AtomicMap<Ustr, InstrumentAny>>,
540 book_sync: &BookSyncTracker,
541 l1_book_subscriptions: &Arc<AtomicMap<InstrumentId, u32>>,
542 book_depths: &AtomicMap<InstrumentId, usize>,
543 http_client: &BinanceSpotHttpClient,
544 snapshot_timeout: Duration,
545 clock: &'static AtomicTime,
546 command_spawner: &TaskSpawner,
547 ) {
548 let ts_init = clock.get_time_ns();
549
550 match msg {
551 BinanceSpotPublicWsMessage::Trade(ref event) => {
552 let symbol = event.symbol;
553 let cache = ws_instruments.load();
554 if let Some(instrument) = cache.get(&symbol) {
555 match parse_json_trade(event, instrument, ts_init) {
556 Ok(trade) => Self::send_data(data_sender, Data::Trade(trade)),
557 Err(e) => log::warn!("Failed to parse Spot JSON trade: {e}"),
558 }
559 }
560 }
561 BinanceSpotPublicWsMessage::BookTicker(ref event) => {
562 let symbol = event.symbol;
563 let cache = ws_instruments.load();
564 if let Some(instrument) = cache.get(&symbol) {
565 match parse_json_book_ticker(event, instrument, ts_init) {
566 Ok(quote) => Self::send_top_of_book(
567 data_sender,
568 l1_book_subscriptions,
569 quote,
570 event.book_update_id,
571 ),
572 Err(e) => log::warn!("Failed to parse Spot JSON book ticker: {e}"),
573 }
574 }
575 }
576 BinanceSpotPublicWsMessage::DepthSnapshot(ref event) => {
577 let symbol = event.symbol;
578 let cache = ws_instruments.load();
579 if let Some(instrument) = cache.get(&symbol) {
580 let deltas = parse_json_depth_snapshot(event, instrument, ts_init);
581 send_book_snapshot(data_sender, book_depths, deltas);
582 }
583 }
584 BinanceSpotPublicWsMessage::DepthDiff(ref event) => {
585 let symbol = event.symbol;
586 let cache = ws_instruments.load();
587 if let Some(instrument) = cache.get(&symbol) {
588 match parse_json_depth_diff(event, instrument, ts_init) {
590 Ok(deltas) => {
591 let update = DepthUpdate {
592 first_update_id: event.first_update_id,
593 final_update_id: event.final_update_id,
594 prev_final_update_id: None,
595 deltas,
596 };
597
598 Self::route_depth_diff(
599 instrument.id(),
600 update,
601 book_sync,
602 instruments,
603 http_client,
604 snapshot_timeout,
605 clock,
606 command_spawner,
607 );
608 }
609 Err(e) => log::warn!("Failed to parse Spot JSON depth update: {e}"),
610 }
611 }
612 }
613 BinanceSpotPublicWsMessage::Kline(ref event) => {
614 let symbol = event.symbol;
615 let cache = ws_instruments.load();
616 if let Some(instrument) = cache.get(&symbol) {
617 match parse_json_kline(event, instrument, ts_init) {
618 Ok(Some(bar)) => {
619 Self::send_data(data_sender, Data::Bar(bar.bar()));
620 let data_type = binance_bar_data_type(bar.bar_type);
621 Self::send_data(
622 data_sender,
623 Data::Custom(CustomData::new(Arc::new(bar), data_type)),
624 );
625 }
626 Ok(None) => {} Err(e) => log::warn!("Failed to parse Spot JSON kline: {e}"),
628 }
629 }
630 }
631 BinanceSpotPublicWsMessage::Ticker(ref event) => {
632 let symbol = event.symbol;
633 let cache = ws_instruments.load();
634 if let Some(instrument) = cache.get(&symbol) {
635 match parse_json_ticker(event, instrument, ts_init) {
636 Ok(ticker) => {
637 let data_type = spot_ticker_data_type(instrument.id());
638 Self::send_data(
639 data_sender,
640 Data::Custom(CustomData::new(Arc::new(ticker), data_type)),
641 );
642 }
643 Err(e) => log::warn!("Failed to parse Spot JSON ticker: {e}"),
644 }
645 }
646 }
647 BinanceSpotPublicWsMessage::ServerShutdown(ref msg) => {
648 log::warn!(
649 "Binance Spot JSON server shutdown notice (event_time={}); disconnect expected within ~10 minutes",
650 msg.event_time,
651 );
652 }
653 BinanceSpotPublicWsMessage::RawJson(value) => {
654 log::debug!("Unhandled Spot JSON message: {value:?}");
655 }
656 BinanceSpotPublicWsMessage::Error(e) => {
657 log::warn!("Spot JSON WebSocket error: code={}, msg={}", e.code, e.msg);
658 }
659 BinanceSpotPublicWsMessage::Reconnected => {
660 log::info!("Spot JSON WebSocket reconnected, rebuilding order book snapshots");
661 book_sync.reset_on_reconnect();
662 }
663 }
664 }
665
666 fn send_top_of_book(
667 data_sender: &EventSender<DataEvent>,
668 l1_book_subscriptions: &Arc<AtomicMap<InstrumentId, u32>>,
669 quote: QuoteTick,
670 sequence: u64,
671 ) {
672 Self::send_data(data_sender, Data::Quote(quote));
673 if l1_book_subscriptions.contains_key("e.instrument_id) {
674 let deltas = quote_to_l1_deltas(quote, sequence);
675 Self::send_data(data_sender, Data::BookDeltas(Box::new(deltas)));
676 }
677 }
678
679 #[expect(
680 clippy::too_many_arguments,
681 reason = "book recovery requires the full subscription and command ownership context"
682 )]
683 fn route_depth_diff(
684 instrument_id: InstrumentId,
685 update: DepthUpdate,
686 book_sync: &BookSyncTracker,
687 instruments: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
688 http_client: &BinanceSpotHttpClient,
689 snapshot_timeout: Duration,
690 clock: &'static AtomicTime,
691 command_spawner: &TaskSpawner,
692 ) {
693 let Some(recovery) = book_sync.handle_update(instrument_id, update) else {
694 return;
695 };
696
697 let http = http_client.clone();
698 let instruments = instruments.clone();
699
700 spawn_recovery(
701 instrument_id,
702 recovery,
703 book_sync.clone(),
704 move |permit| {
705 Self::fetch_depth_snapshot(
706 http.clone(),
707 instruments.clone(),
708 instrument_id,
709 clock,
710 permit,
711 )
712 },
713 depth_request_weight(SNAPSHOT_DEPTH),
714 snapshot_timeout,
715 command_spawner,
716 );
717 }
718
719 fn quote_stream_suffix(&self) -> &'static str {
720 match self.spot_market_data_mode {
721 BinanceSpotMarketDataMode::Sbe => "bestBidAsk",
722 BinanceSpotMarketDataMode::Json => "bookTicker",
723 }
724 }
725
726 fn required_instrument_id_metadata(data_type: &DataType) -> anyhow::Result<InstrumentId> {
727 let raw = data_type
728 .metadata()
729 .as_ref()
730 .and_then(|metadata| metadata.get("instrument_id"))
731 .and_then(|value| value.as_str())
732 .map(str::trim)
733 .filter(|value| !value.is_empty())
734 .context("custom data subscription requires `instrument_id` metadata")?;
735 InstrumentId::from_str(raw)
736 .with_context(|| format!("invalid instrument_id metadata `{raw}`"))
737 }
738
739 async fn fetch_depth_snapshot(
740 http: BinanceSpotHttpClient,
741 instruments: Arc<AtomicMap<InstrumentId, InstrumentAny>>,
742 instrument_id: InstrumentId,
743 clock: &'static AtomicTime,
744 permit: SnapshotPermit,
745 ) -> Result<DepthSnapshot, BinanceBookError> {
746 let params = DepthParams {
747 symbol: instrument_id.symbol.as_str().to_uppercase(),
748 limit: Some(SNAPSHOT_DEPTH),
749 };
750
751 let depth = http
752 .inner()
753 .depth_paced(¶ms, permit)
754 .await
755 .map_err(|e| depth_snapshot_error(instrument_id, &e))?;
756
757 let ts_init = clock.get_time_ns();
758
759 let (price_precision, size_precision) = instruments
760 .load()
761 .get(&instrument_id)
762 .map(|instrument| (instrument.price_precision(), instrument.size_precision()))
763 .ok_or_else(|| {
764 BinanceBookError::Permanent(format!("no instrument cached for {instrument_id}"))
765 })?;
766
767 let deltas = parse_spot_depth_snapshot(
768 &depth,
769 instrument_id,
770 price_precision,
771 size_precision,
772 ts_init,
773 )
774 .map_err(|e| {
775 BinanceBookError::Retryable(format!(
776 "failed to parse depth snapshot for {instrument_id}: {e}"
777 ))
778 })?;
779
780 Ok(DepthSnapshot {
781 last_update_id: depth.last_update_id as u64,
782 deltas,
783 has_event_time: false,
784 })
785 }
786}
787
788fn spot_ticker_data_type(instrument_id: InstrumentId) -> DataType {
789 let metadata = Params::new(
790 [(
791 "instrument_id".to_string(),
792 serde_json::Value::String(instrument_id.to_string()),
793 )]
794 .into(),
795 );
796 DataType::new(
797 "BinanceSpotTicker",
798 Some(metadata),
799 Some(instrument_id.to_string()),
800 )
801}
802
803fn upsert_instruments(
804 cache: &Arc<AtomicMap<InstrumentId, InstrumentAny>>,
805 instruments: &[InstrumentAny],
806) {
807 if instruments.is_empty() {
808 return;
809 }
810
811 cache.rcu(|cache| {
812 for instrument in instruments {
813 cache.insert(instrument.id(), instrument.clone());
814 }
815 });
816}
817
818fn parse_spot_depth_snapshot(
819 depth: &BinanceDepth,
820 instrument_id: InstrumentId,
821 price_precision: u8,
822 size_precision: u8,
823 ts_init: UnixNanos,
824) -> anyhow::Result<OrderBookDeltas> {
825 let sequence = depth.last_update_id as u64;
826
827 let total_levels = depth.bids.len() + depth.asks.len();
828 let mut deltas = Vec::with_capacity(total_levels + 1);
829
830 deltas.push(OrderBookDelta::clear(
832 instrument_id,
833 sequence,
834 ts_init,
835 ts_init,
836 ));
837
838 for (side, levels) in [
839 (OrderSide::Buy, &depth.bids),
840 (OrderSide::Sell, &depth.asks),
841 ] {
842 for level in levels {
843 let price = Price::from_mantissa_exponent_checked(
844 level.price_mantissa,
845 depth.price_exponent,
846 price_precision,
847 )?;
848 let size = Quantity::from_mantissa_exponent_checked(
849 level.qty_mantissa as u64,
850 depth.qty_exponent,
851 size_precision,
852 )?;
853 let order = BookOrder::new(side, price, size, 0);
854
855 deltas.push(OrderBookDelta::new(
856 instrument_id,
857 BookAction::Add,
858 order,
859 RecordFlag::F_SNAPSHOT as u8,
860 sequence,
861 ts_init,
862 ts_init,
863 ));
864 }
865 }
866
867 if let Some(delta) = deltas.last_mut() {
868 delta.flags |= RecordFlag::F_LAST as u8;
869 }
870
871 Ok(OrderBookDeltas::new(instrument_id, deltas))
872}
873
874fn depth_snapshot_error(instrument_id: InstrumentId, e: &BinanceSpotHttpError) -> BinanceBookError {
876 let message = format!("depth snapshot request for {instrument_id} failed: {e}");
877
878 if e.is_retryable() || matches!(e, BinanceSpotHttpError::RetryBudgetExceeded(_)) {
879 BinanceBookError::Retryable(message)
880 } else {
881 BinanceBookError::Permanent(message)
882 }
883}
884
885#[async_trait::async_trait(?Send)]
886impl DataClient for BinanceSpotDataClient {
887 fn client_id(&self) -> ClientId {
888 self.client_id
889 }
890
891 fn venue(&self) -> Option<Venue> {
892 Some(self.venue())
893 }
894
895 fn start(&mut self) -> anyhow::Result<()> {
896 log::info!(
897 "Started: client_id={}, product_type={:?}, environment={:?}",
898 self.client_id,
899 self.config.product_type,
900 self.config.environment,
901 );
902 Ok(())
903 }
904
905 fn stop(&mut self) -> anyhow::Result<()> {
906 log::info!("Stopping {id}", id = self.client_id);
907 self.session_tasks.begin_shutdown();
908 self.command_tasks.begin_shutdown();
909 self.ws_client.begin_shutdown();
910 self.is_connected.store(false, Ordering::Relaxed);
911 Ok(())
912 }
913
914 fn reset(&mut self) -> anyhow::Result<()> {
915 log::debug!("Resetting {id}", id = self.client_id);
916
917 self.session_tasks.begin_shutdown();
918 self.command_tasks.begin_shutdown();
919 self.ws_client.begin_shutdown();
920 self.is_connected.store(false, Ordering::Relaxed);
921
922 self.book_subscriptions.store(AHashMap::new());
923 self.book_deltas.clear();
924 self.book_depths.store(AHashMap::new());
925 self.l1_book_subscriptions.store(AHashMap::new());
926 self.quote_refs.store(AHashMap::new());
927 self.ticker_refs.store(AHashMap::new());
928 self.book_sync.clear();
929
930 Ok(())
931 }
932
933 fn dispose(&mut self) -> anyhow::Result<()> {
934 log::debug!("Disposing {id}", id = self.client_id);
935 self.stop()
936 }
937
938 async fn connect(&mut self) -> anyhow::Result<()> {
939 if self.is_connected() && self.session_tasks.is_open() && self.command_tasks.is_open() {
940 return Ok(());
941 }
942
943 register_binance_custom_data();
944
945 if self.spot_market_data_mode == BinanceSpotMarketDataMode::Sbe
946 && !self.ws_client.has_credentials()
947 {
948 anyhow::bail!(
949 "Binance Spot market data mode SBE requires Ed25519 API credentials. \
950 Set the appropriate env vars for your environment, \
951 or provide api_key/api_secret in the data client config"
952 );
953 }
954
955 self.prepare_task_groups().await?;
956 let ws_client = self.ws_client.clone();
957 let setup_guard =
958 TaskGroupGuard::new(&[&self.session_tasks, &self.command_tasks], move || {
959 ws_client.begin_shutdown();
960 });
961
962 Self::refresh_instrument_catalog(
963 &self.http_client,
964 &self.config.instrument_provider,
965 self.config.us,
966 &self.instruments,
967 &self.status_cache,
968 &self.instrument_update_lock,
969 &self.ws_client,
970 &self.data_sender,
971 self.clock,
972 false,
973 )
974 .await?;
975
976 let session_result = async {
977 match &mut self.ws_client {
978 SpotWsClient::Sbe(ws_client) => {
979 log::info!("Connecting to Binance Spot SBE WebSocket...");
980 ws_client.connect().await.map_err(|e| {
981 anyhow::anyhow!("failed to connect Binance Spot SBE WebSocket: {e}")
982 })?;
983
984 log::info!("Binance Spot SBE WebSocket connected");
985 let stream = ws_client.stream();
986 let sender = self.data_sender.clone();
987 let insts = self.instruments.clone();
988 let ws_insts = ws_client.instruments_cache();
989 let book_sync = self.book_sync.clone();
990 let l1_book_subs = self.l1_book_subscriptions.clone();
991 let book_depths = self.book_depths.clone();
992 let http = self.http_client.clone();
993 let snapshot_timeout =
994 Duration::from_secs(self.config.book_snapshot_timeout_secs);
995 let clock = self.clock;
996 let cancel = self.cancellation_token.clone();
997 let command_spawner = self
998 .command_tasks
999 .spawner()
1000 .context("Binance Spot command task admission is closed")?;
1001
1002 let future = async move {
1003 pin_mut!(stream);
1004
1005 loop {
1006 tokio::select! {
1007 Some(message) = stream.next() => {
1008 Self::handle_ws_message(
1009 message,
1010 &sender,
1011 &insts,
1012 &ws_insts,
1013 &book_sync,
1014 &l1_book_subs,
1015 &book_depths,
1016 &http,
1017 snapshot_timeout,
1018 clock,
1019 &command_spawner,
1020 );
1021 }
1022 () = cancel.cancelled() => {
1023 log::debug!("Spot SBE WebSocket stream task cancelled");
1024 break;
1025 }
1026 }
1027 }
1028 };
1029 self.session_tasks
1030 .spawn(future)
1031 .context("failed to register Binance Spot SBE stream task")?;
1032 }
1033 SpotWsClient::JsonPublic(ws_client) => {
1034 log::info!("Connecting to Binance Spot public JSON WebSocket...");
1035 ws_client.connect().await.map_err(|e| {
1036 anyhow::anyhow!("failed to connect Binance Spot public JSON WebSocket: {e}")
1037 })?;
1038
1039 log::info!("Binance Spot public JSON WebSocket connected");
1040 let stream = ws_client.stream();
1041 let sender = self.data_sender.clone();
1042 let insts = self.instruments.clone();
1043 let ws_insts = ws_client.instruments_cache();
1044 let book_sync = self.book_sync.clone();
1045 let l1_book_subs = self.l1_book_subscriptions.clone();
1046 let book_depths = self.book_depths.clone();
1047 let http = self.http_client.clone();
1048 let snapshot_timeout =
1049 Duration::from_secs(self.config.book_snapshot_timeout_secs);
1050 let clock = self.clock;
1051 let cancel = self.cancellation_token.clone();
1052 let command_spawner = self
1053 .command_tasks
1054 .spawner()
1055 .context("Binance Spot command task admission is closed")?;
1056
1057 let future = async move {
1058 pin_mut!(stream);
1059
1060 loop {
1061 tokio::select! {
1062 Some(message) = stream.next() => {
1063 Self::handle_public_json_ws_message(
1064 message,
1065 &sender,
1066 &insts,
1067 &ws_insts,
1068 &book_sync,
1069 &l1_book_subs,
1070 &book_depths,
1071 &http,
1072 snapshot_timeout,
1073 clock,
1074 &command_spawner,
1075 );
1076 }
1077 () = cancel.cancelled() => {
1078 log::debug!("Spot JSON WebSocket stream task cancelled");
1079 break;
1080 }
1081 }
1082 }
1083 };
1084 self.session_tasks
1085 .spawn(future)
1086 .context("failed to register Binance Spot JSON stream task")?;
1087 }
1088 }
1089
1090 let poll_secs = self.config.instrument_status_poll_secs;
1091 if poll_secs > 0 {
1092 let http = self.http_client.clone();
1093 let poll_sender = self.data_sender.clone();
1094 let poll_instruments = self.instruments.clone();
1095 let poll_status_cache = self.status_cache.clone();
1096 let poll_update_lock = self.instrument_update_lock.clone();
1097 let poll_cancel = self.cancellation_token.clone();
1098 let clock = self.clock;
1099 let us = self.config.us;
1100
1101 let future = async move {
1102 let mut interval =
1103 tokio::time::interval(tokio::time::Duration::from_secs(poll_secs));
1104 interval.tick().await; loop {
1107 tokio::select! {
1108 _ = interval.tick() => {
1109 let _guard = poll_update_lock.lock().await;
1110
1111 match http.request_symbol_statuses(us).await {
1112 Ok(statuses) => {
1113 let ts = clock.get_time_ns();
1114 let inst_guard = poll_instruments.load();
1115 let new_statuses = statuses
1116 .into_iter()
1117 .filter(|(instrument_id, _)| {
1118 inst_guard.contains_key(instrument_id)
1119 })
1120 .collect();
1121 drop(inst_guard);
1122
1123 let mut cache =
1124 (**poll_status_cache.load()).clone();
1125 diff_and_emit_statuses(
1126 &new_statuses, &mut cache, &poll_sender, ts, ts,
1127 );
1128 poll_status_cache.store(cache);
1129 }
1130 Err(e) => {
1131 log::warn!("Instrument status poll failed: {e}");
1132 }
1133 }
1134 }
1135 () = poll_cancel.cancelled() => {
1136 log::debug!("Instrument status polling task cancelled");
1137 break;
1138 }
1139 }
1140 }
1141 };
1142 self.session_tasks
1143 .spawn(future)
1144 .context("failed to register Binance Spot status polling task")?;
1145 log::debug!("Instrument status polling started: interval={poll_secs}s");
1146 }
1147
1148 let refresh_secs = self.config.instrument_refresh_interval_secs;
1149 if refresh_secs > 0 {
1150 let http = self.http_client.clone();
1151 let provider = self.config.instrument_provider.clone();
1152 let us = self.config.us;
1153 let instruments = self.instruments.clone();
1154 let statuses = self.status_cache.clone();
1155 let update_lock = self.instrument_update_lock.clone();
1156 let ws = self.ws_client.clone();
1157 let sender = self.data_sender.clone();
1158 let clock = self.clock;
1159 let cancel = self.cancellation_token.clone();
1160
1161 let future = async move {
1162 let mut interval = tokio::time::interval(Duration::from_secs(refresh_secs));
1163 interval.tick().await;
1164
1165 loop {
1166 tokio::select! {
1167 _ = interval.tick() => {
1168 if let Err(e) = Self::refresh_instrument_catalog(
1169 &http,
1170 &provider,
1171 us,
1172 &instruments,
1173 &statuses,
1174 &update_lock,
1175 &ws,
1176 &sender,
1177 clock,
1178 true,
1179 ).await {
1180 log::warn!("Binance Spot instrument refresh failed: {e}");
1181 }
1182 }
1183 () = cancel.cancelled() => {
1184 log::debug!("Binance Spot instrument refresh task cancelled");
1185 break;
1186 }
1187 }
1188 }
1189 };
1190 self.session_tasks
1191 .spawn(future)
1192 .context("failed to register Binance Spot instrument refresh task")?;
1193 log::debug!("Instrument refresh started: interval={refresh_secs}s");
1194 }
1195
1196 Ok::<(), anyhow::Error>(())
1197 }
1198 .await;
1199
1200 if let Err(e) = session_result {
1201 if let Err(teardown_error) = self.teardown_partial_connect().await {
1202 return Err(e.context(format!(
1203 "Binance Spot data startup teardown failed: {teardown_error}"
1204 )));
1205 }
1206 return Err(e);
1207 }
1208
1209 setup_guard.disarm();
1210 self.is_connected.store(true, Ordering::Release);
1211 log::info!("Connected: client_id={}", self.client_id);
1212 Ok(())
1213 }
1214
1215 async fn disconnect(&mut self) -> anyhow::Result<()> {
1216 self.teardown_partial_connect().await?;
1217
1218 self.book_subscriptions.store(AHashMap::new());
1219 self.book_deltas.clear();
1220 self.book_depths.store(AHashMap::new());
1221 self.l1_book_subscriptions.store(AHashMap::new());
1222 self.quote_refs.store(AHashMap::new());
1223 self.ticker_refs.store(AHashMap::new());
1224 self.book_sync.clear();
1225
1226 self.is_connected.store(false, Ordering::Release);
1227 log::info!("Disconnected: client_id={}", self.client_id);
1228 Ok(())
1229 }
1230
1231 fn is_connected(&self) -> bool {
1232 self.is_connected.load(Ordering::Relaxed)
1233 }
1234
1235 fn is_disconnected(&self) -> bool {
1236 !self.is_connected()
1237 }
1238
1239 fn subscribe(&mut self, cmd: SubscribeCustomData) -> anyhow::Result<()> {
1240 if cmd.data_type.type_name() != "BinanceSpotTicker" {
1241 log::warn!(
1242 "Unsupported custom data subscription: {}",
1243 cmd.data_type.type_name()
1244 );
1245 return Ok(());
1246 }
1247 anyhow::ensure!(
1248 self.spot_market_data_mode == BinanceSpotMarketDataMode::Json,
1249 "Binance Spot 24-hour ticker custom data requires JSON market-data mode"
1250 );
1251 let instrument_id = Self::required_instrument_id_metadata(&cmd.data_type)?;
1252 anyhow::ensure!(
1253 instrument_id.venue == self.venue(),
1254 "Spot ticker requires a BINANCE instrument"
1255 );
1256 let should_subscribe = {
1257 let previous = self
1258 .ticker_refs
1259 .load()
1260 .get(&instrument_id)
1261 .copied()
1262 .unwrap_or(0);
1263 self.ticker_refs
1264 .rcu(|refs| *refs.entry(instrument_id).or_insert(0) += 1);
1265 previous == 0
1266 };
1267
1268 if should_subscribe {
1269 let ws = self.ws_client.clone();
1270 let stream = format!("{}@ticker", instrument_id.symbol.as_str().to_lowercase());
1271 self.spawn_ws(
1272 async move {
1273 ws.subscribe(vec![stream])
1274 .await
1275 .context("ticker subscription")
1276 },
1277 "ticker subscription",
1278 );
1279 }
1280 Ok(())
1281 }
1282
1283 fn subscribe_instruments(&mut self, _cmd: SubscribeInstruments) -> anyhow::Result<()> {
1284 log::debug!("subscribe_instruments: Binance instruments are fetched via HTTP on connect");
1285 Ok(())
1286 }
1287
1288 fn subscribe_instrument(&mut self, _cmd: SubscribeInstrument) -> anyhow::Result<()> {
1289 log::debug!("subscribe_instrument: Binance instruments are fetched via HTTP on connect");
1290 Ok(())
1291 }
1292
1293 fn subscribe_book_deltas(&mut self, cmd: SubscribeBookDeltas) -> anyhow::Result<()> {
1294 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1295 self.subscribe_book(&cmd.with_instrument_ids(instrument_id))?;
1296 self.book_deltas.insert(instrument_id);
1297 Ok(())
1298 })
1299 }
1300
1301 fn subscribe_book_depth(&mut self, cmd: SubscribeBookDepth) -> anyhow::Result<()> {
1302 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1303 anyhow::ensure!(
1304 cmd.book_type == BookType::L2_MBP,
1305 "Binance native depth snapshots require L2_MBP"
1306 );
1307 let depth = cmd.depth.map_or(DEPTH10_LEN, NonZeroUsize::get);
1308 anyhow::ensure!(
1309 depth <= BINANCE_PARTIAL_BOOK_DEPTH,
1310 "Binance native depth snapshots support at most {BINANCE_PARTIAL_BOOK_DEPTH} levels"
1311 );
1312
1313 let request = SubscribeBookDeltas::new(
1314 instrument_id,
1315 cmd.book_type,
1316 cmd.client_id,
1317 cmd.venue,
1318 cmd.command_id,
1319 cmd.ts_init,
1320 NonZeroUsize::new(BINANCE_PARTIAL_BOOK_DEPTH),
1321 cmd.managed,
1322 cmd.correlation_id,
1323 cmd.params.clone(),
1324 );
1325
1326 if let Some(active) = self.book_depths.get_cloned(&instrument_id) {
1327 anyhow::ensure!(
1328 active == depth,
1329 "Binance snapshot depth cannot change while subscribed"
1330 );
1331 return self.subscribe_book(&request);
1332 }
1333
1334 self.book_depths.insert(instrument_id, depth);
1335 if let Err(e) = self.subscribe_book(&request) {
1336 self.book_depths.remove(&instrument_id);
1337 return Err(e);
1338 }
1339
1340 Ok(())
1341 })
1342 }
1343
1344 fn subscribe_quotes(&mut self, cmd: SubscribeQuotes) -> anyhow::Result<()> {
1345 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1346 self.subscribe_top_of_book(instrument_id);
1347 Ok(())
1348 })
1349 }
1350
1351 fn subscribe_trades(&mut self, cmd: SubscribeTrades) -> anyhow::Result<()> {
1352 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1353 let ws = self.ws_client.clone();
1354
1355 let stream = format!("{}@trade", instrument_id.symbol.as_str().to_lowercase());
1356
1357 self.spawn_ws(
1358 async move {
1359 ws.subscribe(vec![stream])
1360 .await
1361 .context("trades subscription")
1362 },
1363 "trade subscription",
1364 );
1365
1366 Ok(())
1367 })
1368 }
1369
1370 fn subscribe_bars(&mut self, cmd: SubscribeBars) -> anyhow::Result<()> {
1371 execute_bar_subscriptions(&cmd.bar_types, |bar_type| {
1372 anyhow::ensure!(
1373 self.spot_market_data_mode == BinanceSpotMarketDataMode::Json,
1374 "Binance Spot kline subscriptions require JSON market-data mode"
1375 );
1376 let ws = self.ws_client.clone();
1377 let interval = bar_spec_to_binance_interval(bar_type.spec())?;
1378
1379 let stream = format!(
1380 "{}@kline_{}",
1381 bar_type.instrument_id().symbol.as_str().to_lowercase(),
1382 interval.as_str()
1383 );
1384
1385 self.spawn_ws(
1386 async move {
1387 ws.subscribe(vec![stream])
1388 .await
1389 .context("bars subscription")
1390 },
1391 "bar subscription",
1392 );
1393
1394 Ok(())
1395 })
1396 }
1397
1398 fn subscribe_instrument_status(
1399 &mut self,
1400 cmd: SubscribeInstrumentStatus,
1401 ) -> anyhow::Result<()> {
1402 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1403 log::debug!(
1404 "subscribe_instrument_status: {instrument_id} (status changes detected via periodic exchange info polling)",
1405 );
1406 Ok(())
1407 })
1408 }
1409
1410 fn unsubscribe_book_deltas(&mut self, cmd: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
1411 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1412 self.book_deltas.remove(&instrument_id);
1413 if !self.book_depths.contains_key(&instrument_id) {
1414 self.unsubscribe_book(&cmd.with_instrument_ids(instrument_id))?;
1415 }
1416
1417 Ok(())
1418 })
1419 }
1420
1421 fn unsubscribe_book_depth(&mut self, cmd: &UnsubscribeBookDepth) -> anyhow::Result<()> {
1422 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1423 self.book_depths.remove(&instrument_id);
1424 if !self.book_deltas.contains(&instrument_id) {
1425 let request = UnsubscribeBookDeltas::new(
1426 instrument_id,
1427 cmd.client_id,
1428 cmd.venue,
1429 cmd.command_id,
1430 cmd.ts_init,
1431 cmd.correlation_id,
1432 cmd.params.clone(),
1433 );
1434 self.unsubscribe_book(&request)?;
1435 }
1436
1437 Ok(())
1438 })
1439 }
1440
1441 fn unsubscribe_quotes(&mut self, cmd: &UnsubscribeQuotes) -> anyhow::Result<()> {
1442 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1443 self.unsubscribe_top_of_book(instrument_id);
1444 Ok(())
1445 })
1446 }
1447
1448 fn unsubscribe(&mut self, cmd: &UnsubscribeCustomData) -> anyhow::Result<()> {
1449 if cmd.data_type.type_name() != "BinanceSpotTicker" {
1450 log::warn!(
1451 "Unsupported custom data unsubscription: {}",
1452 cmd.data_type.type_name()
1453 );
1454 return Ok(());
1455 }
1456 let instrument_id = Self::required_instrument_id_metadata(&cmd.data_type)?;
1457 let should_unsubscribe = match self.ticker_refs.load().get(&instrument_id).copied() {
1458 Some(1) => {
1459 self.ticker_refs.remove(&instrument_id);
1460 true
1461 }
1462 Some(count) if count > 1 => {
1463 self.ticker_refs.rcu(|refs| {
1464 if let Some(existing) = refs.get_mut(&instrument_id) {
1465 *existing -= 1;
1466 }
1467 });
1468 false
1469 }
1470 _ => false,
1471 };
1472
1473 if should_unsubscribe {
1474 let ws = self.ws_client.clone();
1475 let stream = format!("{}@ticker", instrument_id.symbol.as_str().to_lowercase());
1476 self.spawn_ws(
1477 async move {
1478 ws.unsubscribe(vec![stream])
1479 .await
1480 .context("ticker unsubscribe")
1481 },
1482 "ticker unsubscribe",
1483 );
1484 }
1485 Ok(())
1486 }
1487
1488 fn unsubscribe_trades(&mut self, cmd: &UnsubscribeTrades) -> anyhow::Result<()> {
1489 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1490 let ws = self.ws_client.clone();
1491
1492 let stream = format!("{}@trade", instrument_id.symbol.as_str().to_lowercase());
1493
1494 self.spawn_ws(
1495 async move {
1496 ws.unsubscribe(vec![stream])
1497 .await
1498 .context("trades unsubscribe")
1499 },
1500 "trade unsubscribe",
1501 );
1502
1503 Ok(())
1504 })
1505 }
1506
1507 fn unsubscribe_bars(&mut self, cmd: &UnsubscribeBars) -> anyhow::Result<()> {
1508 execute_bar_subscriptions(&cmd.bar_types, |bar_type| {
1509 let ws = self.ws_client.clone();
1510 let interval = bar_spec_to_binance_interval(bar_type.spec())?;
1511
1512 let stream = format!(
1513 "{}@kline_{}",
1514 bar_type.instrument_id().symbol.as_str().to_lowercase(),
1515 interval.as_str()
1516 );
1517
1518 self.spawn_ws(
1519 async move {
1520 ws.unsubscribe(vec![stream])
1521 .await
1522 .context("bars unsubscribe")
1523 },
1524 "bar unsubscribe",
1525 );
1526
1527 Ok(())
1528 })
1529 }
1530
1531 fn unsubscribe_instrument_status(
1532 &mut self,
1533 cmd: &UnsubscribeInstrumentStatus,
1534 ) -> anyhow::Result<()> {
1535 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1536 log::debug!("unsubscribe_instrument_status: {instrument_id}",);
1537 Ok(())
1538 })
1539 }
1540
1541 fn request_instruments(&self, request: RequestInstruments) -> anyhow::Result<()> {
1542 let http = self.http_client.clone();
1543 let sender = self.data_sender.clone();
1544 let instruments_cache = self.instruments.clone();
1545 let request_id = request.request_id;
1546 let client_id = request.client_id.unwrap_or(self.client_id);
1547 let venue = self.venue();
1548 let start = request.start;
1549 let end = request.end;
1550 let params = request.params;
1551 let clock = self.clock;
1552 let provider = self.config.instrument_provider.clone();
1553 let us = self.config.us;
1554 let start_nanos = datetime_to_unix_nanos(start);
1555 let end_nanos = datetime_to_unix_nanos(end);
1556
1557 self.spawn_command(async move {
1558 match http.request_instruments_with_config(&provider, us).await {
1559 Ok(instruments) => {
1560 upsert_instruments(&instruments_cache, &instruments);
1561
1562 let response = DataResponse::Instruments(InstrumentsResponse::new(
1563 request_id,
1564 client_id,
1565 venue,
1566 instruments,
1567 start_nanos,
1568 end_nanos,
1569 clock.get_time_ns(),
1570 params,
1571 ));
1572
1573 if let Err(e) = sender.send(DataEvent::Response(response)) {
1574 log::error!("Failed to send instruments response: {e}");
1575 }
1576 }
1577 Err(e) => log::error!("Instruments request failed: {e:?}"),
1578 }
1579 });
1580
1581 Ok(())
1582 }
1583
1584 fn request_instrument(&self, request: RequestInstrument) -> anyhow::Result<()> {
1585 let instrument_id = request.single_instrument_id()?;
1586
1587 let http = self.http_client.clone();
1588 let sender = self.data_sender.clone();
1589 let instruments = self.instruments.clone();
1590 let request_id = request.request_id;
1591 let client_id = request.client_id.unwrap_or(self.client_id);
1592 let start = request.start;
1593 let end = request.end;
1594 let params = request.params;
1595 let clock = self.clock;
1596 let provider = self.config.instrument_provider.clone();
1597 let us = self.config.us;
1598 let start_nanos = datetime_to_unix_nanos(start);
1599 let end_nanos = datetime_to_unix_nanos(end);
1600
1601 self.spawn_command(async move {
1602 match http.request_instruments_with_config(&provider, us).await {
1603 Ok(all_instruments) => {
1604 upsert_instruments(&instruments, &all_instruments);
1605
1606 let instrument = all_instruments
1607 .into_iter()
1608 .find(|i| i.id() == instrument_id);
1609
1610 if let Some(instrument) = instrument {
1611 let response = DataResponse::Instrument(Box::new(InstrumentResponse::new(
1612 request_id,
1613 client_id,
1614 instrument.id(),
1615 instrument,
1616 start_nanos,
1617 end_nanos,
1618 clock.get_time_ns(),
1619 params,
1620 )));
1621
1622 if let Err(e) = sender.send(DataEvent::Response(response)) {
1623 log::error!("Failed to send instrument response: {e}");
1624 }
1625 } else {
1626 log::error!("Instrument not found: {instrument_id}");
1627 }
1628 }
1629 Err(e) => log::error!("Instrument request failed: {e:?}"),
1630 }
1631 });
1632
1633 Ok(())
1634 }
1635
1636 fn request_data(&self, request: RequestCustomData) -> anyhow::Result<()> {
1637 if request.data_type.type_name() != "BinanceBar" {
1638 log::warn!(
1639 "Unsupported custom data request: {}",
1640 request.data_type.type_name()
1641 );
1642 return Ok(());
1643 }
1644 let bar_type = parse_binance_bar_type(&request.data_type)?;
1645 anyhow::ensure!(
1646 bar_type.aggregation_source() == AggregationSource::External,
1647 "historical BinanceBar requests require EXTERNAL aggregation"
1648 );
1649 anyhow::ensure!(
1650 bar_type.spec().price_type == PriceType::Last,
1651 "historical BinanceBar requests require LAST price type"
1652 );
1653 anyhow::ensure!(
1654 bar_type.spec().is_time_aggregated(),
1655 "historical BinanceBar requests require time aggregation"
1656 );
1657 let http = self.http_client.clone();
1658 let sender = self.data_sender.clone();
1659 let request_id = request.request_id;
1660 let client_id = request.client_id;
1661 let data_type = request.data_type;
1662 let start = request.start;
1663 let end = request.end;
1664 let limit = request.limit.map(|value| value.get() as u32);
1665 let params = request.params;
1666 let clock = self.clock;
1667 let venue = self.venue();
1668 let start_nanos = datetime_to_unix_nanos(start);
1669 let end_nanos = datetime_to_unix_nanos(end);
1670
1671 self.spawn_command(async move {
1672 match http.request_binance_bars(bar_type, start, end, limit).await {
1673 Ok(bars) => {
1674 let response = DataResponse::Data(CustomDataResponse::new(
1675 request_id,
1676 client_id,
1677 Some(venue),
1678 data_type,
1679 binance_bars_to_custom_data(bar_type, bars),
1680 start_nanos,
1681 end_nanos,
1682 clock.get_time_ns(),
1683 params,
1684 ));
1685
1686 if let Err(e) = sender.send(DataEvent::Response(response)) {
1687 log::error!("Failed to send BinanceBar response: {e}");
1688 }
1689 }
1690 Err(e) => log::error!("BinanceBar request failed for {bar_type}: {e:?}"),
1691 }
1692 });
1693 Ok(())
1694 }
1695
1696 fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
1697 let instrument_id = request.single_instrument_id()?;
1698
1699 let http = self.http_client.clone();
1700 let sender = self.data_sender.clone();
1701 let limit = request.limit.map(|n| n.get() as u32);
1702 let request_id = request.request_id;
1703 let client_id = request.client_id.unwrap_or(self.client_id);
1704 let params = request.params;
1705 let clock = self.clock;
1706 let start_nanos = datetime_to_unix_nanos(request.start);
1707 let end_nanos = datetime_to_unix_nanos(request.end);
1708 let start = request.start;
1709 let end = request.end;
1710 anyhow::ensure!(
1711 limit.is_none_or(|value| value <= 1000),
1712 "Binance Spot trade limit must not exceed 1000"
1713 );
1714
1715 self.spawn_command(async move {
1716 let result = if start.is_some() || end.is_some() {
1717 http.request_agg_trades(instrument_id, start, end, limit)
1718 .await
1719 } else {
1720 http.request_trades(instrument_id, limit).await
1721 };
1722
1723 match result.context("failed to request trades from Binance") {
1724 Ok(trades) => {
1725 let response = DataResponse::Trades(TradesResponse::new(
1726 request_id,
1727 client_id,
1728 instrument_id,
1729 trades,
1730 start_nanos,
1731 end_nanos,
1732 clock.get_time_ns(),
1733 params,
1734 ));
1735
1736 if let Err(e) = sender.send(DataEvent::Response(response)) {
1737 log::error!("Failed to send trades response: {e}");
1738 }
1739 }
1740 Err(e) => log::error!("Trade request failed: {e:?}"),
1741 }
1742 });
1743
1744 Ok(())
1745 }
1746
1747 fn request_bars(&self, request: RequestBars) -> anyhow::Result<()> {
1748 let bar_type = request.single_bar_type()?;
1749
1750 let http = self.http_client.clone();
1751 let sender = self.data_sender.clone();
1752 let start = request.start;
1753 let end = request.end;
1754 let limit = request.limit.map(|n| n.get() as u32);
1755 let request_id = request.request_id;
1756 let client_id = request.client_id.unwrap_or(self.client_id);
1757 let params = request.params;
1758 let clock = self.clock;
1759 let start_nanos = datetime_to_unix_nanos(start);
1760 let end_nanos = datetime_to_unix_nanos(end);
1761 anyhow::ensure!(
1762 bar_type.aggregation_source() == AggregationSource::External,
1763 "Binance historical bars require EXTERNAL aggregation"
1764 );
1765 anyhow::ensure!(
1766 bar_type.spec().price_type == PriceType::Last,
1767 "Binance historical bars require LAST price type"
1768 );
1769 anyhow::ensure!(
1770 bar_type.spec().is_time_aggregated(),
1771 "Binance historical bars require time aggregation"
1772 );
1773
1774 self.spawn_command(async move {
1775 let result = http.request_bars(bar_type, start, end, limit).await;
1776
1777 match result.context("failed to request bars from Binance") {
1778 Ok(bars) => {
1779 let response = DataResponse::Bars(BarsResponse::new(
1780 request_id,
1781 client_id,
1782 bar_type,
1783 bars,
1784 start_nanos,
1785 end_nanos,
1786 clock.get_time_ns(),
1787 params,
1788 ));
1789
1790 if let Err(e) = sender.send(DataEvent::Response(response)) {
1791 log::error!("Failed to send bars response: {e}");
1792 }
1793 }
1794 Err(e) => log::error!("Bar request failed: {e:?}"),
1795 }
1796 });
1797
1798 Ok(())
1799 }
1800
1801 fn request_book_snapshot(&self, request: RequestBookSnapshot) -> anyhow::Result<()> {
1802 let instrument_id = request.single_instrument_id()?;
1803
1804 let depth = request.depth.map(|value| value.get() as u32);
1805 anyhow::ensure!(
1806 depth.is_none_or(|value| (1..=5000).contains(&value)),
1807 "Binance Spot order-book depth must be between 1 and 5000"
1808 );
1809 let http = self.http_client.clone();
1810 let book_sync = self.book_sync.clone();
1811 let sender = self.data_sender.clone();
1812 let request_id = request.request_id;
1813 let client_id = request.client_id.unwrap_or(self.client_id);
1814 let params = request.params;
1815 let clock = self.clock;
1816
1817 self.spawn_command(async move {
1818 let weight = depth_request_weight(depth.unwrap_or(100));
1820 let permit = book_sync.pacer().acquire(weight).await;
1821
1822 match http
1823 .request_book_snapshot_with_permit(instrument_id, depth, Some(permit))
1824 .await
1825 {
1826 Ok(book) => {
1827 let response = DataResponse::Book(BookResponse::new(
1828 request_id,
1829 client_id,
1830 instrument_id,
1831 book,
1832 None,
1833 None,
1834 clock.get_time_ns(),
1835 params,
1836 ));
1837
1838 if let Err(e) = sender.send(DataEvent::Response(response)) {
1839 log::error!("Failed to send book snapshot response: {e}");
1840 }
1841 }
1842 Err(e) => log::error!("Book snapshot request failed for {instrument_id}: {e:?}"),
1843 }
1844 });
1845 Ok(())
1846 }
1847}
1848
1849impl BinanceSpotDataClient {
1850 fn subscribe_book(&self, cmd: &SubscribeBookDeltas) -> anyhow::Result<()> {
1851 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1852 let cmd = cmd.with_instrument_ids(instrument_id);
1853 if cmd.book_type == BookType::L1_MBP {
1854 anyhow::ensure!(
1855 cmd.depth.is_none_or(|depth| depth.get() == 1),
1856 "Binance Spot L1_MBP supports depth 1 only"
1857 );
1858 anyhow::ensure!(
1859 !self.book_subscriptions.contains_key(&instrument_id),
1860 "cannot subscribe L1_MBP and L2_MBP for the same Binance Spot instrument"
1861 );
1862 self.l1_book_subscriptions.rcu(|subscriptions| {
1863 *subscriptions.entry(instrument_id).or_insert(0) += 1;
1864 });
1865
1866 self.subscribe_top_of_book(instrument_id);
1867 return Ok(());
1868 }
1869
1870 if cmd.book_type != BookType::L2_MBP {
1871 anyhow::bail!("Binance Spot supports L1_MBP and L2_MBP order book subscriptions");
1872 }
1873
1874 anyhow::ensure!(
1875 !self.l1_book_subscriptions.contains_key(&instrument_id),
1876 "cannot subscribe L1_MBP and L2_MBP for the same Binance Spot instrument"
1877 );
1878 let ws = self.ws_client.clone();
1879 let symbol_lower = instrument_id.symbol.as_str().to_lowercase();
1880 let stream = self.depth_stream(
1881 &symbol_lower,
1882 cmd.depth.map(|d| d.get()),
1883 cmd.params.as_ref(),
1884 )?;
1885
1886 if let Some(existing) = self.book_subscriptions.load().get(&instrument_id) {
1887 anyhow::ensure!(
1888 existing == &stream,
1889 "unsubscribe before changing Binance Spot book depth or update_speed"
1890 );
1891 return Ok(());
1892 }
1893
1894 if self.spot_market_data_mode == BinanceSpotMarketDataMode::Json
1895 && let Some(depth) = cmd.depth
1896 {
1897 let depth = depth.get();
1900
1901 if !BOOK_DEPTHS_JSON.contains(&depth) {
1902 anyhow::bail!(
1903 "Invalid depth {depth} for Binance Spot JSON order book. \
1904 Valid values: {BOOK_DEPTHS_JSON:?}"
1905 );
1906 }
1907
1908 self.book_subscriptions
1909 .insert(instrument_id, stream.clone());
1910 self.spawn_ws(
1911 chain_command(&self.book_command_tail, async move {
1912 ws.subscribe(vec![stream])
1913 .await
1914 .context("book deltas subscription")
1915 }),
1916 "order book subscription",
1917 );
1918
1919 return Ok(());
1920 }
1921
1922 match cmd.depth.map(|d| d.get()) {
1923 Some(depth) => {
1925 anyhow::ensure!(
1926 depth == 20,
1927 "Binance Spot SBE partial books support depth 20 only; use JSON market data for other depths"
1928 );
1929 self.book_subscriptions
1930 .insert(instrument_id, stream.clone());
1931 self.spawn_ws(
1932 chain_command(&self.book_command_tail, async move {
1933 ws.subscribe(vec![stream])
1934 .await
1935 .context("book deltas subscription")
1936 }),
1937 "order book subscription",
1938 );
1939 }
1940 None => {
1942 self.book_subscriptions
1943 .insert(instrument_id, stream.clone());
1944
1945 self.book_sync.subscribe(instrument_id);
1947 self.spawn_ws(
1948 chain_command(&self.book_command_tail, async move {
1949 ws.subscribe(vec![stream])
1950 .await
1951 .context("book deltas subscription")
1952 }),
1953 "order book subscription",
1954 );
1955 }
1956 }
1957
1958 Ok(())
1959 })
1960 }
1961
1962 fn unsubscribe_book(&self, cmd: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
1963 execute_instrument_subscriptions(&cmd.instrument_ids, |instrument_id| {
1964 if let Some(count) = self
1965 .l1_book_subscriptions
1966 .load()
1967 .get(&instrument_id)
1968 .copied()
1969 {
1970 if count == 1 {
1971 self.l1_book_subscriptions.remove(&instrument_id);
1972 } else {
1973 self.l1_book_subscriptions.rcu(|subscriptions| {
1974 if let Some(existing) = subscriptions.get_mut(&instrument_id) {
1975 *existing -= 1;
1976 }
1977 });
1978 }
1979
1980 self.unsubscribe_top_of_book(instrument_id);
1981 return Ok(());
1982 }
1983
1984 let ws = self.ws_client.clone();
1985
1986 let stream = self.book_subscriptions.load().get(&instrument_id).cloned();
1988 self.book_subscriptions.remove(&instrument_id);
1989 self.book_sync.remove(instrument_id);
1990
1991 let Some(stream) = stream else {
1992 return Ok(());
1993 };
1994
1995 self.spawn_ws(
1996 chain_command(&self.book_command_tail, async move {
1997 ws.unsubscribe(vec![stream])
1998 .await
1999 .context("book deltas unsubscribe")
2000 }),
2001 "order book unsubscribe",
2002 );
2003
2004 Ok(())
2005 })
2006 }
2007
2008 fn depth_stream(
2009 &self,
2010 symbol: &str,
2011 depth: Option<usize>,
2012 params: Option<&Params>,
2013 ) -> anyhow::Result<String> {
2014 let mut stream = match depth {
2015 Some(depth) => format!("{symbol}@depth{depth}"),
2016 None => format!("{symbol}@depth"),
2017 };
2018
2019 if self.spot_market_data_mode == BinanceSpotMarketDataMode::Json {
2020 let speed = params.and_then(|p| p.get("update_speed"));
2021 if let Some(speed) = speed {
2022 anyhow::ensure!(
2023 matches!(speed.as_u64(), Some(100 | 1000)),
2024 "Binance Spot JSON update_speed must be 100 or 1000, was {speed}"
2025 );
2026 }
2027
2028 if speed.is_none_or(|speed| speed.as_u64() == Some(100)) {
2029 stream.push_str("@100ms");
2030 }
2031 }
2032
2033 Ok(stream)
2034 }
2035
2036 fn subscribe_top_of_book(&self, instrument_id: InstrumentId) {
2037 let should_subscribe = {
2038 let previous = self
2039 .quote_refs
2040 .load()
2041 .get(&instrument_id)
2042 .copied()
2043 .unwrap_or(0);
2044 self.quote_refs.rcu(|refs| {
2045 *refs.entry(instrument_id).or_insert(0) += 1;
2046 });
2047 previous == 0
2048 };
2049
2050 if should_subscribe {
2051 let ws = self.ws_client.clone();
2052 let suffix = self.quote_stream_suffix();
2053 let stream = format!("{}@{suffix}", instrument_id.symbol.as_str().to_lowercase());
2054 self.spawn_ws(
2055 async move {
2056 ws.subscribe(vec![stream])
2057 .await
2058 .context("top-of-book subscription")
2059 },
2060 "top-of-book subscription",
2061 );
2062 }
2063 }
2064
2065 fn unsubscribe_top_of_book(&self, instrument_id: InstrumentId) {
2066 let should_unsubscribe = match self.quote_refs.load().get(&instrument_id).copied() {
2067 Some(1) => {
2068 self.quote_refs.remove(&instrument_id);
2069 true
2070 }
2071 Some(count) if count > 1 => {
2072 self.quote_refs.rcu(|refs| {
2073 if let Some(existing) = refs.get_mut(&instrument_id) {
2074 *existing -= 1;
2075 }
2076 });
2077 false
2078 }
2079 _ => false,
2080 };
2081
2082 if should_unsubscribe {
2083 let ws = self.ws_client.clone();
2084 let suffix = self.quote_stream_suffix();
2085 let stream = format!("{}@{suffix}", instrument_id.symbol.as_str().to_lowercase());
2086 self.spawn_ws(
2087 async move {
2088 ws.unsubscribe(vec![stream])
2089 .await
2090 .context("top-of-book unsubscribe")
2091 },
2092 "top-of-book unsubscribe",
2093 );
2094 }
2095 }
2096}
2097
2098#[derive(Debug, Clone)]
2099enum SpotWsClient {
2100 Sbe(BinanceSpotWebSocketClient),
2101 JsonPublic(BinanceSpotPublicJsonWebSocketClient),
2102}
2103
2104impl SpotWsClient {
2105 fn has_credentials(&self) -> bool {
2106 match self {
2107 Self::Sbe(client) => client.has_credentials(),
2108 Self::JsonPublic(_) => true, }
2110 }
2111
2112 fn replace_instruments(&self, instruments: &[InstrumentAny]) {
2113 match self {
2114 Self::Sbe(client) => client.replace_instruments(instruments),
2115 Self::JsonPublic(client) => client.replace_instruments(instruments),
2116 }
2117 }
2118
2119 async fn subscribe(&self, streams: Vec<String>) -> anyhow::Result<()> {
2120 match self {
2121 Self::Sbe(client) => client.subscribe(streams).await.map_err(Into::into),
2122 Self::JsonPublic(client) => client.subscribe(streams).await,
2123 }
2124 }
2125
2126 async fn unsubscribe(&self, streams: Vec<String>) -> anyhow::Result<()> {
2127 match self {
2128 Self::Sbe(client) => client.unsubscribe(streams).await.map_err(Into::into),
2129 Self::JsonPublic(client) => client.unsubscribe(streams).await,
2130 }
2131 }
2132
2133 async fn close(&mut self) -> anyhow::Result<()> {
2134 match self {
2135 Self::Sbe(client) => client.close().await.map_err(Into::into),
2136 Self::JsonPublic(client) => client.close().await,
2137 }
2138 }
2139
2140 fn begin_shutdown(&self) {
2141 match self {
2142 Self::Sbe(client) => client.begin_shutdown(),
2143 Self::JsonPublic(client) => client.begin_shutdown(),
2144 }
2145 }
2146}
2147
2148fn resolve_spot_json_ws_url(
2149 base_url_ws: Option<String>,
2150 environment: BinanceEnvironment,
2151 us: bool,
2152) -> String {
2153 let default_url =
2154 get_ws_base_url_with_us(BinanceProductType::Spot, environment, us).to_string();
2155
2156 match base_url_ws {
2157 Some(url) if looks_like_spot_sbe_ws_url(&url) => {
2158 log::warn!(
2159 "Spot JSON market-data mode received an SBE WebSocket URL override (`{url}`); \
2160 using Spot JSON WebSocket default for {environment:?}: {default_url}",
2161 );
2162 default_url
2163 }
2164 Some(url) => url,
2165 None => default_url,
2166 }
2167}
2168
2169fn looks_like_spot_sbe_ws_url(base_url: &str) -> bool {
2170 let without_scheme = base_url
2171 .split_once("://")
2172 .map_or(base_url, |(_, rest)| rest);
2173 let host = without_scheme
2174 .split(['/', ':'])
2175 .next()
2176 .unwrap_or(without_scheme);
2177 host.starts_with("stream-sbe") || host.starts_with("demo-stream-sbe")
2178}
2179
2180#[cfg(test)]
2181mod tests {
2182 use std::{num::NonZeroU32, sync::Arc, time::Duration};
2183
2184 use nautilus_common::{
2185 live::{runner::replace_data_event_sender, sender::EventSender},
2186 messages::DataEvent,
2187 testing::wait_until_async,
2188 };
2189 use nautilus_core::{AtomicMap, nanos::UnixNanos, time::AtomicTime};
2190 use nautilus_live::{book::DEFAULT_BOOK_SNAPSHOT_TIMEOUT_SECS, task::TaskGroup};
2191 use nautilus_model::{
2192 data::Data,
2193 enums::{BookAction, RecordFlag},
2194 identifiers::InstrumentId,
2195 instruments::{Instrument, InstrumentAny, stubs::currency_pair_btcusdt},
2196 };
2197 use nautilus_network::{
2198 http::HttpClient,
2199 ratelimiter::{RateLimiter, quota::Quota},
2200 };
2201 use parking_lot::Mutex;
2202 use rstest::rstest;
2203 use rust_decimal_macros::dec;
2204 use ustr::Ustr;
2205
2206 use super::{
2207 BinanceBookError, BinanceDepth, BinanceEnvironment, BinanceSpotDataClient,
2208 BinanceSpotHttpError, BinanceSpotMarketDataMode, SNAPSHOT_DEPTH,
2209 SNAPSHOT_WEIGHT_PER_MINUTE, depth_request_weight, depth_snapshot_error,
2210 parse_spot_depth_snapshot, resolve_spot_json_ws_url,
2211 };
2212 use crate::{
2213 book::{
2214 pacing::SnapshotPacer,
2215 sync::{BookSyncTracker, DepthSequencing},
2216 },
2217 common::{
2218 consts::{
2219 BINANCE_CLIENT_ID, BINANCE_SPOT_REQUEST_WEIGHT_PER_MINUTE, BINANCE_SPOT_WS_URL,
2220 },
2221 websocket::chain_command,
2222 },
2223 config::BinanceDataClientConfig,
2224 spot::{
2225 http::{BinancePriceLevel, BinanceSpotHttpClient},
2226 sbe::stream::{
2227 BestBidAskStreamEvent, DepthDiffStreamEvent, DepthSnapshotStreamEvent, PriceLevel,
2228 Trade, TradesStreamEvent,
2229 },
2230 websocket::streams::messages::BinanceSpotWsMessage,
2231 },
2232 };
2233
2234 #[tokio::test(start_paused = true)]
2235 async fn full_depth_snapshot_pacing_prevents_http_admission_timeouts() {
2236 let pacer = Arc::new(SnapshotPacer::new(SNAPSHOT_WEIGHT_PER_MINUTE));
2237 let quota = Quota::per_minute(BINANCE_SPOT_REQUEST_WEIGHT_PER_MINUTE);
2238 let request_key = Ustr::from("snapshot");
2239
2240 let limiter = Arc::new(RateLimiter::new_with_quota(
2241 None,
2242 vec![(request_key, quota)],
2243 ));
2244 let client = HttpClient::builder()
2245 .rate_limiters(vec![limiter])
2246 .build()
2247 .unwrap();
2248 let weight = depth_request_weight(SNAPSHOT_DEPTH);
2249 let mut snapshots = tokio::task::JoinSet::new();
2250
2251 for _ in 0..6 {
2252 let pacer = pacer.clone();
2253 let client = client.clone();
2254
2255 snapshots.spawn(async move {
2256 let permit = pacer.acquire(weight).await;
2257 tokio::time::timeout(
2258 Duration::from_secs(DEFAULT_BOOK_SNAPSHOT_TIMEOUT_SECS),
2259 async move {
2260 let keys = vec![request_key; weight as usize];
2261 client.await_rate_limits(Some(&keys)).await;
2262 permit.commit();
2263 },
2264 )
2265 .await
2266 .is_ok()
2267 });
2268 }
2269
2270 let mut admitted = Vec::new();
2271 while let Some(snapshot) = snapshots.join_next().await {
2272 admitted.push(snapshot.unwrap());
2273 }
2274
2275 assert_eq!(admitted, vec![true; 6]);
2276 }
2277
2278 #[rstest]
2279 #[case::trades("trades")]
2280 #[case::bbo("bbo")]
2281 #[case::snapshot("snapshot")]
2282 #[case::diff("diff")]
2283 fn handle_ws_message_rejects_invalid_sbe_then_processes_valid_bbo(#[case] kind: &str) {
2284 let ts_init = UnixNanos::from(1_800_000_000_000_000_000u64);
2285 let clock = Box::leak(Box::new(AtomicTime::new(false, ts_init)));
2286 let instrument = InstrumentAny::CurrencyPair(currency_pair_btcusdt());
2287 let instruments = Arc::new(AtomicMap::new());
2288 instruments.insert(instrument.id(), instrument.clone());
2289 let ws_instruments = Arc::new(AtomicMap::new());
2290 ws_instruments.insert(Ustr::from("BTCUSDT"), instrument);
2291 let l1_book_subscriptions = Arc::new(AtomicMap::<InstrumentId, u32>::new());
2292 let http_client = BinanceSpotHttpClient::new(
2293 BinanceEnvironment::Testnet,
2294 clock,
2295 None,
2296 None,
2297 None,
2298 None,
2299 None,
2300 None,
2301 )
2302 .unwrap();
2303 let (sender, mut receiver) = tokio::sync::mpsc::unbounded_channel();
2304 let sender = EventSender::from(sender);
2305 let pacer = SnapshotPacer::new(NonZeroU32::new(60_000).unwrap());
2306 let book_sync =
2307 BookSyncTracker::new(DepthSequencing::Spot, sender.clone(), Arc::new(pacer));
2308 let event_time_us = 1_700_000_000_000_000;
2309 let message = BinanceSpotWsMessage::BestBidAsk(BestBidAskStreamEvent {
2310 event_time_us,
2311 book_update_id: 123,
2312 price_exponent: -2,
2313 qty_exponent: -4,
2314 bid_price_mantissa: 12_345,
2315 bid_qty_mantissa: 25_000,
2316 ask_price_mantissa: 12_350,
2317 ask_qty_mantissa: 30_000,
2318 symbol: Ustr::from("BTCUSDT"),
2319 });
2320 let command_tasks = TaskGroup::new();
2321 let command_spawner = command_tasks.spawner().unwrap();
2322
2323 let invalid_level = PriceLevel {
2324 price_mantissa: i64::MAX,
2325 qty_mantissa: 1,
2326 };
2327
2328 let invalid = match kind {
2329 "trades" => BinanceSpotWsMessage::Trades(TradesStreamEvent {
2330 event_time_us,
2331 transact_time_us: event_time_us,
2332 price_exponent: 0,
2333 qty_exponent: 0,
2334 trades: vec![
2335 Trade {
2336 id: 1,
2337 price_mantissa: 1,
2338 qty_mantissa: 1,
2339 is_buyer_maker: false,
2340 },
2341 Trade {
2342 id: 2,
2343 price_mantissa: i64::MAX,
2344 qty_mantissa: 1,
2345 is_buyer_maker: true,
2346 },
2347 ],
2348 symbol: Ustr::from("BTCUSDT"),
2349 }),
2350 "bbo" => BinanceSpotWsMessage::BestBidAsk(BestBidAskStreamEvent {
2351 event_time_us,
2352 book_update_id: 122,
2353 price_exponent: 0,
2354 qty_exponent: 0,
2355 bid_price_mantissa: i64::MAX,
2356 bid_qty_mantissa: 1,
2357 ask_price_mantissa: 1,
2358 ask_qty_mantissa: 1,
2359 symbol: Ustr::from("BTCUSDT"),
2360 }),
2361 "snapshot" => BinanceSpotWsMessage::DepthSnapshot(DepthSnapshotStreamEvent {
2362 event_time_us,
2363 book_update_id: 122,
2364 price_exponent: 0,
2365 qty_exponent: 0,
2366 bids: vec![invalid_level],
2367 asks: vec![],
2368 symbol: Ustr::from("BTCUSDT"),
2369 }),
2370 "diff" => BinanceSpotWsMessage::DepthDiff(DepthDiffStreamEvent {
2371 event_time_us,
2372 first_book_update_id: 121,
2373 last_book_update_id: 122,
2374 price_exponent: 0,
2375 qty_exponent: 0,
2376 bids: vec![invalid_level],
2377 asks: vec![],
2378 symbol: Ustr::from("BTCUSDT"),
2379 }),
2380 _ => unreachable!(),
2381 };
2382
2383 BinanceSpotDataClient::handle_ws_message(
2384 invalid,
2385 &sender,
2386 &instruments,
2387 &ws_instruments,
2388 &book_sync,
2389 &l1_book_subscriptions,
2390 &AtomicMap::new(),
2391 &http_client,
2392 Duration::from_secs(10),
2393 clock,
2394 &command_spawner,
2395 );
2396 assert!(matches!(
2397 receiver.try_recv(),
2398 Err(tokio::sync::mpsc::error::TryRecvError::Empty)
2399 ));
2400
2401 BinanceSpotDataClient::handle_ws_message(
2402 message,
2403 &sender,
2404 &instruments,
2405 &ws_instruments,
2406 &book_sync,
2407 &l1_book_subscriptions,
2408 &AtomicMap::new(),
2409 &http_client,
2410 Duration::from_secs(10),
2411 clock,
2412 &command_spawner,
2413 );
2414
2415 let DataEvent::Data(Data::Quote(quote)) = receiver.try_recv().unwrap() else {
2416 panic!("expected quote data event");
2417 };
2418
2419 assert_eq!(quote.instrument_id, InstrumentId::from("BTCUSDT.BINANCE"));
2420 assert_eq!(quote.bid_price.as_decimal(), dec!(123.45));
2421 assert_eq!(quote.ask_price.as_decimal(), dec!(123.50));
2422 assert_eq!(quote.bid_size.as_decimal(), dec!(2.5));
2423 assert_eq!(quote.ask_size.as_decimal(), dec!(3.0));
2424 assert_eq!(quote.ts_event, UnixNanos::from_micros(event_time_us as u64));
2425 assert_eq!(quote.ts_init, ts_init);
2426 }
2427
2428 #[rstest]
2429 #[tokio::test]
2430 async fn chained_book_commands_run_in_issue_order() {
2431 let (sender, _receiver) = tokio::sync::mpsc::unbounded_channel();
2432 replace_data_event_sender(sender);
2433
2434 let config = BinanceDataClientConfig {
2435 spot_market_data_mode: BinanceSpotMarketDataMode::Json,
2436 ..Default::default()
2437 };
2438
2439 let client = BinanceSpotDataClient::new(*BINANCE_CLIENT_ID, config).unwrap();
2440 let order = Arc::new(Mutex::new(Vec::new()));
2441 let unsubscribe = Arc::clone(&order);
2442 let subscribe = Arc::clone(&order);
2443
2444 client.spawn_ws(
2445 chain_command(&client.book_command_tail, async move {
2446 tokio::time::sleep(Duration::from_millis(50)).await;
2447 unsubscribe.lock().push("unsubscribe");
2448 Ok(())
2449 }),
2450 "order book unsubscribe",
2451 );
2452
2453 client.spawn_ws(
2454 chain_command(&client.book_command_tail, async move {
2455 subscribe.lock().push("subscribe");
2456 Ok(())
2457 }),
2458 "order book subscription",
2459 );
2460
2461 wait_until_async(
2462 || {
2463 let finished = order.lock().len() == 2;
2464 async move { finished }
2465 },
2466 Duration::from_secs(5),
2467 )
2468 .await;
2469
2470 assert_eq!(*order.lock(), vec!["unsubscribe", "subscribe"]);
2471 }
2472
2473 #[rstest]
2474 fn parse_spot_depth_snapshot_sets_sequence_and_last_flag() {
2475 let instrument_id = InstrumentId::from("BTCUSDT.BINANCE");
2476 let depth = depth_snapshot(
2477 vec![price_level(10_000, 1_000)],
2478 vec![price_level(10_100, 2_000)],
2479 );
2480
2481 let deltas =
2482 parse_spot_depth_snapshot(&depth, instrument_id, 2, 3, UnixNanos::from(2)).unwrap();
2483
2484 assert_eq!(deltas.deltas.len(), 3);
2485 assert_eq!(deltas.deltas[0].sequence, 123);
2486 assert_eq!(deltas.deltas[1].sequence, 123);
2487 assert_eq!(deltas.deltas[2].sequence, 123);
2488 assert_eq!(deltas.ts_event, UnixNanos::from(2));
2489 assert_eq!(deltas.ts_init, UnixNanos::from(2));
2490 assert_eq!(deltas.deltas[1].order.price.as_decimal(), dec!(100.00));
2491 assert_eq!(deltas.deltas[1].order.size.as_decimal(), dec!(1.000));
2492 assert_eq!(deltas.deltas[1].flags, RecordFlag::F_SNAPSHOT as u8);
2493 assert_eq!(
2494 deltas.deltas[2].flags,
2495 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2496 );
2497 }
2498
2499 #[rstest]
2500 fn parse_spot_depth_snapshot_sets_last_flag_for_bid_only_snapshot() {
2501 let instrument_id = InstrumentId::from("BTCUSDT.BINANCE");
2502 let depth = depth_snapshot(vec![price_level(10_000, 1_000)], vec![]);
2503
2504 let deltas =
2505 parse_spot_depth_snapshot(&depth, instrument_id, 2, 3, UnixNanos::from(2)).unwrap();
2506
2507 assert_eq!(deltas.deltas.len(), 2);
2508 assert_eq!(
2509 deltas.deltas[1].flags,
2510 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2511 );
2512 }
2513
2514 #[rstest]
2515 fn parse_spot_depth_snapshot_returns_clear_only_for_empty_book() {
2516 let instrument_id = InstrumentId::from("BTCUSDT.BINANCE");
2517 let depth = depth_snapshot(vec![], vec![]);
2518
2519 let deltas =
2520 parse_spot_depth_snapshot(&depth, instrument_id, 2, 3, UnixNanos::from(2)).unwrap();
2521
2522 assert_eq!(deltas.deltas.len(), 1);
2523 assert_eq!(deltas.deltas[0].action, BookAction::Clear);
2524 assert_eq!(deltas.deltas[0].sequence, 123);
2525 assert_eq!(
2526 deltas.deltas[0].flags,
2527 RecordFlag::F_SNAPSHOT as u8 | RecordFlag::F_LAST as u8
2528 );
2529 }
2530
2531 #[rstest]
2532 fn parse_spot_depth_snapshot_rejects_out_of_range_price() {
2533 let instrument_id = InstrumentId::from("BTCUSDT.BINANCE");
2534 let depth = BinanceDepth {
2535 last_update_id: 123,
2536 price_exponent: 100,
2537 qty_exponent: -3,
2538 bids: vec![price_level(i64::MAX, 1_000)],
2539 asks: vec![],
2540 };
2541
2542 let result = parse_spot_depth_snapshot(&depth, instrument_id, 2, 3, UnixNanos::from(2));
2543
2544 assert!(result.is_err());
2545 }
2546
2547 #[rstest]
2548 fn parse_spot_depth_snapshot_rejects_out_of_range_quantity() {
2549 let instrument_id = InstrumentId::from("BTCUSDT.BINANCE");
2550 let depth = BinanceDepth {
2551 last_update_id: 123,
2552 price_exponent: -2,
2553 qty_exponent: 100,
2554 bids: vec![price_level(10_000, i64::MAX)],
2555 asks: vec![],
2556 };
2557
2558 let result = parse_spot_depth_snapshot(&depth, instrument_id, 2, 3, UnixNanos::from(2));
2559
2560 assert!(result.is_err());
2561 }
2562
2563 fn depth_snapshot(bids: Vec<BinancePriceLevel>, asks: Vec<BinancePriceLevel>) -> BinanceDepth {
2564 BinanceDepth {
2565 last_update_id: 123,
2566 price_exponent: -2,
2567 qty_exponent: -3,
2568 bids,
2569 asks,
2570 }
2571 }
2572
2573 fn price_level(price_mantissa: i64, qty_mantissa: i64) -> BinancePriceLevel {
2574 BinancePriceLevel {
2575 price_mantissa,
2576 qty_mantissa,
2577 }
2578 }
2579
2580 #[rstest]
2581 fn test_spot_market_data_mode_default_is_sbe() {
2582 assert_eq!(
2583 BinanceSpotMarketDataMode::default(),
2584 BinanceSpotMarketDataMode::Sbe
2585 );
2586 }
2587
2588 #[rstest]
2589 fn test_resolve_spot_json_ws_url_uses_environment_default_without_override() {
2590 assert_eq!(
2591 resolve_spot_json_ws_url(None, BinanceEnvironment::Live, false),
2592 BINANCE_SPOT_WS_URL.to_string()
2593 );
2594 }
2595
2596 #[rstest]
2597 fn test_resolve_spot_json_ws_url_rewrites_sbe_override_to_spot_default() {
2598 assert_eq!(
2599 resolve_spot_json_ws_url(
2600 Some("wss://stream-sbe.binance.com/ws".to_string()),
2601 BinanceEnvironment::Live,
2602 false,
2603 ),
2604 BINANCE_SPOT_WS_URL.to_string()
2605 );
2606 }
2607
2608 #[rstest]
2609 fn test_resolve_spot_json_ws_url_preserves_non_sbe_override() {
2610 let custom = "wss://example.com/ws".to_string();
2611 assert_eq!(
2612 resolve_spot_json_ws_url(Some(custom.clone()), BinanceEnvironment::Live, false),
2613 custom
2614 );
2615 }
2616
2617 #[rstest]
2618 fn test_resolve_spot_json_ws_url_uses_binance_us_default() {
2619 assert_eq!(
2620 resolve_spot_json_ws_url(None, BinanceEnvironment::Live, true),
2621 "wss://stream.binance.us:9443/ws"
2622 );
2623 }
2624
2625 #[rstest]
2626 #[case::smallest(1, 5)]
2627 #[case::tier_one_max(100, 5)]
2628 #[case::tier_two_min(101, 25)]
2629 #[case::tier_two_max(500, 25)]
2630 #[case::tier_three_min(501, 50)]
2631 #[case::tier_three_max(1000, 50)]
2632 #[case::tier_four_min(1001, 250)]
2633 #[case::largest(5000, 250)]
2634 fn depth_request_weight_follows_venue_tiers(#[case] limit: u32, #[case] expected: u32) {
2635 assert_eq!(depth_request_weight(limit), expected);
2636 }
2637
2638 #[rstest]
2639 #[case::network(BinanceSpotHttpError::NetworkError("connection reset".to_string()), true)]
2640 #[case::server_error(
2641 BinanceSpotHttpError::UnexpectedStatus {
2642 status: 503,
2643 body: String::new(),
2644 retry_after: None,
2645 },
2646 true
2647 )]
2648 #[case::rate_limited(
2649 BinanceSpotHttpError::BinanceError {
2650 code: -1003,
2651 message: "Too many requests".to_string(),
2652 status: 429,
2653 retry_after: None,
2654 },
2655 true
2656 )]
2657 #[case::retry_budget_exceeded(
2658 BinanceSpotHttpError::RetryBudgetExceeded("elapsed budget exhausted".to_string()),
2659 true
2660 )]
2661 #[case::invalid_symbol(
2662 BinanceSpotHttpError::BinanceError {
2663 code: -1121,
2664 message: "Invalid symbol.".to_string(),
2665 status: 400,
2666 retry_after: None,
2667 },
2668 false
2669 )]
2670 fn depth_snapshot_error_retries_transient_failures(
2671 #[case] error: BinanceSpotHttpError,
2672 #[case] retryable: bool,
2673 ) {
2674 let instrument_id = InstrumentId::from("BTCUSDT.BINANCE");
2675 let message = format!("depth snapshot request for {instrument_id} failed: {error}");
2676
2677 let classified = depth_snapshot_error(instrument_id, &error);
2678
2679 let expected = if retryable {
2680 BinanceBookError::Retryable(message)
2681 } else {
2682 BinanceBookError::Permanent(message)
2683 };
2684
2685 assert_eq!(classified, expected);
2686 }
2687}